概述

wp_kses_attr() 是 WordPress 中用于清理 HTML 元素属性的核心函数，确保属性符合允许的 HTML 规则。它处理属性验证、移除非法字符，并支持必需属性和允许值数组。

关键要点

• 函数移除所有属性，如果元素不允许任何属性；否则调用 wp_kses_hair() 进一步拆分属性。
• 支持定义属性的允许值数组，若属性值不在列表中，则移除该属性。
• 属性可标记为必需，如果必需属性缺失，KSES 会移除标签的所有属性。
• 清理过程包括移除残留的 < 和 > 字符，并处理 XHTML 闭合斜杠。
• 由于 KSES 不匹配开闭标签，安全回退是剥离所有属性而非移除标签本身。

代码示例

function wp_kses_attr( $element, $attr, $allowed_html, $allowed_protocols ) {
    if ( ! is_array( $allowed_html ) ) {
        $allowed_html = wp_kses_allowed_html( $allowed_html );
    }

    // Is there a closing XHTML slash at the end of the attributes?
    $xhtml_slash = '';
    if ( preg_match( '%s*/s*$%', $attr ) ) {
        $xhtml_slash = ' /';
    }

    // Are any attributes allowed at all for this element?
    $element_low = strtolower( $element );
    if ( empty( $allowed_html[ $element_low ] ) || true === $allowed_html[ $element_low ] ) {
        return "<$element$xhtml_slash>";
    }

    // Split it.
    $attrarr = wp_kses_hair( $attr, $allowed_protocols );

    // Check if there are attributes that are required.
    $required_attrs = array_filter(
        $allowed_html[ $element_low ],
        static function ( $required_attr_limits ) {
            return isset( $required_attr_limits['required'] ) && true === $required_attr_limits['required'];
        }
    );

    /*
     * If a required attribute check fails, we can return nothing for a self-closing tag,
     * but for a non-self-closing tag the best option is to return the element with attributes,
     * as KSES doesn't handle matching the relevant closing tag.
     */
    $stripped_tag = '';
    if ( empty( $xhtml_slash ) ) {
        $stripped_tag = "<$element>";
    }

    // Go through $attrarr, and save the allowed attributes for this element in $attr2.
    $attr2 = '';
    foreach ( $attrarr as $arreach ) {
        // Check if this attribute is required.
        $required = isset( $required_attrs[ strtolower( $arreach['name'] ) ] );

        if ( wp_kses_attr_check( $arreach['name'], $arreach['value'], $arreach['whole'], $arreach['vless'], $element, $allowed_html ) ) {
            $attr2 .= ' ' . $arreach['whole'];

            // If this was a required attribute, we can mark it as found.
            if ( $required ) {
                unset( $required_attrs[ strtolower( $arreach['name'] ) ] );
            }
        } elseif ( $required ) {
            // This attribute was required, but didn't pass the check. The entire tag is not allowed.
            return $stripped_tag;
        }
    }

    // If some required attributes weren't set, the entire tag is not allowed.
    if ( ! empty( $required_attrs ) ) {
        return $stripped_tag;
    }

    // Remove any "<" or ">" characters.
    $attr2 = preg_replace( '/[<>]/', '', $attr2 );

    return "<$element$attr2$xhtml_slash>";
}

注意事项

• 参数 $allowed_html 可以是数组或上下文字符串（如 'post'），非数组时会通过 wp_kses_allowed_html() 转换。
• 函数返回清理后的 HTML 元素字符串，确保输出安全。
• 自 WordPress 5.9.0 起，新增了对属性允许值数组和必需属性的支持。