Gutenberg Block：在WordPress RichText中启用项目符号与编号列表

一、通过allowedFormats属性启用列表 #

WordPress的RichText组件支持通过allowedFormats属性指定允许使用的格式，无序列表对应的格式标识是core/list，有序列表是core/ordered-list。

只需在组件配置中把这两个标识加入allowedFormats数组即可：

<RichText
  tagName="div"
  value={ content }
  onChange={ setContent }
  allowedFormats={ [ 'core/bold', 'core/italic', 'core/list', 'core/ordered-list' ] }
/>

配置完成后，RichText的工具栏会自动显示列表按钮，用户可以直接插入无序列表或有序列表。

注意：如果手动设置了allowedFormats，必须把所有需要的格式都列出来——默认情况下RichText支持大部分常用格式，但手动指定后会覆盖默认配置，未列出的格式会被禁用。

二、其他添加列表功能的方法 #

1. 自定义工具栏按钮 #

如果需要更灵活的工具栏控制，可以通过toolbar属性自定义按钮，手动处理列表格式的切换：

<RichText
  tagName="div"
  value={ content }
  onChange={ setContent }
  toolbar={ {
    controls: [
      'bold',
      'italic',
      {
        name: 'unordered-list',
        icon: 'list-view',
        title: '无序列表',
        onClick: () => {
          const newContent = RichText.toggleFormat( content, { type: 'core/list' } );
          setContent( newContent );
        }
      },
      {
        name: 'ordered-list',
        icon: 'list-ol',
        title: '有序列表',
        onClick: () => {
          const newContent = RichText.toggleFormat( content, { type: 'core/ordered-list' } );
          setContent( newContent );
        }
      }
    ]
  } }
/>

这里用到了RichText.toggleFormat方法来切换列表格式，需要确保已经引入@wordpress/block-editor中的RichText工具。

2. 用BlockControls扩展顶部工具栏 #

在自定义块开发场景中，还可以通过BlockControls组件把列表按钮放在编辑器顶部的全局工具栏，操作更便捷：

import { BlockControls, RichText } from '@wordpress/block-editor';
import { ToolbarGroup, ToolbarButton } from '@wordpress/components';

export default function Edit( { attributes, setAttributes } ) {
  const { content } = attributes;

  return (
    <>
      <BlockControls>
        <ToolbarGroup>
          <ToolbarButton
            icon="list-view"
            label="无序列表"
            onClick={ () => {
              const newContent = RichText.toggleFormat( content, { type: 'core/list' } );
              setAttributes( { content: newContent } );
            } }
          />
          <ToolbarButton
            icon="list-ol"
            label="有序列表"
            onClick={ () => {
              const newContent = RichText.toggleFormat( content, { type: 'core/ordered-list' } );
              setAttributes( { content: newContent } );
            } }
          />
        </ToolbarGroup>
      </BlockControls>
      <RichText
        tagName="div"
        value={ content }
        onChange={ ( newContent ) => setAttributes( { content: newContent } ) }
      />
    </>
  );
}

这种方式的按钮会跟随块选中状态显示在编辑器顶部，适合需要全局操作的自定义块。

内容的提问来源于stack exchange，提问作者Soumya Mitra