块过滤器

WordPress公开了几个API,允许您修改现有块的行为。

登记处

以下过滤器可用于在注册期间扩展块设置。

块类型元数据

筛选从块.json在使用PHP的服务器上注册块类型时,文件。它允许在处理元数据之前应用修改。

过滤器采用一个参数:

  • $元数据(阵列)–元数据加载自块.json用于注册块类型。

以下示例设置api版本的所有块2.

函数example_filter_metadata_registration($metadata){$metadata['apiVersion']=2;返回$metadata;};add_filter('块类型元数据','示例过滤器元数据注册');

下面是一个更健壮的示例,它禁用了标题块的背景色和渐变支持。这个块类型元数据过滤器非常适合策划编辑体验.

函数示例disable_heading_background_color_and_gradients($metadata){//仅将过滤器应用于标题块。if(!isset($metadata['name'])||'核心/标题'!==$元数据[“名称”]){返回$metadata;}//检查“supports”键是否存在。if(isset($metadata[“supports”])&&isset($metadata['“supports'][“color”])){//删除背景色和渐变支持。$metadata['supports']['color']['背景']=false;$metadata['supports']['color']['渐变']=false;}返回$metadata;}add_filter(“块类型元数据”,“示例禁用标题背景颜色和渐变色”);

块类型元数据设置

过滤根据已处理的块类型元数据确定的设置。它可以使用默认情况下未处理的块元数据应用自定义修改。

过滤器采用两个参数:

  • $设置(阵列)–用于注册块类型的已确定设置的数组。
  • $元数据(阵列)–从加载的元数据块.json文件。

以下示例增加了api版本对于所有区块1.

函数example_filter_metadata_registration($settings,$metadata){$settings['api_version']=$metadata['apiPiVersion']+1;返回$settings;};add_filter('块类型元数据设置','示例过滤器元数据注册',10,2);

块.register块类型

使用JavaScript在客户端注册块时,用于筛选块设置。它接收块设置、已注册块的名称以及null或已弃用的块设置(应用于已注册的弃用)作为参数。此筛选器也应用于块的每个不推荐使用的设置。

以下示例确保List块使用规范生成的类名保存(wp-块列表):

函数addListBlockClassName(设置,名称){if(name!=='core/list'){返回设置;}返回{…设置,支架:{…设置支持,className:true,},};}wp.hooks.add过滤器('块.registerBlockType',“my-plugin/class-names/list-block”,添加列表块类名);

块编辑器

以下过滤器可用于在块编辑器中编辑时更改块的行为。

块.getSaveElement

应用于块结果的筛选器节约功能。此过滤器用于替换或扩展元素,例如使用反应克隆元素修改元素的属性或替换其子元素,或返回一个全新的元素。

过滤器的回调接收元素、块类型定义对象和块属性作为参数。它应该返回一个元素。

以下示例将Cover块包装在外部容器div中。

函数wrapCoverBlockInContainer(元素、块类型、属性){//如果元素未定义,则跳过if(!元素){回报;}//仅适用于盖块if(blockType.name!==“核心/覆盖”){回流元件;}//返回包装在div中的元素return{element};}wp.hooks.add过滤器('blocks.getSaveElement',“my-plugin/wrap-cover-block-in-container”,包装盖块集装箱);

块.getSaveContent.extraProps

适用于返回WP元素的所有块的过滤器节约功能。此筛选器用于向节约功能。例如:为该元素添加className、id或任何有效属性。

滤波器接收电流节约元素的props、块类型和块属性作为参数。它应该返回一个道具对象。

以下示例默认为所有块添加红色背景。

函数addBackgroundColorStyle(道具){返回{…道具,style:{backgroundColor:'red'},};}wp.hooks.add过滤器(“blocks.getSaveContent.extraProps”,“my-plugin/add-background-color-style”,添加背景颜色样式);

注:A类块验证如果此过滤器在下次编辑文章时修改现有内容,则会发生错误。编辑器验证post中存储的内容是否与保存()功能。

要避免此验证错误,请使用render_block(渲染块)服务器端修改现有的帖子内容,而不是此过滤器。请参见render_block文档.

块.getBlockDefaultClassName

为块生成的HTML类遵循wp-block-{name}命名法。此筛选器允许提供备用类名。

例子:

//我们的过滤功能函数setBlockCustomClassName(className,blockName){return blockName===“核心/代码”?'my-plugin-code':className;}//添加过滤器wp.hooks.add过滤器('块.getBlockDefaultClassName',“my-plugin/set-block-custom-class-name”,设置块自定义类名);

块.切换到块类型.转换块

用于过滤块变换的单个变换结果。由于转换是多对多的,而不是一对一的,所以传递了所有原始块。

块.getBlockAttributes

在块属性的默认解析之后和验证之前立即调用,以允许插件及时操作属性值以进行验证和/或在编辑器中呈现块的初始值。

编辑。块编辑

用于修改块的编辑组件。它接收原始块块编辑组件并返回一个新包装的组件。

例子:

const{createHigherOrderComponent}=wp.compose;const{InspectorControls}=wp.blockEditor;const{PanelBody}=wp.components;const withMyPluginControls=createHigherOrderComponent((BlockEdit)=>{返回(道具)=>{返回(<><BlockEdit key=“edit”{…props}/><检验员控制><PanelBody>我的自定义控件</InspectorControls></>);};},'使用我的插件控件');wp.hooks.add过滤器('编辑器。块编辑','我的插件/带监控',使用MyPluginControls);

请注意,当此挂钩运行时所有块使用它有可能导致性能退化,特别是在块选择指标方面。

为了缓解这种情况,请考虑是否可以将您执行的任何工作更改为仅在特定条件下运行。

例如,假设您添加的组件只需要在块处于挑选出来的在这种情况下,可以使用块的“选定”状态(道具.is已选择)以限制渲染。

const withMyPluginControls=createHigherOrderComponent((BlockEdit)=>{返回(道具)=>{返回(<><BlockEdit{…props}/>{props.is已选择&&(<检查员控制><PanelBody>我的自定义控件</InspectorControls>) }</>);};},'使用我的插件控件');

编辑。块列表块

用于修改包含块的包装组件编辑组件和所有工具栏。它接收原件阻止列表阻止组件并返回一个新包装的组件。

下面的示例添加了一个唯一的类名。

const{createHigherOrderComponent}=wp.compose;const withClientIdClassName=创建高级订单组件((块列表块)=>{返回(道具)=>{返回(<块列表块{…道具}className={“块-”+props.clientId}/>);};},'带ClientIdClassName');wp.hooks.add过滤器('编辑器。块列表块',“my-plugin/with-client-id-class-name”,带有ClientIdClassName);

可以使用包装器道具返回组件的属性,如下例所示。

const{createHigherOrderComponent}=wp.compose;const withMyWrapperProp=createHigherOrderComponent((块列表块)=>{返回(道具)=>{const wrapperProps={…道具.wrapperProps,“data-my-property”:“值”,};return<BlockListBlock{…props}wrapperProps={wrapperProps}/>;};},'使用MyWrapperProp');wp.hooks.add过滤器('编辑器。块列表块',“my-plugin/with-my-wrapper-prop”,使用MyWrapperDrop);

编辑器.postContentBlockTypes

用于修改即使在锁定模板中使用也应启用的块列表。应在此处添加任何将数据保存到帖子的块。这方面的一个示例是发布特色图像块。通常在模板中使用,即使模板被锁定,此块也应允许选择图像。

下面的示例启用虚拟块名称空间/示例.

const addExampleBlockToPostContentBlockTypes=(块类型)=>{return[…blockTypes,'namespace/example'];};wp.hooks.add过滤器('编辑器.postContentBlockTypes',“my-plugin/post-content-block-types”,将示例块添加到PostContent块类型);

删除块

使用拒绝列表

添加块很容易,删除块也很容易。插件或主题作者可以使用JavaScript中的拒绝列表“注销”块。

将以下代码放入我的plugin.js文件。

//我的plugin.js从“@wordpress/blocks”导入{unregisterBlockType};从“@wordpress/dom-ready”导入domReady;domReady(函数(){unregisterBlockType('core/verse');} );

然后,使用以下函数在编辑器中加载此脚本。

<?php(电话)//my-plugin.php(我的插头.php)函数my_plugin_deny_list_blocks(){wp_排队_脚本(“my-plugin-deny-list-blocks”,插件url('my-plugin.js',__FILE__),数组(“wp-blocks”、“wp-dom-ready”、“wp-edit-post”));}add_action('enqueue_block_editor_assets','my_plugin_deny_list_blocks');
注销块时,可以有比赛条件首先运行的代码是:注册块还是注销块。您希望最后运行未注册代码。为此,必须指定将块注册为依赖项的组件,在这种情况下,wp-edit-post文件。此外,使用wp.domReady()确保加载dom后运行未注册代码。

使用允许列表

如果要禁用除允许列表外的所有块,可以调整上述脚本,如下所示:

//我的plugin.jsvar allowed块=[“核心/段落”,'核心/图像','core/html','核心/自由形式',];wp.blocks.getBlockTypes().forEach(函数(blockType)){if(allowedBlocks.indexOf(blockType.name)===-1){wp.blocks.unregisterBlockType(blockType.name);}} );

隐藏插入器中的块

允许的块类型全部

在WordPress 5.8之前,这个钩子被称为允许的块类型,现已弃用。如果你需要支持旧版本的WordPress,你可能需要一种方法来检测应该使用哪个过滤器。你可以检查一下允许的块类型通过查看WP块编辑器上下文类存在,这是在5.8中引入的。

在服务器上,可以使用允许的块类型全部过滤器。您可以返回true(支持所有块类型)、false(不支持任何块类型)或允许的块类型名称数组。您还可以使用提供的第二个参数$editor_context(编辑_内容)根据块类型的内容筛选块类型。

<?php(电话)//my-plugin.php(我的插头.php)函数示例filter_allowed_block_types_when_post_provided($allowed_block_types,$editor_context){if(!空($editor_context->post)){返回数组(“核心/段落”,“核心/标题”);}返回$allowed_block_types;}add_filter(“allowed_block_types_all”,“example_filter_allowed_block_types_when_post_provided”,10,2);

管理块类别

块类别全部

在WordPress 5.8之前,这个钩子被称为块类别,现已弃用。如果你需要支持旧版本的WordPress,你可能需要一种方法来检测应该使用哪个过滤器。你可以检查一下块类别通过查看WP块编辑器上下文类存在,该类在5.8中引入。

可以使用块类别全部过滤器。您可以通过实现一个返回类别列表的函数,在服务器上执行此操作。它将在块注册期间使用,并在插入器中对块进行分组。您还可以使用提供的第二个参数$editor_context(编辑_内容)根据内容筛选。

//my-plugin.php(我的插头.php)函数示例filter_block_categories_when_post_provided($block_catagories,$editor_context){if(!空($editor_context->post)){阵列_推送($块类别,阵列(“slug”=>“自定义类别”,'标题'=>__('自定义类别','自定义插件'),“icon”=>空,));}返回$block_categories;}add_filter('block_categories_all','example_filter_block_catagories_when_post_provided',10,2);

wp.blocks.updateCategory(更新类别)

还可以通过设置偶像属性。该值可以是WordPress仪表板图标.

您还可以设置SVG格式的自定义图标。要做到这一点,图标应该在前端呈现和设置,这样它可以利用WordPress SVG,从而实现移动兼容性,并使图标更容易访问。

要为上一示例中显示的类别设置SVG图标,请将以下示例JavaScript代码添加到调用wp.blocks.updateCategory(更新类别)例如:

(函数(){var el=反应创建元素;var SVG=wp.primitives。SVG;var circle=el(‘circle’{cx:10,cy:10,r: 10、,fill:'红色',stroke:'蓝色',笔划宽度:'10',} );var svgIcon=el(变量svgIcon=el)(SVG中,{宽度:20,高度:20,viewBox:“0 0 20 20”},圆圈);wp.blocks.updateCategory('my-category',{icon:svgIcon});} )();