wp_kses_allowed_html()
云策文档标注
概述
wp_kses_allowed_html() 函数用于根据指定上下文返回允许的 HTML 标签和属性的数组。它支持多种预定义上下文，如 'post'、'strip'、'data'、'entities'，也允许通过数组自定义允许的 HTML 元素和属性。
关键要点
- 函数返回一个多维数组，键为标签名，值为允许的属性数组。
- 参数 $context 可以是字符串（如 'post'、'strip'、'data'、'entities' 或字段过滤器名称）或数组（直接指定允许的 HTML 元素和属性）。
- 内部使用 apply_filters('wp_kses_allowed_html', $html, $context) 钩子，允许开发者过滤允许的 HTML 标签。
- 在 WordPress 5.0.1 中，'form' 标签被移除，但特定条件下会自动添加回允许列表。
- 函数处理不同上下文时，会返回相应的全局变量（如 $allowedposttags、$allowedtags、$allowedentitynames）或空数组。
代码示例
// strips all html (empty array)
$allowed_html = wp_kses_allowed_html( 'strip' );
// allows all most inline elements and strips all block level elements except blockquote
$allowed_html = wp_kses_allowed_html( 'data' );
// very permissive: allows pretty much all HTML to pass - same as what's normally applied to the_content by default
$allowed_html = wp_kses_allowed_html( 'post' );
// allows a list of HTML Entities such as
$allowed_html = wp_kses_allowed_html( 'entities' );注意事项
- HTML 标签和属性名在 HTML 中不区分大小写，但在添加到 KSES 允许列表时必须使用小写，否则不会被识别。
- 函数自 WordPress 3.5.0 引入，在 5.0.1 版本中移除了 'form' 标签，但通过过滤器可以调整。
原文内容
Returns an array of allowed HTML tags and attributes for a given context.
Parameters
$contextstring|arrayrequired-
The context for which to retrieve tags. Allowed values are
'post','strip','data','entities', or the name of a field filter such as'pre_user_description', or an array of allowed HTML elements and attributes.
Source
function wp_kses_allowed_html( $context = '' ) {
global $allowedposttags, $allowedtags, $allowedentitynames;
if ( is_array( $context ) ) {
// When `$context` is an array it's actually an array of allowed HTML elements and attributes.
$html = $context;
$context = 'explicit';
/**
* Filters the HTML tags that are allowed for a given context.
*
* HTML tags and attribute names are case-insensitive in HTML but must be
* added to the KSES allow list in lowercase. An item added to the allow list
* in upper or mixed case will not recognized as permitted by KSES.
*
* @since 3.5.0
*
* @param array[] $html Allowed HTML tags.
* @param string $context Context name.
*/
return apply_filters( 'wp_kses_allowed_html', $html, $context );
}
switch ( $context ) {
case 'post':
/** This filter is documented in wp-includes/kses.php */
$tags = apply_filters( 'wp_kses_allowed_html', $allowedposttags, $context );
// 5.0.1 removed the `<form>` tag, allow it if a filter is allowing it's sub-elements `<input>` or `<select>`.
if ( ! CUSTOM_TAGS && ! isset( $tags['form'] ) && ( isset( $tags['input'] ) || isset( $tags['select'] ) ) ) {
$tags = $allowedposttags;
$tags['form'] = array(
'action' => true,
'accept' => true,
'accept-charset' => true,
'enctype' => true,
'method' => true,
'name' => true,
'target' => true,
);
/** This filter is documented in wp-includes/kses.php */
$tags = apply_filters( 'wp_kses_allowed_html', $tags, $context );
}
return $tags;
case 'user_description':
case 'pre_term_description':
case 'pre_user_description':
$tags = $allowedtags;
$tags['a']['rel'] = true;
$tags['a']['target'] = true;
/** This filter is documented in wp-includes/kses.php */
return apply_filters( 'wp_kses_allowed_html', $tags, $context );
case 'strip':
/** This filter is documented in wp-includes/kses.php */
return apply_filters( 'wp_kses_allowed_html', array(), $context );
case 'entities':
/** This filter is documented in wp-includes/kses.php */
return apply_filters( 'wp_kses_allowed_html', $allowedentitynames, $context );
case 'data':
default:
/** This filter is documented in wp-includes/kses.php */
return apply_filters( 'wp_kses_allowed_html', $allowedtags, $context );
}
}
Hooks
- apply_filters( ‘wp_kses_allowed_html’, array[] $html, string $context )
-
Filters the HTML tags that are allowed for a given context.
Skip to note 2 content
Steven Lin
Example migrated from Codex:
// strips all html (empty array) $allowed_html = wp_kses_allowed_html( 'strip' ); // allows all most inline elements and strips all block level elements except blockquote $allowed_html = wp_kses_allowed_html( 'data' ); // very permissive: allows pretty much all HTML to pass - same as what's normally applied to the_content by default $allowed_html = wp_kses_allowed_html( 'post' ); // allows a list of HTML Entities such as $allowed_html = wp_kses_allowed_html( 'entities' );