云策 WordPress 开发者社区

块编辑器开发文档

@wordpress/escape-html

查看官方原文 ↗
💡 云策文档标注

概述

@wordpress/escape-html 是一个 WordPress 工具包，提供 HTML 转义实用函数，用于安全处理字符串以防止 HTML 注入和解析问题。它包含多个函数，如转义 & 符号、属性值、HTML 元素等，并支持 ES2015+ 环境。

关键要点

  • 安装方式：通过 npm install @wordpress/escape-html 安装，需 ES2015+ 环境，否则需包含 polyfill。
  • 核心函数：包括 escapeAmpersand、escapeAttribute、escapeEditableHTML、escapeHTML、escapeLessThan、escapeQuotationMark 和 isValidAttributeName。
  • 安全特性：函数针对特定场景（如属性值、可编辑 HTML）提供转义，遵循 W3C HTML 语法规范，并包含 WordPress 特定修复。
  • 贡献方式：作为 Gutenberg 项目的一部分，采用 monorepo 结构，可通过项目贡献指南参与。

注意事项

  • escapeAmpersand 实现不完美，仅转义非字符引用模式的 & 符号，允许无效命名引用。
  • escapeAttribute 转义大于和小于符号以防止 HTML 注入，特别是针对无 unfiltered_html 权限的用户。
  • escapeEditableHTML 要求转义所有 & 符号以确保页面正确渲染。
  • 环境要求：确保代码运行在 ES2015+ 环境，否则需添加 polyfill。
📄 原文内容

Escape HTML utils.

Installation

Install the module

npm install @wordpress/escape-html

This package assumes that your code will run in an ES2015+ environment. If you’re using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

API

escapeAmpersand

Returns a string with ampersands escaped. Note that this is an imperfect implementation, where only ampersands which do not appear as a pattern of named, decimal, or hexadecimal character references are escaped. Invalid named references (i.e. ambiguous ampersand) are still permitted.

Related

Parameters

  • value string: Original string.

Returns

  • string: Escaped string.

escapeAttribute

Returns an escaped attribute value.

Related

Note we also escape the greater than symbol, as this is used by wptexturize to
split HTML strings. This is a WordPress specific fix

Note that if a resolution for Trac#45387 comes to fruition, it is no longer
necessary for __unstableEscapeGreaterThan to be used.

Note we also escape the less-than symbol to prevent HTML injection vulnerabilities
and parsing issues, particularly for users without the unfiltered_html capability.

See: https://core.trac.wordpress.org/ticket/45387

Parameters

  • value string: Attribute value.

Returns

  • string: Escaped attribute value.

escapeEditableHTML

Returns an escaped Editable HTML element value. This is different from escapeHTML, because for editable HTML, ALL ampersands must be escaped in order to render the content correctly on the page.

Parameters

  • value string: Element value.

Returns

  • string: Escaped HTML element value.

escapeHTML

Returns an escaped HTML element value.

Related

Parameters

  • value string: Element value.

Returns

  • string: Escaped HTML element value.

escapeLessThan

Returns a string with less-than sign replaced.

Parameters

  • value string: Original string.

Returns

  • string: Escaped string.

escapeQuotationMark

Returns a string with quotation marks replaced.

Parameters

  • value string: Original string.

Returns

  • string: Escaped string.

isValidAttributeName

Returns true if the given attribute name is valid, or false otherwise.

Parameters

  • name string: Attribute name to test.

Returns

  • boolean: Whether attribute is valid.

Contributing to this package

This is an individual package that’s part of the Gutenberg project. The project is organized as a monorepo. It’s made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project’s main contributor guide.