WordPress教程 · WPtech

WordPress之Gutenberg(古腾堡)自定义块(二)

•̀.̫•́✧ · 10月20日 · 2019年 · 本文3081字 · 阅读8分钟176

本文内容主要参考海拔科技以及Gutenberg 开发API,介绍并解读新版WordPress所采用的 Gutenberg 编辑器 ( Block Editor/块编辑器 )如何创建自定义编辑块,包括块的样式以及扩展工具栏等。

本文适用于WordPress 5.22。关于WordPress Gutenberg自定义系列目录如下:

本文内容主要根据 Gutenberg 开发API ,为上文 WordPress之Gutenberg(古腾堡)自定义块(一) 中的js代码做解读,让大家更了解自定义的构建。

基本结构

利用wp.blocks.registerBlockType('namespace/block-name', {})来构建一个新的自定义块,基本格式如下:

blocks.registerBlockType('namespace/block-name', {
         title: '',
         category: ''
         icon: {},
         description: '',
         attributes: {},
         edit: function(props) {},
         save: function(props) {}
});

属性说明

  • namespace/block-name:自定义块的名称,其中namespace是插件或主题的名称
  • title:自定义块显示名称
  • category:所在分类目录,可选为“ common 、formatting 、layout 、widgets 、embed ”,对应分别是:常用区块、格式、布局元素、小工具、嵌入
  • icon:显示的图标
  • description:描述文字
  • attributes:自定义属性,用于保存属性值
  • edit:编辑时调用的函数,返回一个编辑时的html格式
  • save:保存时调用的函数,返回一个最后呈现的html格式

图标(icon)

输入值为 String 或者 Object

当属性值为 String 时, 可以是任何WordPress的Dashicons, 也可以是自定义svg元素。

// Specifying a dashicon for the block
icon: 'book-alt',
 
// Specifying a custom svg for the block
icon: <svg viewBox="0 0 24 24" xmlns="<a href="http://www.w3.org/2000/svg" rel="nofollow noopener" >http://www.w3.org/2000/svg</a>"><path fill="none" d="M0 0h24v24H0V0z" /><path d="M19 13H5v-2h14v2z" /></svg>, 

当属性值是Object时,如上所述,图标应该包含在src属性中。除了src之外,对象可以包含背景和前景色,例如:

 icon: {
     // 背景色
     background: '#7e70af',
     // 前景色
     foreground: '#fff',
     // 图标属性
     src: 'book-alt',
 } ,

属性(attributes)

用attribute从标记中提取属性的值。最简单的一个例子如下:

{
     url: {
         type: 'string',
     }
 } 

url就相当于一个字符变量,可以在自定义块中调用。在edit和save中,可以利用props.attributes.url调用url值,利用props.setAttributes( { url: value } ); 设置url值。注意:type只能是 null 、 boolean 、 object 、 array 、 number 、 string 、 integer 。

作为提取属性的值,需要加入source(内容来源)和selector(过滤器)两个属性。这个根据不同的需要而相应改变,可以详细阅读 Gutenberg 开发API :Attributes。这里提供三个常用的例子。

//例子1,提取块html中<code>标签内的内容到content中,返回值是字符串形式
content: {
     type: 'string',
     source: 'html',
     selector: 'code',
 },
//例子2,提取块中<span>标签内容到content中,返回值是数组形式
content: {
     type: 'array',
     source: 'children',
     selector: 'span',
 },
//例子3,提取包含类名为lan的类,用于提取某个标签的类。
typeClass: {
     source: 'attribute',
     selector: '.lan',
     attribute: 'class',
 },

函数 edit 和 save

edit 函数在编辑器的上下文中描述块的结构,显示编辑器在使用块时将呈现的内容。save函数定义了将不同属性组合到最终标记中的方式,表示块在网站前面的显示方式。 所以函数返回内容都应该是标准的HTML格式。如:

edit: function() {
     return wp.element.createElement(
         'div',
         null,
         'Your block.'
     );
 }
 save: function() {
     return wp.element.createElement(
         'div',
         null,
         'Your block.'
     );
 }

这个需要根据自己的需求来构建不同的显示内容,本文主要根据上文《 WordPress之Gutenberg(古腾堡)自定义块(一) 》的js代码中主要的内容进行解析。

  • 参数 props
    props相当于该自定义块的数据结构,包含了之前定义的 attributes 内的各属性值,也有创建的函数。
  • wp.element.createElement( )
    这个与HTML的 document.createElement( ) 函数相似,常见用法如 wp.element.createElement( 'nodename', { className: 'classname' }, content) 。nodename为元素名;classname为css类名,该部分可以添加各种属性值,如button的onClick事件等;content为内容,可以为 Document 对象或者空值等。需要在php中引入js文件的array()中添加 'wp-element' 。
  • wp.editor.RichText
    简单说是wp特有的文本编辑, 需要在php中引入js文件的array()中添加 'wp-editor' 。
    主要属性有:
    • value:内容
    • onChange:内容改变时调用的函数
    • placeholder:提示内容
    • multiline:每一行添加的标签名,可选
    • tagName:全部内容的标签名,可选
  • wp.element.Fragment
    使其子元素没有任何包装元素的组件。
  • wp.editor.BlockControls
    当块的edit实现返回时,呈现图标按钮的工具栏。此部分可以阅读 wordpress / editor 关于 BlockControls 的介绍。
  • wp.editor.AlignmentToolbar
    AlignmentToolbar需要为BlockControls元素的子元素,作为块的文本对齐的预配置组件。

总结

自定义块想实现单一的样式功能并不困难,将想要的样式通过css导入,在js文件中将编辑内容save在一个带有你css相应类的标签中即可。想要实现复杂的样式功能,则需要块的扩展以及工具栏等自定义内容了。关于块扩展以及自定义工具栏可以阅读《 WordPress之Gutenberg(古腾堡)自定义块扩展栏》、《WordPress之Gutenberg(古腾堡)自定义块工具栏 》。

0 条回应