WP_HTML_Token

💡 云策文档标注

概述

WP_HTML_Token 是 WordPress HTML 处理器在解析 HTML 时用于引用输入 HTML 字符串中标记的核心类。该类专为 HTML 处理器内部使用设计，与 WP_HTML_Processor 关联。

关键要点

WP_HTML_Token 类用于表示 HTML 解析过程中的标记，包括元素、特殊值（如 "marker"）等。
类属性包括 bookmark_name（书签名）、node_name（节点名）、has_self_closing_flag（自闭合标志）、namespace（命名空间）、integration_node_type（集成点类型）和 on_destroy（销毁回调）。
提供构造函数 __construct、析构函数 __destruct 和 __wakeup 方法，其中 __wakeup 会抛出异常以防止反序列化。
该类自 WordPress 6.4.0 版本引入，部分属性在后续版本（如 6.7.0）中更新。

代码示例

public function __construct( ?string $bookmark_name, string $node_name, bool $has_self_closing_flag, ?callable $on_destroy = null ) {
    $this->bookmark_name         = $bookmark_name;
    $this->namespace             = 'html';
    $this->node_name             = $node_name;
    $this->has_self_closing_flag = $has_self_closing_flag;
    $this->on_destroy            = $on_destroy;
}

注意事项

WP_HTML_Token 主要用于内部处理，开发者应通过 WP_HTML_Processor 使用，避免直接实例化。
bookmark_name 可能为 null，表示标记或节点没有书签；node_name 区分大小写，大写表示 HTML 元素，小写表示特殊值。
has_self_closing_flag 仅指示原始 HTML 中是否存在自闭合标志，不验证其有效性。
namespace 默认为 'html'，也可以是 'svg' 或 'math'，用于指示元素所属命名空间。
__wakeup 方法会抛出 LogicException，确保该类不会被反序列化，以维护数据完整性。

📄 原文内容

Core class used by the HTML processor during HTML parsing for referring to tokens in the input HTML string.

Description

This class is designed for internal use by the HTML processor.

Methods

Name	Description
WP_HTML_Token::__construct	Constructor – creates a reference to a token in some external HTML string.
WP_HTML_Token::__destruct	Destructor.
WP_HTML_Token::__wakeup	Wakeup magic method.

Source

class WP_HTML_Token {
	/**
	 * Name of bookmark corresponding to source of token in input HTML string.
	 *
	 * Having a bookmark name does not imply that the token still exists. It
	 * may be that the source token and underlying bookmark was wiped out by
	 * some modification to the source HTML.
	 *
	 * @since 6.4.0
	 *
	 * @var string
	 */
	public $bookmark_name = null;

	/**
	 * Name of node; lowercase names such as "marker" are not HTML elements.
	 *
	 * For HTML elements/tags this value should come from WP_HTML_Processor::get_tag().
	 *
	 * @since 6.4.0
	 *
	 * @see WP_HTML_Processor::get_tag()
	 *
	 * @var string
	 */
	public $node_name = null;

	/**
	 * Whether node contains the self-closing flag.
	 *
	 * A node may have a self-closing flag when it shouldn't. This value
	 * only reports if the flag is present in the original HTML.
	 *
	 * @since 6.4.0
	 *
	 * @see https://html.spec.whatwg.org/#self-closing-flag
	 *
	 * @var bool
	 */
	public $has_self_closing_flag = false;

	/**
	 * Indicates if the element is an HTML element or if it's inside foreign content.
	 *
	 * @since 6.7.0
	 *
	 * @var string 'html', 'svg', or 'math'.
	 */
	public $namespace = 'html';

	/**
	 * Indicates which kind of integration point the element is, if any.
	 *
	 * @since 6.7.0
	 *
	 * @var string|null 'math', 'html', or null if not an integration point.
	 */
	public $integration_node_type = null;

	/**
	 * Called when token is garbage-collected or otherwise destroyed.
	 *
	 * @var callable|null
	 */
	public $on_destroy = null;

	/**
	 * Constructor - creates a reference to a token in some external HTML string.
	 *
	 * @since 6.4.0
	 *
	 * @param string|null   $bookmark_name         Name of bookmark corresponding to location in HTML where token is found,
	 *                                             or `null` for markers and nodes without a bookmark.
	 * @param string        $node_name             Name of node token represents; if uppercase, an HTML element; if lowercase, a special value like "marker".
	 * @param bool          $has_self_closing_flag Whether the source token contains the self-closing flag, regardless of whether it's valid.
	 * @param callable|null $on_destroy            Optional. Function to call when destroying token, useful for releasing the bookmark.
	 */
	public function __construct( ?string $bookmark_name, string $node_name, bool $has_self_closing_flag, ?callable $on_destroy = null ) {
		$this->bookmark_name         = $bookmark_name;
		$this->namespace             = 'html';
		$this->node_name             = $node_name;
		$this->has_self_closing_flag = $has_self_closing_flag;
		$this->on_destroy            = $on_destroy;
	}

	/**
	 * Destructor.
	 *
	 * @since 6.4.0
	 */
	public function __destruct() {
		if ( is_callable( $this->on_destroy ) ) {
			call_user_func( $this->on_destroy, $this->bookmark_name );
		}
	}

	/**
	 * Wakeup magic method.
	 *
	 * @since 6.4.2
	 */
	public function __wakeup() {
		throw new LogicException( __CLASS__ . ' should never be unserialized' );
	}
}

View all references View on Trac View on GitHub

Changelog

Version	Description
6.4.0	Introduced.

云策 WordPress 开发者社区

类文档