WordPress.org网站
获取WordPress
WordPress.org网站

WordPress开发人员资源

@wordpress/块编辑器

@wordpress/块编辑器

在本文中

返回页首

此模块允许您创建和使用独立的块编辑器。

安装

安装模块

npm install@wordpress/block-editor--保存

此包假定您的代码将在2015年欧洲标准+环境。如果您使用的环境对此类语言功能和API的支持有限或不支持，那么您应该包括polyfill发货@wordpress/babel预设在代码中。

用法

从'react'导入{useState}；导入{块画布，块编辑器提供程序，阻止列表，}来自“@wordpress/block-editor”；函数MyEditorComponent（）{const[blocks，updateBlocks]=useState（[]）；返回(<块编辑器提供程序值={块}onInput={（块）=>updateBlocks（块）}onChange={（块）=>updateBlocks（块）}><BlockCanvas height=“400px”/></BlockEditorProvider>);}//确保也加载块编辑器样式表//导入“@wordpress/components/build-style/style.css”；//导入“@wordpress/block-editor/build-style/style.css”；

在这个例子中，我们正在实例化一个块编辑器。块编辑器由块编辑器提供程序包装器组件，用于传递当前块数组，每次更改onInput（输入）或onChange（更改时）回调的调用取决于更改是否被认为是持久的。

内部块编辑器提供程序，您可以嵌套任何可用的@wordpress/块编辑器UI组件，用于构建编辑器的UI。

在上面的示例中，我们正在渲染阻止列表显示和编辑阻止列表。例如，我们可以添加一个自定义侧边栏并使用块检查器组件可以编辑当前选定块的高级设置。（请参阅API程序所有可用组件的列表）。

这个阻止工具组件用于渲染选定块的工具栏。

在上面的示例中，没有注册的块类型，为了成功使用块编辑器，请确保注册一些块类型。例如，注册核心块类型可以这样做：

从“@wordpress/block-library”导入{registerCoreBlocks}；寄存器核心块（）；//确保也加载块样式表//导入“@wordpress/block-library/build-style/style.css”；//导入“@wordpress/block-library/build-style/editor.css”；//导入“@wordpress/block-library/build-style/theme.css”；

API程序

此包中的任何组件在@wordpress/组件是这些组件的扩展。

除非你创建编辑器，建议使用@wordpress/components中的组件，而不要使用此包中的组件。因为这些组件是为在编辑器中使用而定制的，如果在此上下文之外使用，可能会导致意外行为。

路线控制

相关的

对齐工具栏

相关的

自动完成

相关的

块对齐控制

相关的

块对齐工具栏

相关的

块面包屑

块导航组件，将当前块选择的层次显示为导航。

参数

  • 道具 对象：组件道具。
  • 属性.rootLabelText 一串：面包屑轨迹根元素的翻译标签。

退换商品

  • 元素：阻止面包屑。

方块画布

BlockCanvas组件是用于显示块编辑器画布的组件。我们称之为画布的是一个包含块列表的iframe，您可以对其进行操作。该组件还负责连接所有必要的钩子，以便在编辑器中跨块进行键盘导航，并将内容样式注入iframe。

用法

函数MyBlockEditor（）{const[blocks，updateBlocks]=useState（[]）；返回(<区块编辑器提供程序值={块}onInput={updateBlocks}onChange={persistBlocks}><BlockCanvas height=“400px”/></BlockEditorProvider>);}

参数

  • 道具 对象：组件道具。
  • 支柱.高度 一串：画布高度，默认为300px。
  • 道具.样式 阵列：要注入iframe的内容样式。
  • 道具.儿童 元素：画布的内容，默认为BlockList组件。

退换商品

  • 元素：阻止面包屑。

块颜色样式选择器

未记录的声明。

块上下文提供程序

将传递的值与当前使用的块上下文合并的组件。

相关的

参数

  • 道具 块上下文提供程序属性:

块控件

未记录的声明。

块编辑

未记录的声明。

块编辑器键盘快捷方式

未记录的声明。

块编辑器提供程序

未记录的声明。

块格式控件

未记录的声明。

方块图标

相关的

块检查器

相关的

阻止列表

未记录的声明。

块移动器

相关的

块导航下拉列表

未记录的声明。

块弹出式菜单

相关的

块预览

块预览渲染块或块数组的预览。

相关的

参数

  • 预览 对象：如何显示预览的选项
  • 预览.块 数组|对象：要预览的块实例（对象）或块数组。
  • 预览.viewportWidth 数：预览容器的宽度（以像素为单位）。控制块在预览中渲染的大小。默认值：700。

退换商品

  • 组件：要渲染的组件。

块选择清除器

未记录的声明。

块设置菜单

未记录的声明。

块设置菜单控件

相关的

参数

  • 道具 对象：填充道具。

退换商品

  • 元素：元素。

块样式

未记录的声明。

区块标题

将块的配置标题呈现为字符串，如果无法确定标题，则为空。

用法

<区块标题clientId=“afd1cb17-2c08-4e7a-91be-007ba7ddc3a1”最大长度=｛17｝/>

参数

  • 道具 对象:
  • 属性.客户端ID 一串：块的客户端ID。
  • props.maximumLength（道具最大长度） 数字|未定义：块标题字符串在截断之前的最大长度。
  • 属性上下文 字符串|未定义：要传递到的上下文获取块标签.

退换商品

  • JSX公司。元素：块标题。

块工具栏

渲染块工具栏。

相关的

参数

  • 道具 对象：组件道具。
  • 道具.hideDragHandle 布尔值：显示或隐藏拖放功能的拖动手柄。
  • 道具.变体 一串：工具栏的样式变量，也传递给从块工具栏按钮呈现的下拉菜单。

区块工具

渲染块工具（块工具栏、选择/导航模式工具栏、插入点和内联富格文本工具栏的插槽）。必须围绕块内容和编辑器样式包装器或iframe进行包装。

参数

  • $0 对象：道具。
  • 0美元儿童 对象：块内容和样式容器。
  • $0.__不稳定内容参考 对象：Ref保持内容滚动容器。

块垂直对齐控制

相关的

块垂直对齐工具栏

相关的

按钮块追加

相关的

按钮阻塞器附件

已弃用

使用按钮块追加而不是。

调色板

未记录的声明。

调色板控件

未记录的声明。

对比检查器

相关的

复制处理程序

已弃用

参数

  • 道具 对象:

创建自定义颜色HOC

用于创建“withCustomColors”HOC的高阶组件工厂，该HOC处理类生成颜色值、检索和颜色属性设置的颜色逻辑。

使用此高阶组件处理自定义颜色集。

用法

常量CUSTOM_COLORS=[{name:'红色'，slug:'红色’，color:'#ff0000'}，{name:'蓝色'，slug:'蓝色’，color:'#0000ff'}，];const withCustomColors=创建自定义颜色HOC（CUSTOM_COLORS）；// ...导出默认合成(使用自定义颜色（“backgroundColor”，“borderColor”），我的彩色组件);

参数

  • 颜色阵列 阵列：颜色对象的数组（名称、slug、颜色等）。

退换商品

  • 功能：高阶组件。

默认块追加器

未记录的声明。

字体大小选取器

相关的

获取颜色类名

基于正在使用的颜色及其slug的上下文返回类。

参数

  • 颜色上下文名称 一串：使用颜色的上下文/位置，例如：背景、文本等…
  • colorSlug颜色 一串：颜色的突起。

退换商品

  • ?一串：具有与所提供上下文中的颜色对应的类的字符串。如果未提供colorContextName或colorSlug，则返回未定义的。

按属性值获取颜色对象

提供由主题或编辑器默认设置的颜色对象数组，并且定义的颜色或自定义颜色的值返回描述颜色的颜色对象。

参数

  • 颜色 阵列：由主题或编辑器默认设置的颜色对象数组。
  • 定义的颜色 ?一串：包含颜色段塞的字符串。
  • 自定义颜色 ?一串：包含customColor值的字符串。

退换商品

  • ?对象：如果传递definedColor，并且在颜色中找到名称，则返回与主题或编辑器默认设置完全相同的颜色对象。否则，将定义一个只设置颜色的对象。

按颜色值获取颜色对象

提供由主题或编辑器默认设置的颜色对象数组，颜色值返回与该值匹配或未定义的颜色对象。

参数

  • 颜色 阵列：由主题或编辑器默认设置的颜色对象数组。
  • colorValue（颜色值） ?一串：包含颜色值的字符串。

退换商品

  • ?对象：颜色属性等于colorValue的颜色数组中包含的Color对象。如果没有颜色对象符合此要求，则返回未定义的。

获取计算流体类型值

计算使用clamp（）的流体字体大小值。可以指定最小和最大字体大小或单个字体大小。

如果指定了单个字体大小，则使用对数刻度对其进行缩放。

用法

//根据最小值和最大值计算流体字体大小值。const fontSize=getComputedFluidTypographyValue（{最小字体大小：'20px'，maximumFontSize:'45px'，} );//从单个字体大小计算流体字体大小值。const fontSize=getComputedFluidTypographyValue（{字体大小：'30px'，} );

参数

  • 参数 对象:
  • 参数最小视口宽度 ?一串：类型具有流动性的最小视口大小。如果指定了fontSize，则为可选。
  • args.maximum视口宽度 ?一串：具有流动性的最大尺寸。如果指定了fontSize，则为可选。
  • args.fontSize（参数字体大小） [string|数字]：Size从中派生maximumFontSize和minimumFontSize（如有必要）。如果指定了minimumFontSize和maximumFont Size，则为可选。
  • args.maximumFontSize（参数最大字体大小） ?一串：任何clamp（）计算的最大字体大小。可选。
  • args.minimumFontSize参数最小字体大小 ?一串：任何clamp（）计算的最小字体大小。可选。
  • args.scaleFactor参数 ?数：缩放因子，用于确定字体在边界内的缩放速度。可选。
  • args.minimumFontSizeLimit（参数最小字体大小限制） ?一串：计算出的最小字体大小。可选。

退换商品

  • 字符串|空：使用clamp（）的font-size值。

从预设中获取自定义值

将间距预设转换为自定义值。

参数

  • 价值 一串：要转换的值
  • 间距大小 阵列：当前间距预设对象的数组

退换商品

  • 一串：将间距预设映射到其等效自定义值。

获取字体大小

基于命名字体大小数组以及namedFontSize和customFontSizer值返回字体大小对象。如果namedFontSize未定义或在fontSizes中找不到，则返回一个仅具有基于customFontSize.的大小值的对象。

参数

  • 字体大小 阵列：字体大小对象数组，至少包含“名称”和“大小”值作为属性。
  • 字体大小属性 ?一串：字体大小属性的内容（slug）。
  • 自定义字体大小属性 ?数：自定义字体大小属性（值）的内容。

退换商品

  • ?对象：如果设置了fontSizeAttribute，并且在fontSizes中找到一个相等的slug，则返回该slug的字体大小对象。否则，将返回一个仅具有基于customFontSize的大小值的对象。

获取字体大小类

基于fontSizeName返回类。

参数

  • fontSizeSlug 一串：fontSize的Slug。

退换商品

  • 字符串|未定义：带有与传递的fontSize对应的类的字符串。该类是通过在kebabCase中追加“has-”和fontSizeSlug并以“-font-size”结尾而生成的。

按值获取字体大小对象

返回给定值对应的字体大小对象。

参数

  • 字体大小 阵列：字体大小对象数组。
  • 价值 数：字体大小值。

退换商品

  • 对象：字体大小对象。

按值获取渐变段

检索每个段塞的渐变段塞。

参数

  • 梯度 阵列：渐变调色板
  • 价值 一串：渐变值

退换商品

  • 一串：梯度段塞。

按slug获取渐变值

检索每个段塞的渐变值。

参数

  • 梯度 阵列：渐变调色板
  • 段塞 一串：渐变段塞

退换商品

  • 一串：渐变值。

从CssUnit获取Px

已弃用

此函数意外暴露为移动/本机使用。

退换商品

  • 一串：空字符串。

获取间距预设CssVar

将间距预设转换为自定义值。

参数

  • 价值 一串：要转换的值。

退换商品

  • 字符串|未定义：给定间距预设值的CSS变量字符串。

获取字体类别和样式

为块的排版支持属性提供CSS类名和内联样式。

参数

  • 属性 对象：块属性。
  • 设置 对象|布尔值：合并了theme.json设置

退换商品

  • 对象：排版块支持派生的CSS类和样式。

标题级别下拉列表

用于选择标题级别（1到6）或段落（0）的下拉列表。

参数

  • 支柱 WPHeadingLevel下拉属性：组件道具。

退换商品

  • 组件类型：工具栏。

高度控制

HeightControl渲染用于调整块高度的链接单位控件和范围控件。

相关的

参数

  • 道具 对象:
  • 道具标签 ?一串：控件的标签。
  • props.onChange（更改时的属性） （value:string）=>void：当高度改变时调用。
  • 道具值 一串：当前高度值。

退换商品

  • 组件：要渲染的组件。

内部块

相关的

插入器

未记录的声明。

检查员高级控制

未记录的声明。

检查员控制

相关的

isValue间距预设

检查给定值是一个间距预设。

参数

  • 价值 一串：要检查的值

退换商品

  • 布尔值：如果值是格式为var:preset|spacing|的字符串，则返回true。

调整内容控件

相关的

对齐工具栏

相关的

线路高度控制

相关的

媒体占位符

相关的

MediaReplaceFlow

相关的

MediaUpload（媒体上传）

相关的

媒体上传检查

相关的

多选择滚动到视图

已弃用

如果尚未在视图中，则将多块选择末端滚动到视图中。通过键盘进行选择后，这一点很重要。

未记录的声明。

观察值键入

相关的

面板颜色设置

未记录的声明。

纯文本

相关的

私人蚜虫

私有@wordpress/block-editor API。

递归提供程序

用于的React上下文提供程序使用有递归钩子以防止递归呈现。

使用此提供程序包装块内容并提供相同的内容唯一ID与一起使用的道具使用有递归.

参数

  • 道具 对象:
  • 道具统一ID *：用作块实例唯一标识符的任何值。
  • props.block名称 一串：可选块名。
  • 道具.儿童 JSX公司。元素：反应孩子。

退换商品

  • JSX公司。元素：反应元件。

可重用块重命名提示

未记录的声明。

超文本

相关的

RichTextShortcut（RichText快捷方式）

未记录的声明。

RichText工具栏按钮

未记录的声明。

设置_默认值

默认编辑器设置

类型定义

  • 设置默认值 对象

属性

  • 对齐宽 布尔值：启用/禁用宽对齐/完全对齐
  • 支持布局 布尔值：启用/禁用容器块中的布局支持。
  • 图像编辑 布尔值：图像编辑设置设置为false以禁用。
  • 图像大小 阵列：可用图像大小
  • 最大宽度 数：约束大小调整的最大宽度
  • 允许的块类型 布尔|数组：允许的块类型
  • hasFixed工具栏 布尔值：编辑器工具栏是否固定
  • 分心自由 布尔值：编辑器UI是否无干扰
  • 焦点模式 布尔值：是否启用对焦模式
  • 样式 阵列：编辑器样式
  • 保留CaretInsideBlock 布尔值：插入符号是否应在编辑模式下的块之间移动
  • 正文占位符 一串：空帖子占位符
  • 标题占位符 一串：空标题占位符
  • can锁定块 布尔值：用户是否可以管理块锁定状态
  • 代码编辑已启用 布尔值：用户是否可以切换到代码编辑器
  • 发电机定位器 布尔值：启用/禁用标题块的自动定位生成
  • 启用OpenverseMediaCategory 布尔值：启用/禁用插入器中的Openverse媒体类别。
  • 清除块选择 布尔值：未单击块时，块编辑器是否应在鼠标按下时清除选择。
  • __实验性CanUserUseUnfilteredHTML 布尔值：用户应该能够使用未过滤的HTML还是应该过滤HTML，例如，删除像iframe这样被认为不安全的元素。
  • __实验块目录 布尔值：用户是否启用了阻止目录
  • __实验性块模式 阵列：表示块图案的对象数组
  • __实验块模式类别 阵列：表示块图案类别的对象数组
  • __带有图像块的不稳定Gallery 布尔值：用户是否启用了使用InnerBlocks的重构库块

跳转到所选块

相关的

商店

存储块编辑器名称空间的定义。

相关的

存储配置

块编辑器数据存储配置。

相关的

工具选择器

未记录的声明。

变换样式

应用一系列CSS规则转换将选择器包装在给定类中和/或根据传递的参数重写URL。

参数

  • 样式 编辑样式[]：CSS规则。
  • 包装选择器 一串：包装选择器。

退换商品

  • 阵列：转换的规则。

类型定义

  • 编辑器样式 对象

属性

  • css公司 一串：CSS块，作为单个字符串。
  • 基本URL ?一串：重写URL时用作引用的基URL。
  • 忽略的选择器 ?字符串[]：选择器不换行。

打字机

确保在此组件中的键盘事件期间，文本选择与视口保持相同的垂直距离。垂直距离可能会有所不同。它是最后一次单击或滚动到的位置。

URL输入

相关的

URL输入按钮

相关的

URL端口

相关的

使用块命令

未记录的声明。

使用块显示信息

Hook用于尝试查找匹配的块变体并返回适当的信息以显示原因。为了找到匹配，我们需要以下几点：1。块的客户端id以提取其当前属性。2.应设置块变量处于活动状态支持适当的功能。

如果由于任何原因无法找到块变量匹配，则返回的信息来自块类型。如果找不到具有提供的clientId的blockType，则返回null。

参数

  • 客户端ID 一串：Block的客户端id。

退换商品

  • ?WP块显示信息：块的显示信息，或无效的当找不到块或其类型时。

使用块编辑上下文

这个使用块编辑上下文hook提供有关正在使用该hook的块的信息。它返回一个带有名称,已选定状态，以及客户端ID块的。如果您想创建需要访问当前块clientId但不想依赖作为参数传入的数据的自定义挂钩，那么它很有用。

退换商品

  • 对象：块编辑上下文

使用块编辑模式

允许块限制为编辑该块及其内部块而显示的用户界面。

用法

函数MyBlock（{attributes，setAttributes}）{useBlockEditingMode（“禁用”）；return<div{…useBlockProps（）}>；}

模式可以是三个选项之一：

  • “已禁用”：防止完全编辑块，即不能
    挑选出来的。
  • 'contentOnly'：隐藏所有非内容UI，例如
    工具栏、块移动器、块设置。
  • “默认”：允许按正常方式编辑块。

该模式被所有块的内部块继承，除非它们
他们自己的模式。

如果在块上下文之外调用，则模式将应用于所有块。

参数

  • 模式 ?块编辑模式：要应用的编辑模式。如果未定义，则不会更改当前编辑模式。

退换商品

  • 块编辑模式：当前编辑模式。

使用块属性

此钩子用于将元素轻轻标记为块元素。元素应该是块的最外层元素。调用此钩子并将返回的props传递给元素以标记为块。如果您为元素定义了ref，那么将ref传递给这个钩子是很重要的，钩子反过来会通过它返回的props传递给组件。您也可以选择通过这个钩子传递任何其他道具，它们将被合并并返回。

如果使用API>=v2，则需要在块的最外层元素上使用此挂钩。

用法

从“@wordpress/block-editor”导入{useBlockProps}；导出默认函数Edit（）{const blockProps=使用块属性(className:'my-custom-class'，样式：{颜色：'#222222'，backgroundColor:“#eeeee”})返回(<div{…blockProps}></div>)}

参数

  • 支柱 对象：可选。要传递给元素的属性。如果定义了ref，则必须包含ref。
  • 选项 对象：仅供内部使用的选项。
  • 选项__不稳定IsHtml 布尔值:

退换商品

  • 对象：传递给元素以标记为块的属性。

使用缓存Truthy

保留传递值的最新副本并将其返回。如果值变为假，它将返回最后一个真实副本。

参数

  • 价值 任何:

退换商品

  • 任何：value（值）

使用有递归

React挂钩，用于跟踪以前在块树中渲染的块。易受递归影响的块可以在其编辑防止所述递归的函数。

将此与递归提供程序组件，使用相同的唯一ID钩子和提供程序的值。

参数

  • 唯一ID *：用作块实例唯一标识符的任何值。
  • 块名称 一串：可选块名。

退换商品

  • 布尔值：一个布尔值，描述是否已呈现提供的id。

使用内部块属性

此钩子用于将元素轻轻标记为内部块包装元素。调用此钩子并将返回的props传递给元素，以标记为内部块包装器，从而自动将内部块呈现为子块。如果您为元素定义了一个ref，那么将ref传递给这个钩子是很重要的，钩子将通过返回的道具将其传递给组件。您也可以选择通过这个钩子传递任何其他道具，它们将被合并并返回。

相关的

参数

  • 道具 对象：可选。要传递给元素的属性。如果定义了ref，则必须包含该ref。
  • 选项 对象：可选。内部块选项。

使用设置

已弃用6.5.0改用useSettings。

用于检索正在使用的块实例的给定设置的挂钩。

它首先在块实例层次结构中查找设置。如果没有找到，它将在块编辑器设置中查找。

用法

const isEnabled=useSetting（'typeography.dropCap'）；

参数

  • 路径 一串：设置的路径。

退换商品

  • 任何：返回为设置定义的值。

使用设置

用于检索正在使用的块实例的给定设置的挂钩。

它首先在块实例层次结构中查找设置。如果没有找到，它将在块编辑器设置中查找它们。

用法

const[fixed，sticky]=useSettings（'position.fixed'，'position.stick'）；

参数

  • 路径 字符串[]：设置的路径。

退换商品

  • 任何[]：返回为设置定义的值。

使用缩小

用于将编辑器模式设置为缩小模式的钩子，调用钩子设置模式。

参数

  • 缩小 布尔值：是否应进入缩小模式

警告

相关的

带颜色上下文

未记录的声明。

带颜色

一个高阶组件，用于处理类生成颜色值、检索和颜色属性设置的颜色逻辑。

用于与默认编辑器/主题调色板一起使用。

用法

导出默认合成(带颜色（“backgroundColor”，{textColor:“color”}），我的彩色组件);

参数

  • 颜色类型 …（对象|string）：参数可以是字符串或对象。如果参数是一个对象，那么它应该包含作为键的颜色属性名称和作为值的颜色上下文。如果参数是字符串，则值应该是颜色属性名称，颜色上下文是通过对值应用kebab大小写转换来计算的。颜色上下文表示要使用颜色的上下文/位置。颜色的类名是使用“has”后跟颜色名称并以颜色上下文结尾生成的，所有这些都是在烤肉串中使用的，例如：has-green-background-color。

退换商品

  • 功能：高阶组件。

带有字体大小

高阶组件，用于处理用于类生成、字体大小值检索和字体大小更改处理的字体大小逻辑。

参数

  • 字体大小名称 …（对象|string）：参数都应该是字符串。每个字符串都包含字体大小属性名称，例如：“fontSize”。

退换商品

  • 功能：高阶组件。

写入流量

处理块之间的选择和导航。此组件应围绕BlockList。

参数

  • 道具 对象：组件属性。
  • 道具.儿童 元素：要呈现的子项。

参与此包

这是古腾堡项目的一部分。该项目组织为单回购。它由多个独立的软件包组成，每个包都有特定的用途。此monorepo中的包发布到净现值法并由使用WordPress（文字出版社）以及其他软件项目。

要了解更多关于对这个包或古腾堡整体贡献的信息，请阅读该项目的主要内容贡献者指南.

首次发布

上次更新时间

编辑文章

在GitHub上进行改进：@wordpress/block-editor