WordPress 6.2 引入了 WP_HTML_Tag_Processor
– 一个供块作者在 PHP 中调整块标记中的 HTML 标签属性的工具。 它是新 HTML 处理 API 中的第一个组件。
在 WordPress 中更新 HTML 一直需要使用不舒服的工具。 正则表达式很困难并且容易出现各种错误。 DOMDocument
占用大量资源,无法正确处理现代 HTML,并且在许多托管平台上不可用。
WP_HTML_Tag_Processor
迈出了弥合这一差距的第一步。
标记处理器可以可靠地更新 HTML 属性
标签处理器找到特定的标签并可以更改其属性。 这是在 HTML 块中的第一个 img
标签上设置 alt
属性的示例。
$html = '<img src="/husky.jpg">'; $p = new WP_HTML_Tag_Processor( $html ); if ( $p->next_tag() ) { $p->set_attribute( 'alt', 'Husky in the snow' ); } echo $p->get_updated_html(); // Output: // <img alt="Husky in the snow" src="/husky.jpg">
next_tag()
方法移动到 HTML 中的下一个可用标签,但也接受标签名称、CSS 类或两者以查找特定标签。 根据 HTML 规范,标签和属性名称的查找不区分大小写,但 CSS 类名称是。
if ( $p->next_tag( array( 'tag_name' => 'DIV', 'class_name' => 'block-GROUP' ) ) ) { $p->remove_class( 'block-group' ); $p->add_class( 'wp-block-group' ); }
默认情况下操作是安全的:
- 删除一个属性而不首先检查它是否存在,
- 添加一个可能已经存在的 CSS 类,
- 设置一个属性值而不确保它不会复制现有的值。
您不再需要担心您的代码会将 <textarea> 中的内容和属性值,甚至是 HTML 注释中的内容误认为是真正的标签。
标记处理器符合 HTML5 规范,因此您不必这样做。 它会在必要时自动转义和解码值,并且知道如何处理格式错误的标记。
$ugly_html = <<<HTML <textarea title='<div> elements are semantically void'> <div><!--<div attr-->="</div>"></div>"> </textarea> <div></div> HTML; $p = new WP_HTML_Tag_Processor( $ugly_html ); if ( $p->next_tag( 'div' ) ) { $p->add_class( 'bold' ); } echo $p->get_updated_html(); // Output: // <textarea title='<div> elements are semantically void'> // <div><!--<div attr-->="</div>"></div>"> // </textarea> // <div class="bold"></div>
标记处理器的运行速度足以在关键的热代码路径中运行,并且几乎不会产生内存开销。 在 WordPress 6.2 中,它取代了依赖正则表达式和字符串搜索来执行类似更新的容易出错的代码。
要更高级地使用标签处理器,请阅读大量的课堂文档并学习如何……
- ...设置书签以重新访问已扫描和修改的文档部分。
- …除了开始标签之外,还可以访问像 </div> 这样的结束标签。
- …通过访问文档中的每个标签来运行高级和有状态的查询。
进一步的考虑
有很多事情标签处理器不会做:它不会构建 DOM 文档树、查找嵌套标签或更新标签的内部 HTML 或内部文本。 与 HTML 相关的新 API 的工作仍在继续,未来的 WordPress 版本将建立在这项工作的基础上,以允许从 PHP 中访问块的所有属性(如果块提供 block.json
文件),使用 CSS 选择器查找标签,以及 使用新标签、删除标签和更新的内部标记修改 HTML 结构。
您可以通过 Gutenberg GitHub Repo 上的这个概述问题跟上进一步的发展。