woocommerce/packages/js/sanitize/zh-cn/README.md

@woocommerce/sanitize

使用 DOMPurify 并支持可信类型的 WooCommerce HTML 净化工具。

特性

• 安全的 HTML 净化：使用 DOMPurify 净化 HTML 内容
• 可信类型支持：自动配置可信类型策略以避免冲突
• 可配置：支持自定义允许的标签和属性
• TypeScript 支持：包含完整的 TypeScript 定义

用法

基本 HTML 净化

import { sanitizeHTML } from '@woocommerce/sanitize';

const cleanHTML = sanitizeHTML('<p>Hello <script>alert("xss")</script> World!</p>');
// 返回: '<p>Hello World!</p>'

React 集成

import { sanitizeHTML } from '@woocommerce/sanitize';

function MyComponent( { content } ) {
  const sanitizedContent = {
    __html: sanitizeHTML( content )
  };
  
  return (
    <div dangerouslySetInnerHTML={ sanitizedContent } />
  );
}

自定义配置

import { sanitizeHTML } from '@woocommerce/sanitize';

const customSanitized = sanitizeHTML(
    html,
    {
        tags: ['p', 'br', 'strong'],
        attr: ['class', 'id']
    }
);

选择返回类型

默认情况下，sanitizeHTML 返回一个字符串。您可以使用 returnType 选项选择其他 DOMPurify 返回模式：

import { sanitizeHTML } from '@woocommerce/sanitize';

// 返回一个 HTMLBodyElement
const bodyEl = sanitizeHTML('<p>Hi</p>', { returnType: 'HTMLBodyElement' });

// 返回一个 DocumentFragment
const fragment = sanitizeHTML('<p>Hi</p>', { returnType: 'DocumentFragment' });

可信类型

此包会自动配置一个名为 woocommerce-sanitize 的可信类型策略，以避免与 DOMPurify 的默认策略冲突。该策略在模块加载时初始化。

import { getTrustedTypesPolicy } from '@woocommerce/sanitize';

const policy = getTrustedTypesPolicy();
if (policy) {
  const trustedHTML = policy.createHTML('<p>Content</p>');
  element.innerHTML = trustedHTML; // 在可信类型环境中安全
}

该策略使用与 sanitizeHTML() 相同的规则自动净化 HTML。