wp_js_dataset_name()

💡 云策文档标注

概述

wp_js_dataset_name() 函数用于将 HTML 自定义数据属性名转换为 JavaScript dataset 属性名，遵循 HTML 规范。如果输入不是有效的自定义数据属性，则返回 null。

关键要点

函数检查属性名是否以 'data-' 开头，否则返回 null。
转换规则：移除 'data-' 前缀，并将连字符后的字母转换为大写。
返回类型为 string 或 null，适用于 WordPress 开发中的前端交互。

代码示例

'postId'       === wp_js_dataset_name( 'data-post-id' );
'Before'       === wp_js_dataset_name( 'data--before' );
'-One--Two---' === wp_js_dataset_name( 'data---one---two---' );
null === wp_js_dataset_name( 'post-id' );
null === wp_js_dataset_name( 'data' );
'' === wp_js_dataset_name( 'data-' );
0  === strlen( wp_js_dataset_name( 'data-' ) );

注意事项

函数基于 HTML 规范实现，确保与浏览器行为一致。
输入应为原始 HTML 属性名，如 'data-post-id'。
参考 wp_html_custom_data_attribute_name() 和相关 HTML 规范文档。

📄 原文内容

Return the corresponding JavaScript dataset name for an attribute if it represents a custom data attribute, or null if not.

Description

Custom data attributes appear in an element’s dataset property in a browser, but there’s a specific way the names are translated from HTML into JavaScript. This function indicates how the name would appear in JavaScript if a browser would recognize it as a custom data attribute.

Example:

// Dash-letter pairs turn into capital letters.
'postId'       === wp_js_dataset_name( 'data-post-id' );
'Before'       === wp_js_dataset_name( 'data--before' );
'-One--Two---' === wp_js_dataset_name( 'data---one---two---' );

// Not every attribute name will be interpreted as a custom data attribute.
null === wp_js_dataset_name( 'post-id' );
null === wp_js_dataset_name( 'data' );

// Some very surprising names will; for example, a property whose name is the empty string.
'' === wp_js_dataset_name( 'data-' );
0  === strlen( wp_js_dataset_name( 'data-' ) );

Parameters

$html_attribute_namestringrequired: Raw attribute name as found in the source HTML.

Return

string|null Transformed dataset name, if interpretable as a custom data attribute, else null.

Source

function wp_js_dataset_name( string $html_attribute_name ): ?string {
	if ( 0 !== substr_compare( $html_attribute_name, 'data-', 0, 5, true ) ) {
		return null;
	}

	$end = strlen( $html_attribute_name );

	/*
	 * If it contains characters which would end the attribute name parsing then
	 * something else is wrong and this contains more than just an attribute name.
	 */
	if ( ( $end - 5 ) !== strcspn( $html_attribute_name, "=/> tfrn", 5 ) ) {
		return null;
	}

	/**
	 * > For each name in list, for each U+002D HYPHEN-MINUS character (-)
	 * > in the name that is followed by an ASCII lower alpha, remove the
	 * > U+002D HYPHEN-MINUS character (-) and replace the character that
	 * > followed it by the same character converted to ASCII uppercase.
	 *
	 * @see https://html.spec.whatwg.org/#concept-domstringmap-pairs
	 */
	$custom_name = '';
	$at          = 5;
	$was_at      = $at;

	while ( $at < $end ) {
		$next_dash_at = strpos( $html_attribute_name, '-', $at );
		if ( false === $next_dash_at || $next_dash_at === $end - 1 ) {
			break;
		}

		// Transform `-a` to `A`, for example.
		$c = $html_attribute_name[ $next_dash_at + 1 ];
		if ( ( $c >= 'A' && $c <= 'Z' ) || ( $c >= 'a' && $c <= 'z' ) ) {
			$prefix       = substr( $html_attribute_name, $was_at, $next_dash_at - $was_at );
			$custom_name .= strtolower( $prefix );
			$custom_name .= strtoupper( $c );
			$at           = $next_dash_at + 2;
			$was_at       = $at;
			continue;
		}

		$at = $next_dash_at + 1;
	}

	// If nothing has been added it means there are no dash-letter pairs; return the name as-is.
	return '' === $custom_name
		? strtolower( substr( $html_attribute_name, 5 ) )
		: ( $custom_name . strtolower( substr( $html_attribute_name, $was_at ) ) );
}

View all references View on Trac View on GitHub

Changelog

Version	Description
6.9.0	Introduced.

云策 WordPress 开发者社区

函数文档