237 lines
7.8 KiB
Markdown
237 lines
7.8 KiB
Markdown
### 步骤4：仅对特定区块显示按钮（可选）
|
||
|
||
默认情况下，该按钮会显示在每个富文本工具栏中（如图片说明、按钮、段落等）。您可以通过使用[数据API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data)，仅针对特定类型的区块显示该按钮。
|
||
|
||
以下示例仅对段落区块显示按钮：
|
||
|
||
```js
|
||
import { registerFormatType, toggleFormat } from '@wordpress/rich-text';
|
||
import { RichTextToolbarButton } from '@wordpress/block-editor';
|
||
import { useSelect } from '@wordpress/data';
|
||
|
||
function ConditionalButton( { isActive, onChange, value } ) {
|
||
const selectedBlock = useSelect( ( select ) => {
|
||
return select( 'core/block-editor' ).getSelectedBlock();
|
||
}, [] );
|
||
|
||
if ( selectedBlock && selectedBlock.name !== 'core/paragraph' ) {
|
||
return null;
|
||
}
|
||
|
||
return (
|
||
<RichTextToolbarButton
|
||
icon="editor-code"
|
||
title="示例输出"
|
||
onClick={ () => {
|
||
onChange(
|
||
toggleFormat( value, {
|
||
type: 'my-custom-format/sample-output',
|
||
} )
|
||
);
|
||
} }
|
||
isActive={ isActive }
|
||
/>
|
||
);
|
||
}
|
||
|
||
registerFormatType( 'my-custom-format/sample-output', {
|
||
title: '示例输出',
|
||
tagName: 'samp',
|
||
className: null,
|
||
edit: ConditionalButton,
|
||
} );
|
||
```
|
||
|
||
### 步骤5：在下拉菜单外添加按钮（可选）
|
||
|
||
使用 `RichTextToolbarButton` 组件时，按钮会被添加到默认的下拉菜单中。您可以通过使用 `BlockControls` 组件将按钮直接添加到工具栏。
|
||
|
||
```js
|
||
import { registerFormatType, toggleFormat } from '@wordpress/rich-text';
|
||
import { BlockControls } from '@wordpress/block-editor';
|
||
import { ToolbarGroup, ToolbarButton } from '@wordpress/components';
|
||
|
||
const MyCustomButton = ( { isActive, onChange, value } ) => {
|
||
return (
|
||
<BlockControls>
|
||
<ToolbarGroup>
|
||
<ToolbarButton
|
||
icon="editor-code"
|
||
title="示例输出"
|
||
onClick={ () => {
|
||
onChange(
|
||
toggleFormat( value, {
|
||
type: 'my-custom-format/sample-output',
|
||
} )
|
||
);
|
||
} }
|
||
isActive={ isActive }
|
||
/>
|
||
</ToolbarGroup>
|
||
</BlockControls>
|
||
);
|
||
};
|
||
|
||
registerFormatType( 'my-custom-format/sample-output', {
|
||
title: '示例输出',
|
||
tagName: 'samp',
|
||
className: null,
|
||
edit: MyCustomButton,
|
||
} );
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
如果遇到错误：
|
||
|
||
- 请再次确认是否已先运行 `npm run build`。
|
||
- 确认构建过程中没有语法错误或其他问题。
|
||
- 确认JavaScript已在编辑器中加载。
|
||
- 检查控制台是否有错误消息。
|
||
|
||
## 其他资源
|
||
|
||
本指南中使用的参考文档：
|
||
|
||
- RichText：[`registerFormatType`](/packages/rich-text/README.md#registerformattype)
|
||
- 组件：[`RichTextToolbarButton`](/packages/block-editor/README.md#richtexttoolbarbutton)
|
||
- RichText：[`applyFormat`](/packages/rich-text/README.md#applyformat)
|
||
- RichText：[`removeFormat`](/packages/rich-text/README.md#removeformat)
|
||
- RichText：[`toggleFormat`](/packages/rich-text/README.md#toggleformat)
|
||
|
||
## 结论
|
||
|
||
本指南向您展示了如何在工具栏中添加按钮，并将其格式应用于选定的文本。请尝试使用它，并在下一个插件中探索更多可能性。
|
||
|
||
从 [block-development-examples](https://github.com/WordPress/block-development-examples) 仓库下载 [format-api 示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/format-api-f14b86)。
|
||
|
||
# 格式化工具栏 API
|
||
|
||
## 概述
|
||
|
||
格式化 API 使开发者能够向格式化工具栏添加自定义按钮，并将特定_格式_应用于文本选区。加粗按钮就是格式化工具栏中标准按钮的一个示例。
|
||
|
||
|
||
|
||
在 WordPress 术语中，_格式_是指具有[文本级语义的 HTML 标签](https://www.w3.org/TR/html5/textlevel-semantics.html#text-level-semantics-usage-summary)，用于为文本选区赋予特殊含义。例如，本教程中要挂钩到格式工具栏的按钮将使用 `<samp>` HTML 标签包裹特定文本选区。
|
||
|
||
## 开始之前
|
||
|
||
本指南假设您已熟悉 WordPress 插件及其 JavaScript 加载方式，如需复习请参阅[插件手册](https://developer.wordpress.org/plugins/)或 [JavaScript 教程](/docs/getting-started/fundamentals/javascript-in-the-block-editor.md)。
|
||
|
||
您需要准备：
|
||
|
||
- WordPress 开发环境
|
||
- 已激活并配置就绪的最小化插件
|
||
- 用于构建和入队的 JavaScript 设置
|
||
|
||
您可参考[完整的 format-api 示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/format-api-f14b86)进行设置。
|
||
|
||
## 分步指南
|
||
|
||
本指南将引用 `src/index.js` 作为进行更改的 JavaScript 文件。每步完成后，运行 `npm run build` 会生成 `build/index.js`，该文件随后将加载到文章编辑器界面。
|
||
|
||
### 步骤 1：注册新格式
|
||
|
||
第一步是注册新格式，在 `src/index.js` 中添加以下内容：
|
||
|
||
```js
|
||
import { registerFormatType } from '@wordpress/rich-text';
|
||
|
||
registerFormatType( 'my-custom-format/sample-output', {
|
||
title: '示例输出',
|
||
tagName: 'samp',
|
||
className: null,
|
||
} );
|
||
```
|
||
|
||
可用格式类型列表由 `core/rich-text` 存储库维护。您可查询存储库以确认自定义格式现已可用。
|
||
|
||
在浏览器控制台中运行以下代码进行验证：
|
||
|
||
```js
|
||
wp.data.select( 'core/rich-text' ).getFormatTypes();
|
||
```
|
||
|
||
这将返回包含格式类型的数组，其中包括您自定义的格式。
|
||
|
||
### 步骤 2：向工具栏添加按钮
|
||
|
||
格式就绪后，下一步是通过为 edit 属性注册组件来向 UI 添加按钮。
|
||
|
||
使用 `RichTextToolbarButton` 组件，更新 `src/index.js`：
|
||
|
||
```js
|
||
import { registerFormatType } from '@wordpress/rich-text';
|
||
import { RichTextToolbarButton } from '@wordpress/block-editor';
|
||
|
||
const MyCustomButton = ( props ) => {
|
||
return (
|
||
<RichTextToolbarButton
|
||
icon="editor-code"
|
||
title="示例输出"
|
||
onClick={ () => {
|
||
console.log( '切换格式' );
|
||
} }
|
||
/>
|
||
);
|
||
};
|
||
|
||
registerFormatType( 'my-custom-format/sample-output', {
|
||
title: '示例输出',
|
||
tagName: 'samp',
|
||
className: null,
|
||
edit: MyCustomButton,
|
||
} );
|
||
```
|
||
|
||
检查功能是否正常：构建并重新加载后，选择任意包含文本的区块（例如段落区块）。确认新按钮已添加到格式工具栏。
|
||
|
||
|
||
|
||
点击按钮并在控制台中查看 "toggle format" 消息。
|
||
|
||
如果未看到按钮或消息，请仔细检查是否正确构建和加载了 JavaScript，并查看控制台是否有错误信息。
|
||
|
||
### 步骤 3：点击时应用格式
|
||
|
||
接下来是更新按钮，在点击时应用格式。
|
||
|
||
在本示例中，`<samp>` 标签格式是二元的——文本选区要么具有该标签，要么没有，因此我们可以使用 RichText 包中的 `toggleFormat` 方法。
|
||
|
||
更新 `src/index.js`，修改 `onClick` 操作：
|
||
|
||
```js
|
||
import { registerFormatType, toggleFormat } from '@wordpress/rich-text';
|
||
import { RichTextToolbarButton } from '@wordpress/block-editor';
|
||
|
||
const MyCustomButton = ( { isActive, onChange, value } ) => {
|
||
return (
|
||
<RichTextToolbarButton
|
||
icon="editor-code"
|
||
title="示例输出"
|
||
onClick={ () => {
|
||
onChange(
|
||
toggleFormat( value, {
|
||
type: 'my-custom-format/sample-output',
|
||
} )
|
||
);
|
||
} }
|
||
isActive={ isActive }
|
||
/>
|
||
);
|
||
};
|
||
|
||
registerFormatType( 'my-custom-format/sample-output', {
|
||
title: '示例输出',
|
||
tagName: 'samp',
|
||
className: null,
|
||
edit: MyCustomButton,
|
||
} );
|
||
```
|
||
|
||
验证功能：先构建并重新加载，然后选择文本并点击按钮。浏览器可能会以不同于周围文本的方式显示该选区。
|
||
|
||
您也可以通过切换到 HTML 视图（代码编辑器 `Ctrl+Shift+Alt+M`）来确认，查看被 `<samp>` HTML 标签包裹的文本选区。
|
||
|
||
注册时使用 `className` 选项可向标签添加自定义类。您可以使用该类配合自定义 CSS 来定位元素并按需设置样式。 |