wp_html_custom_data_attribute_name()

💡 云策文档标注

概述

wp_html_custom_data_attribute_name() 函数用于将 JavaScript 元素 dataset 属性中的名称转换为对应的 HTML 自定义数据属性名称。它处理驼峰命名转换，并验证名称是否可表示为有效的 HTML 属性。

关键要点

函数接受一个字符串参数 $js_dataset_name，表示 JS dataset 属性名，返回对应的 HTML 属性名或 null。
转换规则包括：驼峰命名转换为连字符分隔的小写形式，并在开头添加 'data-' 前缀。
如果名称包含无效字符（如 '=', '>', 空格等）或无法表示为 HTML 属性，则返回 null。
空字符串作为输入时，返回 'data-'。

代码示例

'data-post-id'        === wp_html_custom_data_attribute_name( 'postId' );
'data--before'        === wp_html_custom_data_attribute_name( 'Before' );
'data---one---two---' === wp_html_custom_data_attribute_name( '-One--Two---' );

// Not every attribute name will be interpreted as a custom data attribute.
null === wp_html_custom_data_attribute_name( '/not-an-attribute/' );
null === wp_html_custom_data_attribute_name( 'no spaces' );

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

注意事项

参考 HTML 规范（whatwg.org）和 wp_js_dataset_name() 函数以了解更多细节。
该函数在 WordPress 6.9.0 版本中引入。

📄 原文内容

Returns a corresponding HTML attribute name for the given name, if that name were found in a JS element’s dataset property.

Description

Example:

'data-post-id'        === wp_html_custom_data_attribute_name( 'postId' );
'data--before'        === wp_html_custom_data_attribute_name( 'Before' );
'data---one---two---' === wp_html_custom_data_attribute_name( '-One--Two---' );

// Not every attribute name will be interpreted as a custom data attribute.
null === wp_html_custom_data_attribute_name( '/not-an-attribute/' );
null === wp_html_custom_data_attribute_name( 'no spaces' );

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

Parameters

$js_dataset_namestringrequired: Name of JS dataset property to transform.

Return

string|null Corresponding name of an HTML custom data attribute for the given dataset name, if possible to represent in HTML, otherwise null.

Source

function wp_html_custom_data_attribute_name( string $js_dataset_name ): ?string {
	$end = strlen( $js_dataset_name );
	if ( 0 === $end ) {
		return 'data-';
	}

	/*
	 * If it contains characters which would end the attribute name parsing then
	 * something it’s not possible to represent this in HTML.
	 */
	if ( strcspn( $js_dataset_name, "=/> tfrn" ) !== $end ) {
		return null;
	}

	$html_name = 'data-';
	$at        = 0;
	$was_at    = $at;

	while ( $at < $end ) {
		$next_upper_after = strcspn( $js_dataset_name, 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', $at );
		$next_upper_at    = $at + $next_upper_after;
		if ( $next_upper_at >= $end ) {
			break;
		}

		$prefix     = substr( $js_dataset_name, $was_at, $next_upper_at - $was_at );
		$html_name .= strtolower( $prefix );
		$html_name .= '-' . strtolower( $js_dataset_name[ $next_upper_at ] );
		$at         = $next_upper_at + 1;
		$was_at     = $at;
	}

	if ( $was_at < $end ) {
		$html_name .= strtolower( substr( $js_dataset_name, $was_at ) );
	}

	return $html_name;
}

View all references View on Trac View on GitHub

Changelog

Version	Description
6.9.0	Introduced.

云策 WordPress 开发者社区

函数文档