云策 WordPress 开发者社区

函数文档

filter_block_kses()

查看官方原文 ↗
💡 云策文档标注

概述

filter_block_kses() 函数用于过滤和清理已解析的块对象，从块属性值中移除不允许的 HTML。它递归处理块及其内部块，确保内容安全。

关键要点

  • 函数接受三个参数：$block（WP_Block_Parser_Block 对象，必需）、$allowed_html（允许的 HTML 元素和属性数组或上下文名称，必需）、$allowed_protocols（允许的 URL 协议数组，可选，默认为 wp_allowed_protocols() 的结果）。
  • 通过调用 filter_block_kses_value() 处理块属性，并递归处理 innerBlocks 以清理嵌套块。
  • 返回过滤和清理后的块对象数组，确保符合 WordPress 安全标准。

代码示例

function filter_block_kses( $block, $allowed_html, $allowed_protocols = array() ) {
    $block['attrs'] = filter_block_kses_value( $block['attrs'], $allowed_html, $allowed_protocols, $block );

    if ( is_array( $block['innerBlocks'] ) ) {
        foreach ( $block['innerBlocks'] as $i => $inner_block ) {
            $block['innerBlocks'][ $i ] = filter_block_kses( $inner_block, $allowed_html, $allowed_protocols );
        }
    }

    return $block;
}

注意事项

  • 此函数自 WordPress 5.3.1 版本引入，用于增强块编辑器内容的安全性。
  • 与 filter_block_kses_value() 和 filter_block_content() 相关，共同处理块内容的清理。
  • 开发者应确保 $allowed_html 参数正确设置，以避免意外移除必要的 HTML 元素。
📄 原文内容

Filters and sanitizes a parsed block to remove non-allowable HTML from block attribute values.

Parameters

$blockWP_Block_Parser_Blockrequired
The parsed block object.
$allowed_htmlarray[]|stringrequired
An array of allowed HTML elements and attributes, or a context name such as 'post'. See wp_kses_allowed_html() for the list of accepted context names.
$allowed_protocolsstring[]optional
Array of allowed URL protocols.
Defaults to the result of wp_allowed_protocols() .

Default:array()

Return

array The filtered and sanitized block object result.

Source

function filter_block_kses( $block, $allowed_html, $allowed_protocols = array() ) {
	$block['attrs'] = filter_block_kses_value( $block['attrs'], $allowed_html, $allowed_protocols, $block );

	if ( is_array( $block['innerBlocks'] ) ) {
		foreach ( $block['innerBlocks'] as $i => $inner_block ) {
			$block['innerBlocks'][ $i ] = filter_block_kses( $inner_block, $allowed_html, $allowed_protocols );
		}
	}

	return $block;
}

View all references View on Trac View on GitHub

Uses Description
filter_block_kses_value()wp-includes/blocks.php

Filters and sanitizes a parsed block attribute value to remove non-allowable HTML.
filter_block_kses()wp-includes/blocks.php

Filters and sanitizes a parsed block to remove non-allowable HTML from block attribute values.
Used by Description
filter_block_content()wp-includes/blocks.php

Filters and sanitizes block content to remove non-allowable HTML from parsed block attribute values.
filter_block_kses()wp-includes/blocks.php

Filters and sanitizes a parsed block to remove non-allowable HTML from block attribute values.

Changelog

Version Description
5.3.1 Introduced.