+
+在Gutenberg编辑器中激活NVDA后，可按Insert+F7打开元素列表。该功能将页面元素按类型分类展示，包括链接、标题、表单字段、按钮和地标区域。
+
+
+
+请确保元素具有规范标签，建议优先通过地标导航，再结合Tab键与方向键在地标区域内移动焦点。
+
+### VoiceOver + Safari 组合
+
+[VoiceOver](https://support.apple.com/guide/voiceover-guide/welcome/web)是macOS原生屏幕阅读器。可通过系统偏好设置>辅助功能>VoiceOver>启用VoiceOver激活，或在按住Command键的同时快速连按三次Touch ID启用。
+
+
+
+在Gutenberg编辑器中激活VoiceOver后，可按Control+Option+U启动转子功能，快速定位页面中的不同区域与元素。这也是检验元素标签是否规范的有效方式，若转子列表中的名称表述不清，则需要优化改进。
+
+
+
+建议在转子中优先选择区域或较大范围开始测试，而非直接选择独立元素，以便更完整地验证区域内的导航逻辑。
+
+定位目标区域后，可使用Control+Option配合左右方向键在页面元素间移动。请遵循VoiceOver的语音提示进行操作指引。
\ No newline at end of file
diff --git a/contributors/assets/gutenberg-logo-black.svg b/contributors/assets/gutenberg-logo-black.svg
new file mode 100644
index 0000000..467a13b
--- /dev/null
+++ b/contributors/assets/gutenberg-logo-black.svg
@@ -0,0 +1,256 @@
+
+
+
diff --git a/contributors/code/README.md b/contributors/code/README.md
new file mode 100644
index 0000000..2cf62f1
--- /dev/null
+++ b/contributors/code/README.md
@@ -0,0 +1,27 @@
+# 代码贡献指南
+
+关于如何开始为古腾堡项目贡献代码的指南。
+
+## 讨论交流
+
+[Make WordPress Core 博客](https://make.wordpress.org/core/)是获取WordPress开发最新信息的主要平台，包括公告、产品目标、会议记录、会议议程等。
+
+开发讨论将在[Make WordPress Slack](https://make.wordpress.org/chat)（需要注册）的`#core-editor`和`#core-js`频道实时进行。
+
+## 开发中心
+
+古腾堡项目使用GitHub管理代码并跟踪问题。主代码库位于：[https://github.com/WordPress/gutenberg](https://github.com/WordPress/gutenberg)。
+
+浏览[问题列表](https://github.com/wordpress/gutenberg/issues)寻找可参与解决的问题。[初试身手](https://github.com/wordpress/gutenberg/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+First+Issue%22)和[初次审阅](https://github.com/WordPress/gutenberg/pulls?q=is%3Aopen+is%3Apr+label%3A%22Good+First+Review%22)标签是不错的入门起点。
+
+## 贡献者资源
+
+- [入门指南](/docs/contributors/code/getting-started-with-code-contribution.md)：记录开发环境搭建流程，包括测试站点和开发者工具建议
+- [Git工作流](/docs/contributors/code/git-workflow.md)：说明使用拉取请求部署更改的git流程
+- [编码规范](/docs/contributors/code/coding-guidelines.md)：概述古腾堡项目中使用的额外模式与约定
+- [测试概览](/docs/contributors/code/testing-overview.md)：针对古腾堡中PHP和JavaScript开发的测试指南
+- [无障碍测试](/docs/contributors/accessibility-testing.md)：记录古腾堡无障碍功能测试流程
+- [包管理](/docs/contributors/code/managing-packages.md)：说明npm包的管理流程
+- [古腾堡发布流程](/docs/contributors/code/release.md)：古腾堡项目不同类型发布的检查清单
+- [React Native移动编辑器](/docs/contributors/code/react-native/README.md)：参与React Native移动编辑器开发的指南
+- [React Native集成测试指南](/docs/contributors/code/react-native/integration-test-guide.md)：创建移动编辑器集成测试的指南
\ No newline at end of file
diff --git a/contributors/code/auto-cherry-picking.md b/contributors/code/auto-cherry-picking.md
new file mode 100644
index 0000000..8de2446
--- /dev/null
+++ b/contributors/code/auto-cherry-picking.md
@@ -0,0 +1,91 @@
+# 自动化精选合并
+
+`npm run other:cherry-pick` 可自动将带有特定标签的拉取请求精选合并至**当前分支**。
+
+该功能在WordPress主要版本发布时尤为实用，因为脚本默认会查找带有`Backport to WP Beta/RC`标签的已合并拉取请求。
+
+您也可以通过传递自定义标签作为第一个参数，在不同场景中使用此功能。具体示例可参阅本文档末尾的Gutenberg插件发布案例。
+
+运行`npm run other:cherry-pick`会出现以下提示：
+
+```
+当前位于 "wp/6.2" 分支
+本脚本将执行以下操作：
+• 将标记为"Backport to WP Beta/RC"的已合并PR精选合并至此分支
+• 询问是否推送该分支
+• 在每个PR中添加注释
+• 移除每个PR的标签
+
+后两项操作将使用您关联至GitHub CLI（gh命令）的账户执行
+
+是否继续？（Y/n）
+```
+
+同意后将会执行以下流程：
+
+```
+开始逐个执行精选合并..
+
+$ git pull origin wp/6.2 --rebase...
+$ git fetch origin trunk...
+
+发现以下待精选合并的PR：
+ #41198 – 站点编辑器：设置样式预览最小宽度
+
+正在获取提交ID... 完成！
+ #41198 – 860a39665c318d33027d – 站点编辑器：设置样式预览...
+
+开始逐个执行精选合并...
+
+第一轮精选合并：
+ 精选提交：afe9b757b4 对应PR：#41198 – 站点编辑器：设置样式预览...
+精选合并完成！
+
+执行结果：
+ 成功精选合并 1 个PR
+ 合并失败 0 个PR
+
+即将推送至 origin/wp/6.2
+是否继续？（Y/n）
+```
+
+本次运行成功！此时您可以确认是否精选合并了正确的PR。
+
+如果精选合并出现冲突怎么办？脚本会继续处理其他PR并自动重试。
+若部分PR仍合并失败，脚本将跳过这些PR并告知需要手动解决冲突的节点。
+
+无论哪种情况，当您通过精选合并阶段后：
+
+```
+正在推送至 origin/wp/6.2
+添加注释并移除标签...
+ 41198: 已将此PR精选合并至wp/6.2分支以便纳入下一版本：afe9b757b4
+完成！
+```
+
+注释功能为可选操作，仅当您安装[`gh`命令行工具](https://cli.github.com/)时可用。
+
+### 能否使用`Backport to WP Beta/RC`之外的标签？
+
+可以！只需将其作为第一个参数传递：
+
+```
+npm run other:cherry-pick "其他标签"
+```
+
+### 如何用于Gutenberg插件发布？
+
+```
+# 切换到发布分支
+git checkout release/X.Y
+
+# 精选合并所有带有相关回溯标签的已合并PR
+npm run other:cherry-pick "Backport to Gutenberg RC"
+```
+
+### 未来改进方向
+
+未来有望实现根据当前所选分支自动匹配对应标签：
+
+* release/X.Y - 插件发布分支 → "Backport to Gutenberg RC"
+* wp/X.Y - WordPress发布分支 → "Backport to WP Beta/RC"
\ No newline at end of file
diff --git a/contributors/code/back-merging-to-wp-core.md b/contributors/code/back-merging-to-wp-core.md
new file mode 100644
index 0000000..1d2d1dd
--- /dev/null
+++ b/contributors/code/back-merging-to-wp-core.md
@@ -0,0 +1,38 @@
+# 将代码反向合并至WordPress核心
+
+在WordPress软件的主要版本发布时，需要将Gutenberg的功能合并到WordPress核心代码中。通常这涉及提取Gutenberg代码库中`.php`文件的变更，并在WP核心代码库中进行相应更新。
+
+## 合并标准
+
+### 文件/目录范围
+
+以下文件/目录内的变更通常需要反向合并至WP核心：
+
+- `lib/` 目录
+- `phpunit/` 目录
+
+### 排除目录/文件
+
+以下目录/文件_无需_反向合并至WP核心：
+
+- `lib/load.php` - 插件专用代码
+- `lib/experiments-page.php` - 实验性功能为插件专用
+- `packages/block-library` - 将在程序包同步过程中自动处理
+- `packages/e2e-tests/plugins` - 仅限端到端测试相关的PHP文件（主要为测试数据生成器）
+- `phpunit/blocks` - 该代码由Gutenberg维护，测试文件也应保留在此
+
+请注意此列表并未涵盖所有情况。
+
+### 拉取请求标准
+
+通常来说，自[上一稳定版WP核心](https://developer.wordpress.org/block-editor/contributors/versions-in-wordpress/)所包含的最终版Gutenberg发布之日起，所有提交至Gutenberg代码库的PHP代码都应考虑反向合并至WP核心。
+
+但存在以下例外情况，符合这些标准的PR_无需_反向合并至WP核心：
+
+- 未包含PHP代码变更
+- 具有`Backport from WordPress Core`标签 - 该代码已存在于WP核心，正在同步回Gutenberg
+- 具有`Backported to WordPress Core`标签 - 该代码已完成向WP核心的同步
+
+## 扩展阅读
+
+另请参阅关于[Gutenberg PHP代码](/lib/README.md)的补充文档。
\ No newline at end of file
diff --git a/contributors/code/backward-compatibility.md b/contributors/code/backward-compatibility.md
new file mode 100644
index 0000000..52fd656
--- /dev/null
+++ b/contributors/code/backward-compatibility.md
@@ -0,0 +1,79 @@
+# 向后兼容性
+
+历史上，WordPress 以其跨版本保持向后兼容性而闻名。Gutenberg 在其生产环境的公共 API 中尽可能遵循这一原则。在极少数情况下，破坏向后兼容性不可避免，此时需确保：
+
+- 破坏范围应尽可能限制在 API 的小部分区域内。
+- 应通过开发者说明文档向第三方开发者尽可能清晰地记录破坏性变更。
+
+## 生产环境公共 API 的界定标准
+
+Gutenberg 代码库由两种不同类型的包组成：
+
+- **生产环境包**：这些包作为 WordPress 脚本发布（例如：wp-components、wp-editor...）。
+- **开发环境包**：这些包由开发者工具组成，可供第三方开发者用于检查、测试、格式化和构建其主题和插件（例如：@wordpress/scrips、@wordpress/env...）。通常，这些包在第三方项目中作为 npm 依赖项使用。
+
+向后兼容性保证仅适用于生产环境包，因为更新是通过 WordPress 升级进行的。
+
+生产环境包使用 `wp` 全局变量向第三方开发者提供 API。这些 API 可以是 JavaScript 函数、变量和 React 组件。
+
+### 如何保持 JavaScript 函数的向后兼容性
+
+- 函数名称不应更改。
+- 函数的参数顺序不应更改。
+- 函数的返回值类型不应更改。
+- 如果保证所有之前的调用仍然有效，可以对参数进行更改（新增参数、修改语义）。
+
+### 如何保持 React 组件的向后兼容性
+
+- 组件名称不应更改。
+- 组件的属性不应被移除。
+- 应继续支持现有的属性值。如果组件接受函数作为属性，可以更新组件以接受同一属性的新类型，但不应破坏现有用法。
+- 允许添加新属性。
+- 只有在确保之前的上下文契约不被破坏的情况下，才能添加或移除 React Context 依赖。
+
+### 如何保持区块的向后兼容性
+
+- 当编辑器加载时，区块的现有用法不应被破坏或标记为无效。
+- 应保证现有区块的样式。
+- 标记更改应尽可能限制在最小范围内，但如果区块需要更改其保存的标记，导致先前版本无效，则应添加该区块的[**废弃版本**](/docs/reference-guides/block-api/block-deprecation.md)。
+
+## 类名和 DOM 更新
+
+React 组件树内部使用的类名和 DOM 节点不被视为公共 API 的一部分，可以进行修改。
+
+对这些内容的更改应谨慎进行，因为它们可能影响第三方代码的样式和行为（即使它们本不应依赖这些内容）。如果可能，保留旧的类名和 DOM 节点。如果无法保留，请记录更改并撰写开发者说明。
+
+## 废弃
+
+随着项目的发展，现有 API 的缺陷会被发现，或者需要更新以支持新功能。在这种情况下，我们尽量保证现有 API 不被破坏，并构建新的替代 API。
+
+为了鼓励第三方开发者采用新的 API，我们可以使用[**废弃**](/packages/deprecated/README.md)辅助工具来显示一条消息，说明废弃情况并在使用旧 API 时提供替代方案。
+
+明确说明功能何时被废弃。使用辅助方法的 `since` 和 `plugin` 选项。
+
+示例：
+
+```js
+deprecated( 'wp.components.ClipboardButton', {
+ since: '10.3',
+ plugin: 'Gutenberg',
+ alternative: 'wp.compose.useCopyToClipboard',
+} );
+```
+
+## 开发者说明
+
+开发者说明是在 WordPress 发布之前[发布在 make/core 网站上的文章](https://make.wordpress.org/core/tag/dev-notes/)，用于向第三方开发者通报开发者 API 的重要变更，这些变更可能包括：
+
+- 新的 API。
+- 可能影响现有插件和主题的现有 API 变更（例如：类名更改等）。
+- 不可避免的向后兼容性破坏，附带理由和迁移流程。
+- 重要的废弃（即使没有破坏性变更），附带理由和迁移流程。
+
+### 开发者说明工作流程
+
+- 在处理拉取请求时，如果发现需要开发者说明，请为 PR 添加 **Needs Dev Note** 标签。
+- 如果可能，在 PR 中添加评论，说明为什么需要开发者说明。
+- 当即将发布的 WordPress 版本的第一个测试版发布时，检查发布中包含的已合并 PR 列表，这些 PR 标记有 **Needs Dev Note** 标签。
+- 对于每一个这样的 PR，撰写开发者说明，并与 WordPress 发布负责人协调发布开发者说明。
+- 一旦 PR 的开发者说明发布，从 PR 中移除 **Needs Dev Note** 标签。
\ No newline at end of file
diff --git a/contributors/code/coding-guidelines.md b/contributors/code/coding-guidelines.md
new file mode 100644
index 0000000..bef0346
--- /dev/null
+++ b/contributors/code/coding-guidelines.md
@@ -0,0 +1,766 @@
+### 记录 React 组件文档
+
+在可能的情况下，所有组件都应实现为[函数式组件](https://react.dev/learn/your-first-component)，并使用[钩子](https://react.dev/reference/react/hooks)来管理组件的生命周期和状态。
+
+记录函数式组件的方式应与记录其他函数相同。在记录组件时需要注意的主要问题是，该函数通常只接受一个参数（即“props”），该参数可能包含多个属性成员。使用[参数属性的点语法](https://jsdoc.app/tags-param.html#parameters-with-properties)来记录各个属性的类型。
+
+````js
+/**
+ * 将区块配置的标题渲染为字符串，如果无法确定标题则返回空值。
+ *
+ * @example
+ *
+ * ```jsx
+ *
+
+若您正在使用旧版 Jest + Puppeteer 框架，请参阅专用指南。若需从 Jest + Puppeteer 迁移测试，请查阅迁移指南。
+
+
+
+## 运行测试
+
+```bash
+# 运行所有可用测试
+npm run test:e2e
+
+# 以图形界面模式运行
+npm run test:e2e -- --headed
+
+# 在特定浏览器中运行测试（支持 `chromium`、`firefox` 或 `webkit`）
+npm run test:e2e -- --project=webkit --project=firefox
+
+# 运行单个测试文件
+npm run test:e2e -- <测试文件路径> # 例如：npm run test:e2e -- site-editor/title.spec.js
+
+# 调试模式
+npm run test:e2e -- --debug
+```
+
+若您在 Linux 环境下开发，目前需以图形界面模式测试 Webkit 浏览器。若不愿或无法使用图形界面运行（例如无图形界面环境），可在命令前添加 [`xvfb-run`](https://manpages.ubuntu.com/manpages/xenial/man1/xvfb-run.1.html) 在虚拟环境中运行：
+
+```bash
+# 运行所有可用测试
+xvfb-run npm run test:e2e
+
+# 仅运行 webkit 测试
+xvfb-run -- npm run test:e2e -- --project=webkit
+```
+
+若您正在使用 VS Code 进行编辑，可安装 [Playwright 扩展插件](https://playwright.dev/docs/getting-started-vscode)来辅助运行、编写和调试测试。
+
+## 最佳实践
+
+请阅读 Playwright 的[最佳实践指南](https://playwright.dev/docs/best-practices)。
+
+### 禁止使用 `$`，改用 `locator`
+
+实际上，任何返回 `ElementHandle` 的 API 均[不推荐使用](https://playwright.dev/docs/api/class-page#page-query-selector)，包括 `$`、`$$`、`$eval`、`$$eval` 等。[`Locator`](https://playwright.dev/docs/api/class-locator) 是更优秀的 API，可与 Playwright 的[断言功能](https://playwright.dev/docs/api/class-locatorassertions)配合使用。由于定位器采用惰性求值且不返回 Promise，该特性在页面对象模型中表现尤为出色。
+
+### 使用可访问性选择器
+
+尽可能使用 [`getByRole`](https://playwright.dev/docs/locators#locate-by-role) 构建查询。这样既能编写无障碍查询，又无需依赖内部实现细节：
+
+```js
+// 选择包含无障碍名称"Hello World"的按钮（不区分大小写）
+page.getByRole( 'button', { name: 'Hello World' } );
+```
+
+还支持链式调用以执行复杂查询：
+
+```js
+// 在"区块库"区域下选择名称为"按钮"的选项
+page.getByRole( 'region', { name: 'Block Library' } )
+ .getByRole( 'option', { name: 'Buttons' } )
+```
+
+更多使用技巧请参阅[官方文档](https://playwright.dev/docs/locators)。
+
+### 选择器默认采用严格模式
+
+为提升元素查询的最佳实践，选择器默认启用[严格模式](https://playwright.dev/docs/api/class-browser#browser-new-page-option-strict-selectors)，当查询结果包含多个元素时将抛出错误。
+
+### 避免过度封装测试工具，简单工具应内联实现
+
+`e2e-test-utils` 因包含过多工具函数而变得臃肿。其中大部分函数足够简单，可直接在测试中内联实现。借助可访问性选择器，现在编写简单工具函数更加容易。对于特定页面的工具函数，建议采用页面对象模型（但使用 `requestUtils` 清理状态的情况除外，这类工具更适合放在 `e2e-test-utils` 中）。仅当操作足够复杂且需要重复使用时，才考虑创建工具函数。
+
+### 优先采用页面对象模型而非工具函数
+
+如前所述，[页面对象模型](https://playwright.dev/docs/pom)是在特定页面创建可复用工具函数的首选方案。
+
+使用页面对象模型的核心优势在于能将工具函数按命名空间分组，更便于发现和使用。实际上，`e2e-test-utils-playwright` 包中的 `PageUtils` 本身就是页面对象模型，既避免了全局变量的使用，又支持通过 `this` 实现工具函数间的相互调用。
+
+### 通过 REST 接口清理或设置状态
+
+在测试前后手动设置状态效率低下，特别是在测试间需要重复设置时。推荐通过 API 调用来设置状态。请使用 `requestUtils.rest` 和 `requestUtils.batchRest` 调用 [REST API](https://developer.wordpress.org/rest-api/reference/)（如有需要可将其添加到 `requestUtils` 中）。我们仍需为手动设置状态编写测试，但此类测试只需编写一次。
+
+### 避免使用全局变量
+
+在之前的 Jest + Puppeteer 端到端测试中，`page` 和 `browser` 被暴露为全局变量。当同一测试中涉及多个页面/标签页，或需要并行运行多个测试时，这种方式会使工作变得困难。`@playwright/test` 引入了[测试固件](https://playwright.dev/docs/test-fixtures)概念，允许我们将 `page`、`browser` 及其他参数注入到测试中。
+
+### 使用显式断言
+
+单个测试中可根据需要插入多个断言。尽可能使用显式断言是更佳实践。例如，若需在点击按钮前确认其存在，可在执行 `locator.click()` 前使用 `expect( locator ).toBeVisible()`。这样能使测试流程更清晰易读。
+
+## 常见误区
+
+### [过度使用快照](https://github.com/WordPress/gutenberg/tree/HEAD/docs/contributors/code/e2e/overusing-snapshots.md)
+
+## 跨浏览器测试
+
+默认情况下测试仅在 Chromium 中运行。您可以通过给测试添加标签来指定运行浏览器。在测试标题任意位置使用 `@browser` 即可在对应浏览器中运行测试。默认情况下测试始终会在 Chromium 中运行，可通过添加 `-chromium` 后缀禁用 Chromium 测试。支持的浏览器包括 `chromium`、`firefox` 和 `webkit`。
+
+```js
+test( '我将在 @firefox 和 @webkit 中运行（默认包含 chromium）', async ( { page } ) => {
+ // ...
+} );
+
+test( '我仅在 @firefox 中运行（排除 -chromium）', async ( { page } ) => {
+ // ...
+} );
+
+test.describe( '测试分组 (@webkit, -chromium)', () => {
+ test( '我仅在 webkit 中运行', async ( { page } ) => {
+ // ...
+ } );
+} );
+```
\ No newline at end of file
diff --git a/contributors/code/e2e/migration.md b/contributors/code/e2e/migration.md
new file mode 100644
index 0000000..168d4d3
--- /dev/null
+++ b/contributors/code/e2e/migration.md
@@ -0,0 +1,37 @@
+# 迁移指南
+
+本文档概述了将 Jest + Puppeteer 测试迁移至 Playwright 的典型流程。请注意，迁移过程也是重构或重写部分测试的良好契机。开始迁移前，请先阅读[最佳实践](https://github.com/WordPress/gutenberg/tree/HEAD/docs/contributors/code/e2e/README.md#best-practices)指南。
+
+## 测试迁移步骤
+
+1. 在 `packages/e2e-tests/specs` 中选择要迁移的测试套件，将 `.test.js` 重命名为 `.spec.js`，并置于 `test/e2e/specs` 内的相同文件夹结构中。
+2. 从 `@wordpress/e2e-test-utils-playwright` 引入测试辅助工具：
+ ```js
+ const { test, expect } = require( '@wordpress/e2e-test-utils-playwright' );
+ ```
+3. 将所有出现的 `describe`、`beforeAll`、`beforeEach`、`afterEach` 和 `afterAll` 加上 `test.` 前缀。例如，`describe` 变为 `test.describe`。
+4. 使用[夹具 API](https://playwright.dev/docs/test-fixtures) 引入之前全局的变量，如 `page` 和 `browser`。
+5. 删除所有对 `e2e-test-utils` 的导入。改为使用夹具 API 直接获取 `admin`、`editor`、`pageUtils` 和 `requestUtils`。（注意：`admin`、`editor` 和 `pageUtils` 不能在 `beforeAll` 和 `afterAll` 中使用，需改用 `requestUtils` 重写。）
+6. 如果缺少某个工具函数，且步骤较少，可尝试直接在测试中内联实现操作。如果认为有必要作为测试工具函数实现，请参考以下[指南](#测试工具函数迁移步骤)。
+7. 根据推荐的[最佳实践](https://github.com/WordPress/gutenberg/tree/HEAD/docs/contributors/code/e2e/README.md#best-practices)手动迁移测试中的其他细节。请注意，尽管 Playwright 和 Puppeteer 的 API 差异较小，但仍需进行一些手动调整。
+
+## 测试工具函数迁移步骤
+
+在迁移测试工具函数前，请仔细考虑是否必要。Playwright 提供了许多易读且强大的 API，使得许多工具函数不再需要。可先尝试在测试中直接内联实现相同功能。仅当此方法不适用时，再参考以下指南。适合在 `e2e-test-utils-playwright` 包中实现的工具函数示例包括复杂的浏览器 API（如 `pageUtils.dragFiles` 和 `pageUtils.pressKeys`）以及状态设置 API（如 `requestUtils.*`）。
+
+
+
+
+Playwright 工具函数的组织方式与 `e2e-test-utils` 包略有不同。`e2e-test-utils-playwright` 包将工具函数分为以下文件夹：
+- `admin` - 与 WordPress 后台或 WordPress 后台用户界面相关的工具函数（例如 `visitAdminPage`）。
+- `editor` - 用于块编辑器的工具函数（例如 `clickBlockToolbarButton`）。
+- `pageUtils` - 用于与浏览器交互的通用工具函数（例如 `pressKeys`）。
+- `requestUtils` - 用于发起 REST API 请求的工具函数（例如 `activatePlugin`）。这些工具函数用于测试的初始化和清理。
+
+1. 复制 `e2e-test-utils` 中的现有文件，根据工具函数类型粘贴到 `e2e-test-utils-playwright` 的 `admin`、`editor`、`page` 或 `request` 文件夹中。
+2. 更新工具函数中需要重写的部分：
+ - `page` 和 `browser` 变量在 `admin`、`editor` 和 `pageUtils` 中可通过 `this.page` 和 `this.browser` 访问。
+ - 同一类中的所有其他工具函数可通过 `this` 访问，并绑定到同一实例。可移除所有 `import` 语句，改用 `this` 访问。
+ - 如果熟悉 TypeScript，可考虑将工具函数更新为 TypeScript 版本。
+3. 在 `index.ts` 中导入新迁移的工具函数，并将其作为实例字段放入 `Admin`/`Editor`/`PageUtils`/`RequestUtils` 类中。
\ No newline at end of file
diff --git a/contributors/code/e2e/overusing-snapshots.md b/contributors/code/e2e/overusing-snapshots.md
new file mode 100644
index 0000000..4c6afea
--- /dev/null
+++ b/contributors/code/e2e/overusing-snapshots.md
@@ -0,0 +1,125 @@
+# 过度使用快照测试
+
+看看下面的代码。你第一眼能理解这个测试想要做什么吗？
+
+```js
+await editor.insertBlock( { name: 'core/quote' } );
+await page.keyboard.type( '1' );
+await page.keyboard.press( 'Enter' );
+await page.keyboard.press( 'Enter' );
+
+expect( await editor.getEditedPostContent() ).toMatchSnapshot();
+
+await page.keyboard.press( 'Backspace' );
+await page.keyboard.type( '2' );
+
+expect( await editor.getEditedPostContent() ).toMatchSnapshot();
+```
+
+这段代码改编自Gutenberg项目中的真实代码，移除了测试标题和注释，并重构为Playwright版本。理想情况下，端到端测试应该具备自文档化和最终用户可读性；毕竟它们试图模拟最终用户与应用程序的交互方式。然而，这段代码中存在几个值得警惕的问题。
+
+## 快照测试存在的问题
+
+由Jest推广的[快照测试](https://jestjs.io/docs/snapshot-testing)在恰当使用时是个很好的工具。但可能因为它功能强大，开发者经常过度使用。已有许多[文章](https://kentcdodds.com/blog/effective-snapshot-testing)讨论过这个问题。在这个具体案例中，快照测试未能清晰体现开发者的意图。如果不查看其他信息，我们无法明确断言的具体内容。这使得代码难以理解，给除原作者外的所有读者增加了认知负担。作为读者，我们不得不反复查看代码才能完全理解它们。增加的代码复杂性阻碍了贡献者根据需求修改测试的意愿。有时甚至会让原作者感到困惑，导致意外[提交错误的快照](https://github.com/WordPress/gutenberg/pull/42780#discussion_r949865612)。
+
+以下是包含测试标题和注释的同一测试。现在你明白这些断言的实际含义了：
+
+```js
+it( '可以在末尾拆分', async () => {
+ // ...
+
+ // 期望在引用块外有空段落
+ expect( await getEditedPostContent() ).toMatchSnapshot();
+
+ // ...
+
+ // 期望段落被合并到引用块中
+ expect( await getEditedPostContent() ).toMatchSnapshot();
+} );
+```
+
+开发者的意图现在稍微清晰了些，但仍感觉与测试本身脱节。你可能会想尝试[内联快照](https://jestjs.io/docs/snapshot-testing#inline-snapshots)，这确实解决了需要在文件间跳转的问题，但它们仍然不具备自文档化特性也不够明确。我们可以做得更好。
+
+## 解决方案
+
+与其在注释中写断言说明，不如尝试直接明确地写出来。借助`editor.getBlocks`方法，我们可以将其重写为更简单和原子化的断言：
+
+```js
+// ...
+
+// 期望在引用块外有空段落
+await expect.poll( editor.getBlocks ).toMatchObject( [
+ {
+ name: 'core/quote',
+ innerBlocks: [
+ {
+ name: 'core/paragraph',
+ attributes: { content: '1' },
+ },
+ ],
+ },
+ {
+ name: 'core/paragraph',
+ attributes: { content: '' },
+ }
+] );
+
+// ...
+
+// 期望段落被合并到引用块中
+await expect.poll( editor.getBlocks ).toMatchObject( [ {
+ name: 'core/quote',
+ innerBlocks: [
+ {
+ name: 'core/paragraph',
+ attributes: { content: '1' },
+ },
+ {
+ name: 'core/paragraph',
+ attributes: { content: '2' },
+ },
+ ],
+} ] );
+```
+
+这些断言更加可读和明确。你可以添加额外的断言或将现有断言拆分成多个，以突出它们的重要性。是否保留注释取决于你，但当代码本身已经足够可读时，通常可以省略注释。
+
+## 快照测试的变体
+
+由于Playwright缺乏内联快照功能，一些迁移的测试使用字符串断言（`toBe`）来模拟类似效果，避免创建大量快照文件：
+
+```js
+expect( await editor.getEditedPostContent() ).toBe( `
+e2e-test-utils-playwright 包并非旨在完全替代 Jest + Puppeteer 的 e2e-test-utils 包。部分工具函数仅为简化迁移过程而创建，并非必需。
+段落
+` ); +``` + +我们可以将这种模式视为快照测试的变体，在编写时应遵循相同的规则。通常最好使用`editor.getBlocks`或其他方法重写它们，以进行明确断言： + +```js +await expect.poll( editor.getBlocks ).toMatchObject( [ { + name: 'core/paragraph', + attributes: { content: '段落' }, +} ] ); +``` + +## 测试覆盖率怎么办？ + +将明确断言与快照测试比较，我们确实在这个测试中损失了一些测试覆盖率。当我们需要断言块的完整序列化内容时，快照测试仍然有用。但幸运的是，集成测试中的一些测试已经对每个核心块的[完整内容](https://github.com/WordPress/gutenberg/blob/trunk/test/integration/fixtures/blocks/README.md)进行了断言。这些测试在Node.js中运行，比在Playwright中重复相同测试要快得多。在我的机器上运行273个测试用例仅需约5.7秒。这类测试在单元或集成级别效果很好，我们可以在不损失测试覆盖率的情况下更快地运行它们。 + +## 最佳实践 + +在端到端测试中很少需要快照测试，通常有更好的替代方案可以利用明确断言。在确实没有其他合适替代方案时，我们应遵循使用快照测试的最佳实践。 + +### 避免巨大的快照 + +巨大的快照难以阅读和审查。而且，当所有内容都重要时，实际上没有任何内容是重要的。巨大的快照会阻碍我们关注快照的重要部分。 + +### 避免重复的快照 + +如果你发现在同一个测试中创建了多个相似内容的快照，这可能表明你应该进行更原子化的断言。重新思考你想要测试什么，如果第一个快照只是第二个的参考，那么你真正需要的是快照之间的**差异**。将第一个结果存储在变量中，然后断言结果之间的差异。 + +## 延伸阅读 + +- [有效的快照测试 - Kent C. Dodds](https://kentcdodds.com/blog/effective-snapshot-testing) +- [常见测试错误 - Kent C. Dodds](https://kentcdodds.com/blog/common-testing-mistakes) \ No newline at end of file diff --git a/contributors/code/getting-started-with-code-contribution.md b/contributors/code/getting-started-with-code-contribution.md new file mode 100644 index 0000000..32f1c3a --- /dev/null +++ b/contributors/code/getting-started-with-code-contribution.md @@ -0,0 +1,254 @@ +# 代码贡献入门指南 + +以下指南将帮助您设置本地环境，以便为 Gutenberg 项目做出贡献。用于贡献代码的环境与用于扩展 WordPress 区块编辑器的环境存在显著重叠。您可以查阅[开发环境教程](/docs/getting-started/devenv/README.md)获取更多设置信息。 + +## 环境要求 + +- Node.js + Gutenberg 是一个 JavaScript 项目，需要安装 [Node.js](https://nodejs.org/)。项目目前基于 Node.js v20 和 npm v10 构建。虽然我们尽力使用 Node.js 的 Active LTS 版本，但并非总能实现。更多详细信息请参考 [Node.js 发布计划](https://github.com/nodejs/Release#release-schedule)。 + +我们推荐使用 [Node Version Manager](https://github.com/nvm-sh/nvm) (nvm)，这是在 macOS、Linux 和 Windows 10（使用 WSL2）上安装和管理 Node.js 的最简单方式。如需更多安装说明，请参阅[我们的开发工具指南](/docs/getting-started/devenv/README.md#development-tools)或 Node.js 官网。 + +- Git + Gutenberg 使用 git 进行版本控制。请确保您的计算机上安装了最新版本的 git，并拥有 GitHub 账户。您可以阅读 [Git 工作流程](/docs/contributors/code/git-workflow.md)了解如何在 Gutenberg 中使用 git 和 GitHub。 + +- [推荐] Docker Desktop + 我们推荐使用 [wp-env 包](/packages/env/README.md)在本地设置 WordPress 环境。使用 `wp-env` 需要安装 Docker。更多详细信息请参阅[开发环境教程](/docs/getting-started/devenv/README.md)。 + > 注意：若要在 Windows 10 家庭版上安装 Docker，请按照 [Docker for Windows with WSL2 的安装说明](https://docs.docker.com/docker-for-windows/wsl/)操作。 + +作为 Docker 设置的替代方案，您可以使用 [Local](https://localwp.com/)、[WampServer](https://wampserver.aviatechno.net/) 或 [MAMP](https://www.mamp.info/)，甚至可以使用远程服务器。 + +- GitHub CLI + 虽然不是必需，但 [GitHub CLI](https://cli.github.com/) 能极大帮助您在本地检出拉取请求，包括来自 Gutenberg 主仓库和分叉仓库的请求。这在代码审查和测试拉取请求时能显著节省时间。 + +## 获取 Gutenberg 代码 + +请先 Fork Gutenberg 仓库，然后克隆到您的计算机，并将 WordPress 仓库添加为上游源。 + +```bash +$ git clone https://github.com/您的GitHub用户名/gutenberg.git +$ cd gutenberg +$ git remote add upstream https://github.com/WordPress/gutenberg.git +``` + +## 将 Gutenberg 构建为插件 + +安装 Gutenberg 依赖项并以开发模式构建代码： + +```bash +npm install +npm run dev +``` + +> 注意：安装脚本要求系统已安装 [Python](https://www.python.org/) 并配置在环境变量中。根据操作系统的不同，Python 可能已默认安装或需要手动下载安装。 + +有两种构建代码的方式。在开发过程中，您可能希望使用 `npm run dev` 在源文件更改时自动持续构建。开发构建还包含额外的警告和错误信息，便于开发过程中进行故障排除。完成更改后，可以运行 `npm run build` 创建优化的生产构建。 + +构建完成后，Gutenberg 即可作为 WordPress 插件使用！ + +## 本地 WordPress 环境 + +要测试 WordPress 插件，您需要先安装 WordPress 本体。如果您已设置好 WordPress 本地环境，只需将 gutenberg 目录放入 wp-content/plugins/ 目录即可将构建好的 Gutenberg 作为标准 WordPress 插件使用。 + +如果尚未设置本地 WordPress 环境，请按照本节剩余步骤创建环境。 + +## 开发者工具 + +我们建议将编辑器配置为自动检查语法和代码规范错误。这能帮助您在开发过程中自动修复细微的格式问题，从而节省时间。以下是为 Visual Studio Code（许多核心开发者常用的编辑器）的设置指南，这些工具也适用于其他编辑器。 + +### EditorConfig + +[EditorConfig](https://editorconfig.org/) 定义了编辑器的标准配置，例如使用制表符代替空格。您应安装 [VS Code 的 EditorConfig 扩展](https://marketplace.visualstudio.com/items?itemName=editorconfig.editorconfig)，它将自动配置您的编辑器以符合 [.editorconfig](https://github.com/WordPress/gutenberg/blob/HEAD/.editorconfig) 中定义的规则。 + +### ESLint + +[ESLint](https://eslint.org/) 通过静态分析代码来发现问题。代码规范检查规则已集成到持续集成流程中，必须通过检查才能提交代码。您应为 Visual Studio Code 安装 [ESLint 扩展](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)，其他编辑器的集成方案请参阅 [eslint 文档](https://eslint.org/docs/user-guide/integrations)。 + +安装扩展后，ESLint 将使用 Gutenberg 代码库根目录中的 [.eslintrc.js](https://github.com/WordPress/gutenberg/blob/HEAD/.eslintrc.js) 文件作为格式规则。它会在开发时高亮显示问题，您还可以通过以下设置实现在保存时自动修复规范问题： + +```json + "editor.codeActionsOnSave": { + "source.fixAll.eslint": "explicit" + }, +``` + +### Prettier + +[Prettier](https://prettier.io/) 是一款能够定义规范化格式并自动修复代码以匹配该格式的工具。Prettier 与 ESLint 功能相似，但 Prettier 更侧重于格式和样式，而 ESLint 主要用于检测编码错误。 + +若要在 Visual Studio Code 中使用 Prettier，请安装 [Prettier 代码格式化扩展](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)。随后可通过在设置中添加以下配置，将其设为默认格式化工具并实现保存时自动修复问题： +**_注意_：根据文档查看环境的不同，方括号可能显示为双括号，实际正确格式应为单层方括号。** + +```json +"[javascript]": { + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.formatOnSave": true +}, +"[markdown]": { + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.formatOnSave": true +}, +``` + +此配置将使用 Gutenberg 代码库根目录中的 `.prettierrc.js` 文件，该配置继承自 [@wordpress/prettier-config](/packages/prettier-config/README.md) 包。 + +如果仅希望在 Gutenberg 项目中使用此配置，请在项目根目录创建 `.vscode` 文件夹，并将设置存入其中的 `settings.json` 文件。Visual Studio Code 将其称为工作区设置，且仅适用于当前项目。 + +其他编辑器的配置请参阅 [Prettier 编辑器集成文档](https://prettier.io/docs/en/editors.html)。 + +### TypeScript + +**TypeScript** 是 JavaScript 语言的类型化超集。Gutenberg 项目通过 JSDoc 使用 TypeScript 来实现 [JavaScript 文件的类型检查](https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html)。如果您使用 Visual Studio Code，其已内置 TypeScript 支持，其他编辑器的集成方案请参阅 [TypeScript 编辑器支持](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support)。 + +### 使用 Docker 与 wp-env + +[wp-env 工具包](/packages/env/README.md)最初为古腾堡项目开发，旨在通过 Docker 快速创建标准 WordPress 环境。该工具已作为 `@wordpress/env` npm 包发布。 + +默认情况下，在插件目录中运行 `wp-env` 即可创建并启动 WordPress 环境，同时自动挂载并激活对应插件。您还可以配置 `wp-env` 以使用现有安装、多插件或主题。完整文档请参阅 [wp-env 工具包](/packages/env/README.md#wp-envjson)。 + +确保 Docker 处于运行状态，在古腾堡目录中执行以下命令启动 `wp-env`： + +```bash +npm run wp-env start +``` + +该脚本将在后台创建基于最新 WordPress Docker 镜像的实例，并将本地古腾堡插件代码通过 Docker 卷映射到环境中。这样您在本地对代码的任何修改都会即时同步到 WordPress 实例中。 + +> 注意：`npm run` 将使用古腾堡项目内指定的 `wp-env` / `WordPress`?? 版本，确保您运行的是最新的 wp-env 版本。 + +停止运行环境： + +```bash +npm run wp-env stop +``` + +若一切正常，终端将显示如下信息： + +```bash +WordPress 开发站点已启动：http://localhost:8888/ +WordPress 测试站点已启动：http://localhost:8889/ +MySQL 正在监听端口 51220 + + ✔ 完成！（耗时 261 秒 898 毫秒） +``` + +通过右键点击菜单栏（Mac）或系统托盘（Linux/Windows）中的 Docker 图标并选择「控制台」，您将看到脚本已下载若干 Docker 镜像，并正在运行包含完整 WordPress 环境的容器： + + + +彻底删除安装环境： + +```bash +npm run wp-env destroy +``` + +更多命令请查阅[工具包文档](/packages/env/README.md)。 + +#### 访问本地 WordPress 安装 + +WordPress 安装现已可通过 `http://localhost:8888` 访问 + +管理后台地址：`http://localhost:8888/wp-admin/`，登录凭据为：**用户名**：`admin`，**密码**：`password`。您会注意到古腾堡插件已安装并激活，这正是您的本地构建版本。 + +#### 访问 MySQL 数据库 + +古腾堡项目默认集成 phpMyAdmin。您可通过以下地址访问 MySQL 数据库：`http://localhost:9000/`。 + +若需通过其他工具访问数据库，请先获取连接信息： + +1. 在终端中进入本地古腾堡代码库目录 +2. 运行 `npm run wp-env start` - 终端将输出 `wp-env` 环境的相关信息 +3. 在输出信息中查找 _MySQL_ 端口号： + 例如： + +> MySQL 正在监听端口 {MYSQL端口号} + +4. 复制/记录该端口号（注意此端口号会在每次 `wp-env` 重启时变更） +5. 使用以下信息连接 MySQL 实例（请将 `{MYSQL端口号}` 替换为第三步获取的端口号）： + +``` +主机：127.0.0.1 +用户名：root +密码：password +数据库：wordpress +端口：{MYSQL端口号} +``` + +**请注意**：MySQL 端口号会在每次 `wp-env` 重启时变更。若发现无法访问数据库，请重复上述步骤获取新端口号以恢复连接。 + +**技巧**：[Sequel Ace](https://sequel-ace.com/) 是访问 MySQL 数据库的实用图形化工具。其他工具及其使用方式可参阅 [WordPress 数据库访问指南](https://developer.wordpress.org/advanced-administration/before-install/creating-database/)。 + +#### 故障排除 + +若遇到问题，请查阅 [`wp-env` 文档中的故障排除章节](/packages/env/README.md#troubleshooting-common-problems)。 + +### 使用 Local 或 MAMP + +作为 Docker 和 `wp-env` 的替代方案，您也可以使用 [Local](https://localwp.com/)、[WampServer](https://wampserver.aviatechno.net/) 或 [MAMP](https://www.mamp.info/) 来运行本地 WordPress 环境。为此，请通过创建符号链接或将目录复制到相应的 `wp-content/plugins` 目录中，将 Gutenberg 作为常规插件克隆并安装到您的环境中。 + +您还需要进行一些额外配置才能运行端到端测试。 + +将当前目录切换到插件文件夹，并为所有端到端测试插件创建符号链接： + +```bash +ln -s gutenberg/packages/e2e-tests/plugins/* . +``` + +如果添加了新插件，您需要再次运行此命令。运行端到端测试的命令如下： + +```bash +WP_BASE_URL=http://localhost:8888/gutenberg/ npm run test:e2e +``` + +#### PHP 文件缓存 + +您需要禁用 OPCache 才能正确编辑 PHP 文件。修复方法如下： + +- 转到 **MAMP > 首选项 > PHP** +- 在 **缓存** 下选择 **关闭** +- 点击 **确定** 确认 + +#### 传入连接 + +默认情况下，MAMP 启动的 Web 服务器（Apache）会监听所有传入连接，而不仅仅是本地连接。这意味着同一本地网络上的任何人（在某些情况下，甚至是互联网上的任何人）都可以访问您的 Web 服务器。这可能是故意的，对于在其他设备上测试站点很有用，但大多数情况下这可能会引发隐私或安全问题。请记住这一点，不要在此服务器上存储敏感信息。 + +虽然可以修复此问题，但您需要自行承担风险，因为它会破坏 MAMP 解析 Web 服务器配置的能力，从而导致 MAMP 认为 Apache 正在监听错误的端口。建议考虑改用其他工具替代 MAMP。否则，您可以按照以下步骤操作： + +- 编辑 `/Applications/MAMP/conf/apache/httpd.conf` +- 将 `Listen 8888` 改为 `Listen 127.0.0.1:8888` + +#### 链接到其他目录 + +您可能希望在 `plugins` 和 `themes` 目录中创建指向其他文件夹的链接，例如： + +- wp-content/plugins/gutenberg -> ~/projects/gutenberg +- wp-content/themes/twentytwenty -> ~/projects/twentytwenty + +如果是这样，您需要配置 Apache 以允许跟随此类链接： + +- 打开或新建文件 `/Applications/MAMP/htdocs/.htaccess` +- 添加以下行：`Options +SymLinksIfOwnerMatch` + +#### 使用 WP-CLI + +像 MAMP 这样的工具倾向于将 MySQL 配置为使用非默认端口 3306，通常偏好使用 8889。这可能会影响 WP-CLI，使其在尝试连接数据库后失败。要解决此问题，请编辑 `wp-config.php` 并将 `DB_HOST` 常量从 `define( 'DB_HOST', 'localhost' )` 改为 `define( 'DB_HOST', '127.0.0.1:8889' )`。 + +### 在远程服务器上 + +您可以通过在本地构建然后将构建的文件作为插件上传到远程服务器，在开发中使用远程服务器。 + +构建步骤：打开终端（如果在 Windows 上，则打开命令提示符）并导航到您克隆的代码库。输入 `npm ci` 以设置所有依赖项。完成后，输入 `npm run build`。 + +构建完成后，克隆的 Gutenberg 目录包含完整的插件，您可以将整个代码库上传到 `wp-content/plugins` 目录，并在 WordPress 管理后台激活插件。 + +另一种构建后上传的方法是运行 `npm run build:plugin-zip` 来创建插件压缩文件——这需要 `bash` 和 `php` 环境。该脚本会创建 `gutenberg.zip`，您可以通过 WordPress 管理后台安装 Gutenberg。 + +## Storybook + +> Storybook 是一个开源工具，用于独立开发 React、React Native 等的 UI 组件。它使构建出色的 UI 变得有条理且高效。 + +Gutenberg 代码库还集成了 [Storybook](https://storybook.js.org/)，允许在与 WordPress 无关的环境中进行测试和开发。这对于开发可复用组件和尝试通用 JavaScript 模块非常有帮助，无需任何后端依赖。 + +您可以通过本地运行 `npm run storybook:dev` 启动 Storybook。它会自动在浏览器中打开。 + +您还可以在 GitHub Pages 上测试当前 `trunk` 分支的 Storybook：[https://wordpress.github.io/gutenberg/](https://wordpress.github.io/gutenberg/) \ No newline at end of file diff --git a/contributors/code/git-workflow.md b/contributors/code/git-workflow.md new file mode 100644 index 0000000..a93b3e7 --- /dev/null +++ b/contributors/code/git-workflow.md @@ -0,0 +1,155 @@ +## 分支命名规范 + +命名分支时应使用前缀+简短描述的形式，例如：`[类型]/[变更内容]` + +推荐使用的前缀： + +- `add/` = 新增功能 +- `try/` = 实验性功能（暂定添加） +- `update/` = 更新现有功能 +- `remove/` = 移除现有功能 +- `fix/` = 修复现存问题 + +例如：`add/gallery-block` 表示您正在开发新增画廊区块功能 + +## 保持分支同步 + +当多人同时参与项目开发时，拉取请求很容易过时。"过时"的拉取请求是指与主干开发进度脱节的分支，在合并前需要重新同步。 + +同步方式有两种：合并与变基。在Gutenberg项目中推荐使用变基操作。变基会将您的修改重写为基于开发主线的增量提交，从而确保提交历史的整洁与线性。在处理拉取请求期间，您可以随时执行变基操作。**请尽早开启拉取请求**并持续保持提交历史的变基状态。 + +开发主线即 `trunk` 分支。当拉取请求分支因冲突无法合并至主干时（长期存续的拉取请求常出现此情况），您需要在变基过程中手动解决本地副本的冲突。具体操作请参阅《如何对拉取请求执行变基》中的[「执行变基」章节](https://github.com/edx/edx-platform/wiki/How-to-Rebase-a-Pull-Request#perform-a-rebase)。 + +本地解决冲突后，可通过 `git push --force-with-lease` 更新拉取请求。使用 `--force-with-lease` 参数至关重要，它能有效避免意外覆盖他人代码。 + +同步流程可总结为：获取仓库更新 → 基于trunk执行变基 → 推送至远程仓库。具体命令如下： + +```sh +git fetch +git rebase trunk +git push --force-with-lease origin 您的分支名称 +``` + +## 维护派生仓库同步 + +参与拉取请求需先派生Gutenberg仓库作为独立工作副本。随着新代码不断并入主仓库，您的派生仓库容易失去同步。这里您的工作仓库称为 `fork`，主Gutenberg仓库称为 `upstream`。在创建新分支 (`git checkout -b my-new-branch`) 进行功能开发前，请务必先更新派生仓库。 + +需配置 upstream 远程仓库以保持同步： + +```sh +git remote add upstream https://github.com/WordPress/gutenberg.git +git remote -v +origin git@github.com:您的账户/gutenberg.git (fetch) +origin git@github.com:您的账户/gutenberg.git (push) +upstream https://github.com/WordPress/gutenberg.git (fetch) +upstream https://github.com/WordPress/gutenberg.git (push) +``` + +同步派生仓库需先获取上游更新并合并至本地： + +```sh +git fetch upstream +git checkout trunk +git merge upstream/trunk +``` + +本地更新完成后，推送至GitHub完成派生仓库更新： + +```sh +git push +``` + +上述命令将更新您的 `trunk` 分支与上游同步。如需更新其他分支，将 `trunk` 替换为对应分支名即可。 + +## 扩展应用 + +### 提交追溯 + +当需要定位引入特定修改的提交时，忽略仅含样式或格式修改的提交会提升效率。 + +新版 `git` 支持在历史记录中跳过指定提交： + +```sh +git blame --ignore-rev f63053cace3c02e284f00918e1854284c85b9132 -L 66,73 packages/api-fetch/src/middlewares/media-upload.js +``` + +Gutenberg仓库通过 `.git-blame-ignore-revs` 文件记录所有样式与格式修订。使用该文件可一次性忽略所有相关提交： + +```sh +git blame --ignore-revs-file .git-blame-ignore-revs -L 66,73 packages/api-fetch/src/middlewares/media-upload.js +``` + +# Git 工作流程 + +本文档旨在帮助您开始使用 Git 与 Gutenberg 进行协作。Git 是一款强大的源代码管理工具；若要深入学习 Git，请查阅基于 CC BY-NC-SA 3.0 许可证免费在线提供的 [Pro Git 书籍](https://git-scm.com/book/zh/v2)。 + +如果您不熟悉 Git 的使用，值得探索和实践。请尝试 [Git 教程](https://git-scm.com/docs/gittutorial) 以及 [Git 用户手册](https://git-scm.com/docs/user-manual) 来帮助入门。 + +Gutenberg 项目遵循标准的拉取请求流程进行贡献。有关拉取请求的更多详细信息，请参阅 GitHub 的[相关文档](https://docs.github.com/zh/github/collaborating-with-issues-and-pull-requests)。 + +## 概述 + +贡献者的流程概述如下： + +- 复刻（Fork）Gutenberg 代码库。 +- 克隆复刻后的代码库。 +- 创建新分支。 +- 进行代码更改。 +- 确认测试通过。 +- 在新创建的分支中提交代码更改。 +- 将分支推送到复刻的代码库。 +- 向 Gutenberg 代码库提交拉取请求。 + +有关 Gutenberg 项目如何使用 GitHub 的更多信息，请参阅[代码库管理文档](/docs/contributors/repository-management.md)。 + +## Git 工作流程详解 + +代码和文档的工作流程是相同的，因为两者都在 GitHub 中进行管理。您可以观看[贡献文档的视频详解](https://wordpress.tv/2020/09/02/marcus-kazmierczak-contribute-developer-documentation-to-gutenberg/)以及相应的[贡献给 Gutenberg 的教程](https://mkaz.blog/wordpress/contribute-developer-documentation-to-gutenberg/)。 + +以下是 Git 工作流程的视觉概览： + + + +**步骤 1**：前往 GitHub 上的 Gutenberg 代码库，点击 Fork。这将在您的账户下创建主 Gutenberg 代码库的副本。 + + + +**步骤 2**：在本地克隆您复刻的代码库。其地址为：`https://github.com/您的用户名/gutenberg`。克隆操作会将所有文件复制到您的计算机上。打开终端并运行： + +```bash +git clone https://github.com/您的用户名/gutenberg +``` + +这将创建一个名为 `gutenberg` 的目录，其中包含项目的所有文件。由于需要下载 Gutenberg 项目的完整历史记录，此过程可能需要几分钟。 + +**步骤 3**：为您的更改创建一个分支（分支命名规则见下文）。在此示例中，分支名称为完整字符串：`update/my-branch` + +```bash +git switch -c update/my-branch +``` + +**步骤 4**：进行代码更改。全面构建、确认并测试您的更改。请参阅[编码指南](/docs/contributors/code/coding-guidelines.md)和[测试概述](/docs/contributors/code/testing-overview.md)以获取指导。 + +**步骤 5**：使用[良好的提交信息](https://make.wordpress.org/core/handbook/best-practices/commit-messages/)提交您的更改。这会将您的更改提交到本地的代码库副本中。 + +```bash +git commit -m "您的良好提交信息" 路径/到/文件 +``` + +**步骤 6**：将您的更改推送到 GitHub。更改将被推送到您在 GitHub 上复刻的代码库中。 + +```bash +git push -u origin update/my-branch +``` + +**步骤 7**：前往您在 GitHub 上复刻的代码库——它将自动检测到更改，并为您提供创建拉取请求的链接。 + + + +**步骤 8**：创建拉取请求。这将在 WordPress Gutenberg 代码库上创建请求，以集成来自您复刻代码库的更改。 + +**步骤 9**：关注拉取请求上的新动态。如果要求进行任何额外的更改或更新，请在本地进行更改并按照步骤 4-6 推送它们。 + +请勿为更新创建新的拉取请求；通过将更改推送到您的代码库，它将更新同一个 PR。从这个意义上说，PR 是 WordPress Gutenberg 代码库指向您副本的指针。因此，当您更新副本时，PR 也会相应更新。 + +就是这样！一旦获得批准并合并，您的更改将被纳入主代码库。🎉 \ No newline at end of file diff --git a/contributors/code/how-to-get-your-pull-request-reviewed.md b/contributors/code/how-to-get-your-pull-request-reviewed.md new file mode 100644 index 0000000..f9c36ae --- /dev/null +++ b/contributors/code/how-to-get-your-pull-request-reviewed.md @@ -0,0 +1,83 @@ +# 如何让你的拉取请求获得审阅？ + +有时我们发布了拉取请求，却无人[审阅](/docs/contributors/repository-management.md#code-review)我们的工作。该怎么办？ + +吸引审阅主要不在于代码本身——而在于让审阅过程变得轻松。 + +如果你发布的拉取请求未获得任何评论或审阅，可以尝试核心贡献者们使用的策略： + +## 创建最合理的精简PR + +审批一个2000行的PR需要数月时间且令人望而生畏。 + +审批一个50行的PR仅需数日或数小时且轻松自如。 + +大规模提交会拖慢进度。将工作拆分成小模块进行提交，才能更快合并代码、加速学习进程。 + +## 提供相关背景信息： + +请阐明： +* 你要解决什么问题？ +* 你的PR如何解决该问题？ +* 你需要什么反馈？ +* 哪些内容不在讨论范围？ +* 哪些设计不符合直觉？ +* 如何进行测试？ + +总结所有相关议题和PR。 + +这比让他人自行摸索要简单得多。 + +## 让你的PR引人注目 + +所有贡献都在争夺注意力。让你的作品脱颖而出。 + +最简单的方法？说明其重要性： + +❌ 一个获取数据的新React钩子 +✅ `useEntityRecord`：用减少90%模板代码的方式获取数据 + +然后用代码示例、可视化效果和屏幕录像证明其价值。 + +## 展示你的工作 + +在相关议题和PR中发布你的PR链接。 + +提醒相关议题的评论者、先前提交者和技术负责人关注。 + +在WordPress.org Slack的#core-editor频道中提出。获取反馈最便捷的方式是在每周[核心编辑器会议](/docs/getting-started/README.md)的[自由发言环节](https://make.wordpress.org/core/tag/core-editor-agenda/)主动发声。 + +分配相关标签、里程碑和项目（或请他人协助分配）。 + +## 审阅他人的工作 + +这是进入他人视野的最简单途径。 + +查阅相关议题评论者、先前提交者和技术负责人的PR，然后进行审阅。 + +对他们的工作不熟悉？可以： + +* 花时间理解内容 +* 提议结对编程环节 +* 跳过此项，审阅下一个PR + +## 通过清晰表述降低风险 + +风险会增加阻力——当前的批准可能在日后产生反效果。 + +清晰的阐述如同润滑剂。请明确记录： + +* 涉及哪些风险？为何要承担这些风险？ +* 为何此PR是最佳解决方案？ +* 如何将风险最小化？ +* 已尝试过哪些其他方案？ + +## 关注热点领域 + +某些PR天然比其他PR更容易获得关注。 + +请重点投入这些领域。 + +部分议题比其他议题更具时效性（例如列入下一版发布目标的议题），因此能获得更多关注。专注于这些议题将更容易吸引审阅者。 + +如何快速切入？参与WordPress路线图中的活跃项目提供协助 \ No newline at end of file diff --git a/contributors/code/managing-packages.md b/contributors/code/managing-packages.md new file mode 100644 index 0000000..911d409 --- /dev/null +++ b/contributors/code/managing-packages.md @@ -0,0 +1,7 @@ +# 包管理 + +本代码库采用 [npm 工作区](https://docs.npmjs.com/cli/v10/using-npm/workspaces)来管理 WordPress 软件包，并使用 [lerna](https://lerna.js.org/) 将这些软件包发布至 [npm](https://www.npmjs.com/)。这一机制在工作流程中设定了特定步骤，具体说明详见[软件包](https://github.com/WordPress/gutenberg/blob/HEAD/packages/README.md)文档。 + +维护数十个 npm 软件包颇具挑战——追踪变更内容尤为困难。因此我们为每个软件包配置 `CHANGELOG.md` 文件来简化发布流程。作为贡献者，当您提交涉及生产环境的代码时，请按照[维护更新日志](https://github.com/WordPress/gutenberg/blob/HEAD/packages/README.md#maintaining-changelogs)章节的说明，在前述文件中添加对应条目。 + +通过与双周发布的 Gutenberg 插件 RC1 版本保持同步，实现了 WordPress 软件包发布至 npm 的自动化流程。您可以在[Gutenberg 发布流程文档](/docs/contributors/code/release.md#packages-releases-to-npm-and-wordpress-core-updates)中了解此过程及其他发布 npm 软件包新版本的方式。 \ No newline at end of file diff --git a/contributors/code/react-native/README.md b/contributors/code/react-native/README.md new file mode 100644 index 0000000..d4c3033 --- /dev/null +++ b/contributors/code/react-native/README.md @@ -0,0 +1,35 @@ +# React Native 移动编辑器 + +Gutenberg 代码库包含了基于 [React Native](https://reactnative.dev/) 的移动端编辑器源码。 + +## 移动端注意事项 + +贡献者需确保在代码重构期间更新所有受影响的本地移动文件，因为我们目前还无法依赖自动化工具完成这一工作。例如，重命名函数或属性时也需在原生模块中同步修改，否则移动客户端将出现故障。我们已在 PR 中设置了移动端专项 CI 测试作为防护机制，但仍有诸多待完善之处。感谢您的理解与支持。❤️🙇 + +## 移动端专属文件 + +与移动端共享的代码大多位于相同的 JavaScript 模块和 SASS 样式文件中。当代码路径需要区分时，会创建 `.native.js` 或 `.native.scss` 格式的文件变体。某些情况下还可找到针对 Android (`.android.js`) 或 iOS (`.ios.js`) 的平台专属文件。 + +## 在 Android 和 iOS 上运行 Gutenberg Mobile + +如需了解如何在 Android 或 iOS 上运行 **Gutenberg Mobile 演示应用**，请参阅 [React Native 移动版 Gutenberg 入门指南](/docs/contributors/code/react-native/getting-started-react-native.md) + +此外，移动客户端通过[官方 WordPress 应用](https://wordpress.org/mobile/)进行打包和发布。虽然构建流程与移动演示应用略有不同，且目前存放在独立代码库中（[此处为移动端原生代码库](https://github.com/wordpress-mobile/gutenberg-mobile)），但其源代码直接取自本代码库及“网页”端代码路径。 + +## 持续集成中的移动端端到端测试 + +若在拉取请求中遇到 Android/iOS 测试失败，建议采取以下步骤： + +1. 重新运行失败的 GitHub Action 任务（[重新运行指南](https://docs.github.com/en/actions/configuring-and-managing-workflows/managing-a-workflow-run#viewing-your-workflow-history)）—— 多数情况下可解决测试失败问题 +2. 按照[端到端测试文档](/packages/react-native-editor/__device-tests__/README.md)中的步骤在本地运行测试，验证是否会出现相同故障 +3. 除了查看端到端测试日志外，还可从 GitHub 任务的 Artifacts 区域下载视频记录以获取更多有效信息 +4. 检查 PR 中的变更是否需要对 `.native.js` 格式的文件进行相应修改 +5. 若最终仍无法解决移动测试失败问题，欢迎通过 Slack 在 #mobile 或 #core-editor 频道联系贡献者（[免费加入](https://make.wordpress.org/chat/)） + +## 调试移动端单元测试 + +需要时可按照[移动端原生测试指南](/docs/contributors/code/react-native/integration-test-guide.md)中的说明在本地调试移动端单元测试。 + +## 国际化 (i18n) + +关于此主题的更多信息请参阅 [React Native 国际化指南](/docs/contributors/code/react-native/internationalization-guide.md)。 \ No newline at end of file diff --git a/contributors/code/react-native/getting-started-react-native.md b/contributors/code/react-native/getting-started-react-native.md new file mode 100644 index 0000000..bfaa6e0 --- /dev/null +++ b/contributors/code/react-native/getting-started-react-native.md @@ -0,0 +1,148 @@ +# React Native 版移动端 Gutenberg 入门指南 + +欢迎阅读！本文档是针对 Android 和 iOS 设备的区块编辑器原生移动端移植版的入门指南。总体而言，这是一个可在全新项目或现有项目中使用的 React Native 库。请继续阅读了解如何构建、测试和运行。 + +## 环境准备 + +为了获得与项目维护者相近的开发体验，请确保安装以下工具： + +- git +- [nvm](https://github.com/nvm-sh/nvm) +- Node.js 和 npm（使用 nvm 安装） +- [Android Studio](https://developer.android.com/studio/)（用于编译 Android 版应用） +- [Xcode](https://developer.apple.com/xcode/)（用于编译 iOS 应用） +- CocoaPods（通过 `sudo gem install cocoapods` 安装）用于获取 React 及第三方依赖 + +请注意，维护者使用的操作系统平台是 macOS，但相关工具和设置也应适用于其他平台。 + +## 克隆项目 + +```sh +git clone https://github.com/WordPress/gutenberg.git +``` + +## 环境设置 + +请注意，此处描述的命令应在克隆项目的顶层目录中运行。在运行演示应用之前，需要下载并安装项目依赖。通过以下命令完成： + +```sh +nvm install +npm ci +npm run native preios +``` + +## 运行项目 + +```sh +npm run native start:reset +``` + +该命令将在开发模式下运行打包程序（Metro）。打包程序会持续运行，向请求的客户端提供应用包。 + +在打包程序运行的同时，打开另一个终端窗口，使用以下命令编译并运行 Android 应用： + +```sh +npm run native android +``` + +此时应用应在连接的设备或运行的模拟器中打开，并从正在运行的打包程序获取 JavaScript 代码。 + +要使用默认模拟器设备编译并运行 iOS 版本的应用，请使用： + +```sh +npm run native ios +``` + +如果您使用的是 Mac 并已安装相关环境，该命令将尝试在 iOS 模拟器中打开您的应用。 + +### 在其他 iOS 设备模拟器上运行 + +要使用其他设备模拟器编译并运行应用，请使用以下命令。注意使用双 `--` 将模拟器选项传递给 `react-native` CLI： + +```sh +npm run native ios -- -- --simulator="设备名称" +``` + +例如，如果要在 iPhone Xs Max 上运行，请尝试： + +```sh +npm run native ios -- -- --simulator="iPhone Xs Max" +``` + +要查看所有可用 iOS 设备列表，请使用 `xcrun simctl list devices`。 + +### 自定义演示编辑器 + +默认情况下，演示编辑器会渲染大多数受支持的核心区块。这有助于展示编辑器的功能，但在专注于特定区块或功能时可能会分散注意力。可以通过在 `packages/react-native-editor/src/setup-local.js` 文件中使用 `native.block_editor_props` 钩子来自定义编辑器的初始状态。 + +setup-local.js 示例
+ +```js +/** + * WordPress 依赖 + */ +import { addFilter } from '@wordpress/hooks'; + +export default () => { + addFilter( + 'native.block_editor_props', + 'core/react-native-editor', + ( props ) => { + return { + ...props, + initialHtml, + }; + } + ); +}; + +const initialHtml = ` + +仅一个标题
+ +`; +``` + +
+
+## 常见陷阱与注意事项
+
+### 省略 `waitFor` 前的 `await` 会导致误判
+
+在 `waitFor` 前省略 `await` 可能导致测试通过但未验证预期行为的情况。例如，若使用 `toBeDefined` 来断言 `waitFor` 的调用结果，由于 `waitFor` 始终会返回值，断言将通过——即使该值并非我们想要检查的 `ReactTestInstance`。因此建议使用自定义匹配器 `toBeVisible`，可有效防范此类误判情况。
+
+### 使用 `find` 类查询
+
+组件渲染或事件触发后，可能因状态更新产生副作用，导致目标元素尚未渲染。此时需要等待元素可用，为此可使用查询函数的 `find*` 版本，这些函数内部采用 `waitFor` 机制周期性检测元素是否出现。
+
+示例如下：
+
+```js
+const mediaLibraryButton = await findByText( 'WordPress媒体库' );
+```
+
+```js
+const missingBlock = await findByLabelText( /不支持的块\. 第1行/ );
+```
+
+```js
+const radiusSlider = await findByTestId( '滑块圆角半径' );
+```
+
+多数情况下我们会使用 `find*` 函数，但需注意应仅限于真正需要等待元素出现的查询场景。
+
+### `within` 查询
+
+通过 `within` 函数可查询其他元素内部包含的元素，示例如下：
+
+```js
+const missingBlock = await findByLabelText( /不支持的块\. 第1行/ );
+const translatedTableTitle = within( missingBlock ).getByText( '表格' );
+```
+
+## 触发事件
+
+除了查询元素，触发事件模拟用户交互同样重要。为此可使用 `fireEvent` 函数（[文档](https://callstack.github.io/react-native-testing-library/docs/api#fireevent)）。
+
+点击事件示例：
+
+**点击事件：**
+
+```js
+fireEvent.press( settingsButton );
+```
+
+我们也可以触发任意类型事件（包括自定义事件）。以下示例展示如何触发滑块组件的 `onValueChange` 事件（[代码参考](https://github.com/WordPress/gutenberg/blob/520cbd9d2af4bbc275d388edf92a6cadb685de56/packages/components/src/mobile/bottom-sheet/range-cell.native.js#L227)）：
+
+**自定义事件 – onValueChange：**
+
+```js
+fireEvent( heightSlider, 'valueChange', '50' );
+```
+
+## 验证元素行为
+
+完成元素查询和事件触发后，需验证逻辑是否符合预期。可使用与单元测试相同的 Jest `expect` 函数，推荐使用自定义匹配器 `toBeVisible` 来确保元素已定义、属于有效React元素且可见。
+
+示例如下：
+
+```js
+const translatedTableTitle = within( missingBlock ).getByText( '表格' );
+expect( translatedTableTitle ).toBeVisible();
+```
+
+当渲染完整编辑器时，还可验证HTML输出是否符合预期：
+
+```js
+expect( getEditorHtml() ).toBe(
+ '\n\n'
+);
+```
+
+## 清理操作
+
+最后需要清理可能影响后续测试的修改。以下是注册区块后的典型清理示例（需取消注册所有区块）：
+
+```js
+afterAll( () => {
+ // 清理已注册区块
+ getBlockTypes().forEach( ( block ) => {
+ unregisterBlockType( block.name );
+ } );
+} );
+```
+
+## 辅助工具
+
+为简化原生版本集成测试的编写，可在[此README文件](https://github.com/WordPress/gutenberg/blob/HEAD/test/native/integration-test-helpers/README.md)中查看辅助函数列表。
+
+## 常见流程
+
+### 查询区块
+
+通过无障碍访问标签查询区块是常见方式，示例如下：
+
+```js
+const spacerBlock = await waitFor( () =>
+ getByLabelText( /间距区块\. 第1行/ )
+);
+```
+
+关于区块无障碍访问标签的更多信息，可查阅 [`getAccessibleBlockLabel` 函数](https://github.com/WordPress/gutenberg/blob/520cbd9d2af4bbc275d388edf92a6cadb685de56/packages/blocks/src/api/utils.js#L167-L234)的代码实现。
+
+### 添加区块
+
+以下是插入段落区块的示例：
+
+```js
+// 打开插入器菜单
+fireEvent.press( await findByLabelText( '添加区块' ) );
+
+const blockList = getByTestId( 'InserterUI-区块列表' );
+// 通过onScroll事件强制FlatList渲染所有项
+fireEvent.scroll( blockList, {
+ nativeEvent: {
+ contentOffset: { y: 0, x: 0 },
+ contentSize: { width: 100, height: 100 },
+ layoutMeasurement: { width: 100, height: 100 },
+ },
+} );
+
+// 插入段落区块
+fireEvent.press( await findByText( `段落` ) );
+```
+
+# React Native 集成测试指南
+
+## 什么是集成测试？
+
+集成测试被定义为将不同部分作为整体进行测试的一种测试类型。在我们的场景中，需要测试的部件是指为特定区块或编辑器逻辑所需渲染的不同组件。最终它们与单元测试非常相似，因为它们都是使用 Jest 库通过相同命令运行的。主要区别在于，对于集成测试，我们将使用特定库 [`react-native-testing-library`](https://testing-library.com/docs/react-native-testing-library/intro/) 来测试编辑器如何渲染不同组件。
+
+## 集成测试的结构
+
+测试可以包含以下部分：
+
+- [设置](#设置)
+- [渲染](#渲染)
+- [查询元素](#查询元素)
+- [触发事件](#触发事件)
+- [验证元素行为](#验证元素行为)
+- [清理](#清理)
+
+我们还在后续章节中提供了常见任务示例和技巧：
+
+- [辅助工具](#辅助工具)
+- [常见流程](#常见流程)
+- [工具](#工具)
+- [常见陷阱与注意事项](#常见陷阱与注意事项)
+
+## 设置
+
+这部分通常通过使用 Jest 回调函数 `beforeAll` 和 `beforeEach` 来完成，目的是准备测试可能需要的所有内容，比如注册区块或模拟部分逻辑。
+
+以下是一个预期所有核心区块可用时的常见模式示例：
+
+```js
+beforeAll( () => {
+ // 注册所有核心区块
+ registerCoreBlocks();
+} );
+```
+
+## 渲染
+
+在引入测试逻辑之前，我们需要先渲染要测试的组件。根据是否使用作用域组件方法或完整编辑器方法，这部分会有所不同。
+
+### 使用作用域组件方法
+
+以下是渲染封面区块的示例（摘自[此代码](https://github.com/WordPress/gutenberg/blob/86cd187873984f80ddeeec3e82454b486dd1860f/packages/block-library/src/cover/test/edit.native.js#L82-L91)）：
+
+```js
+// 此导入指向区块的索引文件
+import { metadata, settings, name } from '../index';
+
+...
+
+const setAttributes = jest.fn();
+const attributes = {
+ backgroundType: IMAGE_BACKGROUND_TYPE,
+ focalPoint: { x: '0.25', y: '0.75' },
+ hasParallax: false,
+ overlayColor: { color: '#000000' },
+ url: 'mock-url',
+};
+
+...
+
+// 在插槽内渲染封面编辑器的简化树结构
+const CoverEdit = ( props ) => (
+ 
+
+## 单元测试
+
+```sh
+npm run test:native
+```
+
+## 集成测试
+
+[Appium](https://appium.io/) 自带诊断工具。通过以下命令运行：
+
+```sh
+npx appium-doctor
+```
+
+
+
+请解决所有必需的依赖项。
+
+### iOS 集成测试
+
+若能确保 iOS 本地环境正常运行，iOS 端到端测试将十分简单。首先停止所有正在运行的 Metro 进程（之前通过 `npm run native start:reset` 启动）。
+
+然后在终端中输入：
+
+```sh
+npm run native test:e2e:ios:local
+```
+
+通过指定文件名可运行部分测试用例：
+
+```sh
+npm run native test:e2e:ios:local gutenberg-editor-paragraph.test.js
+```
+
+若一切顺利，将呈现如下效果：
+
+
+
+### Android 集成测试
+
+**创建新的虚拟设备**，需与 [packages/react-native-editor/**device-tests**/helpers/caps.js](https://github.com/WordPress/gutenberg/blob/trunk/packages/react-native-editor/__device-tests__/helpers/caps.js#L30) 中指定的设备参数匹配。截至本文撰写时，需使用 Pixel 3 XL 镜像配合 Android 9（API 28）系统。
+
+首先启动虚拟设备：点击手机图标进入 AVD 管理器，然后点击绿色启动按钮。
+
+
+
+确保没有 Metro 进程正在运行（之前通过 `npm run native start:reset` 启动）。
+
+然后在终端中运行：
+
+```sh
+npm run native test:e2e:android:local
+```
+
+通过指定文件名可运行部分测试用例：
+
+```
+npm run native test:e2e:android:local gutenberg-editor-paragraph.test.js
+```
+
+稍等片刻后应显示：
+
+
+
+# React Native 开发环境配置指南（macOS 版）
+
+是否对移动端原生编辑器开发感兴趣？本指南将手把手带您完成开发环境配置！
+
+请注意，本文说明主要针对 macOS 环境。若需配置其他环境，请参考 [React Native 快速入门文档](https://reactnative.dev/docs/environment-setup) 获取相关指引和步骤。
+
+## 克隆 Gutenberg 项目
+
+```sh
+git clone git@github.com:WordPress/gutenberg.git
+```
+
+### 安装 node 与 npm
+
+若您同时参与多个 JS 项目，建议使用 node 版本管理器。管理器可让您自由切换不同的 node 和 npm 版本。
+
+我们推荐使用 [nvm](https://github.com/nvm-sh/nvm)。
+
+安装 nvm 后，在克隆项目的根目录下执行：
+
+```sh
+nvm install 'lts/*'
+nvm alias default 'lts/*' # 设置为新终端打开时的默认版本
+nvm use # 切换至项目配置版本
+```
+
+随后安装依赖：
+
+```
+npm ci
+```
+
+### 已有旧版 Gutenberg 代码？
+
+若您已持有 Gutenberg 代码，请务必彻底清理 `node_modules` 并重新安装依赖。
+这将有助于避免后续出现错误。
+
+```sh
+npm run distclean
+npm ci
+```
+
+## iOS 环境配置
+
+### CocoaPods 依赖管理
+
+需要安装 [CocoaPods](https://guides.cocoapods.org/using/getting-started.html) 来获取 React 及第三方依赖。安装步骤因 Ruby 管理方式而异。
+
+#### 系统自带 Ruby
+
+若使用 MacOS 默认 Ruby，需通过 `sudo` 命令安装 Cocoapods：
+
+```
+sudo gem install cocoapods
+```
+
+注意：Mac M1 芯片与 Cocoapods 存在兼容性问题。若遇安装问题，可尝试执行以下命令安装 ffi 包（确保以正确架构安装 pods）：
+
+```
+sudo arch -x86_64 gem install ffi
+arch -x86_64 pod install
+```
+
+#### Ruby 版本管理器
+
+若使用 Ruby 版本管理器，可能无需手动安装 Cocoapods 或 `ffi` 包。请参照所选管理器的文档进行操作。
+
+若需在 [WordPress iOS 应用](https://github.com/wordpress-mobile/WordPress-iOS) 中运行 Gutenberg（而非仅演示应用），推荐使用 [`rbenv`](https://github.com/rbenv/rbenv) 管理器。
+
+### 配置 Xcode
+
+通过 App Store 安装 [Xcode](https://developer.apple.com/xcode/) 后启动：
+
+- 接受许可协议
+- 确认 `Xcode > 偏好设置 > 位置 > 命令行工具` 指向当前 Xcode 版本
+
+
+
+### 环境诊断工具
+
+可通过 [react-native doctor](https://reactnative.dev/blog/2019/11/18/react-native-doctor) 检测开发环境缺失项。在 Gutenberg 项目根目录或 `/packages/react-native-editor` 文件夹内运行：
+
+```sh
+npx @react-native-community/cli doctor
+```
+
+
+
+尝试让 `doctor` 工具修复所有“通用”和“iOS”问题（此时“Android”项显示❌无需担心，后续会处理！）
+
+### 运行演示应用
+
+当所有通用和 iOS 问题解决后，尝试运行：
+
+```
+npm run native start:reset # 启动 metro 打包器
+```
+
+另开终端窗口执行：
+
+```
+npm run native ios
+```
+
+等待构建完成后，演示应用将在 iOS 模拟器中运行：
+
+
+
+## Android 环境配置
+
+### Java开发工具包（JDK）
+
+[React Native文档](https://reactnative.dev/docs/environment-setup)推荐的JDK名为Azul Zulu。可通过[Homebrew](https://brew.sh/)安装。安装Homebrew后，在终端执行以下命令：
+
+```
+brew tap homebrew/cask-versions
+brew install --cask zulu11
+```
+
+若系统已安装JDK，需确保版本为JDK 11或更高。
+
+### 配置Android Studio
+
+编译Android应用需先[下载Android Studio](https://developer.android.com/studio)。
+
+打开现有项目，选择已克隆的Gutenberg文件夹。
+
+点击下图高亮的立方体图标进入SDK管理器，也可通过`工具 > SDK管理器`进入：
+
+
+
+在此界面可下载SDK平台、软件包及其他工具。需勾选“显示包详细信息”查看特定版本，因为构建过程对E2E测试和开发环境有特定版本要求：
+
+
+
+根据[build.gradle](https://github.com/WordPress/gutenberg/blob/trunk/packages/react-native-editor/android/build.gradle)勾选所有相关软件包，点击“应用”开始下载。node_modules中的build.gradle文件可能包含其他依赖项。
+
+若不想逐行查阅文件，系统会在堆栈跟踪中提示缺失包，但此方法需多次尝试。
+
+
+
+
+
+
+
+### 更新路径配置
+
+导出以下环境变量并更新$PATH。若终端使用zsh可添加到`~/.zshrc`文件，若使用bash则添加到`~/.bash_profile`：
+
+```sh
+### Android Studio自带的Java：
+export JAVA_HOME=/Applications/Android\ Studio.app/Contents/jre/Contents/Home
+### Android Home可在Android Studio中配置：偏好设置 > 系统设置 > Android SDK
+export ANDROID_HOME=$HOME/Library/Android/sdk
+export PATH=$PATH:$ANDROID_HOME/emulator
+export PATH=$PATH:$ANDROID_HOME/tools
+export PATH=$PATH:$ANDROID_HOME/tools/bin
+export PATH=$PATH:$ANDROID_HOME/platform-tools
+```
+
+保存后执行source命令或重启终端使配置生效：
+
+```sh
+source ~/.zshrc
+```
+
+或
+
+```sh
+source ~/.bash_profile
+```
+
+若找不到SDK路径，可通过Android Studio > 偏好设置 > 系统设置 > Android SDK验证位置：
+
+
+
+### 创建设备镜像
+
+点击右下角带Android标识的手机图标创建虚拟设备镜像：
+
+
+
+进入“Android虚拟设备管理器(AVD)”，点击“创建虚拟设备”，选择手机类型：
+
+
+
+选择目标SDK版本（对应[build.gradle](https://github.com/WordPress/gutenberg/blob/trunk/packages/react-native-editor/android/build.gradle)中的targetSdkVersion设置）：
+
+
+
+可根据需要调整高级设置（可选），最后点击完成。
\ No newline at end of file
diff --git a/contributors/code/release/README.md b/contributors/code/release/README.md
new file mode 100644
index 0000000..2d5eef3
--- /dev/null
+++ b/contributors/code/release/README.md
@@ -0,0 +1,23 @@
+# Gutenberg 发布流程
+
+GitHub 上的 [Gutenberg 代码库](https://github.com/WordPress/gutenberg) 用于执行多种类型的发布。本页概述了不同的发布流程，并为您提供每种类型对应的文档指引。
+
+## 前置条件
+
+在开始任何发布流程之前，需满足以下要求才能成功发布稳定版的 Gutenberg 插件：
+
+- 成为 [Gutenberg 开发团队](https://developer.wordpress.org/block-editor/contributors/repository-management/#teams) 的成员。这将使您具备启动与发布流程相关的 GitHub 操作以及将拉取请求（PR）回溯到发布分支的权限。
+- 拥有 [Make WordPress Core](https://make.wordpress.org/core) 博客的写权限。这将允许您起草发布文稿。
+- 获得 Gutenberg 核心团队成员的批准，以便将新版本的 Gutenberg 上传至 WordPress.org 插件目录。
+
+## 插件发布
+
+插件发布涉及创建新版本的 Gutenberg 插件并将其发布到 WordPress.org 插件目录。此流程包括创建候选版本、测试以及最终发布。
+
+有关如何执行插件发布的详细说明，请参阅 [Gutenberg 插件发布](https://developer.wordpress.org/block-editor/contributors/code/release/plugin-release/)。
+
+## 软件包发布
+
+软件包发布涉及将更新后的 WordPress 软件包版本发布到 npm。此流程包括与插件发布、WordPress 核心更新以及独立的错误修复发布同步。
+
+有关软件包发布和 WordPress 核心更新的完整说明，请参阅 [发布软件包至 NPM 及 WordPress 核心更新](https://developer.wordpress.org/block-editor/contributors/code/release/package-release-and-core-updates/)。
\ No newline at end of file
diff --git a/contributors/code/release/package-release-and-core-updates.md b/contributors/code/release/package-release-and-core-updates.md
new file mode 100644
index 0000000..afe34fb
--- /dev/null
+++ b/contributors/code/release/package-release-and-core-updates.md
@@ -0,0 +1,156 @@
+- 系统会多次要求您输入一次性密码（OTP），即您使用的双因素认证应用生成的验证码。根据待发布软件包的数量，您可能需要输入多个OTTP，因为这些代码往往在所有软件包发布前就会失效。
+- 若发布流程意外中断（可能因超时或输错OTP导致），可通过执行 [`npx lerna publish from-package`](https://lerna.js.org/docs/features/version-and-publish#from-package) 命令恢复操作。
+
+6. 最后，当 npm 软件包发布完成后，请将 Lerna 生成的提交记录（"发布"和更新日志更新）遴选合并到 Gutenberg 的 `trunk` 分支。
+
+## 开发版发布
+
+如[同步 Gutenberg 插件](#synchronizing-the-gutenberg-plugin)章节所述，软件包每两周会从 `wp/latest` 分支发布一次。此外，开发者可随时通过开发版来测试 `trunk` 分支即将推出的变更。我们利用[软件包分发标签](https://docs.npmjs.com/cli/v7/commands/npm-dist-tag)功能，使得根据 npm 指南使用未来版本代码成为可能：
+
+> 默认情况下，npm 使用 `latest` 标签标识软件包当前版本，执行 `npm install
+若新版本已存在RC版本，您必须将相同提交精选至对应发布分支，因为它们不会自动包含。例如：若您正准备发布12.5的新次要版本，仅向
+
+精选过程可通过[`npm run cherry-pick`](/docs/contributors/code/auto-cherry-picking.md)脚本自动化执行，但运行脚本时请确保使用`Backport to Gutenberg Minor Release`标签。
+
+同时必须确保所有纳入的PR都已分配至该次要版本对应的GitHub里程碑。需注意：PR合并时会自动分配至下一个稳定版本的里程碑，因此您需要在GitHub中逐一手动调整PR的里程碑归属。
+
+例如，若您正在发布`12.5.4`版本，所有精选至该版本的PR必须从`12.6`里程碑移除，并重新分配至`12.5`里程碑。
+
+完成精选后，可移除PR上的`Backport to Gutenberg Minor Release`标签。
+
+当稳定发布分支整理就绪且PR分配正确里程碑后，即可将分支推送至GitHub，并通过GitHub网站图形界面继续发布流程。
+
+### 运行小版本发布
+
+
+
+前往 Gutenberg 的 GitHub 仓库的 Actions 标签页，找到 [“构建 Gutenberg 插件压缩包” 操作](https://github.com/WordPress/gutenberg/actions/workflows/build-plugin-zip.yml)。现在，你需要**仔细**根据当前插件发布版本的信息选择下一步操作：
+
+**如果**上一个发布版本是**稳定版**（`X.Y.Z`，例如 `12.5.0`、`12.5.1` 等），请将 `Use workflow from` 字段保留为 `trunk`，并在文本输入框中指定 `stable`。工作流将自动创建一个小版本，根据需要递增 z 值（`x.y.(z+1)`）。
+
+**但如果**上一个发布版本是 **RC 版本**（例如 `X.Y.0-rc.1`），你需要在创建发布时**手动**选择**稳定版本的发布分支**（例如 `12.5.0`）。如果不这样做，工作流将发布下一个主要的**稳定**版本（例如 `12.6.0`），而这并不是你想要的。
+
+为此，在运行工作流时，从 `Use workflow from` 下拉菜单中选择适当的 `release/` 分支（例如 `release/12.5`），并在文本输入框中指定 `stable`。
+
+#### 为之前的稳定版本创建小版本
+
+即使已经发布了更新的稳定版本，也可以为任何发布分支创建小版本。这可以用于**任何**之前的发布分支，从而更灵活地向用户提供更新。过去，用户必须等待下一个稳定版本，可能需要几天时间。现在，可以根据需要迅速将修复推送到任何之前的发布分支。
+
+该过程与上述已有 RC 版本时的流程相同：选择一个之前的发布分支，输入 `stable`，然后点击 “Run workflow”。发布将在 Gutenberg 的 GitHub 发布页面和 WordPress 核心仓库的 SVN 中以 `tag` 的形式发布到 [https://plugins.svn.wordpress.org/gutenberg/tags/](https://plugins.svn.wordpress.org/gutenberg/tags/)。SVN 的 `trunk` 目录不会被修改。
+
+**重要提示：** 在发布由 [“构建插件压缩包” 工作流](https://github.com/WordPress/gutenberg/actions/workflows/build-plugin-zip.yml) 创建的草稿时，请确保**取消勾选** “Set as last release” 复选框。如果不小心勾选了，[“将 Gutenberg 插件上传到 WordPress.org 插件仓库” 工作流](https://github.com/WordPress/gutenberg/actions/workflows/upload-release-to-plugin-repo.yml) 仍会正确将其**作为标签（并且不会替换 `trunk` 版本）** 上传到 WordPress 插件仓库的 SVN——工作流会执行一些版本计算以确定插件的发布方式——但你仍然需要在 GitHub 上通过将正确的发布设置为 `latest` 来修复状态，具体操作在 [发布页面](https://github.com/WordPress/gutenberg/releases/) 上进行！
+
+### 故障排除
+
+> 发布草稿已创建，但内容为空/包含错误消息
+
+如果你忘记将正确的里程碑分配给你精选的 PR，那么生成的更新日志可能不符合预期。
+
+务必手动验证更新日志中显示的 PR 是否与精选到发布分支的 PR 一致。
+
+此外，如果发布仅包含一个 PR，但未将该 PR 分配到正确的里程碑，则在生成更新日志时会显示错误。在这种情况下，你可以编辑发布说明，手动添加缺失的 PR 的详细信息（格式可参考之前的发布）。
+
+如果由于某种原因里程碑已关闭，你可以为了发布的目的重新打开它。
+
+> 发布草稿仅包含 1 个资源文件，而其他发布包含 3 个。
+
+这是正常现象。发布草稿仅包含插件压缩包。只有在发布后，其他资源才会生成并添加到发布中。
+
+> 是否需要将点发布版本发布到 WordPress.org？
+
+是的。方法与主要的插件发布流程相同。你需要 Gutenberg 核心团队或 Gutenberg 发布团队的成员批准发布工作流。
+
+> 发布过程未能将版本更新提交精选到 `trunk` 分支。
+
+首先，通过检查 `trunk` 上的最新提交是否包含版本更新提交来确认步骤失败。然后在发布分支上回退版本更新提交——使用命令 `git revert --no-edit {commitHash}`。最后，推送更改并重新开始发布过程。
+
+# Gutenberg 插件发布指南
+
+## 快速参考
+
+### 时间安排
+
+- 在里程碑日期（通常为周三）发布 RC1 版本
+- 下周三发布正式稳定版
+
+### 常规发布流程
+
+#### 步骤 1：准备工作
+
+- 使用模板创建[发布工单](https://github.com/WordPress/gutenberg/issues/new?template=New_release.md)（可选操作，但有助于逐步执行流程）
+- 审核里程碑中的所有 PR 并添加适当标签（`[Type] Bug`、`[Type] Enhancement` 等）
+- 测试更新日志：`npm run other:changelog -- --milestone="Gutenberg X.Y"`
+
+#### 步骤 2：构建发布版本
+
+- 在 [#core-editor](https://wordpress.slack.com/messages/C02QB2JS7) Slack 频道发布公告
+- 前往 GitHub Actions → [构建插件压缩包工作流](https://github.com/WordPress/gutenberg/actions/workflows/build-plugin-zip.yml)
+- 保持 `Use workflow from` 选项为 `trunk`（默认值）
+- 输入 `rc`（候选版本）或 `stable`（正式版本）
+- 点击 `Run workflow`
+- 当[GitHub Releases](https://github.com/WordPress/gutenberg/releases)中生成发布草稿后，立即发布以继续工作流
+- 仅限稳定版：等待团队批准上传至 WordPress.org——这是工作流的最后一步，用于将插件部署到插件目录（[示例](https://github.com/WordPress/gutenberg/actions/runs/18559811968)）
+
+#### 步骤 3：编辑发布说明
+
+- 在[GitHub Releases](https://github.com/WordPress/gutenberg/releases)中找到草稿
+- 清理更新日志：修正拼写错误，调整分类不当的条目，合并相关 PR
+- 移除仅限移动端的更改和已回滚的 PR
+
+#### 步骤 4：撰写发布文章
+
+- 使用[谷歌文档模板](https://docs.google.com/document/d/1D-MTOCmL9eMlP9TDTXqlzuKVOg_ghCPm9_whHFViqMk/edit)
+- 重点介绍本次发布的 3-5 项关键功能
+- 稳定版发布后，在 [make.wordpress.org/core](https://make.wordpress.org/core/) 上发布文章
+
+### 额外候选版本与次要版本 (X.Y.Z)
+
+针对 RC1 后的紧急修复或主要版本间的关键错误修复：
+
+#### 遴选错误修复
+
+- 新 RC 版本：使用标有 `Backport to Gutenberg RC` 的 PR
+- 次要版本：使用标有 `Backport to Gutenberg Minor Release` 的 PR
+- 切换到相应发布分支：`git checkout release/X.Y`
+- 运行：`npm run other:cherry-pick "[Label Name]"`
+- 在运行工作流**之前**，将 PR 重新分配到正确的里程碑（例如从 `12.6` 改为 `12.5`）
+
+#### 运行发布工作流
+
+- 前往[构建插件压缩包工作流](https://github.com/WordPress/gutenberg/actions/workflows/build-plugin-zip.yml)
+- 从 `Use workflow from` 下拉菜单中选择发布分支
+- 继续执行上述步骤 2-4
+
+---
+
+## 详细流程
+
+发布 Gutenberg 插件稳定版的第一步是在 Gutenberg 代码库中[创建工单](https://github.com/WordPress/gutenberg/issues/new?template=New_release.md)。该工单模板名为 "Gutenberg Release"，包含从候选版本到更新日志整理、遴选代码、稳定版发布及发布文章的完整清单。[Gutenberg 21.2](https://github.com/WordPress/gutenberg/issues/70662) 的工单就是一个很好的范例。
+
+该清单可帮助您与参与发布流程的开发人员及其他团队协调，确保所有必要步骤均已完成，且所有人员都清楚时间安排和重要里程碑。
+
+## 发布周期
+
+Gutenberg 的主要版本大约每两周发布一次。当前及后续版本会在 [GitHub 里程碑](https://github.com/WordPress/gutenberg/milestones) 中追踪，同时标注每个版本的发布日期。
+
+**在当前里程碑日期**（也称为标记日期），Gutenberg 的首个候选版本（RC）将发布。这是插件的预发布版本，供插件作者和用户测试。如果发现任何回归问题，可以发布新的 RC 版本。
+
+候选版本按增量方式编号，从 `-rc.1` 开始，然后是 `-rc.2`，依此类推。一旦首个 RC（RC1）发布，发布文章的准备工作随即启动。
+
+**RC1 发布一周后**，基于最后一个 RC 及必要的回归修复创建稳定版本。稳定版发布后，发布文章将同步上线。
+
+如果在插件的稳定版本中发现关键错误，可随时发布修补版本。
+
+## 版本管理
+
+每个主要的 Gutenberg 版本由一位版本管理员（也称为版本负责人）负责运作。该负责人或小型团队在更广泛的 [Gutenberg 开发团队](https://developer.wordpress.org/block-editor/contributors/repository-management/#teams)支持下，负责 Gutenberg 版本的发布工作。
+
+版本管理员负责启动所有发布活动，任何对发布计划的更改都需要他们的批准。在紧急情况下或版本管理员无法参与时，其他团队成员可以采取适当行动，但应随时向版本管理员通报情况。
+
+release/12.5分支精选了提交，但12.6.0-rc.1已发布，则需将相同提交精选至release/12.6分支，否则这些提交不会包含在后续12.6版本中！通常建议与下个版本的发布协调员协同处理此流程。
+
+如果您是 Gutenberg 开发团队成员，并且有兴趣主导 Gutenberg 版本发布，请在 #core-editor Slack 频道中联系我们。
+
+
+## 准备发布
+
+插件发布流程大部分是自动化的，并在 GitHub 上进行。您无需在本地计算机上执行任何步骤。不过，建议在本地保留一份 Gutenberg 副本，用于准备更新日志、进行常规测试，以及应对可能需要多个候选版本的情况。关于这一点，后续会详细说明。
+
+这里有一个[11分钟的视频](https://youtu.be/TnSgJd3zpJY)，演示了插件发布流程。如果您对该流程不熟悉，建议先观看视频。以下段落也记录了该流程，并提供了更详细的说明。
+
+### 组织和标记里程碑 PR
+
+
+ 快速参考
+
+
+准备 Gutenberg 版本的第一步是组织所有分配给当前[里程碑](https://github.com/WordPress/gutenberg/milestones)的 PR，并确保每个 PR 都正确标记。[标签](https://github.com/WordPress/gutenberg/labels)用于自动生成更新日志，更改 PR 上的标签比事后在发布部分重新组织现有更新日志要快得多。
+
+要测试将在发布工作流中运行的更新日志自动化功能，您可以在本地 Gutenberg 副本中使用以下命令，并指定您正在处理的稳定版本里程碑：
+
+```
+npm run other:changelog -- --milestone="Gutenberg 16.2"
+```
+
+该命令的输出是所提供里程碑的更新日志，上述示例中是 Gutenberg 16.2。您可以将输出复制并粘贴到 Markdown 文档中，这样可以更方便地查看，并允许您跟踪每个 PR 的链接。
+
+所有 PR 都应有一个以 `[Type]` 为前缀的标签以及子类别标签。两个最常见的标签是 `[Type] Bug` 和 `[Type] Enhancement`。在查看生成的更新日志时，请特别注意以下内容：
+
+- **增强功能：** 查找没有附加任何子类别的 PR。
+- **错误修复：** 同样查找没有附加任何子类别的 PR。
+- **其他：** 此部分中的 PR 没有任何标签。
+
+根据需要更新每个 PR 的标签。您可以继续生成更新日志，直到您满意为止。现在，您可以开始候选版本工作流了。
+
+-
+
- 确保所有 PR 都正确标记。 +
- 每个 PR 必须有一个以
[Type]为前缀的标签。
+
+您可以在 changelog.js 文件中查看如何根据 PR 标签生成更新日志。
+
+
+### 运行发布工作流
+
+
+ 快速参考
+
+
+在开始之前，请在 [#core-editor](https://wordpress.slack.com/messages/C02QB2JS7) Slack 频道中宣布您即将开始工作流，并说明您是要发布 Gutenberg 的稳定版本还是候选版本。
+
+然后转到 Gutenberg 仓库，点击 Actions 标签页，找到 [构建 Gutenberg 插件 Zip](https://github.com/WordPress/gutenberg/actions/workflows/build-plugin-zip.yml) 操作。注意蓝色的横幅，上面写着“此工作流有一个 `workflow_dispatch` 事件触发器。” 展开其右侧的“Run workflow”下拉菜单。
+
+
+
+要发布插件的候选版本，请在文本字段中输入 `rc`。要发布稳定版本，请输入 `stable`。在每种情况下，按下“Run workflow”按钮。
+
+这将触发一个 GitHub Actions (GHA) 工作流，该工作流将提升插件版本、构建 Gutenberg 插件 `.zip` 文件、创建发布草稿并附加插件 `.zip` 文件。这部分过程通常需要大约六分钟。工作流将出现在列表顶部，紧挨着蓝色横幅下方。完成后，工作流的状态图标将从黄色圆点变为绿色对勾。您可以通过点击工作流来查看更详细的视图。
+
+## 排查发布问题
+
+> 插件已成功发布至 WordPress.org 插件目录，但工作流却显示失败。
+
+此类情况偶有发生，例如可参考[该案例](https://github.com/WordPress/gutenberg/actions/runs/16325916698/job/46115920213)。
+
+请务必确认以下事项：
+
+- 插件在目录中功能正常
+- ZIP 包内容（参见[下载页面](https://plugins.trac.wordpress.org/browser/gutenberg/)）完整无误（无明显文件缺失）
+- [Gutenberg SVN 仓库](https://plugins.trac.wordpress.org/browser/gutenberg/)包含两次新提交（查看[提交记录](https://plugins.trac.wordpress.org/browser/gutenberg/)）：
+ - `trunk` 目录应包含 "Committing version X.Y.Z" 提交
+ - 新增的 `tags/X.Y.Z` 目录内容与 `trunk` 一致，且最新提交为 "Tagging version X.Y.Z"
+
+最可能的情况是标签目录未能自动创建。这是[已知问题](https://github.com/WordPress/gutenberg/issues/55295)，可[通过手动操作修复](https://github.com/WordPress/gutenberg/issues/55295#issuecomment-1759292978)。
+
+请将 `SVN_USERNAME`、`SVN_PASSWORD` 和 `VERSION` 替换为实际值，或先将其设为全局环境变量：
+
+```sh
+# 检出代码库
+svn checkout https://plugins.svn.wordpress.org/gutenberg/trunk --username "$SVN_USERNAME" --password "$SVN_PASSWORD" gutenberg-svn
+
+# 进入本地目录
+cd gutenberg-svn
+
+# 若本地已存在代码库
+# 且未执行检出操作，请确保更新至最新版本
+svn up .
+
+# 将当前主干内容复制至新标签目录
+svn copy https://plugins.svn.wordpress.org/gutenberg/trunk https://plugins.svn.wordpress.org/gutenberg/tags/$VERSION -m 'Tagging version $VERSION' --no-auth-cache --non-interactive --username "$SVN_USERNAME" --password "$SVN_PASSWORD"
+```
+
+操作过程中如需帮助，请及时向团队求助。
+
+## 发布文档撰写
+
+发布文档由发布经理主导，并依托[古腾堡开发团队](https://developer.wordpress.org/block-editor/contributors/repository-management/#teams)成员协作完成。该流程包含一系列顺序步骤，因涉及人员众多且需协调配合，需在发布候选版与正式版之间的时间窗口内严格执行。古腾堡正式版于每周三发布，距首个候选版间隔一周。
+
+-
+
- + 在 #core-editor 中宣布您即将开始发布工作流。 + +
- + 运行 构建 Gutenberg 插件 Zip 工作流。 + +
+ 时间线
+
+
+### 选定发布亮点
+
+整理完更新日志后，下一步是选取若干重要变更作为发布公告的亮点。这些亮点通常聚焦于新功能与体验优化（包括性能与无障碍改进），也可包含重要的 API 变更或关键缺陷修复。
+
+鉴于古腾堡涉及面广且每个里程碑周期会合并大量 PR，时有值得重点介绍的变更被疏漏。因此本环节需要发布经理与其他古腾堡开发团队成员协同完成。若不确定如何选择，可随时向团队成员寻求建议。
+
+### 发布素材准备
+
+发布公告需配置若干视觉素材。公告特色图片建议沿用上一版本使用的图片（媒体库中文件名应为 'gb-featured'）。
+
+公告正文中的横幅可通过名为「Gutenberg What's New Banner」的同步模式插入。使用该模式后请将版本号更新为正确数值。
+
+重点功能还需配套视觉素材。针对核心功能可向设计团队申请专业素材，其他功能若操作熟练也可自行制作。申请设计素材时，请在 Slack 的 [#design](https://wordpress.slack.com/archives/C02S78ZAL) 频道中提出请求，可参考[15.8 版本申请范例](https://wordpress.slack.com/archives/C02S78ZAL/p1684161811926279)。素材将存放于专为该版本创建的[谷歌网盘文件夹](https://drive.google.com/drive/folders/1U8bVbjOc0MekWjpMjNaVFVhHFEzQkYLB)中。
+
+制作 WordPress 发布素材时，可使用动画（视频或 GIF）或静态图片展示亮点。参考[往期发布公告](https://make.wordpress.org/core/tag/gutenberg-new/)的呈现方式，注意动画更适合演示操作流程，而直接的功能亮点用静态图片即可。创作过程中请避免使用版权素材，并移除浏览器画布中可见的插件标识。
+
+### 创建候选发布补丁（代码拣选）
+
+-
+
- 复制发布公告谷歌文档模板——周三至周五 +
- 选定发布亮点——周五至周一 +
- 亮点确定后向设计团队申请素材（图片、视频）——周五至周一 +
- 起草发布公告并申请同行评审——周一至周三 +
- 正式版发布后公开公告——周三 +
+ 快速参考
+
+
+在RC版本发布后、最终稳定版发布前，一些与发布相关的错误可能会被修复并提交到`trunk`分支。稳定版本不会自动包含这些修复。需要手动将这些修复纳入，这个过程称为代码拣选。
+
+作为发布经理，您可能会通过以下几种方式了解到这些错误：
+
+- 贡献者可能会在已关闭的PR上添加`Backport to Gutenberg RC`标签。[在发布最终版本前，请搜索这些PR](https://github.com/WordPress/gutenberg/pulls?q=is%3Apr+label%3A%22Backport+to+Gutenberg+RC%22+is%3Aclosed)。
+- 您可能会在[#core-editor](https://wordpress.slack.com/messages/C02QB2JS7) Slack频道收到直接消息或通知，告知您需要纳入RC的PR。即使在这种情况下，也应在PR上添加`Backport to Gutenberg RC`标签。
+
+#### 自动化代码拣选
+
+代码拣选过程可以通过Gutenberg中包含的`npm run other:cherry-pick "[Insert Label]"`脚本自动完成。运行命令时需要使用`Backport to Gutenberg RC`标签，并确保所有需要拣选的PR都已分配该标签。
+
+-
+
- 确保所有需要拣选的PR都标记有
Backport to Gutenberg RC标签。
+ - 在本地克隆的Gutenberg仓库中，切换到发布分支：
git checkout release/X.Y
+ - 使用自动化脚本拣选所有已合并的PR：
npm run other:cherry-pick "Backport to Gutenberg RC"
+
+要拣选PR，您必须克隆（而不是分叉）Gutenberg仓库并具有写入权限。只有Gutenberg开发团队的成员才有执行此操作的必要权限。
+
+将Gutenberg仓库克隆到本地开发环境后，首先切换到发布分支：
+
+```
+git checkout release/X.Y
+```
+
+接下来，使用适当的反向移植标签拣选所有已合并的PR：
+
+```
+npm run other:cherry-pick "Backport to Gutenberg RC"
+```
+
+在后台，该脚本将执行以下操作：
+
+- 拣选所有带有`Backport to Gutenberg RC`标签的PR
+- 将它们添加到发布里程碑
+- 将所有更改`git push`到发布分支
+- 在PR上添加评论，表明它已被拣选
+- 从PR中移除`Backport to Gutenberg RC`标签
+
+以下是该过程的截图：
+
+
+
+#### 手动代码拣选
+
+如果您需要逐个、逐步处理代码拣选，可以手动按照以下顺序操作。在检出相应的发布分支后：
+
+1. 使用`git cherry-pick [SHA]`按时间顺序拣选每个PR。
+2. 完成后，使用`git push`将更改推送到GitHub。
+3. 移除所有已拣选PR的`Backport to Gutenberg RC`标签，并将里程碑更新为当前发布版本。
+
+要查找拉取请求的`[SHA]`，请打开PR，您将在末尾附近看到“`[用户名]`将提交`[SHA]`合并到`trunk`”的消息。
+
+
+
+如果拣选的修复值得在稳定版本发布前再发布一个候选版本，请按照上述说明创建一个。在[#core-editor](https://wordpress.slack.com/messages/C02QB2JS7) Slack频道中告知其他贡献者已发布新的候选版本。
+
+### 发布版本
+
+
+ 快速参考
+
+
+只有当您对发布草稿中的更新日志内容满意时，才点击“发布版本”按钮。
+
+请注意，您无需更改按钮上方的复选框。如果您发布的是RC版本，“设置为预发布版本”将自动被选中；如果您发布的是稳定版本，“设置为最新版本”将被选中。
+
+
+
+发布版本将为该版本创建一个`git`标签，发布版本，并触发[另一个GHA工作流](https://github.com/WordPress/gutenberg/actions/workflows/upload-release-to-plugin-repo.yml)，其目的有两个：
+
+1. 使用您刚刚编辑的发布说明更新`changelog.txt`；
+2. 将新插件版本上传到WordPress.org插件仓库（SVN）（仅当您发布稳定版本时）。
+
+最后一步需要[Gutenberg发布团队](https://github.com/orgs/WordPress/teams/gutenberg-release)、[Gutenberg核心团队](https://github.com/orgs/WordPress/teams/gutenberg-core)或[WordPress核心团队](https://github.com/orgs/WordPress/teams/wordpress-core)成员的批准。这些团队在发布准备就绪时会收到通知邮件，但如果时间紧迫，您可以在`#core-editor` Slack频道中询问或通知[Gutenberg发布团队](https://github.com/orgs/WordPress/teams/gutenberg-release)以加速流程。建议在启动发布流程之前提前联系，以便有人准备好批准。找到新版本的[“将Gutenberg插件上传到WordPress.org插件仓库”工作流](https://github.com/WordPress/gutenberg/actions/workflows/upload-release-to-plugin-repo.yml)，并[批准](https://docs.github.com/en/actions/how-tos/managing-workflow-runs-and-deployments/managing-deployments/reviewing-deployments#approving-or-rejecting-a-job)它。
+
+一旦获得批准，新版本的Gutenberg将对全球的WordPress用户可用。上传后，请确认可以从WordPress插件仪表盘下载和更新最新版本。
+
+最后一步是在[make.wordpress.org/core](https://make.wordpress.org/core/)上撰写发布文章。您可以在下面找到一些相关提示。
\ No newline at end of file
diff --git a/contributors/code/scripts.md b/contributors/code/scripts.md
new file mode 100644
index 0000000..3fe898c
--- /dev/null
+++ b/contributors/code/scripts.md
@@ -0,0 +1,75 @@
+## Polyfill 脚本
+
+编辑器还为某些可能并非所有现代浏览器都支持的功能提供了 polyfill。
+
+建议使用主要的 `wp-polyfill` 脚本句柄，它会负责加载以下所有提到的 polyfill。
+
+| 脚本名称 | 句柄 | 描述 |
+| ------------------------------------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------- |
+| [Babel Polyfill](https://babeljs.io/docs/en/babel-polyfill) | wp-polyfill | 模拟完整的 ES2015+ 环境。主脚本，用于加载以下所有附加的 polyfill |
+| [Fetch Polyfill](https://www.npmjs.com/package/whatwg-fetch) | wp-polyfill-fetch | 实现标准 Fetch 规范子集的 polyfill |
+| [Promise Polyfill](https://www.npmjs.com/package/promise-polyfill) | wp-polyfill-promise | 适用于浏览器和 Node 的轻量级 ES6 Promise polyfill |
+| [Formdata Polyfill](https://www.npmjs.com/package/formdata-polyfill) | wp-polyfill-formdata | 有条件地替换原生实现的 polyfill |
+| [Node Contains Polyfill](https://www.npmjs.com/package/polyfill-library) | wp-polyfill-node-contains | 用于 Node.contains 的 polyfill |
+| [Element Closest Polyfill](https://www.npmjs.com/package/element-closest) | wp-polyfill-element-closest | 返回 DOM 树中与选择器匹配的最接近的元素 |
+
+## 打包与代码共享
+
+当使用如 [webpack](https://webpack.js.org/) 这样的 JavaScript 打包工具时，此处提到的脚本可以从打包文件中排除，并通过 WordPress 以脚本依赖的形式提供，参见 [`wp_enqueue_script`](https://developer.wordpress.org/reference/functions/wp_enqueue_script/#default-scripts-included-and-registered-by-wordpress)。
+
+[`@wordpress/dependency-extraction-webpack-plugin`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/dependency-extraction-webpack-plugin) 提供了一个 webpack 插件，用于帮助从打包文件中提取 WordPress 依赖项。`@wordpress/scripts` 的 [`build`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/scripts#build) 脚本默认包含此插件。
+
+| [NUX](/packages/nux/README.md) | wp-nux | 包含用于引导新用户熟悉WordPress管理界面的组件及wp.data相关方法 |
+| [Plugins](/packages/plugins/README.md) | wp-plugins | WordPress插件管理模块 |
+| [Redux Routine](/packages/redux-routine/README.md) | wp-redux-routine | 用于生成器协程的Redux中间件 |
+| [Rich Text](/packages/rich-text/README.md) | wp-rich-text | 实现HTML/DOM树与富文本值相互转换的辅助函数 |
+| [Shortcode](/packages/shortcode/README.md) | wp-shortcode | WordPress短代码模块 |
+| [Token List](/packages/token-list/README.md) | wp-token-list | 可构造的纯JavaScript [DOMTokenList](https://developer.mozilla.org/en-US/docs/Web/API/DOMTokenList)实现，支持非浏览器运行时环境 |
+| [URL](/packages/url/README.md) | wp-url | 用于操作URL的实用工具集 |
+| [Viewport](/packages/viewport/README.md) | wp-viewport | 用于响应浏览器视口尺寸变化的模块 |
+| [Wordcount](/packages/wordcount/README.md) | wp-wordcount | WordPress字数统计工具 |
+
+## 第三方脚本
+
+编辑器还使用了一些流行的第三方程序包和脚本。插件开发者同样可以直接使用这些脚本，无需将其打包到代码中（避免增加文件体积）。
+
+| 脚本名称 | 注册句柄 | 功能描述 |
+| ---------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------- |
+| [React](https://reactjs.org) | react | 用于构建用户界面的JavaScript库 |
+| [React Dom](https://reactjs.org/docs/react-dom.html) | react-dom | 作为React的DOM和服务器渲染器入口点，需与React配合使用 |
+| [Moment](https://momentjs.com/) | moment | 用于解析、验证、操作和显示JavaScript中的日期时间 |
+| [Lodash](https://lodash.com) | lodash | 提供通用编程任务工具函数的JavaScript库 |
+
+# 脚本
+
+编辑器为插件开发者提供了多个供应商和内部脚本。下表记录了脚本名称、句柄和描述。
+
+## WordPress 脚本
+
+编辑器包含多个功能包以实现各种功能。插件开发者可以利用它们来创建区块、编辑器插件或通用插件。
+
+| 脚本名称 | 句柄 | 描述 |
+| -------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Blob](/packages/blob/README.md) | wp-blob | Blob 实用工具 |
+| [区块库](/packages/block-library/README.md) | wp-block-library | 编辑器的区块库 |
+| [区块](/packages/blocks/README.md) | wp-blocks | 区块创建 |
+| [区块序列化默认解析器](/packages/block-serialization-default-parser/README.md) | wp-block-serialization-default-parser | WordPress 文档的默认区块序列化解析器实现 |
+| [区块序列化规范解析器](/packages/block-serialization-spec-parser/README.md) | wp-block-serialization-spec-parser | WordPress 文章的语法文件 (grammar.pegjs) |
+| [组件](/packages/components/README.md) | wp-components | 用于创建通用 UI 元素的通用组件 |
+| [组合](/packages/compose/README.md) | wp-compose | 一系列便捷的高阶组件 (HOCs) |
+| [核心数据](/packages/core-data/README.md) | wp-core-data | 简化和操作核心 WordPress 实体的访问 |
+| [数据](/packages/data/README.md) | wp-data | 数据模块作为管理插件和 WordPress 本身应用状态的枢纽 |
+| [日期](/packages/date/README.md) | wp-date | WordPress 的日期模块 |
+| [弃用](/packages/deprecated/README.md) | wp-deprecated | 用于记录消息以通知开发者某个功能已弃用的实用工具 |
+| [DOM](/packages/dom/README.md) | wp-dom | WordPress 的 DOM 实用工具模块 |
+| [DOM 就绪](/packages/dom-ready/README.md) | wp-dom-ready | DOM 加载完成后执行回调 |
+| [编辑器](/packages/editor/README.md) | wp-editor | WordPress 编辑器的构建块 |
+| [编辑文章](/packages/edit-post/README.md) | wp-edit-post | WordPress 的编辑文章模块 |
+| [元素](/packages/element/README.md) | wp-element | 元素简单来说是基于 [React](https://reactjs.org/) 的抽象层 |
+| [HTML 转义](/packages/escape-html/README.md) | wp-escape-html | HTML 转义实用工具 |
+| [钩子](/packages/hooks/README.md) | wp-hooks | 一个轻量高效的 JavaScript 事件管理器 |
+| [HTML 实体](/packages/html-entities/README.md) | wp-html-entities | WordPress 的 HTML 实体实用工具 |
+| [国际化](/packages/i18n/README.md) | wp-i18n | 客户端本地化的国际化实用工具 |
+| [浅比较](/packages/is-shallow-equal/README.md) | wp-is-shallow-equal | 用于对两个对象或数组执行浅比较的函数 |
+| [键码](/packages/keycodes/README.md) | wp-keycodes | WordPress 的键码实用工具，用于检查 `onKeyDown` 等事件中按下的键 |
+| [列出可重用区块](/packages/list-reusable-blocks/README.md) | wp-list-reusable-blocks | 用于在可重用区块列表页面添加导入/导出链接的包 |
\ No newline at end of file
diff --git a/contributors/code/testing-overview.md b/contributors/code/testing-overview.md
new file mode 100644
index 0000000..70ba941
--- /dev/null
+++ b/contributors/code/testing-overview.md
@@ -0,0 +1,647 @@
+#### 最佳实践
+
+若你正着手重构，快照会是个不错的选择。你可以将其作为分支的首个提交，并观察其演变过程。
+
+快照本身并不体现我们的预期目标。快照最适合与描述期望的其他测试结合使用，如下例所示：
+
+```jsx
+test( '当启用planets属性时应包含mars', () => {
+ const { container } = render( -
+
- 在发布草稿中，点击“发布版本”按钮。 +
- 如果发布稳定版本，需获得Gutenberg发布团队、Gutenberg核心团队或WordPress核心团队成员的批准，才能将新插件版本上传到WordPress.org插件仓库（SVN）。 +
- 上传后，确认可以从WordPress插件仪表盘下载和更新最新版本。 +
+
+古腾堡标识由[Cristel Rossignol](https://twitter.com/cristelrossi)设计，基于GPL协议发布。[下载SVG格式标识](https://raw.githubusercontent.com/WordPress/gutenberg/HEAD/docs/contributors/assets/gutenberg-logo-black.svg)。
+
+### 古腾堡的核心目标
+
+古腾堡的终极目标是打造直观易用的文章与页面编辑体验，让用户轻松创建丰富布局。区块编辑器是首款基于此内容创作方法论推出的产品。
+
+根据[项目启动宣言](https://make.wordpress.org/core/2017/01/04/focus-tech-and-design-leads/)：
+
+> 该编辑器致力于打造全新的页面与文章构建体验，让富媒体内容创作变得轻松自如，并通过“区块”功能简化当前需要短代码、自定义HTML或复杂嵌入操作才能实现的效果。
+
+我们可从中提炼出若干核心原则：
+
+- **富媒体内容创作是WordPress的核心优势**
+- **区块将在统一界面中整合功能与交互模式**：用户无需再使用短代码、自定义HTML或粘贴嵌入链接。只需掌握区块使用方法，即可解锁全部功能
+- **提升核心功能的可发现性**：消除难以察觉的“隐藏功能”。WordPress支持大量区块和30余种嵌入类型，需增强其可见度
+
+### 设计初衷
+
+WordPress区别于其他系统的特质在于：只要用户掌握HTML和CSS并能构建自定义主题，即可实现无限可能的文章布局。
+
+古腾堡将编辑器重塑为直观工具，让用户无需技术背景即可通过简单点击创作富媒体内容、构建精美布局。WordPress将成为人人可用的强大灵活内容创作平台。
+
+### 愿景规划
+
+古腾堡致力于降低富媒体内容创作门槛。这意味着需要确保默认设置的合理性，将高级布局选项集成至区块中，并使核心操作触手可及。任何人都应能无障碍地使用WordPress创作内容。
+
+**WordPress站点的所有元素都将区块化**：无论是文本、图片、相册、小工具、短代码，还是通过插件添加的自定义HTML片段。用户仅需掌握区块界面这一种交互方式。
+
+**所有区块平等共存**：它们统一位于插入器界面中。通过最近使用记录、搜索功能、标签分类和分组管理，确保常用区块随时可用。
+
+**拖拽操作作为辅助**：为了更好的可访问性和平台兼容性，拖拽交互作为点击、跳转和空格等明确操作的增强功能存在。
+
+**占位符设计至关重要**：支持中性占位状态的区块都应实现该特性。图片占位区块显示媒体库入口按钮，文本占位区块呈现输入提示。通过占位符设计，我们可以预定义可编辑布局，用户只需填充内容即可。
+
+**直接操作符合直觉**：区块界面允许用户在页面上直接操控内容。插件和主题开发者将通过构建自定义区块来支持和扩展这种体验。
+
+**定制化无需代码编辑**：传统定制方式需要复杂标记语言，而复杂标记极易出错。古腾堡让定制过程更直观可靠。开发者可提供直接渲染布局片段的定制区块（例如三栏功能网格），并明确指定用户可直接编辑的部分。这意味着用户能自主更新文本、替换图片、调整栏数，无需寻求开发者帮助，也不必担心破坏布局。
\ No newline at end of file
diff --git a/contributors/design/the-block.md b/contributors/design/the-block.md
new file mode 100644
index 0000000..7c5a24c
--- /dev/null
+++ b/contributors/design/the-block.md
@@ -0,0 +1,30 @@
+# 区块即界面
+
+古腾堡编辑器的核心在于区块概念。从技术角度看，区块既将抽象层级从单一文档提升至有意义元素的集合，又通过明确结构取代了HTML与生俱来的模糊性。
+
+对用户而言，区块允许以更统一、更易用的方式直接向站点添加任意内容、媒体或功能。“添加区块”按钮使用户能在一个界面访问完整的功能库，无需反复翻查菜单或记忆短代码。
+
+但最重要的是，古腾堡基于_直接操作_原则构建——这意味着控制元素显示方式的核心选项都_在区块本身的语境中_完成操作。这相较于传统WordPress模式是重大变革，后者往往将选项深藏在多层导航菜单中，通过间接机制控制页面元素。
+
+例如用户可以在画布的区块界面内完成添加图片、编写图注、调整宽度版式、添加环绕链接等全套操作。这一原则同样适用于“导航菜单”等复杂区块，用户能够直接添加、编辑、移动并最终完成导航栏的完整呈现。
+
+- 用户仅需掌握区块这一种界面，即可编辑站点的所有内容。用户不必编写短代码、自定义HTML或理解隐藏机制来嵌入内容
+- 古腾堡让核心功能更易被发现，减少了难以寻觅的“神秘元素”。WordPress支持大量区块和30多种嵌入内容，现在让我们提升它们的可见度
+
+## 构建区块
+
+这对设计师和开发者意味着什么？区块结构加直接操作原则意味着需要以全新思路设计WordPress组件。让我们再次审视区块的架构：
+
+
+
+### 区块内容区是主要交互界面
+
+区块内容区的占位内容可视为引导用户执行操作指令或“填空”的界面指南（后续将详述占位符概念）。由于内容区直接对应网站实际呈现效果，此处的交互最贴合直接操作原则，也最符合用户直觉。这应被视为添加和操控内容、调整显示效果的主交互界面。
+
+### 区块工具栏承载无法融入占位界面的关键选项
+
+基础区块设置并非总能融入占位符/内容界面。作为次要选项，对区块功能至关重要的配置可置于区块工具栏。虽然区块工具栏与直接操作隔了一层，但仍保持高度情境化且全屏可见，因此是理想的次要选项。
+
+### 设置侧栏仅应用于高级三级控件
+
+设置侧栏在小屏/移动设备上默认隐藏，即使在桌面视图也可能被折叠。因此不应将区块基础运营的必要功能置于此处。选择合理的默认设置，将重要操作置于区块工具栏，把侧栏视作仅高级用户可能发现的拓展区域。
\ No newline at end of file
diff --git a/contributors/documentation/README.md b/contributors/documentation/README.md
new file mode 100644
index 0000000..1830360
--- /dev/null
+++ b/contributors/documentation/README.md
@@ -0,0 +1,213 @@
+### 提示说明
+
+区块编辑器手册支持与其他WordPress手册相同的[提示样式](https://make.wordpress.org/docs/handbook/documentation-team-handbook/handbooks-style-and-formatting-guide/#formatting)。但由于区块编辑器手册文档发布位置（npm、GitHub）不同，短代码的实现方式并不理想。
+
+推荐的Markdown实现方式是使用原始HTML和`callout callout-LEVEL`类。例如：
+
+```html
+这是一个**信息**提示框。
+```
+
+可用的样式类包括：`info`、`tip`、`alert`、`warning`
+
+
+这是一个**技巧**提示框。
+
+
+
+这是一个**信息**提示框。
+
+
+
+这是一个**警示**提示框。
+
+
+
+这是一个**警告**提示框。
+
+
+
+注意：在提示框中，链接也需要使用HTML `<a href></a>`标签表示法。
+常规的链接转换不适用于提示框中的链接。
+例如，要访问"入门指南 > 创建区块"页面，GitHub中的URL是
+https://developer.wordpress.org/docs/getting-started/devenv/get-started-with-create-block.md
+但在区块编辑器手册中需要硬编码为
+https://developer.wordpress.org/block-editor/getting-started/create-block/ 才能正确链接。
+
+
+### 编辑器配置
+
+您应该配置编辑器使用Prettier自动格式化Markdown文档。完整详情请参阅[入门文档](/docs/contributors/code/getting-started-with-code-contribution.md)。
+
+使用Visual Studio Code和Prettier扩展的配置示例：
+
+```json
+"[[markdown]]": {
+ "editor.defaultFormatter": "esbenp.prettier-vscode",
+ "editor.formatOnSave": true
+},
+```
+
+
+根据您查看本文档的位置，方括号可能显示为双括号。正确格式应为单层方括号。
+
+
+### 视频嵌入
+
+区块编辑器手册中的视频需要以未公开形式托管在[WordPress YouTube频道](https://www.youtube.com/@WordPress)。此过程需要额外权限。如需帮助，请在Slack的#marketing频道中联系。
+
+视频上传到YouTube后，获取视频嵌入链接。链接格式如下：
+
+```
+https://www.youtube.com/embed/nrut8SfXA44?si=YxvmHmAoYx-BDCog
+```
+
+然后，在文档中需要嵌入视频的位置放置以下代码。请相应更新嵌入链接和视频标题。
+
+```html
+
+```
+
+
+视频应采用
+
+## 资源
+
+- [文案指南](/docs/contributors/documentation/copy-guide.md) - 为Gutenberg项目编写说明、文档或其他贡献的指南
+
+- WordPress文档团队的[语气与风格指南](https://make.wordpress.org/docs/handbook/documentation-team-handbook/tone-and-voice-guide/)
+
+# 文档贡献指南
+
+关于如何开始为古腾堡项目贡献文档的指南。
+
+## 讨论渠道
+
+[WordPress文档制作博客](https://make.wordpress.org/docs/)是获取WordPress文档最新信息的主要平台，包括公告、产品目标、会议记录、会议议程等。
+
+文档相关的实时讨论在[WordPress官方Slack](https://make.wordpress.org/chat)的`#docs`频道进行（需要注册）。文档团队的每周例会于UTC时间每周二14:00举行。
+
+古腾堡项目使用GitHub管理代码和跟踪问题。主代码库位于：[https://github.com/WordPress/gutenberg](https://github.com/WordPress/gutenberg)。如需查找可处理的文档问题，请浏览[带有文档标签的议题](https://github.com/WordPress/gutenberg/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A%22%5BType%5D+Documentation%22+)。
+
+## 文档类型
+
+古腾堡项目包含两大类文档：
+
+1. [用户文档](https://wordpress.org/documentation/article/wordpress-block-editor/)：介绍作者如何使用编辑器发布文章。要贡献用户文档，请关注文档博客或通过#docs Slack频道了解当前优先事项。
+2. [区块编辑器手册](https://developer.wordpress.org/block-editor/)：涵盖与古腾堡项目相关的所有内容，包括开发、扩展以及您正在阅读的专门针对古腾堡的贡献指南。
+
+本文档剩余部分将重点说明如何贡献区块编辑器手册。
+
+## 区块编辑器手册流程
+
+区块编辑器手册由[古腾堡项目代码库](https://github.com/WordPress/gutenberg/)中`/docs/`目录的Markdown文件与软件包生成的文档共同组成。
+
+自动化任务会每隔15分钟将文档发布至[区块编辑器手册站点](https://developer.wordpress.org/block-editor/)。
+
+关于如何使用git通过拉取请求部署更改，请参阅[Git工作流程](/docs/contributors/code/git-workflow.md)文档。另可观看[视频教程](https://wordpress.tv/2020/09/02/marcus-kazmierczak-contribute-developer-documentation-to-gutenberg/)及配套的[古腾堡文档贡献幻灯片](https://mkaz.blog/wordpress/contribute-developer-documentation-to-gutenberg/)。
+
+### 手册结构
+
+手册根据文档功能类型划分为四个部分。[文档系统](https://documentation.divio.com/)详细阐述了各类文档的需求和功能，简而言之包括：
+
+- **入门教程** - 引导学习者逐步完成目标的完整课程，例如[创建区块教程](/docs/getting-started/devenv/get-started-with-create-block.md)。
+- **操作指南** - 针对完成特定小型任务的简短教程，例如[如何向区块工具栏添加按钮](/docs/how-to-guides/format-api.md)。
+- **参考指南** - API文档，纯功能说明。
+- **概念解析** - 侧重于知识学习而非具体任务的深度文档。
+
+### 模板
+
+我们提供[操作指南模板](https://raw.githubusercontent.com/WordPress/gutenberg/trunk/docs/contributors/documentation/how-to-guide-template.md)来规范指南结构。如需创建新操作指南，可复制模板中的Markdown内容开始编写。
+
+该模板基于"优质文档项目"的范例制作。如需创建高质量文档，可参考其[模板库](https://github.com/thegooddocsproject/templates)获取更多示例。
+
+### 更新文档
+
+更新现有页面的步骤：
+
+1. 检出古腾堡代码库
+2. 创建功能分支，例如`docs/update-contrib-guide`
+3. 对现有文档进行必要修改
+4. 提交更改
+5. 使用[[Type] Developer Documentation](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Developer%20Documentation)标签创建拉取请求
+
+### 创建新文档
+
+添加新文档需要配置可运行的JavaScript开发环境来构建文档，请参阅[JavaScript构建设置文档](/docs/how-to-guides/javascript/js-build-setup.md)：
+
+1. 在[docs](https://github.com/WordPress/gutenberg/tree/HEAD/docs)文件夹中创建Markdown文件，使用小写字母、无空格（如需分隔请使用连字符）及`.md`扩展名
+2. 使用markdown语法添加内容。所有文档必须包含且仅包含一个`h1`标签
+3. 在[toc.json](https://github.com/WordPress/gutenberg/blob/HEAD/docs/toc.json)层级结构中添加文档条目。格式请参考现有条目
+4. 运行`npm run docs:build`以更新`manifest.json`
+5. 将`manifest.json`与其他更新文件一并提交
+
+如果忘记运行`npm run docs:build`，您的PR将无法通过静态分析检查，因为`manifest.json`文件存在未提交的本地变更必须被提交。
+
+### 软件包文档编写
+
+软件包文档由文档工具自动生成，通过提取软件包根目录下README.md文件的内容实现。但有时将README内容拆分为更易读的小节更为合适。
+
+可通过在软件包中创建`docs`目录并添加`toc.json`文件来实现，该文件包含对`docs`目录下其他markdown文件的引用。`toc.json`文件应包含要作为主README文件子页面添加的页面数组，其格式遵循自动生成的[`manifest.json`](https://github.com/WordPress/gutenberg/blob/HEAD/docs/manifest.json)文件。
+
+为确保这些页面嵌套在主软件包名称下，请正确设置`parent`属性。以下示例展示了如何为[`@wordpress/create-block`章节](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/)添加子页面：
+
+```json
+[
+ {
+ "title": "@wordpress/create-block 外部模板",
+ "slug": "packages-create-block-external-template",
+ "markdown_source": "../packages/create-block/docs/external-template.md",
+ "parent": "packages-create-block"
+ }
+]
+```
+
+### 链接使用规范
+
+在某些情况下可能需要链接到其他内部文档页面。需要重点说明的是，所有文档可在不同上下文中浏览：
+
+- 区块编辑器手册
+- GitHub网站
+- npm网站
+
+要创建适用于所有上下文的链接，必须使用不带`https://github.com/WordPress/gutenberg`前缀的绝对路径链接。可通过以下模式引用文件：
+
+- `/docs/*.md`
+- `/packages/*/README.md`
+- `/packages/components/src/**/README.md`
+
+这样就能在上述三种上下文中正确处理链接。
+
+请使用Gutenberg代码库中的完整目录和文件名（而非发布路径）；区块编辑器手册会生成短链接——您可以在教程部分看到这一点。同样地，手册中会省略`readme.md`部分，但链接中应包含该部分。
+
+例如，本页面的链接为：`/docs/contributors/documentation/README.md`
+
+16:9宽高比，并以最高分辨率拍摄。
+
+注意：常规链接转换不适用于标注框内的链接。详见下文。
+
+
+### 代码示例规范
+
+Markdown中的代码示例应使用三个反引号```` ``` ````包裹，并需包含语言标识符。请参阅[GitHub关于代码块的文档](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks)。
+
+Gutenberg文档的独特功能是`codetabs`切换器，可同时显示两个版本的代码，常用于展示`JSX`和`Plain`代码示例。
+
+以下是`codetabs`章节的示例：
+
+````md
+ \{\% codetabs \%\}
+ \{\% JSX \%\}
+ ```js
+ // JSX代码示例
+ ```
+ \{\% Plain \%\}
+ ```js
+ // 原生代码示例
+ ```
+ \{\% end \%\}
+````
+
+代码示例的首选格式是JSX，这应作为默认视图。源代码中排在第一的示例将作为默认显示。
+
+**注意：** 并非每个指南都需要提供原生JavaScript代码示例。建议仅为入门教程或简短示例提供原生代码，但Gutenberg软件包及更广泛的React和JavaScript生态系统中的大多数代码都采用需要构建过程的JSX格式。
\ No newline at end of file
diff --git a/contributors/documentation/copy-guide.md b/contributors/documentation/copy-guide.md
new file mode 100644
index 0000000..484dbbd
--- /dev/null
+++ b/contributors/documentation/copy-guide.md
@@ -0,0 +1,294 @@
+# 文案撰写指南
+
+## 长文本规范
+
+适用于编写多行/多步骤说明，或对页面功能进行叙述性引导的规范。
+
+具体内容会随语境变化，但以下通用建议可供参考：
+
+#### 第一：善用缩写形式！
+
+缩写更符合对话习惯，能轻松让文本显得亲切自然（同时还能节省篇幅：可谓双赢）。
+
+#### 第二：删减冗余表达
+
+以下两种情形常出现堆砌词藻却不表意的情况：
+
+首先是使用被动语态时：
+> 该区块可用于展示单张图片。
+
+当看到“可用于”“被用于”等表述时需警惕：你正在使用被动语态。改用主动语态能让句子更简洁有力：
+> 该区块展示单张图片。
+
+其次是回避明确断言而使用模糊表述时：
+> 图库区块可帮助您以优雅布局展示多张图片。
+
+到底能不能？既然是我们开发的软件，就应该明确说明其功能：
+> 图库区块以优雅布局展示多张图片。
+
+“允许您”这个短语也常被滥用：
+> 预格式化文本允许您保留制表符和换行符。
+
+功能本身并不“允许”用户操作，它们只是实现特定目标的工具。直接说明其作用即可：
+> 预格式化文本会保留制表符和换行符。
+
+更直接的表述往往更清晰。建议在审校时重点检查“可以”“能够”“可能”“允许您”“帮助”等高频冗余词，这些都是需要精简表述的常见信号。
+
+#### 第三：慎用“简单”“便捷”“只需”
+
+我们无权定义何为简单——这应由用户判定。若宣称某项操作简单，而用户实际体验却并非如此，会削弱用户对我们及产品的信任。“只需”同样如此——许多人知道避免使用“简单”，却频繁使用“只需”。“只需点击这里”“只需输入用户名”，这种表述暗示操作轻而易举，但我们无法预知用户可能遇到的困难。
+
+具体说明往往更安全有效。“简单”和“便捷”常是我们未充分解释的托辞。遇到这些词时，请思考它们替代的具体含义。例如“按回车键添加区块很简单”实际想表达的是“您无需将手离开键盘即可为页面添加内容”。既然如此，何不直接说明具体优势？
+
+当然并非要完全禁用这些词汇。当描述封面图区块需要更少配置，或介绍快速创建自定义区块工具时，完全可以说“封面图区块已简化”或“我们正让自定义区块创建更便捷”——此时这些词是相对且描述性的。重点是要避免将其用作绝对断言，并借机提供更具体明确的说明。
+
+#### 第四：警惕“我们”滥用
+
+当文本频繁出现“我们”，意味着焦点偏离了软件使用者而转向开发者。虽然有时确需如此，但多数情况下，重点应始终围绕用户需求及其获得的价值，而非“我们的成果”或“我们的意图”。
+
+只有我们自己在意这些；用户要的只是好用的软件。若发现文本中“我们”频现，请考虑将表述重构为聚焦用户获益与成功体验。
+
+#### 五、注意字母大小写规范
+
+标题和副标题有两种书写格式：
+
+**标题格式**：每个单词的首字母大写
+**句子格式**：仅句首单词首字母大写
+
+功能名称和仪表板区域通常采用标题格式（如"站点统计"或"最新发布"），而功能标签则多使用句子格式（如"显示按钮"或"评论点赞功能"——其中"点赞"因作为功能名称需首字母大写，但整体标签仍遵循句子格式）。
+
+当处理整页界面文本时，请确保同类文本（标题、工具提示、按钮等）保持统一的大小写规范。
+
+## 错误信息撰写指南
+
+如何编写清晰实用的错误信息
+
+#### 一、重视错误信息中的语气与语调——它们传递着重要信息
+
+语气语调传递的信息量不亚于文字本身。错误信息需要承载大量信息且通常要求简洁，但切忌牺牲语调的平衡，避免走向负面苛责或过度乐观的极端。
+
+假设用户因权限不足无法发布文章，以下是我们应避免的表述方式：
+
+> 您的用户角色不正确。
+
+这种表述显得疏离冷漠。
+
+> 停！您无权进行此操作。
+
+这种表述带有不必要的警告意味和严厉感。
+
+> 哎呀，我们不能让您这么操作哦！
+
+这种表述显得过于轻佻。
+
+即便在错误提示中，我们仍可保持直接、积极且友善的沟通。具体如何实现？请看第二至第四条建议！
+
+#### 二、尽可能提供解决方案
+
+优秀的错误信息不应仅停留在问题告知：
+
+> 您的用户角色不正确。
+
+然后呢？为什么这很重要？我该如何解决？这条信息对我有何帮助？用户需要了解角色权限的重要性，以及如何获取相应权限来完成目标操作。若错误信息未提供指导，用户将陷入困境——如果我们不明确说明，用户很可能重复触发相同的错误。
+
+#### 三、避免为节省空间而滥用专业术语
+
+> 您的用户角色不正确。请联系站点管理员。
+
+这个版本似乎有所改进：至少指明了解决方向。
+
+但细想仍存缺陷：用户仍不清楚自身角色定位及其重要性，也不明白"站点管理员"具体指代谁、如何联系。
+
+虽然这条错误信息在技术上完全准确，但并未传递有效信息。若以理解和解决问题为目标，技术准确性未必能直接达成。
+
+"您的账号暂无文章发布权限"虽未采用用户角色界面的专业术语，但清晰说明了问题症结，即使用户不了解"用户角色"概念也能理解。基于这种认知，即使提示信息止步于此，用户也能意识到需要申请权限。
+
+与现有界面术语保持一致固然重要，但绝不能以牺牲理解为代价。
+
+#### 四、切勿假定用户理解错误来源
+
+> 您的用户角色不正确。
+
+在我们看来，用户显然是在尝试发布内容或修改无权限设置时触发此提示。但对用户而言未必如此：用户往往会频繁点击操作，特别是在不确定如何完成某项任务时，未必能立即记起前序操作页面或设置项（及其意图）。
+
+优秀的错误信息应包含引导用户的上下文提示。"您的账号暂无文章发布权限"既提醒了用户尝试发布文章的操作意图，也明确了触发错误的具体障碍所在。
+
+## 项目符号列表
+
+（顾名思义）撰写项目符号列表的指南
+
+#### 第一：保持所有条目句式结构平行
+
+平行结构能让列表更便于快速阅读——其可预测性能减轻读者的认知负担。
+
+**优秀范例：**
+> 这个区块能实现什么功能？应有尽有！
+>
+> - 添加引用内容
+> - 高亮心仪链接
+> - 展示多张图片
+> - 创建项目符号列表
+
+每个条目都是完整句子并以句号结尾（若列表均为单字或双字条目，通常可合并为常规单句——既提升可读性又节省空间）。每行皆以动词开头说明区块功能，且主语始终指向用户。用户能快速理解此列表，因为读完首条后即可掌握后续内容的阅读逻辑与信息类型。
+
+**欠佳示例：**
+> 这个区块能实现什么功能？应有尽有！
+>
+> - 您可以添加引用内容
+> - 高亮您喜欢的链接
+> - 它能展示多张图片，很适合创建相册！
+> - 项目符号列表
+
+本例中各行表述方式各异（有的以动词开头，有的以名词开头），句子主语不断切换（时而用户，时而区块），部分条目附加说明而部分没有，存在不完整句子且标点使用不统一。阅读此类列表需要耗费更多精力，因为读者必须逐条解析内容，无法预判各条目信息结构。
+
+注意：这并非要求每个条目都必须简短且以行为动词开头！“可预测”不等于“简单化”，核心在于保持一致的句式结构。以下示例同样符合规范：
+> 这个区块能实现什么功能？应有尽有！
+>
+> - 尝试添加引用——有时他人的表述更为精妙！
+> - 用它高亮心仪链接，链接分享可是互联网的硬通货
+> - 创建展示多图的美术馆，尽情呈现您的摄影佳作
+
+本例中各条目以更具用户视角的动词开头，并辅以补充信息增强趣味性。标点符号的灵活运用避免了刻板感，但由于基本结构一致，仍保持良好可读性。
+
+#### 第二：犹豫不决时，以动词启句（但无需固守同一动词）
+
+必须使用动词开头吗？非也。但若举棋不定，选择动词开头通常稳妥（尤其当列表描述系列动作或可选操作时）。在纯粹的操作说明中（如需要用户做出选择的界面文案），所有条目使用相同动词开头并无不可：
+
+> 请选择后续操作：
+>
+> - 添加纯文本区块
+> - 添加引文区块
+> - 添加图片区块
+
+若列表更具说服性质（如通过列举优势引导功能使用）或包含多步骤说明，则应变换动词以生动语言吸引读者：
+
+> 这个区块能实现什么功能？应有尽有！
+>
+> - 尝试添加引用——有时他人的表述更为精妙！
+> - 用它高亮心仪链接，链接分享可是互联网的硬通货
+> - 创建展示多图的美术馆，尽情呈现您的摄影佳作
+
+这些并非铁律——例如在说服性列表中，为增强聚焦性与冲击力亦可使用相同动词。但上述原则确是构建优质列表的基石。
+
+#### 第三：当内容明显是列表时，无需刻意声明
+
+**优秀范例：**
+> 这个区块能实现什么功能？应有尽有！
+>
+> - 添加引用内容
+> - 高亮心仪链接
+> - 展示多张图片
+
+**欠佳示例：**
+> 这个区块能实现什么功能？应有尽有！以下是部分使用场景示例：
+>
+> - 您可以添加引用内容
+> - 高亮您喜欢的链接
+> - 它能展示多张图片，很适合创建相册！
+
+要在极致清晰与信任用户之间找到平衡。一方面我们深知用户未必细读说明，另一方面冗余提示又易让用户产生被低估智商的感受。
+
+#### 四、善用粗体突出重点
+
+在项目符号列表中，粗体能引导读者关注核心信息。当列表项包含补充性次要内容时，这种方法尤为有效。
+
+“关键信息”是精髓所在：粗体自带视觉引力，因此请始终聚焦每个列表项中最核心的内容：
+
+> 这个区块有哪些功能？应有尽有！
+>
+> - 尝试插入**引述**——有时他人的精辟见解最值得分享
+> - 用它高亮你钟爱的**链接**——分享链接是互联网的硬通货
+> - 创建展示多张图片的**相册**，尽情呈现你的摄影佳作
+
+反之，过度使用粗体会造成视觉混乱：
+
+> **这个区块有哪些功能？** 应有尽有！
+>
+> - 尝试插入**引述**——有时他人的精辟见解最值得分享
+> - 用它高亮你钟爱的**链接**——分享**链接**是互联网的硬通货
+> - 创建展示**多张图片**的**相册**，尽情呈现你的最佳**摄影作品**
+
+当列表简短基础时，无需使用粗体——徒增冗余：
+
+> 这个区块有哪些功能？应有尽有！
+>
+> - 插入**引述**
+> - 高亮**链接**
+> - 展示多张**图片**
+
+简洁的表述自带聚焦效果，无需额外强调。
+
+## 界面描述指南
+
+撰写功能简介或选项说明的单行文本规范
+
+#### 一、清晰至上！
+
+若用户无法理解选择某项功能将实现什么效果，再巧妙的双关语也毫无意义。文字游戏和俚语往往表意模糊，容易引发误解。如确需使用，应仅作为补充信息——绝不可用于解释核心功能——且必须确保能被广泛理解。
+
+#### 二、呼应首章原则，警惕冗余表达
+
+主动语态通常更优，在有限的界面空间里，精简表达对用户快速决策至关重要。以下对比可见如何通过精简实现更清晰的指引：
+
+> 当您点击X时，将会触发Y效果
+
+对比
+
+> 点击X即可实现Y
+
+虽然补充说明看似能引导用户，实则模糊了核心信息：
+
+> 当您点击“设置”按钮时，弹窗将显示所有可用的高级设置
+
+对比
+
+> 点击“设置”访问高级选项
+
+类似冗余表达还有“当您完成X后…”或“若需实现X…”。虽然在用户需要决策路径时后者确有必要，但多数情况下，“要实现X…”的简洁表达更为高效。
+
+#### 三、明确具体
+
+当操作需要前置条件时，必须明确说明具体要求及后续效果。避免使用“当您准备就绪时”这类模糊表述——准备什么？需具体说明前提条件。
+
+“准备就绪”可能指：
+- 当需要添加新内容区块时
+- 当对文章内容满意时
+- 完成文章校对后
+- 当需要设置特色图片时
+- 完成所有参数配置后
+
+包罗万象的表述实则毫无意义。指引越具体，实用性越强，用户对产品的信任度也越高。
+
+#### 四、保留文字温度
+
+虽以清晰为首要原则，且界面空间有限，但说明文字仍可保有感染力。
+
+单行描述也应保持完整句式：
+> 列表。支持编号与符号形式
+
+对比
+
+> 添加列表，可选择编号或符号样式
+
+适当使用缩略形式：
+> 添加列表。系统将提供格式选项
+
+对比
+
+> 添加符号列表——我们会提供格式选项
+
+善用标点构建语言节奏：
+> 列表。支持编号与符号形式
+
+对比
+
+> 添加列表——编号或符号样式任君选择
+
+坚持使用通俗表达：
+> 添加无序列表或有序列表
+
+对比
+
+> 添加列表，可选择编号或符号样式
+
+（再次强调：请勿使用文字游戏！“感染力”在界面指引中应是含蓄的——我们要的是自然的人性化表达，而非刻意的俏皮话。）
\ No newline at end of file
diff --git a/contributors/documentation/how-to-guide-template.md b/contributors/documentation/how-to-guide-template.md
new file mode 100644
index 0000000..bf454f8
--- /dev/null
+++ b/contributors/documentation/how-to-guide-template.md
@@ -0,0 +1,56 @@
+# 操作指南模板
+
+## 概述
+
+操作指南通过一系列步骤引导用户完成单个任务。本指南的重点不在于概念教学，而是旨在回答"如何实现..."这一问题。
+
+概述部分需总结问题所在，并可包含正确使用该解决方案的场景和背景信息。
+
+## 开始之前
+
+需包含前提条件和基本要求说明：
+
+- 前提条件一：WordPress开发环境
+- 前提条件二：熟悉JavaScript和Gutenberg编辑器
+- 前提条件三：自定义区块或主题
+
+在此处包含其他重要信息，例如已知问题或程序缺陷。
+
+## 分步指南
+
+本指南应包含循序渐进的指导说明。可使用代码片段、图片或截图辅助说明每个步骤。根据实际需要设置步骤数量，尽量保持每个步骤简洁明了。
+
+### 步骤一：[可选标题]
+
+阐述第一步操作的简要说明。
+
+### 步骤二：[可选标题]
+
+有序列表的引导语句：
+
+1. 子步骤A
+2. 子步骤B
+3. 子步骤C
+
+### 步骤三：[可选标题]
+
+代码片段的解释说明。例如：
+
+```shell
+npm install
+npm run build
+```
+
+## 故障排除
+
+- 可能出现哪些问题？
+- 潜在错误信息及应对措施？
+
+## 结语
+
+总结已完成的步骤，说明用户达成的目标。可附上相关文章链接、更复杂的示例，或提供深入学习的途径。
+
+
\ No newline at end of file
diff --git a/contributors/folder-structure.md b/contributors/folder-structure.md
new file mode 100644
index 0000000..2a7d687
--- /dev/null
+++ b/contributors/folder-structure.md
@@ -0,0 +1,145 @@
+# 目录结构
+
+以下片段说明了 Gutenberg 代码库的组织结构，省略了不相关或显而易见的项目，并附有进一步说明：
+
+ │
+ ├── LICENSE
+ ├── README.md
+ ├── SECURITY.md
+ ├── CONTRIBUTING.md
+ │
+ ├── .editorconfig
+ ├── .eslintignore
+ ├── .eslintrc
+ ├── .jshintignore
+ ├── .eslintignore
+ ├── .prettierrc.js
+ ├── .stylelintignore
+ ├── .stylelintrc.js
+ ├── .markdownlintignore
+ ├── .npmpackagejsonlintrc.json
+ ├── phpcs.xml.dist
+ │ 用于配置代码库中各种代码检查工具（PHP、JS、样式等）的
+ │ 点文件和配置文件。
+ │
+ ├── .browserslistrc
+ ├── babel.config.js
+ ├── jsconfig.json
+ ├── tsconfig.json
+ ├── tsconfig.base.json
+ ├── webpack.config.js
+ │ 转译和打包配置文件。
+ │
+ ├── .wp-env.json
+ │ 开发和测试环境配置文件。
+ │ 包含 WordPress 和 Gutenberg 插件。
+ │
+ ├── composer.lock
+ ├── composer.json
+ │ PHP 依赖管理文件。主要用于开发工具。
+ │ 生产代码不使用外部 PHP 依赖。
+ │
+ ├── package-lock.json
+ ├── package.json
+ │ JavaScript 依赖管理文件。同时用于开发工具和生产依赖。
+ │ package.json 还用于定义日常开发中使用的常用任务和脚本。
+ │
+ ├── changelog.txt
+ ├── readme.txt
+ │ 托管在 WordPress 插件仓库中的 Gutenberg 插件的
+ │ 说明文档和更新日志。
+ │
+ ├── gutenberg.php
+ │ Gutenberg 插件的入口文件。
+ │
+ ├── post-content.php
+ │ Gutenberg 插件中用于展示编辑器的演示文章内容。
+ │
+ ├── .github/*
+ │ 各类 GitHub 功能配置（问题与 PR 模板、CI、负责人）。
+ │
+ ├── bin/api-docs
+ │ 用于生成 API 文档的工具/脚本。
+ │
+ ├── bin/packages
+ │ 用于构建 WordPress 包的脚本集合。
+ │
+ ├── bin/plugin
+ │ 用于执行 Gutenberg 插件发布和 npm 发布的工具。
+ │
+ ├── docs/tool
+ │ 用于生成区块编辑器手册 Markdown 页面的工具。
+ │
+ ├── docs/*.md
+ │ 构成[区块编辑器手册](https://developer.wordpress.org/block-editor/)的
+ │ 文档页面集合。
+ │
+ ├── platform-docs
+ │ 面向非 WordPress 开发者的文档网站，
+ │ 这些开发者在自己的应用程序中使用 Gutenberg。
+ │ 部署于 [https://wordpress.org/gutenberg-framework/](https://wordpress.org/gutenberg-framework/)。
+ │
+ │
+ ├── lib
+ │ Gutenberg 插件的 PHP 源代码。
+ │
+ ├── lib/compact/wordpress-x.x
+ │ 已包含在 WordPress X.X 版本中的 PHP 代码。
+ │ 保留该目录以确保插件与旧版 WordPress 的兼容性。
+ │
+ ├── packages
+ │ WordPress 包的源代码。
+ │ 包可分为：
+ │ - 在 WordPress 和 Gutenberg 插件中加载的生产环境 JavaScript 脚本和样式，
+ │ 或作为 npm 包分发。
+ │ - 可通过 npm 获取的开发工具。
+ │
+ ├── packages/{packageName}/package.json
+ │ 当前包的依赖项。
+ │
+ ├── packages/{packageName}/CHANGELOG.md
+ ├── packages/{packageName}/README.md
+ │
+ ├── packages/{packageName}/src/**/*.js
+ ├── packages/{packageName}/src/**/*.scss
+ │ 指定包的源代码。
+ |
+ ├── packages/{packageName}/src/**/*.test.js
+ │ JavaScript 单元测试。
+ |
+ ├── packages/{packageName}/src/**/{ComponentName}/index.js
+ │ 指定组件的入口文件。
+ |
+ ├── packages/{packageName}/src/**/{ComponentName}/style.scss
+ │ 指定组件的样式入口文件。
+ │
+ ├── packages/{packageName}/src/**/{ComponentName}/stories/*.js
+ │ 用于加载到 Gutenberg Storybook 的组件故事。
+ │
+ ├── phpunit
+ │ Gutenberg 插件 PHP 代码的单元测试。
+ │
+ ├── storybook
+ │ [Gutenberg Storybook](https://wordpress.github.io/gutenberg/) 的配置。
+ │
+ ├── test/integration
+ │ WordPress 包集成测试集合。
+ │
+ ├── test/native
+ │ Gutenberg Mobile 单元测试配置。
+ │
+ ├── test/unit
+ │ 包单元测试配置。
+ │
+ ├── test/e2e
+ │ Gutenberg 插件的端到端测试。
+ │
+ ├── test/performance
+ │ 性能指标测试。结果跟踪于
+ │ [Gutenberg 性能看板](https://codevitals.run/project/gutenberg)。
+ │
+ ├── tools/eslint
+ │ ESLint 检查工具的配置文件。
+ │
+ ├── tools/webpack
+ │ webpack 构建的配置文件。
\ No newline at end of file
diff --git a/contributors/localizing.md b/contributors/localizing.md
new file mode 100644
index 0000000..97e4632
--- /dev/null
+++ b/contributors/localizing.md
@@ -0,0 +1,11 @@
+# Gutenberg本地化指南
+
+Gutenberg插件通过通用插件翻译系统（GlotPress）进行翻译，访问地址：https://translate.wordpress.org。更多信息请参阅[GlotPress翻译流程文档](https://make.wordpress.org/polyglots/handbook/tools/glotpress-translate-wordpress-org/)。
+
+若需为您的区域或语言翻译Gutenberg，请在此处[选择对应区域设置](https://translate.wordpress.org/projects/wp-plugins/gutenberg)，然后翻译*开发版本*（包含插件字符串）和/或*开发版本说明文档*（请参考[插件页面](https://wordpress.org/plugins/gutenberg/)详情选项卡中的内容进行翻译）。
+
+具备相应权限的全局翻译编辑（GTE）或项目翻译编辑（PTE）将在适当时间内处理您的翻译内容。
+
+当某个区域设置的插件字符串翻译完成度达到95%并通过审核后，系统将自动生成语言包。
+
+随着Gutenberg被纳入WordPress核心程序，这意味着在已安装翻译版WordPress的站点中，超过51%的站点会同时将Gutenberg的翻译字符串编译至核心语言包中。
\ No newline at end of file
diff --git a/contributors/repository-management.md b/contributors/repository-management.md
new file mode 100644
index 0000000..766bd1b
--- /dev/null
+++ b/contributors/repository-management.md
@@ -0,0 +1,162 @@
+### 设计评审
+
+若您的拉取请求涉及设计/用户界面改动，请务必添加相应标签以提醒设计团队。如需申请设计评审，请在PR中添加[需要设计反馈](https://github.com/WordPress/gutenberg/labels/Needs%20Design%20Feedback)标签。若存在需要更新设计/用户界面的PR，请使用[Figma库更新](https://github.com/WordPress/gutenberg/labels/Figma%20Library%20Update)标签。
+
+需进行设计评审的变更类型指南：
+- 基于既有设计的修改，需确认设计在变更后仍然有效
+- 任何涉及视觉效果的改动
+- 针对某个创意或探索性想法希望获得设计反馈
+
+### 合并拉取请求
+
+满足以下条件的拉取请求通常可被合并：
+- 被认定对代码库具有重要价值
+- 符合所有相关代码评审标准
+- 必要时配备充分测试覆盖
+- 经过所有潜在边界情况验证
+- 已正确添加更新日志条目
+- 经过原作者以外的成员评审
+- 已[变基](/docs/contributors/code/git-workflow.md#keeping-your-branch-up-to-date)至`trunk`分支最新版本
+
+最终合并决定由 **@wordpress/gutenberg-core** 团队作出。
+
+GitHub上WordPress组织的所有成员均具备评审和合并拉取请求的权限。若您已完成PR评审并对代码质量有信心，请批准该拉取请求并通过评论提及**@wordpress/gutenberg-core**或参与该PR的核心成员。待其确认无异议后，您即可将PR合并至主干分支。
+
+多数拉取请求将自动分配发布里程碑，但请确保已合并的PR获得相应分配。此举可建立代码变更的历史沿革记录，便于所有项目参与者（包括非技术人员）追溯信息。
+
+### 关闭拉取请求
+
+某些情况下，无论投入多少额外精力（如超出范围），拉取请求可能始终无法合并。此时应在关闭PR时礼貌地与贡献者沟通说明原因，这有助于促进未来的建设性参与。
+
+请确保：
+1. 感谢贡献者投入的时间与精力
+2. 完整阐述关闭拉取请求的决策依据
+3. 尽可能提供相关支持文档链接
+
+参考沟通模板：
+> 感谢____为本次拉取请求付出的时间。
+>
+> 关闭此PR的原因是____。进一步说明，____。
+>
+> 更多详情请参阅____和____。
+
+## 团队架构
+
+本项目使用两个GitHub团队：
+- [Gutenberg核心团队](https://github.com/orgs/WordPress/teams/gutenberg-core)：由积极参与项目的成员组成，包括定期参加会议、参与问题分类会议、执行代码评审、开发功能与修复缺陷、执行插件及npm发布等。
+
+- [Gutenberg团队](https://github.com/orgs/WordPress/teams/gutenberg)：由至少完成2-3项重要项目贡献的成员组成。
+
+若您符合多项重要贡献已被代码库采纳的标准，并希望加入Gutenberg团队，欢迎在[#core-editor Slack频道](https://make.wordpress.org/chat/)提出申请。
+
+## 项目管理
+
+我们使用[GitHub项目](https://github.com/WordPress/gutenberg/projects)来追踪那些当前无需立即执行，但需要保留供未来参考的事项细节。
+
+# 代码库管理
+
+本文档为动态更新文档，旨在阐述我们如何协作管理 Gutenberg 代码库。若您希望提出修改建议，请通过提交议题进行讨论或直接向文档发起拉取请求。
+
+本文档涵盖以下内容：
+
+- [议题管理](#议题)
+ - [标签分类](#标签)
+ - [里程碑设置](#里程碑)
+ - [议题分类流程](#议题分类流程)
+- [拉取请求](#拉取请求)
+ - [代码审查](#代码审查)
+ - [设计评审](#设计评审)
+ - [合并拉取请求](#合并拉取请求)
+ - [关闭拉取请求](#关闭拉取请求)
+ - [如何让您的拉取请求获得审核？](/docs/contributors/code/how-to-get-your-pull-request-reviewed.md)
+- [项目管理](#项目)
+
+## 议题管理
+
+健康的议题列表应确保议题兼具相关性与可操作性。相关性指议题需符合项目当前优先级；可操作性则要求解决方案清晰明确。
+
+对于无关或不可操作的议题应及时关闭，以免阻碍项目进展。不妨将议题列表视作工作台：堆积的杂物越多，有效工作空间就越受限。
+
+### 标签分类
+
+所有议题需配置[一个或多个标签](https://github.com/WordPress/gutenberg/labels)。
+
+工作流标签以“Needs”开头，可根据需要灵活添加。理想情况下，每个工作流标签应有对应跟进团队（例如无障碍团队负责 `Needs Accessibility Feedback`，测试团队负责 `Needs Testing` 等）。
+
+标有[优先级-高](https://github.com/WordPress/gutenberg/labels/%5BPriority%5D%20High)与[优先级-紧急](https://github.com/WordPress/gutenberg/labels/%5BPriority%5D%20OMGWTFBBQ)的议题需指定处理人员或纳入活跃里程碑。
+
+求助类或操作指南类问题应首先发布于相关支持论坛。若不确定是否属于程序错误，支持团队或论坛志愿者将协助排查问题，为撰写有效的错误报告收集必要信息。
+
+常见标签示例：
+
+- [初试推荐](https://github.com/WordPress/gutenberg/labels/Good%20First%20Issue) - 适合新贡献者处理的议题。请通过评论申领任务，并在提交拉取请求时标注议题编号。
+- [初审推荐](https://github.com/WordPress/gutenberg/labels/Good%20First%20Review) - 适合有意参与代码审查的新贡献者处理的拉取请求。
+- [需无障碍反馈](https://github.com/WordPress/gutenberg/labels/Needs%20Accessibility%20Feedback) - 影响无障碍访问的变更需经专项审查（如标记语言修改）。
+- [需设计反馈](https://github.com/WordPress/gutenberg/labels/Needs%20Design%20Feedback) - 涉及设计或用户体验的变更需获得设计确认。
+- [[类型]程序错误](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Bug) - 现有功能存在异常。
+- [[类型]功能增强](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Enhancement) - 可提升 Gutenberg 使用体验的改进方案。
+- [[类型]插件兼容性](https://github.com/WordPress/gutenberg/labels/%5BType%5D%20Plugin%20Interoperability) - 记录 Gutenberg 与插件/扩展的冲突情况。需通知插件作者并提供解决方案文档。
+- [[状态]需补充信息](https://github.com/WordPress/gutenberg/labels/%5BStatus%5D%20Needs%20More%20Info) - 议题需补充关键信息方可推进处理，通常需要发起者配合完善。
+
+[查阅完整标签目录](https://github.com/WordPress/gutenberg/labels)获取所有标签说明。
+
+### 里程碑
+
+我们将事项归入[里程碑](https://github.com/wordpress/gutenberg/milestones)以便更好地分类。事项会被添加至以`WordPress`开头的里程碑，而拉取请求则会被添加至以`(Gutenberg)`结尾的里程碑。
+
+以下是一些您可能会看到的里程碑：
+
+- [WordPress X.Y](https://github.com/WordPress/gutenberg/milestone/70)：为未来WordPress版本需要完成的任务。
+- [X.Y (Gutenberg)](https://github.com/WordPress/gutenberg/milestone/85)：针对Gutenberg插件X.Y版本的拉取请求。
+- [未来](https://github.com/WordPress/gutenberg/milestone/35)：这是经大家一致确认为有益但不属于其他分类的事项。
+
+### 事项分类
+
+为了保持事项列表的健康状态，需要定期进行分类。_分类_是指审查现有事项，确保它们具有相关性、可操作性，并包含所有必要信息。
+
+任何人都可以帮助分类，但您需要拥有Gutenberg仓库的贡献者权限才能修改事项的标签或编辑其标题。
+
+详情请参阅[分类贡献者指南](/docs/contributors/triage.md)。
+
+## 拉取请求
+
+Gutenberg针对所有代码和文档变更采用功能分支拉取请求工作流。从高层次看，流程如下：
+
+1. 在本地检出一个新的功能分支。
+2. 进行修改，并彻底测试。
+3. 对修改满意后提交更改，并推送分支。
+4. 打开您的拉取请求。
+5. 如果您是拥有适当访问权限的常规贡献者，请正确标记和命名您的拉取请求（见下文）。
+
+关于拉取请求的标记和命名，以下指南有助于更高效、有条理地编制变更日志。这些指南对常规贡献者尤为重要。但请不要因纠结于这些细节而阻碍您分享工作——出错是难免的，且易于修正！
+
+- 处理实验性界面和功能时，应用`[Type] Experimental`标签，而非`Feature`、`Enhancement`等。
+- 为技术包（脚本、create-block、添加React钩子等）开发新功能时，应用`[Type] New API`标签，而非`Feature`、`Enhancement`等。
+- 修复项目内部工具的缺陷或进行增强时，应用`[Type] Build Tooling`标签，而非`Bugs`、`Enhancement`等。
+- 在拉取请求标题中，与其描述为修复问题所做的代码变更，不如提及实际修复的缺陷。例如：与其说“在组件中检查可为空对象”，不如说“修复点击复制块按钮时编辑器崩溃的问题”。
+
+除上述流程外，还有几点需要强调：
+
+- 重要的拉取请求应有相关事项作为前提，该事项需明确待解决的问题，并允许在实际编写代码前讨论最合适的解决方案。
+- 为使代码更易于合并，每个拉取请求应仅包含一个概念性变更。保持贡献的原子性可使拉取请求讨论聚焦于单一主题，并能够逐案审批变更。
+- 不同的拉取请求可处理其关联事项中的不同项目或待办事项，若事项较为复杂，无需单个拉取请求覆盖单个事项。
+
+### 代码审查
+
+每个拉取请求除自动测试外，还需经过人工代码审查。代码审查的目标可概括为：
+
+- **正确性**——变更是否实现了预期功能？
+- **安全性**——恶意方是否会找到利用此变更的途径？
+- **可读性**——数月后您自己能否理解此变更？
+- **优雅性**——变更在整体风格和架构中是否协调？
+- **利他性**——此变更如何为整体做出贡献？
+
+_作为审查者_，您的反馈应聚焦于想法而非个人。力求理解、保持尊重，并专注于建设性对话。
+
+_作为贡献者_，您的责任是从建议中学习，并根据反馈迭代您的拉取请求（如有需要）。力求协作，为整体做出最佳贡献。
+
+鼓励所有愿意尝试的人参与代码审查。若您审查了拉取请求并对变更充满信心，请批准它。若您觉得它尚未完全准备好合并，请添加审查意见，说明在最终批准前需要另一组人员复核。这有助于过滤明显缺陷，并简化核心成员的审查工作。关注后续审查也有助于未来提升您的审查信心。
+
+若您尚未准备好进行完整审查，可尝试在PR中评论。关于功能或变更缘由的提问同样有益。您也可以在不进行完整审查的情况下，对您理解的代码部分变更发表评论。
+
+若您在获取审查方面遇到困难，请参阅：[如何让您的拉取请求获得审查？](/docs/contributors/code/how-to-get-your-pull-request-reviewed.md)
\ No newline at end of file
diff --git a/contributors/triage.md b/contributors/triage.md
new file mode 100644
index 0000000..969b1ab
--- /dev/null
+++ b/contributors/triage.md
@@ -0,0 +1,109 @@
+## 问题关闭说明
+
+问题会基于以下原因被关闭：
+
+- 某个拉取请求（PR）和/或最新版本已解决所报告的问题。
+- 与当前已有报告重复。
+- 更适合在 WordPress.org 论坛中处理的帮助请求。
+- 无法复现的问题。
+- 需要更多信息但问题提出者超过两周未回复的情况。
+- 被判定为无法修复或当前行为符合预期的项目。
+
+## 专项分类流程
+
+### 发布专项分类
+
+以下是在版本发布期间进行分类时需遵循的指南。与常规分类不同，发布专项分类的重点在于准确识别可能阻碍发布的严重问题并推动解决方案。
+
+- **如果某个错误是在候选版本（RC）中引入，且可能严重影响多个工作流程**，请将其添加到对应版本的里程碑中，并在 WordPress.org Slack 的 [#core-editor](https://wordpress.slack.com/archives/C02QB2JS7) 频道中标记。
+- **如果错误是在最新版本中引入，且下一个候选版本尚未发布**，理想情况下开发者应在候选版本发布前修复！修复的紧迫性应与问题可能造成的破坏程度成正比。此时，请将其添加到候选版本的里程碑中，如情况紧急，可在 WordPress.org Slack 的 [#core-editor](https://wordpress.slack.com/archives/C02QB2JS7) 频道中提醒。
+- **如果错误并非在最新版本中引入**，则无需设置里程碑。取而代之的是，若问题较为紧迫，可使用如 `[Priority] High`（高优先级）等标签，必要时也可在每周的核心会议中提出关注。
+
+### 设计专项分类
+
+除了前述常规分类流程外，针对参与分类的设计相关人员，以下补充了更侧重设计视角的专项流程。
+
+- PR 测试与审查：这应是日常自主分类的首要步骤。
+- 标签 `Needs Design Feedback`（需设计反馈）：检查问题是否确实需要设计反馈，并在可能的情况下提供反馈。可按优先级、项目看板或评论数量排序处理。收集到足够意见后，请移除此标签并确定后续步骤（例如添加 `Needs Design` 标签）。
+- 标签 `Needs Design`（需设计）：问题是否真的需要设计介入？是否符合某个重点方向？若已有设计方案，请标记为 `Needs Design Feedback` 以便更好归类问题。
+
+提醒事项：
+
+- 必要时请要求提供截图。
+- 在合并前要求进行迭代并记录所有变更。
+- 若问题未在看板中，请检查其是否适用于某个特定重点方向。
+- 若问题或拉取请求尚未确定优先级，可考虑添加优先级标签以推动进展。
+
+有关每周设计分类的更多详细信息及参与方式，请[查阅本指南](https://make.wordpress.org/design/handbook/workflows/weekly-gutenberg-design-triage/)。
+
+# 问题分类
+
+为保持代码库的良好状态，需定期进行问题分类。**问题分类是指审查现有议题和拉取请求，确保它们具有相关性、可操作性且包含所有必要信息的实践**。任何人都可以协助分类，但若要对议题标签进行修改或编辑标题，您需要成为 Gutenberg 代码库分类团队的成员。
+
+> 除本页面外，[GitHub 问题分类教程](https://learn.wordpress.org/tutorial/how-to-do-triage-on-github/)也是了解分类工作的优质资源
+
+## 加入分类团队
+
+分类团队是由志愿者组成的开放团体，其专项职责是确保 Gutenberg 代码库的问题分类工作持续开展。分类工作存在多种形式：
+
+- 由成员自主安排的定期个人分类时段
+- 在固定时间组织的集体分类会议（可通过[查阅会议页面](https://make.wordpress.org/meetings/)了解这些分类会议及对应的 Slack 频道）
+- 针对特定看板、标签或功能的专项分类会议
+
+分类团队成员需符合以下期望：
+
+- 每周至少完成一次分类工作（包括自主分类）
+- 尽可能参加组织的集体分类会议
+- 若您为特定标签或看板加入分类团队，请向其他成员说明您的专注领域
+
+若您希望加入该团队，可随时在 #core-editor [Slack 频道](https://make.wordpress.org/chat/)中提出申请。
+
+## 处理首次分类任务
+
+请从以下筛选列表中选择一项开始工作（注：在[议题总页面](https://github.com/wordpress/gutenberg/issues)点击“Sort”选项即可找到大部分筛选条件）：
+
+- **所有[未贴标签的](https://github.com/WordPress/gutenberg/issues?q=is%3Aopen+is%3Aissue+no%3Alabel+sort%3Aupdated-asc) Gutenberg 议题**。通过添加标签进行分类，可帮助专注特定领域的贡献者更便捷地发现相关议题并着手处理
+- **所有[未贴标签的](https://github.com/WordPress/gutenberg/pulls?q=is%3Aopen+is%3Apr+no%3Alabel) Gutenberg 拉取请求**。此操作需具备代码基础能力，关于标签使用规范请[查阅拉取请求标注指南](/docs/contributors/repository-management.md#pull-requests)。您也可随时与拉取请求作者确认标签是否准确反映其意图
+- **[最近更新日期最早](https://github.com/WordPress/gutenberg/issues?q=is%3Aopen+is%3Aissue+sort%3Aupdated-asc)的 Gutenberg 议题**。对陈旧且可能过时的议题进行分类，可避免重要工作被遗漏
+- **所有[零评论](https://github.com/wordpress/gutenberg/issues?q=is%3Aissue+is%3Aopen+comments%3A0+)的 Gutenberg 议题**。处理此列表可确保所有议题获得关注，并识别需要补充信息或深入讨论的议题
+- **Gutenberg 中[评论数最少](https://github.com/wordpress/gutenberg/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-asc)的议题**。处理此列表有助于社区发现需要推动的提案
+- **Gutenberg 中[评论数最多](https://github.com/wordpress/gutenberg/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-desc)的议题**。若您能参与停滞的讨论，最佳处理方式是总结当前进展并明确待办事项/阻碍因素等，从而推动重要复杂议题的解决
+- 您还可**在 GitHub 上创建自定义筛选器**。若您认为某个筛选器对社区有价值，欢迎提交拉取请求将其加入本列表
+
+## 常规问题分类流程
+
+在处理问题分类时，无论是针对上述列表还是普通问题，请逐条处理。以下是针对每个问题可执行的步骤：
+
+1. 首先**搜索重复问题**。若问题重复，请评论"重复 #问题编号"并关闭，同时将相关新信息补充至现有问题中（切记同时搜索已关闭问题中的重复项！）。
+2. 若**问题缺少标签，请补充相应标签**以便更好归类（需加入分类团队后获得相应权限）。添加标签时，建议先使用带[Type]前缀的标签（如[Type]功能增强或[Type]程序错误）标明问题类型，随后可添加更具描述性的标签。若问题涉及特定核心区块，可添加[Block]前缀标签；若影响特定功能，可使用[Feature]标签。最后还有针对特定关注领域的标签，如无障碍访问和国际化。可在此处[查看所有可用标签](https://github.com/WordPress/gutenberg/labels)。
+3. 若**标题表述不够清晰，请编辑优化标题**（需相应权限）。特别建议将问题相关的主要功能置于标题开头（[示例](https://github.com/WordPress/gutenberg/issues/6193)），并尽量使标题简洁且具描述性（[示例](https://github.com/WordPress/gutenberg/issues/6193)）。
+4. 若是**错误报告，请测试确认或添加`需测试`标签**。若信息不足无法确认，请添加`[状态]需补充信息`标签并索要必要细节。若错误报告缺少重现步骤，请要求提交者补充，这对问题排查尤为重要。
+5. **及时移除不再需要的`[状态]需补充信息`标签**，例如当问题作者已提供足够详情的回复时。
+6. **若作者超过两周未回复，可备注后关闭未处理的`[状态]需补充信息`问题**。
+7. 若问题存在讨论但**未明确可执行步骤，请跟进参与者商定行动方案**。在评论中回复时务必@每位参与者。
+8. 若您有信心进一步处理问题，还可：
+ - 通过调试验证错误报告有效性，尝试定位技术细节
+ - 核查问题是否缺少细节并尝试补充（例如当错误报告缺少视觉细节时，可在本地重现问题并上传截图或GIF）
+ - 若认为该问题适合新手贡献者尝试解决，可考虑添加"新手推荐"标签
+
+**常用标签**
+
+总体而言，以下标签在问题分类中非常实用，可能是您最常使用的标签。完整标签列表可在此处[查看](https://github.com/WordPress/gutenberg/labels)。
+
+| 标签 | 适用场景 |
+| ------------------------- | ------------------------------------------------------------------------ |
+| `[类型]程序错误` | 现有功能出现故障时 |
+| `[类型]功能增强` | 针对现有功能提出改进建议时 |
+| `[类型]求助请求` | 用户咨询配置/实现相关问题时 |
+| `需技术反馈` | 出现新功能提案或API变更建议时 |
+| `需补充信息` | 问题描述不明确或需要补充细节时 |
+| `需测试` | 新问题需要确认，或旧错误可能已失效时 |
+
+**优先级标签判定**
+
+若您对当前报告有充分了解且具备判断信心，可考虑添加优先级标签。请注意，未标注优先级即表示普通级别。
+
+| 标签 | 适用场景 |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `优先级:高` | 符合当前重点方向，且导致严重使用故障（包括流程问题、视觉错误和区块故障） |
+| `优先级:低` | 非重点方向的增强功能、边缘场景错误、旧版浏览器兼容问题 |
\ No newline at end of file
diff --git a/contributors/versions-in-wordpress.md b/contributors/versions-in-wordpress.md
new file mode 100644
index 0000000..dea717d
--- /dev/null
+++ b/contributors/versions-in-wordpress.md
@@ -0,0 +1,229 @@
+```chinese
+| 4.9-5.4 | 5.2.15 |
+| 4.9-5.4 | 5.2.14 |
+| 4.9-5.4 | 5.2.13 |
+| 4.9-5.4 | 5.2.12 |
+| 4.9-5.4 | 5.2.11 |
+| 4.9-5.4 | 5.2.10 |
+| 4.9-5.4 | 5.2.9 |
+| 4.9-5.4 | 5.2.8 |
+| 4.9-5.4 | 5.2.7 |
+| 4.9-5.4 | 5.2.6 |
+| 4.9-5.4 | 5.2.5 |
+| 4.9-5.4 | 5.2.4 |
+| 4.9-5.4 | 5.2.3 |
+| 4.9-5.4 | 5.2.2 |
+| 4.9-5.4 | 5.2.1 |
+| 4.9-5.4 | 5.2 |
+| 4.8 | 5.1.19 |
+| 4.8 | 5.1.18 |
+| 4.8 | 5.1.17 |
+| 4.8 | 5.1.16 |
+| 4.8 | 5.1.15 |
+| 4.8 | 5.1.14 |
+| 4.8 | 5.1.13 |
+| 4.8 | 5.1.12 |
+| 4.8 | 5.1.11 |
+| 4.8 | 5.1.10 |
+| 4.8 | 5.1.9 |
+| 4.8 | 5.1.8 |
+| 4.8 | 5.1.7 |
+| 4.8 | 5.1.6 |
+| 4.8 | 5.1.5 |
+| 4.8 | 5.1.4 |
+| 4.8 | 5.1.3 |
+| 4.8 | 5.1.2 |
+| 4.8 | 5.1.1 |
+| 4.8 | 5.1 |
+| 4.7.1 | 5.0.22 |
+| 4.7.1 | 5.0.21 |
+| 4.7.1 | 5.0.20 |
+| 4.7.1 | 5.0.19 |
+| 4.7.1 | 5.0.18 |
+| 4.7.1 | 5.0.17 |
+| 4.7.1 | 5.0.16 |
+| 4.7.1 | 5.0.15 |
+| 4.7.1 | 5.0.14 |
+| 4.7.1 | 5.0.13 |
+| 4.7.1 | 5.0.12 |
+| 4.7.1 | 5.0.11 |
+| 4.7.1 | 5.0.10 |
+| 4.7.1 | 5.0.9 |
+| 4.7.1 | 5.0.8 |
+| 4.7.1 | 5.0.7 |
+| 4.7.1 | 5.0.6 |
+| 4.7.1 | 5.0.5 |
+| 4.7.1 | 5.0.4 |
+| 4.7.1 | 5.0.3 |
+| 4.7.0 | 5.0.2 |
+| 4.6.1 | 5.0.1 |
+| 4.6.1 | 5.0 |
+```
+
+（表格内容为版本号对应关系，无需翻译，已完整保留原始格式）
+
+# WordPress中的Gutenberg版本
+
+每个WordPress主要版本发布时，都会包含一个新的Gutenberg版本。长期以来，这给用户在调试问题和准确报告错误时带来了困惑。为简化这一过程，我们编制了本文档，作为各WordPress主要版本集成Gutenberg版本的权威对照表。需要注意的是，在WordPress测试期间，可能会根据需要引入后续Gutenberg版本中的额外错误修复。若需了解WordPress主要版本发布说明之外各Gutenberg版本的详细更新内容，请查阅[Make Core发布的版本说明](https://make.wordpress.org/core/tag/gutenberg-new/)。
+
+如发现任何错误，请在[WordPress.org Slack](https://make.wordpress.org/chat/)的#core-editor频道中提出。
+
+| Gutenberg版本 | WordPress版本 |
+| ----------------- | ------------- |
+| 19.4-20.4 | 6.8 |
+| 18.6-19.3 | 6.7.2 |
+| 18.6-19.3 | 6.7.1 |
+| 18.6-19.3 | 6.7 |
+| 17.8-18.5 | 6.6.2 |
+| 17.8-18.5 | 6.6.1 |
+| 17.8-18.5 | 6.6 |
+| 16.8-17.7 | 6.5.5 |
+| 16.8-17.7 | 6.5.4 |
+| 16.8-17.7 | 6.5.3 |
+| 16.8-17.7 | 6.5.2 |
+| 16.8-17.7 | 6.5 |
+| 16.2-16.7 | 6.4.4 |
+| 16.2-16.7 | 6.4.5 |
+| 16.2-16.7 | 6.4.3 |
+| 16.2-16.7 | 6.4.2 |
+| 16.2-16.7 | 6.4.1 |
+| 16.2-16.7 | 6.4 |
+| 15.2-16.1 | 6.3.5 |
+| 15.2-16.1 | 6.3.4 |
+| 15.2-16.1 | 6.3.3 |
+| 15.2-16.1 | 6.3.2 |
+| 15.2-16.1 | 6.3.1 |
+| 15.2-16.1 | 6.3 |
+| 14.2-15.1 | 6.2.6 |
+| 14.2-15.1 | 6.2.5 |
+| 14.2-15.1 | 6.2.4 |
+| 14.2-15.1 | 6.2.3 |
+| 14.2-15.1 | 6.2.2 |
+| 14.2-15.1 | 6.2.1 |
+| 14.2-15.1 | 6.2 |
+| 13.1-14.1 | 6.1.7 |
+| 13.1-14.1 | 6.1.6 |
+| 13.1-14.1 | 6.1.5 |
+| 13.1-14.1 | 6.1.4 |
+| 13.1-14.1 | 6.1.3 |
+| 13.1-14.1 | 6.1.2 |
+| 13.1-14.1 | 6.1.1 |
+| 13.1-14.1 | 6.1 |
+| 12.0-13.0 | 6.0.9 |
+| 12.0-13.0 | 6.0.8 |
+| 12.0-13.0 | 6.0.7 |
+| 12.0-13.0 | 6.0.6 |
+| 12.0-13.0 | 6.0.5 |
+| 12.0-13.0 | 6.0.4 |
+| 12.0-13.0 | 6.0.3 |
+| 12.0-13.0 | 6.0.2 |
+| 12.0-13.0 | 6.0.1 |
+| 12.0-13.0 | 6.0 |
+| 10.8-11.9 | 5.9.10 |
+| 10.8-11.9 | 5.9.9 |
+| 10.8-11.9 | 5.9.8 |
+| 10.8-11.9 | 5.9.7 |
+| 10.8-11.9 | 5.9.6 |
+| 10.8-11.9 | 5.9.5 |
+| 10.8-11.9 | 5.9.4 |
+| 10.8-11.9 | 5.9.3 |
+| 10.8-11.9 | 5.9.2 |
+| 10.8-11.9 | 5.9.1 |
+| 10.8-11.9 | 5.9 |
+| 10.0-10.7 | 5.8.10 |
+| 10.0-10.7 | 5.8.9 |
+| 10.0-10.7 | 5.8.8 |
+| 10.0-10.7 | 5.8.7 |
+| 10.0-10.7 | 5.8.6 |
+| 10.0-10.7 | 5.8.5 |
+| 10.0-10.7 | 5.8.4 |
+| 10.0-10.7 | 5.8.3 |
+| 10.0-10.7 | 5.8.2 |
+| 10.0-10.7 | 5.8.1 |
+| 10.0-10.7 | 5.8 |
+| 9.3-9.9 | 5.7.12 |
+| 9.3-9.9 | 5.7.11 |
+| 9.3-9.9 | 5.7.10 |
+| 9.3-9.9 | 5.7.9 |
+| 9.3-9.9 | 5.7.8 |
+| 9.3-9.9 | 5.7.7 |
+| 9.3-9.9 | 5.7.6 |
+| 9.3-9.9 | 5.7.5 |
+| 9.3-9.9 | 5.7.4 |
+| 9.3-9.9 | 5.7.3 |
+| 9.3-9.9 | 5.7.2 |
+| 9.3-9.9 | 5.7.1 |
+| 9.3-9.9 | 5.7 |
+| 8.6-9.2 | 5.6.14 |
+| 8.6-9.2 | 5.6.13 |
+| 8.6-9.2 | 5.6.12 |
+| 8.6-9.2 | 5.6.11 |
+| 8.6-9.2 | 5.6.10 |
+| 8.6-9.2 | 5.6.9 |
+| 8.6-9.2 | 5.6.8 |
+| 8.6-9.2 | 5.6.7 |
+| 8.6-9.2 | 5.6.6 |
+| 8.6-9.2 | 5.6.5 |
+| 8.6-9.2 | 5.6.4 |
+| 8.6-9.2 | 5.6.3 |
+| 8.6-9.2 | 5.6.2 |
+| 8.6-9.2 | 5.6.1 |
+| 8.6-9.2 | 5.6 |
+| 7.6-8.5 | 5.5.15 |
+| 7.6-8.5 | 5.5.14 |
+| 7.6-8.5 | 5.5.13 |
+| 7.6-8.5 | 5.5.12 |
+| 7.6-8.5 | 5.5.11 |
+| 7.6-8.5 | 5.5.10 |
+| 7.6-8.5 | 5.5.9 |
+| 7.6-8.5 | 5.5.8 |
+| 7.6-8.5 | 5.5.7 |
+| 7.6-8.5 | 5.5.6 |
+| 7.6-8.5 | 5.5.5 |
+| 7.6-8.5 | 5.5.4 |
+| 7.6-8.5 | 5.5.3 |
+| 7.6-8.5 | 5.5.2 |
+| 7.6-8.5 | 5.5.1 |
+| 7.6-8.5 | 5.5 |
+| 6.6-7.5 | 5.4.16 |
+| 6.6-7.5 | 5.4.15 |
+| 6.6-7.5 | 5.4.14 |
+| 6.6-7.5 | 5.4.13 |
+| 6.6-7.5 | 5.4.12 |
+| 6.6-7.5 | 5.4.11 |
+| 6.6-7.5 | 5.4.10 |
+| 6.6-7.5 | 5.4.9 |
+| 6.6-7.5 | 5.4.8 |
+| 6.6-7.5 | 5.4.7 |
+| 6.6-7.5 | 5.4.6 |
+| 6.6-7.5 | 5.4.5 |
+| 6.6-7.5 | 5.4.4 |
+| 6.6-7.5 | 5.4.3 |
+| 6.6-7.5 | 5.4.2 |
+| 6.6-7.5 | 5.4.1 |
+| 6.6-7.5 | 5.4 |
+| 5.5-6.5 | 5.3.18 |
+| 5.5-6.5 | 5.3.17 |
+| 5.5-6.5 | 5.3.16 |
+| 5.5-6.5 | 5.3.15 |
+| 5.5-6.5 | 5.3.14 |
+| 5.5-6.5 | 5.3.13 |
+| 5.5-6.5 | 5.3.12 |
+| 5.5-6.5 | 5.3.11 |
+| 5.5-6.5 | 5.3.10 |
+| 5.5-6.5 | 5.3.9 |
+| 5.5-6.5 | 5.3.8 |
+| 5.5-6.5 | 5.3.7 |
+| 5.5-6.5 | 5.3.6 |
+| 5.5-6.5 | 5.3.5 |
+| 5.5-6.5 | 5.3.4 |
+| 5.5-6.5 | 5.3.3 |
+| 5.5-6.5 | 5.3.2 |
+| 5.5-6.5 | 5.3.1 |
+| 5.5-6.5 | 5.3 |
+| 4.9-5.4 | 5.2.21 |
+| 4.9-5.4 | 5.2.20 |
+| 4.9-5.4 | 5.2.19 |
+| 4.9-5.4 | 5.2.18 |
+| 4.9-5.4 | 5.2.17 |
+| 4.9-5.4 | 5.2.16 |
\ No newline at end of file
diff --git a/explanations/README.md b/explanations/README.md
new file mode 100644
index 0000000..4380006
--- /dev/null
+++ b/explanations/README.md
@@ -0,0 +1,12 @@
+# 说明
+
+## [架构](/docs/explanations/architecture/README.md)
+
+- [核心概念](/docs/explanations/architecture/key-concepts.md)
+- [数据格式与数据流](/docs/explanations/architecture/data-flow.md)
+- [模块化与WordPress包](/docs/explanations/architecture/modularity.md)
+- [区块编辑器性能](/docs/explanations/architecture/performance.md)
+- 数据模块背后的设计决策是什么？
+- [为什么选择Puppeteer作为端到端测试工具？](/docs/explanations/architecture/automated-testing.md)
+- [不同编辑器包之间有什么区别？每个包的用途是什么？](/docs/explanations/architecture/modularity.md#whats-the-difference-between-the-different-editor-packages-whats-the-purpose-of-each-package)
+- [模板与模板部件流程](/docs/explanations/architecture/full-site-editing-templates.md)
\ No newline at end of file
diff --git a/explanations/architecture/README.md b/explanations/architecture/README.md
new file mode 100644
index 0000000..1c353b2
--- /dev/null
+++ b/explanations/architecture/README.md
@@ -0,0 +1,18 @@
+# 架构
+
+让我们从宏观视角审视区块编辑器及Gutenberg代码库的架构设计与用户体验原则。
+
+## 编辑器
+
+- [核心概念](/docs/explanations/architecture/key-concepts.md)
+- [数据格式与数据流](/docs/explanations/architecture/data-flow.md)
+- [实体与撤销/重做机制](/docs/explanations/architecture/entities.md)
+- [全站编辑模板](/docs/explanations/architecture/full-site-editing-templates.md)
+- [编辑器样式体系](/docs/explanations/architecture/styles.md)
+- [性能优化](/docs/explanations/architecture/performance.md)
+
+## Gutenberg代码库
+
+- [模块化与WordPress包管理](/docs/explanations/architecture/modularity.md)
+- [代码库目录结构解析](/docs/contributors/folder-structure.md)
+- **已过时！** [为何选择Puppeteer作为端到端测试工具？](/docs/explanations/architecture/automated-testing.md)
\ No newline at end of file
diff --git a/explanations/architecture/assets/global-styles-input-output.excalidraw b/explanations/architecture/assets/global-styles-input-output.excalidraw
new file mode 100644
index 0000000..5257050
--- /dev/null
+++ b/explanations/architecture/assets/global-styles-input-output.excalidraw
@@ -0,0 +1,922 @@
+{
+ "type": "excalidraw",
+ "version": 2,
+ "source": "https://excalidraw.com",
+ "elements": [
+ {
+ "type": "rectangle",
+ "version": 69,
+ "versionNonce": 1371893668,
+ "isDeleted": false,
+ "id": "dE1I-EnEvkRXGzhdq1JtQ",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 460,
+ "y": 200,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 180,
+ "height": 100,
+ "seed": 1590887460,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [
+ {
+ "id": "whcfsZ0hp0-cjJAqlj0ob",
+ "type": "arrow"
+ },
+ {
+ "id": "sL5M8MOmbWBPiIMWJPKAv",
+ "type": "arrow"
+ },
+ {
+ "id": "iOHR_Txg1Rt_gfJPeXqZg",
+ "type": "arrow"
+ },
+ {
+ "id": "yLz66yM1_qJAWngBli08H",
+ "type": "arrow"
+ }
+ ],
+ "updated": 1643633406183
+ },
+ {
+ "type": "text",
+ "version": 153,
+ "versionNonce": 670281809,
+ "isDeleted": false,
+ "id": "5rFvoYoEiSaqNhwmlPjxf",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 500,
+ "y": 220,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 106,
+ "height": 51,
+ "seed": 1103877284,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [],
+ "updated": 1643794034400,
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "WordPress'\ntheme.json",
+ "baseline": 44,
+ "textAlign": "left",
+ "verticalAlign": "top",
+ "containerId": null,
+ "originalText": "WordPress'\ntheme.json"
+ },
+ {
+ "type": "rectangle",
+ "version": 61,
+ "versionNonce": 47826468,
+ "isDeleted": false,
+ "id": "otWLW4l8pmq6prNMU4yVj",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 700,
+ "y": 200,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 160,
+ "height": 100,
+ "seed": 1273608996,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [
+ {
+ "id": "yLz66yM1_qJAWngBli08H",
+ "type": "arrow"
+ }
+ ],
+ "updated": 1643633405414
+ },
+ {
+ "type": "text",
+ "version": 128,
+ "versionNonce": 1069768604,
+ "isDeleted": false,
+ "id": "r1nDCG4qF6PJ6TXDA8D0W",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 720,
+ "y": 220,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 100,
+ "height": 51,
+ "seed": 217970972,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [
+ {
+ "id": "yLz66yM1_qJAWngBli08H",
+ "type": "arrow"
+ }
+ ],
+ "updated": 1643633404909,
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "theme's\ntheme.json",
+ "baseline": 44,
+ "textAlign": "left",
+ "verticalAlign": "top",
+ "containerId": null,
+ "originalText": "theme's\ntheme.json"
+ },
+ {
+ "type": "rectangle",
+ "version": 161,
+ "versionNonce": 516967708,
+ "isDeleted": false,
+ "id": "uyFiLHMSH6y7H-s3quAxV",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 920,
+ "y": 40,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 200,
+ "height": 80,
+ "seed": 412676132,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [
+ {
+ "id": "rAP823QGa675R6VNN5_Fj",
+ "type": "arrow"
+ },
+ {
+ "id": "zqYpQBYVH8MUQ1gbny0DW",
+ "type": "arrow"
+ },
+ {
+ "id": "bZAzg4sYJCkziajbnNelc",
+ "type": "arrow"
+ },
+ {
+ "id": "Gf8rkiJMUzlf_neDMa8Uo",
+ "type": "arrow"
+ }
+ ],
+ "updated": 1643633370772
+ },
+ {
+ "type": "text",
+ "version": 252,
+ "versionNonce": 788243108,
+ "isDeleted": false,
+ "id": "2fO2-BoHTfIU44g9j0n-S",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 940,
+ "y": 60,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 165,
+ "height": 51,
+ "seed": 231248924,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [
+ {
+ "id": "Gf8rkiJMUzlf_neDMa8Uo",
+ "type": "arrow"
+ },
+ {
+ "id": "RXAV87dIe7h-TdMpPkj8G",
+ "type": "arrow"
+ }
+ ],
+ "updated": 1643633370772,
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "Global styles UI\nin site editor",
+ "baseline": 44,
+ "textAlign": "left",
+ "verticalAlign": "top",
+ "containerId": null,
+ "originalText": "Global styles UI\nin site editor"
+ },
+ {
+ "type": "rectangle",
+ "version": 85,
+ "versionNonce": 1702175071,
+ "isDeleted": false,
+ "id": "hewO7U2_RQB8vdU_-mPPB",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 580,
+ "y": 660,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 340,
+ "height": 100,
+ "seed": 726898972,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [
+ {
+ "id": "ccK0gnrFParTub-zbOTR2",
+ "type": "arrow"
+ },
+ {
+ "id": "eP2wDSsiTc_n6dPEvV37C",
+ "type": "arrow"
+ }
+ ],
+ "updated": 1643794081747
+ },
+ {
+ "type": "text",
+ "version": 117,
+ "versionNonce": 581323025,
+ "isDeleted": false,
+ "id": "eU8Kg0BNmsuuDOweR3g88",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 660,
+ "y": 700,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 215,
+ "height": 26,
+ "seed": 404952740,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [],
+ "updated": 1643794068178,
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "global-styles-inline-css",
+ "baseline": 18,
+ "textAlign": "left",
+ "verticalAlign": "top",
+ "containerId": null,
+ "originalText": "global-styles-inline-css"
+ },
+ {
+ "type": "text",
+ "version": 13,
+ "versionNonce": 1960935025,
+ "isDeleted": false,
+ "id": "CnDgoEZ_UKEJ24A9Y8p-H",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 597,
+ "y": 667,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 38,
+ "height": 26,
+ "seed": 2110409124,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [],
+ "updated": 1643794076348,
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "CSS",
+ "baseline": 18,
+ "textAlign": "left",
+ "verticalAlign": "top",
+ "containerId": null,
+ "originalText": "CSS"
+ },
+ {
+ "type": "rectangle",
+ "version": 134,
+ "versionNonce": 827573105,
+ "isDeleted": false,
+ "id": "ymhNrWoCwMcy97bV3wcKR",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 480,
+ "y": 440,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 600.0000000000001,
+ "height": 60,
+ "seed": 856798492,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [
+ {
+ "id": "rAP823QGa675R6VNN5_Fj",
+ "type": "arrow"
+ },
+ {
+ "id": "zqYpQBYVH8MUQ1gbny0DW",
+ "type": "arrow"
+ },
+ {
+ "id": "whcfsZ0hp0-cjJAqlj0ob",
+ "type": "arrow"
+ },
+ {
+ "id": "bZAzg4sYJCkziajbnNelc",
+ "type": "arrow"
+ },
+ {
+ "id": "sL5M8MOmbWBPiIMWJPKAv",
+ "type": "arrow"
+ },
+ {
+ "id": "3BPPljmfDBwi9j0UFo72A",
+ "type": "arrow"
+ },
+ {
+ "id": "iOHR_Txg1Rt_gfJPeXqZg",
+ "type": "arrow"
+ },
+ {
+ "id": "Vb1dPpA_zGw4ibPc2H8XD",
+ "type": "arrow"
+ },
+ {
+ "id": "4EUXGzEm8Fy3BBuebotFc",
+ "type": "arrow"
+ },
+ {
+ "id": "celRUoUyUQIT-gGhAXyEK",
+ "type": "arrow"
+ },
+ {
+ "id": "yLz66yM1_qJAWngBli08H",
+ "type": "arrow"
+ }
+ ],
+ "updated": 1643794050979
+ },
+ {
+ "type": "arrow",
+ "version": 761,
+ "versionNonce": 2121815743,
+ "isDeleted": false,
+ "id": "Vb1dPpA_zGw4ibPc2H8XD",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 779.6809331076444,
+ "y": 299.60856638674625,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 2.816506265121575,
+ "height": 132.78830939921954,
+ "seed": 1207657756,
+ "groupIds": [],
+ "strokeSharpness": "round",
+ "boundElements": [],
+ "updated": 1643794051290,
+ "startBinding": null,
+ "endBinding": {
+ "elementId": "ymhNrWoCwMcy97bV3wcKR",
+ "gap": 7.603124214034267,
+ "focus": 0.010960154267448993
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ 2.816506265121575,
+ 132.78830939921954
+ ]
+ ]
+ },
+ {
+ "type": "line",
+ "version": 116,
+ "versionNonce": 2071091108,
+ "isDeleted": false,
+ "id": "uIhYulJsyst7aUpzTX4go",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "dotted",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 340.5942201212048,
+ "y": 361.19947067946197,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 916.0579537755439,
+ "height": 0,
+ "seed": 1575735580,
+ "groupIds": [],
+ "strokeSharpness": "round",
+ "boundElements": [],
+ "updated": 1643633370772,
+ "startBinding": null,
+ "endBinding": null,
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": null,
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ 916.0579537755439,
+ 0
+ ]
+ ]
+ },
+ {
+ "type": "text",
+ "version": 57,
+ "versionNonce": 1217366463,
+ "isDeleted": false,
+ "id": "siLfF4byWfGnkekw1DNmu",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "dotted",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 380,
+ "y": 40,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 68,
+ "height": 26,
+ "seed": 941782436,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [],
+ "updated": 1643794093388,
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "INPUT",
+ "baseline": 18,
+ "textAlign": "left",
+ "verticalAlign": "top",
+ "containerId": null,
+ "originalText": "INPUT"
+ },
+ {
+ "type": "line",
+ "version": 155,
+ "versionNonce": 571458340,
+ "isDeleted": false,
+ "id": "2EOVSOSu-XvcXmsarGRNX",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "dotted",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 340.31421109884974,
+ "y": 599.7727356031537,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 916.0579537755439,
+ "height": 0,
+ "seed": 482945060,
+ "groupIds": [],
+ "strokeSharpness": "round",
+ "boundElements": [],
+ "updated": 1643633370772,
+ "startBinding": null,
+ "endBinding": null,
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": null,
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ 916.0579537755439,
+ 0
+ ]
+ ]
+ },
+ {
+ "type": "text",
+ "version": 65,
+ "versionNonce": 438071580,
+ "isDeleted": false,
+ "id": "iqUBVRUA4jHj817dlF-oa",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "dotted",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 360,
+ "y": 640,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 89,
+ "height": 26,
+ "seed": 578631196,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [],
+ "updated": 1643633370772,
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "OUTPUT",
+ "baseline": 18,
+ "textAlign": "left",
+ "verticalAlign": "top",
+ "containerId": null,
+ "originalText": "OUTPUT"
+ },
+ {
+ "type": "text",
+ "version": 160,
+ "versionNonce": 2029239972,
+ "isDeleted": false,
+ "id": "2Zb3N-iXP0MEwBqCay37k",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "dotted",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 520,
+ "y": 460,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 505,
+ "height": 26,
+ "seed": 934136228,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [],
+ "updated": 1643633370772,
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "Internal Representation (WP_Theme_JSON object)",
+ "baseline": 18,
+ "textAlign": "left",
+ "verticalAlign": "top",
+ "containerId": null,
+ "originalText": "Internal Representation (WP_Theme_JSON object)"
+ },
+ {
+ "type": "arrow",
+ "version": 694,
+ "versionNonce": 1024752273,
+ "isDeleted": false,
+ "id": "celRUoUyUQIT-gGhAXyEK",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 779.718628924312,
+ "y": 501,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 1.0791064091945373,
+ "height": 126.66251027234523,
+ "seed": 2100655268,
+ "groupIds": [],
+ "strokeSharpness": "round",
+ "boundElements": [],
+ "updated": 1643794051290,
+ "startBinding": {
+ "elementId": "ymhNrWoCwMcy97bV3wcKR",
+ "gap": 1,
+ "focus": 0.0018167083707156541
+ },
+ "endBinding": null,
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ 1.0791064091945373,
+ 126.66251027234523
+ ]
+ ]
+ },
+ {
+ "type": "rectangle",
+ "version": 179,
+ "versionNonce": 1901269284,
+ "isDeleted": false,
+ "id": "4IJppZHOQRDTcVw-pjt1z",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 920,
+ "y": 200,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 180,
+ "height": 100,
+ "seed": 1157165980,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [
+ {
+ "id": "rAP823QGa675R6VNN5_Fj",
+ "type": "arrow"
+ },
+ {
+ "id": "zqYpQBYVH8MUQ1gbny0DW",
+ "type": "arrow"
+ },
+ {
+ "id": "bZAzg4sYJCkziajbnNelc",
+ "type": "arrow"
+ },
+ {
+ "id": "3BPPljmfDBwi9j0UFo72A",
+ "type": "arrow"
+ },
+ {
+ "id": "4EUXGzEm8Fy3BBuebotFc",
+ "type": "arrow"
+ },
+ {
+ "id": "Gf8rkiJMUzlf_neDMa8Uo",
+ "type": "arrow"
+ },
+ {
+ "id": "RXAV87dIe7h-TdMpPkj8G",
+ "type": "arrow"
+ }
+ ],
+ "updated": 1643633370772
+ },
+ {
+ "type": "text",
+ "version": 289,
+ "versionNonce": 880880164,
+ "isDeleted": false,
+ "id": "CA1UwOP4UrmE6pla-3RZT",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 960,
+ "y": 220,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 100,
+ "height": 51,
+ "seed": 1509336100,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [
+ {
+ "id": "RXAV87dIe7h-TdMpPkj8G",
+ "type": "arrow"
+ }
+ ],
+ "updated": 1643633398374,
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "user's\ntheme.json",
+ "baseline": 44,
+ "textAlign": "left",
+ "verticalAlign": "top",
+ "containerId": null,
+ "originalText": "user's\ntheme.json"
+ },
+ {
+ "type": "text",
+ "version": 84,
+ "versionNonce": 773068836,
+ "isDeleted": false,
+ "id": "loyhrrk-dULHcklwEwSld",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "dotted",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 360,
+ "y": 380,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 118,
+ "height": 26,
+ "seed": 1415224092,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElements": [],
+ "updated": 1643633370773,
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "INTERNALS",
+ "baseline": 18,
+ "textAlign": "left",
+ "verticalAlign": "top",
+ "containerId": null,
+ "originalText": "INTERNALS"
+ },
+ {
+ "type": "arrow",
+ "version": 878,
+ "versionNonce": 400369375,
+ "isDeleted": false,
+ "id": "4EUXGzEm8Fy3BBuebotFc",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 1020.5557521929989,
+ "y": 301,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 0.8847309846728422,
+ "height": 129,
+ "seed": 1086156700,
+ "groupIds": [],
+ "strokeSharpness": "round",
+ "boundElements": [],
+ "updated": 1643794051290,
+ "startBinding": {
+ "elementId": "4IJppZHOQRDTcVw-pjt1z",
+ "gap": 1,
+ "focus": -0.12071261013586085
+ },
+ "endBinding": {
+ "elementId": "ymhNrWoCwMcy97bV3wcKR",
+ "gap": 10.000000000000002,
+ "focus": 0.7974420373674143
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ -0.8847309846728422,
+ 129
+ ]
+ ]
+ },
+ {
+ "type": "arrow",
+ "version": 20,
+ "versionNonce": 39323804,
+ "isDeleted": false,
+ "id": "RXAV87dIe7h-TdMpPkj8G",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 1020.9070453807711,
+ "y": 120.28604858589358,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 0.9070453807711374,
+ "height": 59.71395141410642,
+ "seed": 748070564,
+ "groupIds": [],
+ "strokeSharpness": "round",
+ "boundElements": [],
+ "updated": 1643633370773,
+ "startBinding": {
+ "elementId": "2fO2-BoHTfIU44g9j0n-S",
+ "focus": 0.012843458210903786,
+ "gap": 9.286048585893582
+ },
+ "endBinding": {
+ "elementId": "4IJppZHOQRDTcVw-pjt1z",
+ "focus": 0.09846585725336464,
+ "gap": 20
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ -0.9070453807711374,
+ 59.71395141410642
+ ]
+ ]
+ },
+ {
+ "type": "arrow",
+ "version": 897,
+ "versionNonce": 44630129,
+ "isDeleted": false,
+ "id": "yLz66yM1_qJAWngBli08H",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 540.1474954442242,
+ "y": 301,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 3.013965627388984,
+ "height": 131.59259259259267,
+ "seed": 1185633948,
+ "groupIds": [],
+ "strokeSharpness": "round",
+ "boundElements": [],
+ "updated": 1643794051290,
+ "startBinding": {
+ "elementId": "dE1I-EnEvkRXGzhdq1JtQ",
+ "gap": 1,
+ "focus": 0.1209125431173364
+ },
+ "endBinding": {
+ "elementId": "ymhNrWoCwMcy97bV3wcKR",
+ "gap": 7.407407407407392,
+ "focus": -0.7848083884682261
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ 3.013965627388984,
+ 131.59259259259267
+ ]
+ ]
+ }
+ ],
+ "appState": {
+ "gridSize": 20,
+ "viewBackgroundColor": "#ffffff"
+ },
+ "files": {}
+}
\ No newline at end of file
diff --git a/explanations/architecture/assets/global-styles-input-output.png b/explanations/architecture/assets/global-styles-input-output.png
new file mode 100644
index 0000000..ecfcdc6
Binary files /dev/null and b/explanations/architecture/assets/global-styles-input-output.png differ
diff --git a/explanations/architecture/assets/modules.excalidraw b/explanations/architecture/assets/modules.excalidraw
new file mode 100644
index 0000000..86f168e
--- /dev/null
+++ b/explanations/architecture/assets/modules.excalidraw
@@ -0,0 +1,1946 @@
+{
+ "type": "excalidraw",
+ "version": 2,
+ "source": "https://excalidraw.com",
+ "elements": [
+ {
+ "type": "rectangle",
+ "version": 360,
+ "versionNonce": 330848466,
+ "isDeleted": false,
+ "id": "lUtT4B0Dcbh1jZWTf-Pmx",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 538,
+ "y": -24,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 296.99999999999994,
+ "height": 184,
+ "seed": 42288654,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [
+ "QLn4BR5QLdchLbbb7y3fb",
+ "TzpUf-tsg6VY1wgAzUtsW"
+ ]
+ },
+ {
+ "type": "text",
+ "version": 241,
+ "versionNonce": 1697895758,
+ "isDeleted": false,
+ "id": "h4SvuiM0FqPyeGvKT_Cgq",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 634,
+ "y": 42,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 110,
+ "height": 50,
+ "seed": 2011405010,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "WordPress \nREST API",
+ "baseline": 43,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "rectangle",
+ "version": 305,
+ "versionNonce": 412708498,
+ "isDeleted": false,
+ "id": "McdqQdNimFO5S_blWnGqe",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 608.5,
+ "y": 239,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 181,
+ "height": 134,
+ "seed": 791925842,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [
+ "QLn4BR5QLdchLbbb7y3fb",
+ "TzpUf-tsg6VY1wgAzUtsW",
+ "zBZdXkTFmJO9KXJqxovCk",
+ "KF9YfK1TYP8afMie5CvX_",
+ "80vcK5NnLsmPE0vh6TArx",
+ "dLVJH9bDssWAtSq5-YWqQ",
+ "9CDIL9ezNU7U6jmKxIj6S",
+ "s0syZkTZO3RyvCl68ZEKu"
+ ]
+ },
+ {
+ "type": "arrow",
+ "version": 926,
+ "versionNonce": 1807571406,
+ "isDeleted": false,
+ "id": "TzpUf-tsg6VY1wgAzUtsW",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 697.7421379211554,
+ "y": 237.62686567164178,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 1.342798060683208,
+ "height": 76.25373134328356,
+ "seed": 2056431630,
+ "groupIds": [],
+ "strokeSharpness": "round",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "McdqQdNimFO5S_blWnGqe",
+ "gap": 1.3731343283582096,
+ "focus": -0.002036659877800407
+ },
+ "endBinding": {
+ "elementId": "lUtT4B0Dcbh1jZWTf-Pmx",
+ "gap": 1.3731343283582096,
+ "focus": -0.054989816700611
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": null,
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ -1.342798060683208,
+ -76.25373134328356
+ ]
+ ]
+ },
+ {
+ "type": "rectangle",
+ "version": 1777,
+ "versionNonce": 1018720786,
+ "isDeleted": false,
+ "id": "3brGgyPnliY43-VLkQbVO",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 362,
+ "y": 502,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 184.00000000000003,
+ "height": 137,
+ "seed": 1484302030,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [
+ "qYtX-Dbe48WGy5NUs2SWN",
+ "bpFYMjIuLwNHKYoF5sP1m",
+ "zBZdXkTFmJO9KXJqxovCk",
+ "zDwPJzeKWLvw4E2gXDD7h",
+ "tF0J9QyFKzLm643LknUSp",
+ "2QB5PnOHSjpZxpfsPWK9N",
+ "d0bomk6ntAhDkzr1jutsJ",
+ "vjN8YKa1-pss_8nUBz9sE",
+ "KF9YfK1TYP8afMie5CvX_",
+ "80vcK5NnLsmPE0vh6TArx",
+ "f62E6s_57Je1ZPUXcCtX_",
+ "9CDIL9ezNU7U6jmKxIj6S",
+ "s0syZkTZO3RyvCl68ZEKu",
+ "UJjYgRCPkN8MK54EHuFBW"
+ ]
+ },
+ {
+ "type": "text",
+ "version": 956,
+ "versionNonce": 1590489102,
+ "isDeleted": false,
+ "id": "inFwWqiXEHuINtuaBxfEa",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 374,
+ "y": 560,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 168,
+ "height": 20,
+ "seed": 1576359634,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [
+ "-rW8RlMAg9krSeGI2WgDY",
+ "bpFYMjIuLwNHKYoF5sP1m"
+ ],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "@wordpress/edit-post",
+ "baseline": 14,
+ "textAlign": "center",
+ "verticalAlign": "middle"
+ },
+ {
+ "type": "rectangle",
+ "version": 985,
+ "versionNonce": 680301970,
+ "isDeleted": false,
+ "id": "pDgrhb9xTc--X-w4JYTNs",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 977,
+ "y": 820,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 187.99999999999994,
+ "height": 144,
+ "seed": 1937873106,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [
+ "zDwPJzeKWLvw4E2gXDD7h",
+ "tF0J9QyFKzLm643LknUSp",
+ "-Xd-x5jHExxdRzXBxuDgG"
+ ]
+ },
+ {
+ "type": "text",
+ "version": 353,
+ "versionNonce": 133114699,
+ "isDeleted": false,
+ "id": "MkPnoYQafrQJx2pxVJ1Yj",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 627,
+ "y": 294,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 136,
+ "height": 20,
+ "seed": 476050446,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "@wordpress/data",
+ "baseline": 14,
+ "textAlign": "center",
+ "verticalAlign": "middle"
+ },
+ {
+ "type": "text",
+ "version": 235,
+ "versionNonce": 2104689358,
+ "isDeleted": false,
+ "id": "10Fa43h0aaCGAOmTuy4M9",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 511,
+ "y": 189,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 161,
+ "height": 20,
+ "seed": 928272786,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "@wordpress/apiFetch",
+ "baseline": 14,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "text",
+ "version": 1035,
+ "versionNonce": 156096786,
+ "isDeleted": false,
+ "id": "dkdIk6pT4WXxVzPRoShAL",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 987,
+ "y": 885,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 171,
+ "height": 18.387096774193544,
+ "seed": 1424271950,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 14.709677419354838,
+ "fontFamily": 1,
+ "text": "@wordpress/block-editor",
+ "baseline": 12.387096774193544,
+ "textAlign": "center",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "text",
+ "version": 546,
+ "versionNonce": 2036521554,
+ "isDeleted": false,
+ "id": "UvOX7k0ZNJko4MmagViJb",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 345,
+ "y": 244,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 69,
+ "height": 60,
+ "seed": 436020174,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "retrieve \nedited\n post",
+ "baseline": 54,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "rectangle",
+ "version": 1778,
+ "versionNonce": 947372050,
+ "isDeleted": false,
+ "id": "HDpe1eQvOQBy-DQ-08BAe",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 256,
+ "y": 820.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 184.00000000000003,
+ "height": 137,
+ "seed": 780465742,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [
+ "qYtX-Dbe48WGy5NUs2SWN",
+ "-rW8RlMAg9krSeGI2WgDY",
+ "bpFYMjIuLwNHKYoF5sP1m",
+ "9yv_MGYQYvx5-mDLvir57",
+ "losiO7bv6zt5N836LnRRO"
+ ]
+ },
+ {
+ "type": "text",
+ "version": 1561,
+ "versionNonce": 2079425038,
+ "isDeleted": false,
+ "id": "m4OzW-ennijYUZh1fXM_Z",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 278,
+ "y": 876,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 142,
+ "height": 20,
+ "seed": 227576274,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "@wordpress/blocks",
+ "baseline": 14,
+ "textAlign": "center",
+ "verticalAlign": "middle"
+ },
+ {
+ "type": "text",
+ "version": 1216,
+ "versionNonce": 995124114,
+ "isDeleted": false,
+ "id": "HJmrroFIvv3NtW-04tPnv",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 453,
+ "y": 806,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 160,
+ "height": 40,
+ "seed": 353140818,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [
+ "-rW8RlMAg9krSeGI2WgDY"
+ ],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "parse post content \nas blocks",
+ "baseline": 34,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "arrow",
+ "version": 997,
+ "versionNonce": 1664158478,
+ "isDeleted": false,
+ "id": "zDwPJzeKWLvw4E2gXDD7h",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 802.1288386374247,
+ "y": 873.2154561884701,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 162,
+ "height": 0.835325367748851,
+ "seed": 841320402,
+ "groupIds": [],
+ "strokeSharpness": "round",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "IbjzKI7nkNZcIk0emr1CM",
+ "focus": -0.2525685281587491,
+ "gap": 11.128838637424678
+ },
+ "endBinding": {
+ "elementId": "aQhRkVVPjCbceVVmXJAqr",
+ "focus": -1.3049652210649765,
+ "gap": 7.050781556218908
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ 162,
+ 0.835325367748851
+ ]
+ ]
+ },
+ {
+ "type": "text",
+ "version": 667,
+ "versionNonce": 1820554450,
+ "isDeleted": false,
+ "id": "aQhRkVVPjCbceVVmXJAqr",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 804,
+ "y": 827,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 160,
+ "height": 40,
+ "seed": 105484306,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [
+ "zDwPJzeKWLvw4E2gXDD7h"
+ ],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "render block list to \nedit parsed content",
+ "baseline": 34,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "arrow",
+ "version": 744,
+ "versionNonce": 658012494,
+ "isDeleted": false,
+ "id": "tF0J9QyFKzLm643LknUSp",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 963.1446744404734,
+ "y": 917.3370618394133,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 164.4152128934861,
+ "height": 0.9076979169312835,
+ "seed": 2061209550,
+ "groupIds": [],
+ "strokeSharpness": "round",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "pDgrhb9xTc--X-w4JYTNs",
+ "gap": 13.855325559526591,
+ "focus": -0.34117533294611724
+ },
+ "endBinding": {
+ "elementId": "IbjzKI7nkNZcIk0emr1CM",
+ "gap": 7.729461546987295,
+ "focus": 0.38320132234349474
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ -164.4152128934861,
+ 0.9076979169312835
+ ]
+ ]
+ },
+ {
+ "type": "text",
+ "version": 732,
+ "versionNonce": 1637943954,
+ "isDeleted": false,
+ "id": "N6ghE6kmiiSIw-G2RF4cR",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 827,
+ "y": 926,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 102,
+ "height": 20,
+ "seed": 1489153550,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "edited blocks",
+ "baseline": 14,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "rectangle",
+ "version": 530,
+ "versionNonce": 1287135118,
+ "isDeleted": false,
+ "id": "ABPY44UfhcdQ5WnUXgCE9",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 159.5,
+ "y": -24,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 296.99999999999994,
+ "height": 184,
+ "seed": 572741266,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [
+ "QLn4BR5QLdchLbbb7y3fb",
+ "TzpUf-tsg6VY1wgAzUtsW",
+ "U0zFx--iW_PEJin8uKAPt",
+ "vjN8YKa1-pss_8nUBz9sE"
+ ]
+ },
+ {
+ "type": "text",
+ "version": 354,
+ "versionNonce": 91470955,
+ "isDeleted": false,
+ "id": "q_7-RjILSxs3tZuaDB5jH",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 268,
+ "y": 69,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 78,
+ "height": 25,
+ "seed": 1690690322,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "post.php",
+ "baseline": 18,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "text",
+ "version": 391,
+ "versionNonce": 629739026,
+ "isDeleted": false,
+ "id": "XDocQzG8AkRvf6lr9JtEc",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 263,
+ "y": 34,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 79,
+ "height": 25,
+ "seed": 1339152270,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 20,
+ "fontFamily": 1,
+ "text": "WPAdmin",
+ "baseline": 18,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "arrow",
+ "version": 1564,
+ "versionNonce": 317075858,
+ "isDeleted": false,
+ "id": "vjN8YKa1-pss_8nUBz9sE",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 308.04521862589274,
+ "y": 162.98092819589388,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 38.95472061044086,
+ "height": 382.9225584793661,
+ "seed": 2041473806,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "ABPY44UfhcdQ5WnUXgCE9",
+ "focus": 0.011258377745750744,
+ "gap": 2.980928195893881
+ },
+ "endBinding": {
+ "elementId": "3brGgyPnliY43-VLkQbVO",
+ "focus": 0.44833062939390156,
+ "gap": 15.000060763666397
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ 6.998887874642407,
+ 382.9225584793661
+ ],
+ [
+ 38.95472061044086,
+ 380.9229339041349
+ ]
+ ]
+ },
+ {
+ "type": "text",
+ "version": 509,
+ "versionNonce": 452782222,
+ "isDeleted": false,
+ "id": "O_dGAVA2Ad4VVa0q-TO85",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 171,
+ "y": 317,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 122,
+ "height": 40,
+ "seed": 1077528850,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "Initialize \nthe post editor",
+ "baseline": 34,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "rectangle",
+ "version": 1362,
+ "versionNonce": 1057227474,
+ "isDeleted": false,
+ "id": "IbjzKI7nkNZcIk0emr1CM",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 613,
+ "y": 819,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 178,
+ "height": 144,
+ "seed": 2127531218,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [
+ "zDwPJzeKWLvw4E2gXDD7h",
+ "tF0J9QyFKzLm643LknUSp",
+ "9yv_MGYQYvx5-mDLvir57",
+ "losiO7bv6zt5N836LnRRO",
+ "f62E6s_57Je1ZPUXcCtX_",
+ "dLVJH9bDssWAtSq5-YWqQ",
+ "d1SMxBnX-sncsVzKwbEew"
+ ]
+ },
+ {
+ "type": "text",
+ "version": 1401,
+ "versionNonce": 625986382,
+ "isDeleted": false,
+ "id": "t6Xj5NZnKRCvlxEmVINsR",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 634.5,
+ "y": 883,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 134,
+ "height": 19,
+ "seed": 1096409422,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 14.709677419354838,
+ "fontFamily": 1,
+ "text": "@wordpress/editor",
+ "baseline": 13,
+ "textAlign": "center",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "arrow",
+ "version": 45,
+ "versionNonce": 1476421188,
+ "isDeleted": false,
+ "id": "9yv_MGYQYvx5-mDLvir57",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 613,
+ "y": 859,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 171,
+ "height": 0,
+ "seed": 2012384910,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "IbjzKI7nkNZcIk0emr1CM",
+ "focus": 0.4444444444444444,
+ "gap": 1
+ },
+ "endBinding": {
+ "elementId": "HDpe1eQvOQBy-DQ-08BAe",
+ "focus": -0.43795620437956206,
+ "gap": 2
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ -171,
+ 0
+ ]
+ ]
+ },
+ {
+ "type": "arrow",
+ "version": 109,
+ "versionNonce": 1934823420,
+ "isDeleted": false,
+ "id": "losiO7bv6zt5N836LnRRO",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 610.5,
+ "y": 912,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 165.88295575603843,
+ "height": 1.157299730926752,
+ "seed": 524900050,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "IbjzKI7nkNZcIk0emr1CM",
+ "focus": -0.2979631757573413,
+ "gap": 2.5
+ },
+ "endBinding": {
+ "elementId": "HDpe1eQvOQBy-DQ-08BAe",
+ "focus": 0.30616250689753877,
+ "gap": 4.617044243961573
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ -165.88295575603843,
+ -1.157299730926752
+ ]
+ ]
+ },
+ {
+ "type": "text",
+ "version": 1264,
+ "versionNonce": 742061650,
+ "isDeleted": false,
+ "id": "zG5RvICD4F3YcU6Gps0N3",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 456.5,
+ "y": 922,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 127,
+ "height": 40,
+ "seed": 759868622,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [
+ "-rW8RlMAg9krSeGI2WgDY",
+ "bpFYMjIuLwNHKYoF5sP1m"
+ ],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "serialize blocks \nto post content",
+ "baseline": 34,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "arrow",
+ "version": 328,
+ "versionNonce": 300702738,
+ "isDeleted": false,
+ "id": "f62E6s_57Je1ZPUXcCtX_",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 553,
+ "y": 609.2283258680051,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 86.18601002588642,
+ "height": 208.08736954660247,
+ "seed": 51212302,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "3brGgyPnliY43-VLkQbVO",
+ "focus": 0.6038522340716648,
+ "gap": 7
+ },
+ "endBinding": {
+ "elementId": "IbjzKI7nkNZcIk0emr1CM",
+ "focus": -0.7057751682484675,
+ "gap": 6.912630453397469
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ 86.18601002588642,
+ -5.228325868005087
+ ],
+ [
+ 86.18601002588642,
+ 202.85904367859737
+ ]
+ ]
+ },
+ {
+ "type": "text",
+ "version": 154,
+ "versionNonce": 379889166,
+ "isDeleted": false,
+ "id": "QvLT5BI50g8KCKtxx1mb5",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 447,
+ "y": 689,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 184,
+ "height": 40,
+ "seed": 1480368786,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "Render components \nto edit post properties",
+ "baseline": 34,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "arrow",
+ "version": 137,
+ "versionNonce": 267061714,
+ "isDeleted": false,
+ "id": "dLVJH9bDssWAtSq5-YWqQ",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 717.6920056946436,
+ "y": 812.0511368080635,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 0.6920056946436262,
+ "height": 436.05113680806346,
+ "seed": 465217294,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "IbjzKI7nkNZcIk0emr1CM",
+ "focus": 0.1774945524835427,
+ "gap": 6.948863191936539
+ },
+ "endBinding": {
+ "elementId": "McdqQdNimFO5S_blWnGqe",
+ "focus": -0.19743556130360193,
+ "gap": 3
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ -0.6920056946436262,
+ -436.05113680806346
+ ]
+ ]
+ },
+ {
+ "type": "text",
+ "version": 708,
+ "versionNonce": 2139141198,
+ "isDeleted": false,
+ "id": "6CR4zY_a8ShNCI3k8WOMF",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 741.5,
+ "y": 533,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 94,
+ "height": 40,
+ "seed": 1757731730,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "make edits \nto the post",
+ "baseline": 34,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "arrow",
+ "version": 243,
+ "versionNonce": 1028521874,
+ "isDeleted": false,
+ "id": "9CDIL9ezNU7U6jmKxIj6S",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 408,
+ "y": 495,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 202,
+ "height": 220,
+ "seed": 1955539602,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "3brGgyPnliY43-VLkQbVO",
+ "focus": -0.48389621188036475,
+ "gap": 7
+ },
+ "endBinding": {
+ "elementId": "McdqQdNimFO5S_blWnGqe",
+ "focus": 0.41370761939482315,
+ "gap": 1.5
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ -3,
+ -220
+ ],
+ [
+ 199,
+ -218
+ ]
+ ]
+ },
+ {
+ "type": "arrow",
+ "version": 469,
+ "versionNonce": 104921742,
+ "isDeleted": false,
+ "id": "s0syZkTZO3RyvCl68ZEKu",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 475.0748849169114,
+ "y": 495.9067426418228,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 125.70072406543284,
+ "height": 170.74647458243362,
+ "seed": 1064223054,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "3brGgyPnliY43-VLkQbVO",
+ "focus": 0.23601826970336381,
+ "gap": 6.093257358177198
+ },
+ "endBinding": {
+ "elementId": "McdqQdNimFO5S_blWnGqe",
+ "focus": -0.32221509826026673,
+ "gap": 9.591233454271105
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ -1.866842436615339,
+ -170.74647458243362
+ ],
+ [
+ 123.8338816288175,
+ -169.1942339044115
+ ]
+ ]
+ },
+ {
+ "type": "text",
+ "version": 635,
+ "versionNonce": 910966098,
+ "isDeleted": false,
+ "id": "fH8Zs_ID5t56EDgibwfUm",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 438.5,
+ "y": 297,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 104,
+ "height": 20,
+ "seed": 1170144978,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "save changes",
+ "baseline": 14,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "rectangle",
+ "version": 2131,
+ "versionNonce": 1369340110,
+ "isDeleted": false,
+ "id": "K7VFWYXQ24D2SHN5g-xlP",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 614,
+ "y": 1215.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 184.00000000000003,
+ "height": 137,
+ "seed": 1033269326,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [
+ "qYtX-Dbe48WGy5NUs2SWN",
+ "-rW8RlMAg9krSeGI2WgDY",
+ "bpFYMjIuLwNHKYoF5sP1m",
+ "9yv_MGYQYvx5-mDLvir57",
+ "losiO7bv6zt5N836LnRRO",
+ "d1SMxBnX-sncsVzKwbEew",
+ "-Xd-x5jHExxdRzXBxuDgG",
+ "UJjYgRCPkN8MK54EHuFBW"
+ ]
+ },
+ {
+ "type": "text",
+ "version": 1919,
+ "versionNonce": 2017248018,
+ "isDeleted": false,
+ "id": "cEJxDDVp37m8WC8FZxLBE",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 616,
+ "y": 1270,
+ "strokeColor": "#000000",
+ "backgroundColor": "transparent",
+ "width": 182,
+ "height": 20,
+ "seed": 1635910546,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "@wordpress/components",
+ "baseline": 14,
+ "textAlign": "center",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "arrow",
+ "version": 180,
+ "versionNonce": 1797455300,
+ "isDeleted": false,
+ "id": "d1SMxBnX-sncsVzKwbEew",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 704,
+ "y": 966,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 2,
+ "height": 248,
+ "seed": 747964626,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "IbjzKI7nkNZcIk0emr1CM",
+ "focus": -0.02907814187972633,
+ "gap": 3
+ },
+ "endBinding": {
+ "elementId": "K7VFWYXQ24D2SHN5g-xlP",
+ "focus": -0.04931817191652507,
+ "gap": 1.5
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ -2,
+ 248
+ ]
+ ]
+ },
+ {
+ "type": "arrow",
+ "version": 307,
+ "versionNonce": 182956156,
+ "isDeleted": false,
+ "id": "-Xd-x5jHExxdRzXBxuDgG",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 1072.3109902433837,
+ "y": 965,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 370.3109902433837,
+ "height": 248,
+ "seed": 202943310,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "pDgrhb9xTc--X-w4JYTNs",
+ "gap": 1,
+ "focus": -0.027278151905208426
+ },
+ "endBinding": {
+ "elementId": "K7VFWYXQ24D2SHN5g-xlP",
+ "focus": -0.04347826086956521,
+ "gap": 2.5
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ -2.310990243383685,
+ 131
+ ],
+ [
+ -370.3109902433837,
+ 131
+ ],
+ [
+ -370.3109902433837,
+ 248
+ ]
+ ]
+ },
+ {
+ "type": "arrow",
+ "version": 350,
+ "versionNonce": 1023845700,
+ "isDeleted": false,
+ "id": "UJjYgRCPkN8MK54EHuFBW",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 362,
+ "y": 608,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 539,
+ "height": 604,
+ "seed": 145563346,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "startBinding": {
+ "elementId": "3brGgyPnliY43-VLkQbVO",
+ "focus": -0.5474452554744527,
+ "gap": 1
+ },
+ "endBinding": {
+ "elementId": "K7VFWYXQ24D2SHN5g-xlP",
+ "focus": 0.015938824396535836,
+ "gap": 3.5
+ },
+ "lastCommittedPoint": null,
+ "startArrowhead": null,
+ "endArrowhead": "arrow",
+ "points": [
+ [
+ 0,
+ 0
+ ],
+ [
+ -196,
+ 0
+ ],
+ [
+ -194,
+ 494
+ ],
+ [
+ 339,
+ 489
+ ],
+ [
+ 343,
+ 604
+ ]
+ ]
+ },
+ {
+ "type": "text",
+ "version": 429,
+ "versionNonce": 2009088910,
+ "isDeleted": false,
+ "id": "lSCQaBWN4J0WRPxYp2uoo",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 727,
+ "y": 1127,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 110,
+ "height": 60,
+ "seed": 1661316114,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 16,
+ "fontFamily": 1,
+ "text": "Use reusable \ncomponents \nto render UI",
+ "baseline": 54,
+ "textAlign": "left",
+ "verticalAlign": "top"
+ },
+ {
+ "type": "ellipse",
+ "version": 38,
+ "versionNonce": 369230930,
+ "isDeleted": false,
+ "id": "KeA708xNXTWu0pafgRJSL",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 254,
+ "y": 305,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 23,
+ "height": 22,
+ "seed": 853985042,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": []
+ },
+ {
+ "type": "text",
+ "version": 48,
+ "versionNonce": 1179427278,
+ "isDeleted": false,
+ "id": "iWMDMo2gKB4X2rL4oaalg",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 260.5,
+ "y": 305,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 11,
+ "height": 23,
+ "seed": 1544659854,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 20,
+ "fontFamily": 2,
+ "text": "1",
+ "baseline": 18,
+ "textAlign": "center",
+ "verticalAlign": "middle"
+ },
+ {
+ "type": "ellipse",
+ "version": 296,
+ "versionNonce": 195144210,
+ "isDeleted": false,
+ "id": "5md7eYYWVibRGbMVbZvgC",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 359.5,
+ "y": 305.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 23,
+ "height": 22,
+ "seed": 54788622,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": []
+ },
+ {
+ "type": "text",
+ "version": 307,
+ "versionNonce": 942880782,
+ "isDeleted": false,
+ "id": "54MK4zUZitJhJabfozstJ",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 366,
+ "y": 305.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 11,
+ "height": 23,
+ "seed": 1149201874,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 20,
+ "fontFamily": 2,
+ "text": "2",
+ "baseline": 18,
+ "textAlign": "center",
+ "verticalAlign": "middle"
+ },
+ {
+ "type": "ellipse",
+ "version": 471,
+ "versionNonce": 29792210,
+ "isDeleted": false,
+ "id": "QR0h4yeUaMYdz5Yq5lf2U",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 604.5,
+ "y": 680.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 23,
+ "height": 22,
+ "seed": 911510030,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": []
+ },
+ {
+ "type": "text",
+ "version": 483,
+ "versionNonce": 1433208398,
+ "isDeleted": false,
+ "id": "apBf80kSLTGS_xKauF78Z",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 611,
+ "y": 680.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 11,
+ "height": 23,
+ "seed": 1855677906,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 20,
+ "fontFamily": 2,
+ "text": "3",
+ "baseline": 18,
+ "textAlign": "center",
+ "verticalAlign": "middle"
+ },
+ {
+ "type": "ellipse",
+ "version": 376,
+ "versionNonce": 1216859538,
+ "isDeleted": false,
+ "id": "cEjRyNgMRhHi00kI4ZdRE",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 539.5,
+ "y": 825.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 23,
+ "height": 22,
+ "seed": 416075090,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": []
+ },
+ {
+ "type": "text",
+ "version": 388,
+ "versionNonce": 1054018702,
+ "isDeleted": false,
+ "id": "nb81f_gWryUebiJdeho5W",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 546,
+ "y": 825.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 11,
+ "height": 23,
+ "seed": 1093593294,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 20,
+ "fontFamily": 2,
+ "text": "4",
+ "baseline": 18,
+ "textAlign": "center",
+ "verticalAlign": "middle"
+ },
+ {
+ "type": "ellipse",
+ "version": 419,
+ "versionNonce": 1574637842,
+ "isDeleted": false,
+ "id": "edcEhW3EQaqK_OpY2xbM5",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 867.5,
+ "y": 797.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 23,
+ "height": 22,
+ "seed": 1463623118,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": []
+ },
+ {
+ "type": "text",
+ "version": 431,
+ "versionNonce": 1307033870,
+ "isDeleted": false,
+ "id": "2O2KjKy9AGit_YaaggTba",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 874,
+ "y": 797.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 11,
+ "height": 23,
+ "seed": 486993426,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 20,
+ "fontFamily": 2,
+ "text": "5",
+ "baseline": 18,
+ "textAlign": "center",
+ "verticalAlign": "middle"
+ },
+ {
+ "type": "ellipse",
+ "version": 493,
+ "versionNonce": 909844178,
+ "isDeleted": false,
+ "id": "YdsRRRSZ_0Ri6wogNpp6-",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 932.5,
+ "y": 922.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 23,
+ "height": 22,
+ "seed": 763406418,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": []
+ },
+ {
+ "type": "text",
+ "version": 505,
+ "versionNonce": 900230990,
+ "isDeleted": false,
+ "id": "PHeW962z041M37JQx14Yo",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 939,
+ "y": 922.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 11,
+ "height": 23,
+ "seed": 1719287246,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 20,
+ "fontFamily": 2,
+ "text": "6",
+ "baseline": 18,
+ "textAlign": "center",
+ "verticalAlign": "middle"
+ },
+ {
+ "type": "ellipse",
+ "version": 443,
+ "versionNonce": 718501010,
+ "isDeleted": false,
+ "id": "eDt_EPMgUD0nS3Sljoojc",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 581.5,
+ "y": 921.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 23,
+ "height": 22,
+ "seed": 1995643346,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": []
+ },
+ {
+ "type": "text",
+ "version": 455,
+ "versionNonce": 901338510,
+ "isDeleted": false,
+ "id": "suGGbL7s9ttjRwCvt_UoN",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 588,
+ "y": 921.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 11,
+ "height": 23,
+ "seed": 2025956430,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 20,
+ "fontFamily": 2,
+ "text": "7",
+ "baseline": 18,
+ "textAlign": "center",
+ "verticalAlign": "middle"
+ },
+ {
+ "type": "ellipse",
+ "version": 397,
+ "versionNonce": 492507730,
+ "isDeleted": false,
+ "id": "c1IOrSA3B8mc_gXboWjfO",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 843.5,
+ "y": 539.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 23,
+ "height": 22,
+ "seed": 521446354,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": []
+ },
+ {
+ "type": "text",
+ "version": 431,
+ "versionNonce": 1196651470,
+ "isDeleted": false,
+ "id": "0zWPhd_iaI4kAgKN8ya5p",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 850,
+ "y": 539.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 11,
+ "height": 23,
+ "seed": 81115726,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 20,
+ "fontFamily": 2,
+ "text": "8",
+ "baseline": 18,
+ "textAlign": "center",
+ "verticalAlign": "middle"
+ },
+ {
+ "type": "ellipse",
+ "version": 471,
+ "versionNonce": 1421092306,
+ "isDeleted": false,
+ "id": "GIG1H7lfyR6S7-AtVzGmH",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 441.5,
+ "y": 323.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 23,
+ "height": 22,
+ "seed": 1124068562,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": []
+ },
+ {
+ "type": "text",
+ "version": 483,
+ "versionNonce": 476534862,
+ "isDeleted": false,
+ "id": "eF0Kvnyd8dffx8-q4yU8U",
+ "fillStyle": "hachure",
+ "strokeWidth": 1,
+ "strokeStyle": "solid",
+ "roughness": 1,
+ "opacity": 100,
+ "angle": 0,
+ "x": 448,
+ "y": 323.5,
+ "strokeColor": "#000000",
+ "backgroundColor": "#15aabf",
+ "width": 11,
+ "height": 23,
+ "seed": 1591705934,
+ "groupIds": [],
+ "strokeSharpness": "sharp",
+ "boundElementIds": [],
+ "fontSize": 20,
+ "fontFamily": 2,
+ "text": "9",
+ "baseline": 18,
+ "textAlign": "center",
+ "verticalAlign": "middle"
+ }
+ ],
+ "appState": {
+ "gridSize": null,
+ "viewBackgroundColor": "#ffffff"
+ }
+}
\ No newline at end of file
diff --git a/explanations/architecture/assets/modules.png b/explanations/architecture/assets/modules.png
new file mode 100644
index 0000000..ef134f1
Binary files /dev/null and b/explanations/architecture/assets/modules.png differ
diff --git a/explanations/architecture/automated-testing.md b/explanations/architecture/automated-testing.md
new file mode 100644
index 0000000..ecbb463
--- /dev/null
+++ b/explanations/architecture/automated-testing.md
@@ -0,0 +1,20 @@
+# 自动化测试
+
+## 为何选择Puppeteer作为端到端测试工具？
+
+当前存在丰富的网络端到端自动化测试工具生态。因此常有人提出疑问："为何Gutenberg选用[Puppeteer](https://developers.google.com/web/tools/puppeteer/)而非([Cypress](https://cypress.io/)、[Selenium](https://www.selenium.dev/)、[Playwright](https://github.com/microsoft/playwright)等)？"考虑到端到端测试在构建结果方面存在历史性的不稳定性，在评估工具提供的价值是否超过维护成本时，这个问题显得尤为关键。虽然我们应始终保持重新评估早期决策的开放态度，但无论是过去还是现在，Puppeteer始终是端到端测试方案中的最佳折中选择。
+
+其优势包括：
+
+- **与现有测试框架的互操作性**。Puppeteer"仅"是一个控制Chrome浏览器的工具，并不预设测试环境的集成方式。虽然这需要额外确保测试环境的可用性，但也使其能够灵活适配现有配置。Gutenberg得以在单元测试和端到端测试中持续使用Jest框架。这与Cypress等其他方案形成鲜明对比——后者提供自成体系的测试框架和断言库作为一体化解决方案。
+- **表达力强且可预测的API**。Puppeteer在底层浏览器行为访问与现代化JavaScript[异步/等待语法](https://developer.mozilla.org/zh-CN/docs/Learn/JavaScript/Asynchronous/Async_await)的命令发布/响应等待之间实现了精妙平衡。相较之下，其他方案要么不支持原生异步功能，要么未开放直接浏览器访问权限，要么采用自定义领域特定语言来表达浏览器命令和断言。尽管Puppeteer主要针对Chrome浏览器在跨浏览器覆盖方面存在局限，但有限的浏览器目标反而能提供更一致的测试结果，并确保代码在浏览器环境中获得更可靠的评估。
+- **暴露问题而非掩盖缺陷**。许多替代方案提供自动等待网络请求完成或页面元素异步加载的功能。虽然这为处理不可预知的延迟提供了便利，但也可能无意间掩盖真实存在的用户体验问题。例如，若某个元素仅在网络请求或计算完成后才会显示，开发者很容易忽略这些延迟可能导致用户遭遇不可预测的挫败体验（[案例](https://github.com/WordPress/gutenberg/pull/11287)）。鉴于开发者通常在高性能设备和稳定网络环境下测试，低端设备或不稳定网络连接下的韧性考量往往被忽视。Puppeteer通过显式的`waitFor*`表达式迫使开发者正视这些延迟，使测试更贴近真实用户的体验场景。
+- **调试功能**。当测试失败时，必须具备直观的问题诊断与解决手段。虽然相比竞品功能较为基础，但Puppeteer确实提供了"有头模式"（可见浏览器界面）和延迟操作等调试选项。结合其与原生语言/运行时功能（如调试器语句或断点）的良好互操作性，为开发者提供了充分的调试支持。
+
+更多背景信息请参阅：
+
+- [测试概览：端到端测试](/docs/contributors/code/testing-overview.md#端到端测试)
+- [测试：Puppeteer端到端测试实验](https://github.com/WordPress/gutenberg/pull/5618)
+ - 在早期迭代中，贡献团队曾选择Cypress进行端到端测试。该拉取请求阐述了该方案存在的问题，并提出了向Puppeteer迁移的初步建议。
+- [JavaScript聊天纪要：2020年1月28日](https://make.wordpress.org/core/2020/02/04/javascript-chat-summary-january-28-2020/)
+ - Playwright是由多位Puppeteer原始贡献者打造的新方案。它提供更广泛的浏览器覆盖和更可靠的测试表现。尽管撰写本文时该工具尚处早期开发阶段，但已引起将其作为未来端到端测试方案的评估兴趣。
\ No newline at end of file
diff --git a/explanations/architecture/data-flow.md b/explanations/architecture/data-flow.md
new file mode 100644
index 0000000..f0869f4
--- /dev/null
+++ b/explanations/architecture/data-flow.md
@@ -0,0 +1,125 @@
+### 分隔符与解析表达式语法
+
+我们最终选择尝试寻找一种方法，在保留现有HTML语法规范性、明确性和无歧义性的基础上进行创新。在HTML体系内，我们拥有多种可行方案。
+
+在这些方案中，有人提出了一种新颖思路：通过将数据存储在HTML注释中，既能确保不破坏文档中原有的HTML结构，又能保证浏览器会忽略这些内容，同时还能简化文档解析流程。
+
+HTML注释的独特之处在于它们不会合法存在于模糊位置——比如像`
欢迎来到区块世界。
+ +``` + +区块分为静态与动态两类。静态区块包含渲染内容和属性对象，可根据变更重新渲染。动态区块在生成文章内容时需要服务器端数据和渲染过程。 + +每个区块包含属性或配置设置，这些数据可从内容中的原始HTML、元数据或其他自定义来源获取。 + +详细了解[数据格式与数据流](/docs/explanations/architecture/data-flow.md)。 + +### 区块转换 + +区块具备转换为其他区块类型的能力。既可实现基础操作（如将段落转为标题），也能完成复杂转换（如多张图片转为相册）。区块转换适用于单个区块及多选区块组合，内部区块变体也可作为转换目标。 + +### 区块变体 + +区块变体是特定区块类型的预定义初始属性集合。该API支持创建基础区块，并衍生出多种配置方案。变体提供不同的交互界面，既可在库中显示为全新区块，也可作为插入新区块时的预设模板。详见[API文档](/docs/reference-guides/block-api/block-registration.md#variations-optional)。 + +**区块进阶指南** +- **[区块API](/docs/reference-guides/block-api/README.md)** +- **[教程：构建自定义区块](/docs/getting-started/devenv/get-started-with-create-block.md)** + +## 可复用区块 + +可复用区块是区块（或多个区块组合）的**实例**，可在多处插入和编辑，并保持全局同步。当在某处编辑可复用区块时，所有使用该区块的文章和页面都会同步更新。典型应用场景包括：具有特定内容和自定义颜色的标题区块（用于多个页面），以及侧边栏小组件（用于所有页面）。 + +对可复用区块的任何编辑都会自动同步到所有使用位置，避免在不同文章中重复修改。 + +技术上，可复用区块以隐藏文章类型（`wp_block`）存储，属于动态区块，通过"引用"方式关联`post_id`并返回对应区块的`post_content`。 + +## 区块模式 + +[区块模式](/docs/reference-guides/block-api/block-patterns.md)是由多个区块组合形成的设计范式。这些设计模式为快速构建高级页面和布局提供起点，无需逐个插入区块。区块模式小至单个区块，大至整页内容。与可复用区块不同，模式插入后不会与原始内容保持同步，其包含的区块需用户自行编辑定制。本质上，模式就是常规区块的组合。主题可通过注册模式，为用户提供符合其设计语言的快速入门方案。 + +## 模板 + +文章编辑器专注于内容创作，而[模板](/docs/reference-guides/block-api/block-templates.md)编辑器支持用区块声明和编辑整个站点（从页眉到页脚）。模板系统分为完整页面模板和模板部件（描述模板内的可复用区域，包括页眉、侧边栏、页脚等语义区域）。 + +这些模板和模板部件可由主题组合注册。用户也可通过区块编辑器完全自定义它们。在编辑模板时，与站点属性（如站点标题、描述、徽标、导航等）交互的区块集合尤为实用。自定义模板保存在`wp_template`文章类型中，包括静态页面和动态页面（如归档页、单篇文章页、首页、404页等）。 + +注意：自定义文章类型也可通过初始`post_content`模板初始化，请勿与上述主题模板系统混淆。 + +深入了解[全站编辑模板](/docs/explanations/architecture/full-site-editing-templates.md)。 + +## 样式 + +样式系统（代码中仍沿用旧称“全局样式”）既是用户通过编辑器访问的界面，也是通过[`theme.json`文件](/docs/how-to-guides/themes/global-settings-and-styles.md)实现的配置系统。该文件整合了通常分散在多个`add_theme_support`调用中的配置项，简化与编辑器的通信。其目标是改进以下功能的声明方式：应启用的设置、主题提供的特定工具（如自定义调色板）、可用的设计工具，以及协调WordPress、活跃主题和用户样式的基础架构。 + +了解更多关于[全局样式](/docs/explanations/architecture/styles.md#global-styles)的信息。 \ No newline at end of file diff --git a/explanations/architecture/modularity.md b/explanations/architecture/modularity.md new file mode 100644 index 0000000..8c7a643 --- /dev/null +++ b/explanations/architecture/modularity.md @@ -0,0 +1,103 @@ +## 进阶阅读 + +- [软件包参考](/docs/reference-guides/packages.md) + +# 模块化设计 + +WordPress 区块编辑器的核心理念在于通过组合独立区块来撰写文章或构建页面。区块之间能够相互调用与交互，这种设计赋予了系统高度的模块化特性与灵活性。 + +但区块编辑器的模块化不仅体现在功能与输出层面。古腾堡项目仓库本身也是由多个可复用独立模块（即程序包）构建而成，这些模块共同构成了我们熟悉的应用程序与交互界面。这些模块被称为 [WordPress 程序包](https://www.npmjs.com/org/wordpress)，会定期发布并更新至 npm 包仓库。 + +这些程序包不仅为区块编辑器提供核心支持，也可用于增强 WordPress 管理后台或外部环境的任何页面。 + +## 设计理念 + +采用模块化架构为所有参与者带来多重优势： + +- 每个程序包都是独立单元，拥有明确定义的公共 API 用于与其他程序包及第三方代码交互。这使得**核心贡献者**能更清晰地理解代码库，可专注于单个程序包的开发维护，并在明确知晓变更影响范围的前提下进行更新 +- 模块化架构对**终端用户**同样有益。通过在不同管理页面选择性加载脚本，有效控制资源包体积。例如当使用组件包构建插件设置页面时，就无需额外加载区块编辑器包 +- 这种架构允许**第三方开发者**通过 npm 或 WordPress 脚本依赖的方式，在 WordPress 内外环境中复用这些程序包 + +## 程序包分类 + +古腾堡仓库中的几乎所有功能都被构建为程序包。这些程序包可分为两大类型： + +### 生产环境包 + +这类程序包以 JavaScript 脚本形式随 WordPress 核心发布，构成在浏览器中运行的实际生产代码。例如： +- `components` 程序包提供可复用的 React 组件集合，用于快速原型设计与界面构建 +- `api-fetch` 程序包可用于调用 WordPress REST API + +第三方开发者可通过两种方式使用这些生产环境包： + +- 若在 WordPress 环境外构建 JavaScript 应用、网站或页面，可像使用常规 npm 包那样调用： + +``` +npm install @wordpress/components +``` + +```js +import { Button } from '@wordpress/components'; + +function MyApp() { + return ; +} +``` + +- 若开发 WordPress 插件，建议直接调用 WordPress 内置程序包。这样可实现多插件共享同一程序包，避免代码重复。在 WordPress 中，这些程序包以后缀为 `wp-包名称`（如 `wp-components`）的脚本句柄形式提供。只需将脚本添加到插件依赖中，即可通过全局变量 `wp` 调用： + +```php +// myplugin.php +// 注册依赖 "components" 和 "element" 程序包的示例 +wp_register_script( 'myscript', 'pathtomyscript.js', array ('wp-components', "react" ) ); +``` + +```js +// 在脚本中使用程序包 +const { Button } = wp.components; + +function MyApp() { + return ; +} +``` + +手动定义脚本依赖对开发者而言可能繁琐易错。若需了解如何自动化此流程，请参阅 [@wordpress/scripts](https://developer.wordpress.org/block-editor/packages/packages-scripts/#build) 与 [@wordpress/dependency-extraction-webpack-plugin](https://developer.wordpress.org/block-editor/packages/packages-dependency-extraction-webpack-plugin/) 文档。 + +#### 包含样式文件的功能包 + +部分生产环境功能包需依赖样式文件才能正常运行。 + +- 若通过 npm 依赖形式使用功能包，样式文件将存放于功能包的 `build-style` 目录。请确保在应用中加载该样式文件。 +- 若在 WordPress 环境中使用，需通过 wp_enqueue_style 函数加载样式文件，或将其添加至现有样式依赖中。样式文件句柄命名规则与脚本句柄保持一致。 + +在现有 WordPress 页面环境中，若未正确定义脚本或样式依赖，当这些资源已被 WordPress 或其他插件加载时，您的插件仍可能正常运行。但为规避未来版本可能出现的兼容性问题，强烈建议完整定义所有依赖项。 + +#### 包含数据存储的功能包 + +部分 WordPress 生产环境功能包通过数据存储机制管理状态。这些存储空间也可被第三方插件和主题调用，用于数据获取与操作。数据存储命名遵循 `core/功能包名称` 的标准化格式（例如 `@wordpress/block-editor` 功能包定义并使用 `core/block-editor` 数据存储）。 + +若在插件中通过此类存储空间访问或操作 WordPress 数据，请务必将对应的 WordPress 脚本添加至插件脚本依赖中以确保正常运行（例如：若从 `core/block-editor` 存储获取数据，应按前文示例将 `wp-block-editor` 包添加至脚本依赖）。 + +### 开发环境功能包 + +此类功能包用于开发模式，协助开发者完成 JavaScript 应用、WordPress 插件及主题的开发、构建和发布等日常任务。包含代码规范检查、项目构建、测试验证等开发工具。 + +## 编辑器功能包 + + + +### 不同编辑器功能包有何区别？各自承担什么职责？ + +新贡献者往往会对文章编辑器由三个独立功能包（`@wordpress/edit-post`、`@wordpress/editor` 和 `@wordpress/block-editor`）分层构建的架构感到惊讶。 + +前文[设计初衷](#why)章节已说明单个功能包如何满足特定需求的设计理念，这同样适用于以下功能包： + +- `@wordpress/block-editor` 提供用于实现区块编辑器的组件，其操作对象为区块对象数组的基础数据。该包不预设数据保存方式，且无需感知（或依赖）WordPress 环境。 +- `@wordpress/editor` 是 WordPress 文章专用的增强版区块编辑器。它在 `@wordpress/block-editor` 组件基础上构建，具备 WordPress 文章概念感知能力，将表征区块的数据加载保存机制与文章及其内容相关联。同时提供在编辑器环境中处理文章对象的相关组件（如文章标题输入组件）。该功能包支持编辑任何文章类型的文章，且不限定渲染环境必须位于特定 WordPress 界面或布局中。 +- `@wordpress/edit-post` 是 WordPress 后台“新建文章”（“编辑文章”）界面的具体实现。它负责对 `@wordpress/editor` 和 `@wordpress/block-editor` 提供的各类组件进行布局编排，完全掌控其在 WordPress 管理后台特定界面中的呈现方式。 + +通过这样的结构设计，这些功能包可在“新建文章”界面之外实现多样化组合应用： + +- `@wordpress/edit-site` 或 `@wordpress/edit-widgets` 功能包可分别实现“站点编辑器”或“小工具编辑器”，其实现方式与 `@wordpress/edit-post` 高度相似。 +- `@wordpress/editor` 可应用于“可重用区块”功能的实现，因其本质上是与 `wp_block` 文章类型关联的嵌套区块编辑器。 +- `@wordpress/block-editor` 可独立于 WordPress 环境使用，或采用完全不同的保存机制。例如：可用于构建网站文章的评论区编辑器。 \ No newline at end of file diff --git a/explanations/architecture/performance.md b/explanations/architecture/performance.md new file mode 100644 index 0000000..5851192 --- /dev/null +++ b/explanations/architecture/performance.md @@ -0,0 +1,97 @@ +# 性能表现 + +性能是编辑器应用的关键特性，块编辑器也不例外。 + +## 指标衡量 + +为确保块编辑器在版本迭代和开发过程中始终保持高性能，我们通过[性能基准测试任务](#性能基准测试任务)监控以下核心指标： + +部分关键指标包括： + +- **加载时间：** 编辑器页面加载所需时长。涵盖服务器响应时间、首次绘制时间、首次内容绘制时间、DOM内容加载完成时间、页面完全加载时间以及首区块渲染时间（文章与站点编辑场景均包含）。 +- **输入响应时间：** 在编辑器中输入时浏览器作出响应所需时长。 +- **区块选择时间：** 用户选择区块后浏览器作出响应所需时长（插入区块等效于选择区块，监控选择操作即可同步覆盖这两项指标）。 + +## 关键性能决策与解决方案 + +**数据模块异步模式** + +WordPress组件库与块编辑器的数据模块基于Redux构建。这意味着状态全局存储，当状态发生变化时，依赖该状态的组件（UI）会相应更新。 + +随着渲染组件数量增加（例如长文编辑时），由于全局状态会向所有组件分发事件，性能将受到影响。这是Redux应用的常见问题，Gutenberg通过数据模块异步模式解决了这一难题。 + +异步模式的核心在于：开发者可自主决定以同步或异步方式刷新/重渲染React组件树的特定部分。 + +在此语境下，异步渲染意味着当全局状态触发变更时，订阅者（组件）不会立即被同步调用，而是等待浏览器进入空闲状态后再执行React树更新。 + +基于**编辑特定区块时，该区块的更新极少影响内容其他部分**这一理念，块编辑器画布仅以同步模式渲染当前选中区块，其余所有区块均采用异步渲染。这确保了随着文章内容增长，编辑器仍能保持流畅响应。 + +## 性能基准测试任务 + +我们提供了跨分支/标签/提交进行性能对比的工具。可通过以下方式本地运行：`./bin/plugin/cli.js perf [分支名]`，例如： + +``` +./bin/plugin/cli.js perf trunk v8.1.0 v8.0.0 +``` + +为获得最精确结果，运行测试时必须确保测试版本与环境（主题等）完全一致，各分支间唯一差异应为Gutenberg插件版本（或用于构建插件的分支）。 + +为实现该目标，指令会先创建以下目录结构： + + │ + ├── tests/packages/e2e-tests/specs/performance/* + │ 待运行的实际性能测试 + │ + ├── tests/test/emptytheme + │ 测试环境所用主题（站点编辑器） + │ + │── envs/branch1/.wp-env.json + │ branch1的wp-env配置文件（除插件目录外与其他分支配置相同） + │── envs/branch1/plugin + │ branch1的Gutenberg插件构建副本（通过git checkout branch1获取） + │ + └── envs/branchX + 所有其他分支均复制perf-envs/branch1的目录结构 + +完成目录准备后，性能测试指令将循环执行各性能测试套件（文章编辑器与站点编辑器），并执行以下操作： + +1. 启动`branch1`对应环境 +2. 运行当前套件的性能测试 +3. 停止`branch1`对应环境 +4. 对其余所有分支重复前三步操作 +5. 计算当前套件所有性能指标的中位数值 + +所有测试套件执行完毕后，将生成汇总报告。 + +## 通过CodeVitals追踪性能 + +每次提交的性能结果将推送至codevitals，可在[Gutenberg数据看板](https://www.codevitals.run/project/gutenberg)查看。通过趋势图可追踪特定指标随时间的变化情况。 + +因此确保所计算指标的稳定性至关重要。这意味着在代码与环境相同的情况下，重复运行测试应获得相近结果。 + +由于性能任务运行于GitHub CI环境，我们不能完全相信两次相似任务运行获得的数值一致性。例如GitHub CI可能随时间推移分配不同的CPU与内存资源。为缓解此问题，每次在trunk分支运行性能任务时，我们会将当前提交的性能与固定的参考提交哈希进行对比，这样无论环境如何变化，都能持续追踪当前提交与参考提交间的相对差异。 + +### 更新参考提交 + +Gutenberg仅支持两个WP版本，这对性能任务产生两方面影响： + + - 当Gutenberg支持的最低版本变更时，用于运行性能任务的基础WP版本需同步更新。为此，我们依赖插件`readme.txt`文件中的`Tested up to`标识。每次该标识变更时，性能任务所用版本也会相应调整。 + + - 更新性能任务使用的WP版本意味着，用于保证性能测试稳定性的参考提交很可能与当前WP版本不兼容。因此每次`readme.txt`中的`Tested up to`标识更新时，必须同步更新`.github/workflows/performance.yml`中使用的参考提交。 + +新选的参考提交哈希需满足以下要求： + + - 与`Tested up to`标识使用的新WP版本兼容 + - 已在codevitals.run平台追踪所有现有指标 + +当发布涉及最低WordPress版本要求变更的插件更新时，需更新Core SVN中失去支持分支的端到端测试GitHub Action工作流，否则该分支在发布后的首次工作流运行将会失败。 + +可通过在测试矩阵中添加`gutenberg-version`输入来固定工作流中使用的插件版本。[Core-59221](https://core.trac.wordpress.org/changeset/59221)展示了6.4分支的此类变更示例。 + +**注意：** 请始终使用包含错误修复的最终发行版（例如`x.y.2`或`x.y.3`）。若最终发行版尚未确定，请创建[Trac工单](https://core.trac.wordpress.org/ticket/62488)以免遗忘。 + +**选择提交的简易方法是选取trunk分支上最近一次通过性能测试的提交。** + +## 拓展阅读 + +- [高性能编辑器的演进之路](https://riad.blog/2020/02/14/a-journey-towards-a-performant-web-editor/) \ No newline at end of file diff --git a/explanations/architecture/styles.md b/explanations/architecture/styles.md new file mode 100644 index 0000000..c73dbe6 --- /dev/null +++ b/explanations/architecture/styles.md @@ -0,0 +1,549 @@ +#### 语义化类名 + +当前正在扩展布局区块支持输出的稳定语义化类名，相关讨论可在[此议题](https://github.com/WordPress/gutenberg/issues/38719)中查看。 + +目前通过布局区块支持可输出的语义化类名包括： + +- `is-layout-flow`：采用默认/流式布局类型的区块 +- `is-layout-constrained`：采用约束布局类型的区块 +- `is-layout-flex`：采用弹性布局类型的区块 +- `is-layout-grid`：采用网格布局类型的区块 +- `wp-container-$id`：其中`$id`为半随机数。该容器类仅当区块包含非默认布局值时存在，请勿直接将其用于CSS选择器，因其可能动态变化 +- `is-horizontal`：当区块显式设置`orientation`为`horizontal`时 +- `is-vertical`：当区块显式设置`orientation`为`vertical`时 +- `is-content-justification-left`：当区块显式设置`justifyContent`为`left`时 +- `is-content-justification-center`：当区块显式设置`justifyContent`为`center`时 +- `is-content-justification-right`：当区块显式设置`justifyContent`为`right`时 +- `is-content-justification-space-between`：当区块显式设置`justifyContent`为`space-between`时 +- `is-nowrap`：当区块显式设置`flexWrap`为`nowrap`时 + +### 禁用自动生成的布局样式 + +由于核心结构区块需要依赖布局样式，系统默认开启布局样式输出。但主题可通过使用`disable-layout-styles`区块支持来禁用自动生成的区块布局样式，同时保留语义化类名输出。选择此方案的主题需自行提供完整的布局样式支持，具体请参阅[主题支持文档](https://developer.wordpress.org/block-editor/how-to-guides/themes/theme-support/#disabling-base-layout-styles)中的相关说明。 + +### 基础布局样式 + +基础布局样式是指那些选择特定布局类型的所有区块共通的样式。常见的基础布局样式示例包括：为采用弹性布局类型的区块（例如按钮区块和社交图标区块）设置 `display: flex`，以及为受限布局提供默认的最大宽度。 + +基础布局样式通过[处理全局样式的主要 PHP 类](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/class-wp-theme-json.php)输出，并构成全局样式表的一部分。为了在经典主题中支持核心区块，无论主题是否提供自身的 `theme.json` 文件，这些样式始终会被输出。 + +通用布局定义存储在[核心布局区块支持文件](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-supports/layout.php)中。 + +### 独立布局样式 + +当选择支持布局的区块被渲染时，会通过 [`layout.php`](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-supports/layout.php) 处理并将以下两项内容添加到输出中： + +- 语义类名会被添加到区块标记中，以指示正在使用的布局设置。例如，`is-layout-flow` 用于使用默认/流式布局的区块（如群组区块），而 `is-content-justification-right` 会在用户将区块设置为右对齐时添加。 +- 为正在渲染的单个区块上设置的非默认布局值生成独立样式。这些样式通过容器类名附加到区块上，类名格式为 `wp-container-$id`，其中 `$id` 是一个[唯一编号](https://developer.wordpress.org/reference/functions/wp_unique_id/)。 + +### 可用的布局类型 + +目前有四种布局类型在使用： + +- 默认/流式布局：项目垂直堆叠。父容器区块的显示值未指定，因此可以使用该 HTML 元素的默认值。对于大多数元素，这通常是 `block`。子元素之间的间距通过垂直边距处理。 +- 受限布局：项目垂直堆叠，使用与流式布局相同的间距逻辑。具有子内容宽度的限制，为标准内容尺寸和宽尺寸输出宽度。默认使用 `theme.json` 中 `settings.layout` 设置的全局 `contentSize` 和 `wideSize` 值。 +- 弹性布局：项目使用弹性盒子布局显示。默认为水平方向。子元素之间的间距通过 `gap` CSS 属性处理。 +- 网格布局：项目使用网格布局显示。默认为 `auto-fill` 方式生成列，但也可以设置为固定列数。子元素之间的间距通过 `gap` CSS 属性处理。 + +关于控制区块之间的间距以及启用区块间距控制，请参阅：[什么是 blockGap，我该如何使用它？](https://developer.wordpress.org/block-editor/how-to-guides/themes/global-settings-and-styles/#what-is-blockgap-and-how-can-i-use-it) + +### 从主题中定位布局或容器区块 + +布局区块支持旨在通过区块和站点编辑器实现对布局功能的控制。在可能的情况下，尽量使用区块的功能来确定特定的布局需求，而不是依赖额外的样式表。 + +对于希望定位容器区块以添加或调整特定样式的主题，区块的类名通常是最佳选择。例如 `wp-block-group` 或 `wp-block-columns` 这样的类名通常是定位特定区块的可靠类名。除了区块和布局类名外，还有一个由区块和布局组合而成的类名：例如，对于具有受限布局的群组区块，类名将是 `wp-block-group-is-layout-constrained`。 + +对于使用特定布局类型的区块进行定位，请避免定位 `wp-container-`，因为容器类可能不会始终出现在渲染的标记中。 + +### 从界面控件到HTML标记 + +若您遵循[区块教程](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/)，可深入了解[区块API](https://developer.wordpress.org/block-editor/reference-guides/block-api/)的各个组成部分，并构建专属区块。本文将介绍区块如何让用户编辑其状态的核心概念。 + +要构建上述交互体验，区块开发者需具备以下要素： + +1. **界面控件**：向用户提供选项交互，例如调整区块字体大小。该控件负责读取区块数据（当前是否已设定字体大小？）及其他必要信息（本区块允许使用哪些字号？）。可查阅现有[组件库](https://developer.wordpress.org/block-editor/reference-guides/components/)。 +2. **区块属性**：区块需存储数据以记录修改状态，例如是否已设定字号。了解区块如何定义[属性](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/)。 +3. **样式数据接入**：控件可能需要获取区块可用样式的外部信息，如色彩列表或字号列表。这类预设样式通常由主题定义（WordPress也提供默认配置）。查看主题可向编辑器提供的[数据列表](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/#settings)，以及开发者如何通过[useSetting](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/#usesetting)获取这些数据。 +4. **将用户样式序列化为HTML标记**：用户操作后，需相应更新区块HTML标记（添加对应类或行内样式）。此序列化过程由[编辑/保存](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-edit-save/)函数与[render_callback](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/creating-dynamic-blocks/)函数实现，它们将区块数据转换为HTML代码。 + +本质上，这些是区块开发者实现用户样式定制需关注的核心机制。虽然完全手动可实现，但针对通用样式需求，可通过自动化API——区块支持功能来简化流程。 + +### 区块支持API + +[区块支持](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/)API允许区块声明其支持的功能。通过在[block.json文件](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/)中添加配置信息，区块可向系统声明允许用户执行的操作类型。 + +例如： + +```json +{ + "name": "core/paragraph", + "...": "...", + "supports": { + "typography": { + "fontSize": true + } + } +} +``` + +段落区块在其`block.json`中声明支持字号调整。这意味着区块将显示字号调节控件（除非被主题禁用，详见[主题配置参考](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/)）。系统会自动配置控件数据（当前字号、可用字号列表），并在用户操作时将区块数据序列化为HTML标记（自动附加类与行内样式）。 + +通过`block.json`使用区块支持机制，开发者仅需数行代码即可实现完整交互体验。查看[区块支持API文档](/docs/reference-guides/block-api/block-supports.md)了解如何为静态或动态区块添加支持功能。 + +除简化开发流程外，该机制还有以下优势： + +- 区块样式信息可被原生移动应用和服务端调用 +- 区块对同类样式使用统一控件，确保用户体验一致性 +- 所用界面控件将随系统升级自动优化，无需开发者干预 + +# 编辑器中的样式 + +本文档将介绍影响区块编辑器用户内容的相关样式核心概念，同时提供对应的参考指南和教程链接，方便读者深入探究每个主题。本文主要面向区块创作者和参与区块编辑器项目的开发人员。 + +## HTML 与 CSS + +用户在区块编辑器中创建内容时，实际上在生成一系列产物：一个 HTML 文档和若干 CSS 样式表（可内嵌于文档或作为外部文件）。 + +最终生成的 HTML 文档由以下要素共同构成： + +- 主题提供的 [WordPress 模板](https://developer.wordpress.org/themes/basics/template-files/)（通过 PHP 实现的经典主题或通过 HTML 模板实现的区块主题）（[详细了解](https://developer.wordpress.org/themes/block-themes/#differences-and-similarities-between-classic-themes-and-block-themes)二者差异） +- 具有预定义结构（HTML 标记）的[区块](https://developer.wordpress.org/block-editor/reference-guides/core-blocks/)与版式 +- 用户对内容的修改：添加内容、转换现有内容（如将段落转换为标题）或调整内容（为区块添加类或内联样式） + +前端加载的样式表包含： + +- **区块样式**：区块自带的样式表。在前端，您可能会看到 WordPress 定义的所有区块样式合并为单一样式表（`wp-block-library-*`），也可能是每个使用中的区块拥有独立样式表（如 `wp-block-group-*`、`wp-block-columns-*` 等）。完整说明请参阅[此说明文档](https://make.wordpress.org/core/2021/07/01/block-styles-loading-enhancements-in-wordpress-5-8/)。 +- **全局样式**：这些样式通过 theme.json 文件的数据动态生成（参见[说明文档](https://make.wordpress.org/core/2021/06/25/introducing-theme-json-in-wordpress-5-8/)、[参考指南](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/)和[操作指南](https://developer.wordpress.org/block-editor/how-to-guides/themes/global-settings-and-styles/)）。具体而言，它会整合来自 WordPress 的 theme.json、主题自带的 theme.json（如有）以及用户通过站点编辑器的全局样式侧边栏提供的数据，最终生成一个 ID 为 `global-styles-inline-css` 的内嵌样式表。 +- **主题样式**：传统上主题会自行注册样式表，其 ID 基于主题名称（如 `twentytwentytwo-style-css`）。如今除了自有样式表外，主题还可声明包含样式的 theme.json 文件，这些样式将成为全局样式生成样式表的一部分。 +- **用户样式**：用户在编辑器中的某些操作会生成样式内容，例如双色调、布局或链接颜色等功能。 +- **其他样式**：WordPress 核心和插件也可注册样式表。 + +## 区块样式 + +自 WordPress 5.0 引入区块编辑器以来，一直提供为用户“添加样式”到特定区块的工具。通过这些工具，用户可为区块附加新类或内联样式，从而改变其视觉呈现。 + +默认情况下，区块具有预设的 HTML 标记。以段落区块为例： + +```html + +``` + +在最简形式下，任何针对 `p` 选择器的样式规则都会作用于该区块，无论这些规则来自区块、主题或其他来源。 + +用户可通过应用不同样式来改变区块状态：文本对齐方式、颜色、字体大小、行高等。这些状态通过 HTML 属性（主要是 `class` 或 `style` 属性，也可以是区块作者认为合适的任何其他属性）反映在区块的 HTML 标记中。 + +经过用户修改后，初始标记可能变为： + +```html + +``` + +这就是我们所说的“用户提供的区块样式”，也称为“本地样式”或“序列化样式”。本质上，每个工具（字体大小、颜色等）最终都会向区块标记添加若干类和/或内联样式。这些类对应的 CSS 样式属于区块、全局或主题样式表的一部分。 + +修改区块状态的能力，加上区块可嵌套于其他区块的特性（例如段落区块位于编组区块内），创造了海量的潜在状态和样式组合可能。 + +#### 设置项到CSS规则的转换 + +从 `settings` 部分中，所有预设值都将转换为遵循此命名结构的CSS自定义属性：`--wp--preset--<类别>-<别名>`。选择器遵循上述样式部分描述的相同规则。 + +例如，以下 theme.json 配置： + +```json +{ + "settings": { + "color": { + "palette": { + "default": [ + { + "slug": "vivid-red", + "value": "#cf2e2e", + "name": "Vivid Red" + } + ], + "theme": [ + { + "slug": "foreground", + "value": "#000", + "name": "Foreground" + } + ] + } + }, + "blocks": { + "core/site-title": { + "color": { + "palette": { + "theme": [ + { + "slug": "foreground", + "value": "#1a4548", + "name": "Foreground" + } + ] + } + } + } + } + } +} +``` + +将被转换为以下CSS样式规则： + +```CSS +body { + --wp--preset--color--vivid-red: #cf2e2e; + --wp--preset--color--foreground: #000; +} + +.wp-block-site-title { + --wp--preset--color--foreground: #1a4548; +} +``` + +除了CSS自定义属性外，除双色调外的所有预设都会为每个值生成CSS类。上例还会生成以下CSS类： + +```CSS +/* vivid-red */ +.has-vivid-red-color { color: var(--wp--preset--color--vivid-red) !important; } +.has-vivid-red-background-color { background-color: var(--wp--preset--color--vivid-red) !important; } +.has-vivid-red-border-color { border-color: var(--wp--preset--color--vivid-red) !important; } + +/* foreground */ +.has-foreground-color { color: var(--wp--preset--color--foreground) !important; } +.has-foreground-background-color { background-color: var(--wp--preset--color--foreground) !important; } +.has-foreground-border-color { border-color: var(--wp--preset--color--foreground) !important; } + +/* 站点标题内的foreground */ +.wp-block-site-title .has-foreground-color { color: var(--wp--preset--color--foreground) !important; } +.wp-block-site-title .has-foreground-background-color { background-color: var(--wp--preset--color--foreground) !important; } +.wp-block-site-title .has-foreground-border-color { border-color: var(--wp--preset--color--foreground) !important; } +``` + +### 全局样式API的当前限制 + +#### 1. **为区块设置不同CSS选择器需服务端注册** + +默认情况下，分配给区块的选择器是 `.wp-block-<区块名称>`。但区块可以根据需要更改此设置，可以通过其 `block.json` 中的 `__experimentalSelector` 属性提供CSS选择器。 + +如果区块这样做，需要在服务端使用 `block.json` 进行注册，否则全局样式代码无法访问该信息，将使用区块的默认CSS选择器。 + +#### 2. **无法为不同样式定位不同HTML节点** + +每个样式块只能使用单个选择器。 + +当区块使用 `__experimentalSkipSerialization` 将不同样式属性序列化到包装器以外的不同节点时，这一点尤为重要。详见"区块支持的当前限制"。 + +#### 3. **每个区块仅支持单一属性** + +与区块支持类似，区块只能使用任何样式的单个实例。例如，区块只能拥有单一字体大小。详见相关"区块支持的当前限制"。 + +#### 4. **仅使用区块支持的区块会显示在全局样式UI中** + +站点编辑器中的全局样式UI设有按区块样式的界面。区块列表是使用来自区块 `block.json` 的区块支持动态生成的。如果区块希望被列出，需要使用区块支持机制。 + +## 布局样式 + +除了单个区块级别和全局样式中的样式外，还存在为基于区块的主题和经典主题输出的布局样式概念。 + +布局区块支持输出用于创建布局的区块之间共享的通用布局样式。布局样式对于为作为其他区块容器的任何区块提供通用样式非常有用。依赖这些布局样式的区块示例包括群组、行、列、按钮和社交图标。核心区块通过其 `block.json` 文件中 `supports` 下的 `layout` 设置启用此功能。 + +布局样式主要输出在两个位置： + +### 区块支持API的当前限制 + +尽管区块支持API具有实用价值，但区块开发者仍需注意其存在的一些限制。为了更好地理解这些限制，我们以表格区块为例进行说明： + +```html +| 标题 | +
|---|
| 第一行 | +
| 第二行 | +
| 页脚 | +
| 标题 | +
| { decodeEntities( page.title.rendered ) } | +
无结果
+ }
+ // ...
+}
+
+function MyFirstApp() {
+ // ...
+
+ return (
+
+ // ...
+
+ )
+}
+```
+
+请注意，我们没有构建自定义的加载指示器，而是利用了[Spinner](https://developer.wordpress.org/block-editor/reference-guides/components/spinner/)组件。
+
+我们仍然需要知道页面选择器`hasResolved`与否。我们可以使用`hasFinishedResolution`选择器来查明：
+
+`wp.data.select('core').hasFinishedResolution( 'getEntityRecords', [ 'postType', 'page', { search: 'home' } ] )`
+
+它接受选择器的名称和_你传递给该选择器的完全相同参数_，如果数据已加载则返回`true`，如果我们仍在等待则返回`false`。让我们将其添加到`useSelect`中：
+
+```js
+import { useSelect } from '@wordpress/data';
+import { store as coreDataStore } from '@wordpress/core-data';
+
+function MyFirstApp() {
+ // ...
+ const { pages, hasResolved } = useSelect( select => {
+ // ...
+ return {
+ pages: select( coreDataStore ).getEntityRecords( 'postType', 'page', query ),
+ hasResolved:
+ select( coreDataStore ).hasFinishedResolution( 'getEntityRecords', ['postType', 'page', query] ),
+ }
+ }, [searchTerm] );
+
+ // ...
+}
+```
+
+还有最后一个问题。很容易出现拼写错误，最终传递给`getEntityRecords`和`hasFinishedResolution`的参数不同。确保它们完全相同至关重要。我们可以通过将参数存储在变量中来消除这种风险：
+
+```js
+import { useSelect } from '@wordpress/data';
+import { store as coreDataStore } from '@wordpress/core-data';
+function MyFirstApp() {
+ // ...
+ const { pages, hasResolved } = useSelect( select => {
+ // ...
+ const selectorArgs = [ 'postType', 'page', query ];
+ return {
+ pages: select( coreDataStore ).getEntityRecords( ...selectorArgs ),
+ hasResolved:
+ select( coreDataStore ).hasFinishedResolution( 'getEntityRecords', selectorArgs ),
+ }
+ }, [searchTerm] );
+
+ // ...
+}
+```
+
+瞧！大功告成。
+
+# 构建页面列表
+
+在这一部分，我们将构建一个可筛选的WordPress页面列表。本节完成后，应用将呈现如下效果：
+
+
+
+让我们逐步了解实现过程。
+
+## 步骤一：构建PagesList组件
+
+首先构建一个基础React组件来展示页面列表：
+
+```js
+function MyFirstApp() {
+ const pages = [{ id: 'mock', title: '示例页面' }]
+ return -
+ { pages?.map( page => (
+
- + { page.title } + + ) ) } +
-
+ { pages?.map( page => (
+
- + { decodeEntities( page.title.rendered ) } + + ) ) } +
| 标题 | +
|---|
| { decodeEntities( page.title.rendered ) } | +
+
+ )
+}
+```
+
+请注意，这里我们并未使用原生`input`标签，而是利用了[SearchControl](https://developer.wordpress.org/block-editor/reference-guides/components/search-control/)组件。其实际效果如下：
+
+
+
+搜索框初始为空，输入内容会存储在`searchTerm`状态值中。若您不熟悉[useState](https://react.dev/reference/react/useState)钩子函数，可查阅[React官方文档](https://react.dev/reference/react/useState)了解更多。
+
+现在我们可以仅请求匹配`searchTerm`的页面数据。查阅[WordPress API文档](https://developer.wordpress.org/rest-api/reference/pages/)可知，[/wp/v2/pages](https://developer.wordpress.org/rest-api/reference/pages/)接口支持`search`查询参数，用于_限定返回匹配字符串的结果_。具体使用方法如下：
+
+```js
+wp.data.select( 'core' ).getEntityRecords( 'postType', 'page', { search: 'home' } )
+```
+
+在浏览器开发者工具中运行此代码段，将触发请求至`/wp/v2/pages?search=home`（而非基础的`/wp/v2/pages`）。
+
+接下来在`useSelect`调用中实现对应逻辑：
+
+```js
+import { useSelect } from '@wordpress/data';
+import { store as coreDataStore } from '@wordpress/core-data';
+
+function MyFirstApp() {
+ // ...
+ const { pages } = useSelect( select => {
+ const query = {};
+ if ( searchTerm ) {
+ query.search = searchTerm;
+ }
+ return {
+ pages: select( coreDataStore ).getEntityRecords( 'postType', 'page', query )
+ }
+ }, [searchTerm] );
+
+ // ...
+}
+```
+
+当存在搜索词时，`searchTerm`将作为`search`查询参数使用。请注意，`searchTerm`也被列入`useSelect`的依赖项数组，确保在搜索词变更时重新执行`getEntityRecords`。
+
+最终整合后的`MyFirstApp`组件代码如下：
+
+```js
+import { useState } from 'react';
+import { createRoot } from 'react-dom';
+import { SearchControl } from '@wordpress/components';
+import { useSelect } from '@wordpress/data';
+import { store as coreDataStore } from '@wordpress/core-data';
+
+function MyFirstApp() {
+ const [searchTerm, setSearchTerm] = useState( '' );
+ const pages = useSelect( select => {
+ const query = {};
+ if ( searchTerm ) {
+ query.search = searchTerm;
+ }
+ return select( coreDataStore ).getEntityRecords( 'postType', 'page', query );
+ }, [searchTerm] );
+
+ return (
+
+
+ )
+}
+```
+
+大功告成！现在我们可以对结果进行筛选了：
+
+
\ No newline at end of file
diff --git a/how-to-guides/data-basics/3-building-an-edit-form.md b/how-to-guides/data-basics/3-building-an-edit-form.md
new file mode 100644
index 0000000..c9d529b
--- /dev/null
+++ b/how-to-guides/data-basics/3-building-an-edit-form.md
@@ -0,0 +1,552 @@
+## 接下来做什么？
+
+* **上一篇：** [构建页面列表](/docs/how-to-guides/data-basics/2-building-a-list-of-pages.md)
+* **下一篇：** [构建创建页面表单](/docs/how-to-guides/data-basics/4-building-a-create-page-form.md)
+* （可选）在 block-development-examples 代码库中查看[完整示例应用](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/data-basics-59c8f8)
+
+# 构建编辑表单
+
+本节内容将为我们的应用添加*编辑*功能。以下是即将构建功能的预览图：
+
+
+
+### 步骤一：添加“编辑”按钮
+
+要实现*编辑*功能首先需要添加编辑按钮，让我们从在`PagesList`组件中添加按钮开始：
+
+```js
+import { Button } from '@wordpress/components';
+import { decodeEntities } from '@wordpress/html-entities';
+
+const PageEditButton = () => (
+
+)
+
+function PagesList( { hasResolved, pages } ) {
+ if ( ! hasResolved ) {
+ return 暂无结果
;
+ }
+
+ return (
+ | 标题 | +操作 | +
| { decodeEntities( page.title.rendered ) } | +
+ |
+
+
+ );
+}
+```
+
+现在让按钮触发显示刚创建的编辑表单。由于本教程不侧重网页设计，我们将使用需要最少代码量的[`Modal`](https://developer.wordpress.org/block-editor/reference-guides/components/modal/)组件将两者连接。更新`PageEditButton`如下：
+
+```js
+import { Button, Modal, TextControl } from '@wordpress/components';
+
+function PageEditButton({ pageId }) {
+ const [ isOpen, setOpen ] = useState( false );
+ const openModal = () => setOpen( true );
+ const closeModal = () => setOpen( false );
+ return (
+ <>
+
+ { isOpen && (
+
+
+
+
+
+
+ );
+}
+```
+
+现在效果应如图所示：
+
+
+
+### 步骤五：保存表单数据
+
+既然我们已经能够编辑页面标题，接下来要确保能够保存它。在 Gutenberg 数据系统中，我们使用 `saveEditedEntityRecord` 操作将变更保存到 WordPress REST API。该操作会发送请求、处理结果，并更新 Redux 状态中的缓存数据。
+
+以下示例可在浏览器开发者工具中尝试：
+
+```js
+// 将数字9替换为实际页面ID
+wp.data.dispatch( 'core' ).editEntityRecord( 'postType', 'page', 9, { title: '更新后的标题' } );
+wp.data.dispatch( 'core' ).saveEditedEntityRecord( 'postType', 'page', 9 );
+```
+
+以上代码片段保存了新标题。与之前不同，现在 `getEntityRecord` 会反映更新后的标题：
+
+```js
+// 将数字9替换为实际页面ID
+wp.data.select( 'core' ).getEntityRecord( 'postType', 'page', 9 ).title.rendered
+// 返回："更新后的标题"
+```
+
+在 REST API 请求完成后，实体记录会立即更新以反映所有已保存的变更。
+
+这是带有生效*保存*按钮的 `EditPageForm` 组件示例：
+
+```js
+function EditPageForm( { pageId, onCancel, onSaveFinished } ) {
+ // ...
+ const { saveEditedEntityRecord } = useDispatch( coreDataStore );
+ const handleSave = () => saveEditedEntityRecord( 'postType', 'page', pageId );
+
+ return (
+
+ {/* ... */}
+
+ );
+}
+```
+
+虽然功能已实现，但还需修复一个问题：表单模态框不会自动关闭，因为我们从未调用 `onSaveFinished`。幸运的是，`saveEditedEntityRecord` 返回的 Promise 会在保存操作完成后解析。让我们在 `EditPageForm` 中利用这个特性：
+
+```js
+function EditPageForm( { pageId, onCancel, onSaveFinished } ) {
+ // ...
+ const handleSave = async () => {
+ await saveEditedEntityRecord( 'postType', 'page', pageId );
+ onSaveFinished();
+ };
+ // ...
+}
+```
+
+### 步骤六：错误处理
+
+此前我们乐观地假设*保存*操作总能成功。但实际操作可能因以下原因失败：
+
+* 网站可能宕机
+* 更新内容可能无效
+* 页面可能已被他人删除
+
+为了在出现这些问题时通知用户，我们需要进行两处调整。当更新失败时，我们不希望关闭表单模态框。仅当更新确实成功时，`saveEditedEntityRecord` 返回的 Promise 才会解析为更新后的记录。若出现异常，则会解析为空值。我们可以利用这一点来保持模态框开启状态：
+
+```js
+function EditPageForm( { pageId, onSaveFinished } ) {
+ // ...
+ const handleSave = async () => {
+ const updatedRecord = await saveEditedEntityRecord( 'postType', 'page', pageId );
+ if ( updatedRecord ) {
+ onSaveFinished();
+ }
+ };
+ // ...
+}
+```
+
+很好！现在让我们来显示错误信息。可以通过 `getLastEntitySaveError` 选择器获取失败详情：
+
+```js
+// 将数字9替换为实际页面ID
+wp.data.select( 'core' ).getLastEntitySaveError( 'postType', 'page', 9 )
+```
+
+以下是在 `EditPageForm` 中的具体应用：
+
+```js
+function EditPageForm( { pageId, onSaveFinished } ) {
+ // ...
+ const { lastError, page } = useSelect(
+ select => ({
+ page: select( coreDataStore ).getEditedEntityRecord( 'postType', 'page', pageId ),
+ lastError: select( coreDataStore ).getLastEntitySaveError( 'postType', 'page', pageId )
+ }),
+ [ pageId ]
+ )
+ // ...
+ return (
+
+
+ {/* ... */}
+
+
+ {/* ... */}
+ { lastError ? (
+
+ );
+}
+```
+
+太棒了！现在 `EditPageForm` 已能完全感知错误状态。
+
+让我们通过触发无效更新来查看错误提示效果。由于文章标题很难引发错误，我们可以将 `date` 属性设置为 `-1` —— 这必定会触发验证错误：
+
+```js
+function EditPageForm( { pageId, onCancel, onSaveFinished } ) {
+ // ...
+ const handleChange = ( title ) => editEntityRecord( 'postType', 'page', pageId, { title, date: -1 } );
+ // ...
+}
+```
+
+刷新页面后，打开表单修改标题并点击保存，您将看到如下错误提示：
+
+
+
+非常好！现在我们可以**恢复 `handleChange` 函数的先前版本**，继续下一步操作。
+
+### 步骤七：状态指示器
+
+我们的表单还存在最后一个问题：缺乏视觉反馈。在表单消失或显示错误信息之前，我们无法完全确定*保存*按钮是否生效。
+
+现在我们将解决这个问题，并向用户传达两种状态：_保存中_和_未检测到更改_。相关的选择器是`isSavingEntityRecord`和`hasEditsForEntityRecord`。与`getEntityRecord`不同，这些选择器从不发起HTTP请求，仅返回当前实体记录状态。
+
+让我们在`EditPageForm`中使用它们：
+
+```js
+function EditPageForm( { pageId, onSaveFinished } ) {
+ // ...
+ const { isSaving, hasEdits, /* ... */ } = useSelect(
+ select => ({
+ isSaving: select( coreDataStore ).isSavingEntityRecord( 'postType', 'page', pageId ),
+ hasEdits: select( coreDataStore ).hasEditsForEntityRecord( 'postType', 'page', pageId ),
+ // ...
+ }),
+ [ pageId ]
+ )
+}
+```
+
+现在我们可以使用`isSaving`和`hasEdits`在保存过程中显示加载动画，并在无编辑内容时禁用保存按钮：
+
+```js
+function EditPageForm( { pageId, onSaveFinished } ) {
+ // ...
+ return (
+ // ...
+
+ 错误：{ lastError.message }
+
+ ) : false }
+ {/* ... */}
+
+
+
+
+ // ...
+ );
+}
+```
+
+请注意，当没有编辑内容或页面正在保存时，我们会禁用*保存*按钮。这是为了防止用户意外重复点击按钮。
+
+此外，由于`@wordpress/data`不支持中断正在进行的*保存*操作，我们也相应禁用了*取消*按钮。
+
+实际运行效果如下：
+
+
+
+
+### 整体联调
+
+所有组件都已就位，太棒了！以下是我们本章构建的完整代码：
+
+```js
+import { useDispatch } from '@wordpress/data';
+import { Button, Modal, TextControl } from '@wordpress/components';
+
+function PageEditButton( { pageId } ) {
+ const [ isOpen, setOpen ] = useState( false );
+ const openModal = () => setOpen( true );
+ const closeModal = () => setOpen( false );
+ return (
+ <>
+
+ { isOpen && (
+
+
+ );
+}
+```
+
+### 步骤四：实现页面标题字段的可编辑功能
+
+我们的*页面标题*字段存在一个问题：无法编辑。它接收固定值但在输入时不会更新。我们需要一个 `onChange` 处理函数。
+
+您可能在其他 React 应用中也见过类似的模式，这被称为["受控组件"](https://reactjs.org/docs/forms.html#controlled-components)：
+
+```js
+function VanillaReactForm({ initialTitle }) {
+ const [title, setTitle] = useState( initialTitle );
+ return (
+ 错误：{ lastError.message }
+ ) : (
+ false
+ ) }
+
+
+
+
+
+
+ );
+}
+```
+
+我们添加了一个 `onChange` 处理函数，通过 `editEntityRecord` 操作跟踪编辑，然后将选择器更改为 `getEditedEntityRecord`，以便 `page.title` 始终反映更改。
+
+现在的效果如下：
+
+
\ No newline at end of file
diff --git a/how-to-guides/data-basics/4-building-a-create-page-form.md b/how-to-guides/data-basics/4-building-a-create-page-form.md
new file mode 100644
index 0000000..493e38d
--- /dev/null
+++ b/how-to-guides/data-basics/4-building-a-create-page-form.md
@@ -0,0 +1,395 @@
+# 构建创建页面表单
+
+在[上一章节](/docs/how-to-guides/data-basics/3-building-an-edit-form.md)中我们创建了*编辑页面*功能，本章节我们将新增*创建页面*功能。以下是我们即将构建功能的预览：
+
+
+
+### 步骤一：添加“创建新页面”按钮
+
+首先我们构建一个用于显示创建页面表单的按钮，这与我们在[第三章节](/docs/how-to-guides/data-basics/3-building-an-edit-form.md)构建的编辑按钮类似：
+
+```js
+import { useDispatch } from '@wordpress/data';
+import { Button, Modal, TextControl } from '@wordpress/components';
+
+function CreatePageButton() {
+ const [isOpen, setOpen] = useState( false );
+ const openModal = () => setOpen( true );
+ const closeModal = () => setOpen( false );
+ return (
+ <>
+
+ { isOpen && (
+
+
+
+
+
+
+ );
+}
+```
+
+最终效果如下所示：
+
+
+
+### 步骤二：提取受控页面表单
+
+按钮就位后，我们可以全力构建表单。本教程重点在于数据管理，因此不会构建完整的页面编辑器。表单将仅包含一个字段：文章标题。
+
+幸运的是，我们在[第三章节](/docs/how-to-guides/data-basics/3-building-an-edit-form.md)构建的`EditPageForm`已经实现了80%的功能。大部分用户界面已就绪，我们将在`CreatePageForm`中复用这些组件。首先将表单UI提取为独立组件：
+
+```js
+function EditPageForm( { pageId, onCancel, onSaveFinished } ) {
+ // ...
+ return (
+
+
+
+
+ );
+}
+```
+
+这段代码的质量优化不应改变应用程序的任何功能。让我们尝试编辑页面来确认：
+
+
+
+很好！编辑表单依然存在，现在我们有了构建新`CreatePageForm`的基础模块。
+
+### 整合所有代码
+
+以下是本章节构建的全部内容：
+
+```js
+function CreatePageForm( { onCancel, onSaveFinished } ) {
+ const [title, setTitle] = useState();
+ const { lastError, isSaving } = useSelect(
+ ( select ) => ( {
+ lastError: select( coreDataStore )
+ .getLastEntitySaveError( 'postType', 'page' ),
+ isSaving: select( coreDataStore )
+ .isSavingEntityRecord( 'postType', 'page' ),
+ } ),
+ []
+ );
+
+ const { saveEntityRecord } = useDispatch( coreDataStore );
+ const handleSave = async () => {
+ const savedRecord = await saveEntityRecord(
+ 'postType',
+ 'page',
+ { title, status: 'publish' }
+ );
+ if ( savedRecord ) {
+ onSaveFinished();
+ }
+ };
+
+ return (
+ 错误：{ lastError.message }
+ ) : (
+ false
+ ) }
+
+
+
+
+
+
+ );
+}
+```
+
+现在只需刷新页面即可体验表单功能：
+
+
+
+## 后续步骤
+
+* **下一章节：** [添加删除按钮](/docs/how-to-guides/data-basics/5-adding-a-delete-button.md)
+* **上一章节：** [构建编辑表单](/docs/how-to-guides/data-basics/3-building-an-edit-form.md)
+* （可选）在 block-development-examples 代码库中查看[完整应用](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/data-basics-59c8f8)
+
+### 步骤三：构建CreatePageForm组件
+
+`CreatePageForm`组件只需提供渲染`PageForm`组件所需的七个属性：
+
+* 标题
+* 标题变更处理函数
+* 编辑状态标识
+* 最后错误信息
+* 保存状态标识
+* 取消处理函数
+* 保存处理函数
+
+具体实现如下：
+
+#### 标题、标题变更处理、编辑状态
+
+`EditPageForm`组件更新并保存的是Redux状态中已存在的实体记录，因此我们依赖`editedEntityRecords`选择器。
+
+而`CreatePageForm`不存在预先的实体记录，只有空表单。用户输入的内容仅存在于本地表单，可通过React的`useState`钩子进行跟踪：
+
+```js
+function CreatePageForm( { onCancel, onSaveFinished } ) {
+ const [title, setTitle] = useState();
+ const handleChange = ( title ) => setTitle( title );
+ return (
+ 错误：{ lastError.message }
+ ) : (
+ false
+ ) }
+
+
+
+
+ 暂无数据
;
+ }
+
+ return (
+ | 标题 | +操作 | +
| { decodeEntities( page.title.rendered ) } | +
+
+
+ |
+
+ {/* ... */}
+
+ );
+}
+```
+
+本教程重点在于页面管理，不深入讨论上述代码细节。若想了解`@wordpress/notices`的详细信息，建议查阅[手册页面](https://developer.wordpress.org/block-editor/reference-guides/data/data-core-notices/)。
+
+现在我们已经准备好向用户报告可能发生的错误了。
+
+#### 发送通知
+
+有了 SnackbarNotices 组件后，我们现在可以发送通知了！具体操作如下：
+
+```js
+import { useEffect } from 'react';
+import { store as noticesStore } from '@wordpress/notices';
+function DeletePageButton( { pageId } ) {
+ const { createSuccessNotice, createErrorNotice } = useDispatch( noticesStore );
+ // 如果传入存储句柄而非回调函数，useSelect 将返回选择器列表：
+ const { getLastEntityDeleteError } = useSelect( coreDataStore )
+ const handleDelete = async () => {
+ const success = await deleteEntityRecord( 'postType', 'page', pageId);
+ if ( success ) {
+ // 告知用户操作成功：
+ createSuccessNotice( "页面已删除！", {
+ type: 'snackbar',
+ } );
+ } else {
+ // 在 deleteEntityRecord 执行失败后，直接使用选择器获取最新错误信息
+ const lastError = getLastEntityDeleteError( 'postType', 'page', pageId );
+ const message = ( lastError?.message || '出现错误。' ) + ' 请刷新页面后重试。'
+ // 向用户明确展示操作失败原因：
+ createErrorNotice( message, {
+ type: 'snackbar',
+ } );
+ }
+ }
+ // ...
+}
+```
+
+太好了！现在 `DeletePageButton` 已完全具备错误感知能力。让我们看看实际错误提示效果。通过将 `pageId` 乘以一个大数值来触发无效删除操作：
+
+```js
+function DeletePageButton( { pageId, onCancel, onSaveFinished } ) {
+ pageId = pageId * 1000;
+ // ...
+}
+```
+
+刷新页面并点击任意 `删除` 按钮后，您将看到如下错误提示：
+
+
+
+完美！现在可以**移除 `pageId = pageId * 1000;` 这行代码**。
+
+接下来尝试实际删除页面。刷新浏览器并点击删除按钮后，您将看到：
+
+
+
+大功告成！
+
+### 完整功能集成
+
+所有组件已就绪，太棒了！以下是本章节完成的所有代码变更：
+
+```js
+import { useState, useEffect } from 'react';
+import { useSelect, useDispatch } from '@wordpress/data';
+import { Button, Modal, TextControl } from '@wordpress/components';
+
+function MyFirstApp() {
+ const [searchTerm, setSearchTerm] = useState( '' );
+ const { pages, hasResolved } = useSelect(
+ ( select ) => {
+ const query = {};
+ if ( searchTerm ) {
+ query.search = searchTerm;
+ }
+ const selectorArgs = ['postType', 'page', query];
+ const pages = select( coreDataStore ).getEntityRecords( ...selectorArgs );
+ return {
+ pages,
+ hasResolved: select( coreDataStore ).hasFinishedResolution(
+ 'getEntityRecords',
+ selectorArgs,
+ ),
+ };
+ },
+ [searchTerm],
+ );
+
+ return (
+
+
+ );
+}
+
+function SnackbarNotices() {
+ const notices = useSelect(
+ ( select ) => select( noticesStore ).getNotices(),
+ []
+ );
+ const { removeNotice } = useDispatch( noticesStore );
+ const snackbarNotices = notices.filter( ( { type } ) => type === 'snackbar' );
+
+ return (
+
+
+ 暂无结果
;
+ }
+
+ return (
+ | 标题 | +操作 | +
| { page.title.rendered } | +
+
+
+ |
+
{ __( '你好世界', 'myguten' ) }
; + }, + + save: () => { + const blockProps = useBlockProps.save( { style: { color: 'red' } } ); + + return{ __( '你好世界', 'myguten' ) }
; + }, +} ); +``` + +在上述示例中，该函数将使用第一个参数作为要翻译的字符串。第二个参数是文本域，必须与插件指定的文本域标识符匹配。 + +常用函数（这些函数与它们的 PHP 版本相对应）包括： + +- `__( '你好世界', 'my-text-domain' )` - 翻译特定字符串。 +- `_n( '%s 条评论', '%s 条评论', numberOfComments, 'my-text-domain' )` - 根据给定数字翻译并返回单数或复数形式。 +- `_x( '默认', '区块样式', 'my-text-domain' )` - 在特定上下文中翻译字符串。 + +
+注意：所有向用户显示的字符串都应使用 i18n 函数进行包装。
+
+
+当代码中的所有字符串都完成包装后，最后一步是使用 [wp_set_script_translations()](https://developer.wordpress.org/reference/functions/wp_set_script_translations/) 函数告知 WordPress 您的 JavaScript 包含翻译内容。
+
+```php
+\n"
+"Language-Team: 语言团队
+
+ );
+ },
+
+ // 不保存信息至区块
+ // 数据通过钩子保存至文章元数据
+ save: () => {
+ return null;
+ },
+} );
+```
+
+创建文章并添加元数据区块即可验证功能。您将看到可输入值的字段。当保存文章（草稿或已发布）时，文章元数据值也会同步保存。可通过保存后重新加载草稿来验证——重新加载后表单仍将保留输入内容。
+
+您还可以检查数据库表`wp_postmeta`，确认新文章ID包含新字段数据。
+
+**故障排除**：请确保在每次修改后重新构建代码（您更新了步骤1的PHP代码，且JavaScript文件已正确加入队列）。检查构建输出和开发者控制台是否有错误信息。
\ No newline at end of file
diff --git a/how-to-guides/notices/README.md b/how-to-guides/notices/README.md
new file mode 100644
index 0000000..7015197
--- /dev/null
+++ b/how-to-guides/notices/README.md
@@ -0,0 +1,82 @@
+# 通知
+
+通知是显示在管理页面顶部附近的信息性用户界面元素。WordPress核心程序、主题和插件都使用通知来指示操作结果，或吸引用户关注必要信息。
+
+在经典编辑器中，挂接到`admin_notices`操作的通知可以渲染任意HTML内容。而在区块编辑器中，通知则受限于更规范的API。
+
+## 经典编辑器中的通知
+
+在经典编辑器中，"文章草稿已更新"通知的示例如下：
+
+
+
+生成等效的"文章草稿已更新"通知需要如下代码：
+
+```php
+/**
+ * 挂接到'admin_notices'操作来渲染
+ * 通用HTML通知。
+ */
+function myguten_admin_notice() {
+ $screen = get_current_screen();
+ // 仅在文章编辑器中显示此通知。
+ if ( ! $screen || 'post' !== $screen->base ) {
+ return;
+ }
+ // 渲染通知的HTML内容。
+ wp_admin_notice(
+ sprintf( __( '文章草稿已更新。预览文章' ), get_preview_post_link() ),
+ array(
+ 'type' => 'success',
+ 'dismissible' => true,
+ )
+ );
+};
+add_action( 'admin_notices', 'myguten_admin_notice' );
+```
+
+重要的是，`admin_notices`钩子允许开发者渲染任意HTML内容。这样做的主要优势是开发者拥有极大的灵活性。关键劣势在于，任意HTML使得通知功能的后续迭代更加困难（甚至不可能），因为迭代需要兼容各种任意HTML。这就是区块编辑器采用规范API的原因。
+
+## 区块编辑器中的通知
+
+在区块编辑器中，"文章已发布"通知的示例如下：
+
+
+
+生成等效的"文章已发布"通知需要如下代码：
+
+```js
+( function ( wp ) {
+ wp.data.dispatch( 'core/notices' ).createNotice(
+ 'success', // 可选类型：success, info, warning, error
+ '文章已发布。', // 显示的文本内容
+ {
+ isDismissible: true, // 用户是否可关闭该通知
+ // 用户可执行的操作
+ actions: [
+ {
+ url: '#',
+ label: '查看文章',
+ },
+ ],
+ }
+ );
+} )( window.wp );
+```
+
+当在JavaScript应用程序生命周期中生成通知时，您应该使用此_通知数据API_。
+
+为了更好地理解上述具体代码示例：
+
+- `wp`是WordPress的全局窗口变量
+- `wp.data`是区块编辑器提供的用于访问数据存储的对象
+- `wp.data.dispatch('core/notices')`访问由通知包注册到区块编辑器数据存储的功能
+- `createNotice()`是通知包提供的用于注册新通知的函数。区块编辑器通过读取通知数据存储来了解需要显示哪些通知
+
+请查看[_在编辑器中加载资源_](/docs/how-to-guides/enqueueing-assets-in-the-editor.md)教程，了解如何将自定义JavaScript加载到区块编辑器中的基础知识。
+
+## 了解更多
+
+区块编辑器提供完整的API用于生成通知。官方文档是了解功能可能性的绝佳资源。
+
+要获取可用操作和选择器的完整列表，请参阅[通知数据手册](/docs/reference-guides/data/data-core-notices.md)页面。
\ No newline at end of file
diff --git a/how-to-guides/notices/block-editor-notice.png b/how-to-guides/notices/block-editor-notice.png
new file mode 100644
index 0000000..89bf3e4
Binary files /dev/null and b/how-to-guides/notices/block-editor-notice.png differ
diff --git a/how-to-guides/notices/classic-editor-notice.png b/how-to-guides/notices/classic-editor-notice.png
new file mode 100644
index 0000000..d96f4aa
Binary files /dev/null and b/how-to-guides/notices/classic-editor-notice.png differ
diff --git a/how-to-guides/platform/README.md b/how-to-guides/platform/README.md
new file mode 100644
index 0000000..205e3c5
--- /dev/null
+++ b/how-to-guides/platform/README.md
@@ -0,0 +1,60 @@
+# 开发平台
+
+古腾堡项目不仅致力于为WordPress打造更优秀的编辑器，更在构建一个可扩展的开发平台。该平台包含一系列可用于Web应用程序的JavaScript工具包。[查看npm上的可用工具包列表](https://www.npmjs.com/org/wordpress)。
+
+## 用户界面组件
+
+[WordPress组件包](/packages/components/README.md)提供了一系列可在项目中直接使用的UI组件。访问[WordPress Storybook网站](https://wordpress.github.io/gutenberg/)可交互式查看可用组件及其设置。
+
+以下是在项目中使用组件的快速示例：
+
+安装依赖：
+
+```bash
+npm install --save @wordpress/components
+```
+
+在React中使用：
+
+```jsx
+import { Button } from '@wordpress/components';
+
+function MyApp() {
+ return ;
+}
+```
+
+多数组件包含样式CSS文件，需要引入才能正常显示样式。组件样式表位于`node_modules/@wordpress/components/build-style/style.css`，可直接链接或复制到项目中引入。
+
+## 开发脚本
+
+[`@wordpress/scripts`工具包](/packages/scripts/README.md)是一组可复用的JavaScript开发脚本——包含构建、代码检查和测试脚本，无需额外配置文件即可使用。
+
+以下是使用`wp-scripts`工具的快速示例：
+
+安装依赖：
+
+```bash
+npm install --save-dev @wordpress/scripts
+```
+
+在package.json文件中添加脚本配置：
+
+```json
+ "scripts": {
+ "build": "wp-scripts build",
+ "format": "wp-scripts format",
+ "lint:js": "wp-scripts lint-js",
+ "start": "wp-scripts start"
+ }
+```
+
+配置后即可使用`npm run build`命令，通过预设的webpack配置构建项目，代码格式化和检查同理。`start`命令用于开发模式。完整文档请参阅[`@wordpress/scripts`工具包](/packackages/scripts/README.md)。
+
+更多信息请参考区块编辑器手册中的[JavaScript入门教程](/docs/how-to-guides/javascript/js-build-setup.md)。
+
+## 区块编辑器
+
+[`@wordpress/block-editor`工具包](https://developer.wordpress.org/block-editor/packages/packages-block-editor/)支持创建和使用独立的区块编辑器。
+
+详细了解请阅读[“构建自定义区块编辑器”教程](/docs/how-to-guides/platform/custom-block-editor.md)。
\ No newline at end of file
diff --git a/how-to-guides/platform/custom-block-editor.md b/how-to-guides/platform/custom-block-editor.md
new file mode 100644
index 0000000..2f51bd3
--- /dev/null
+++ b/how-to-guides/platform/custom-block-editor.md
@@ -0,0 +1,531 @@
+## 总结
+
+恭喜您完成本指南的学习！现在您应该对区块编辑器的工作原理有了更深入的理解。
+
+您刚刚构建的自定义区块编辑器完整代码已[发布于GitHub](https://github.com/getdave/standalone-block-editor)，欢迎下载并亲自体验。在实践操作中不断探索，将所学知识推向新的高度。
+
+## 区块持久化
+
+在创建自定义区块编辑器的旅程中，您已经取得了长足进展。但还有一个重要领域有待探讨——区块持久化。换句话说，就是让您的区块在页面刷新之间保持保存并可用。
+
+
+
+由于这仅是一项实验，本指南选择使用浏览器的`localStorage` API来处理区块数据保存。在实际应用场景中，您可能会选择更可靠稳健的系统（例如数据库）。
+
+接下来，让我们深入探讨如何处理区块保存。
+
+### 在状态中存储区块
+
+查看`src/components/block-editor/index.js`文件时，您会注意到已创建了将区块存储为数组的状态：
+
+```jsx
+// 文件：src/components/block-editor/index.js
+
+const [ blocks, updateBlocks ] = useState( [] );
+```
+
+如前所述，`blocks`作为`value`属性传递给"受控"组件`在WordPress后台进行独立区块编辑器的实验
+ + + +本实验旨在探索在WordPress后台创建独立区块编辑器实例的难易程度。
+ +``` + +### 检索历史区块数据 + +实现持久化固然重要，但只有当这些数据在每次完整页面重载时被检索并在编辑器中恢复，才能真正发挥作用。 + +访问数据会产生副作用，因此必须使用`useEffect`钩子来处理： + +```jsx +// 文件：src/components/block-editor/index.js + +useEffect( () => { + const storedBlocks = window.localStorage.getItem( 'getdavesbeBlocks' ); + + if ( storedBlocks && storedBlocks.length ) { + updateBlocks( () => parse( storedBlocks ) ); + createInfoNotice( '区块已加载', { + type: 'snackbar', + isDismissible: true, + } ); + } +}, [] ); +``` + +该处理程序： + +- 从本地存储中获取序列化的区块数据 +- 使用`parse()`工具将序列化区块转换回JavaScript对象 +- 调用状态设置器`updateBlocks`，使状态中的`blocks`值更新为从LocalStorage检索到的区块 + +这些操作的结果是，受控的`
+ 本指南涉及的完整代码可通过配套的WordPress插件下载。该插件中的演示代码是核心学习资源。
+
+
+## 代码语法
+
+本指南中的代码片段使用 JSX 语法。当然您也可以选择使用原生 JavaScript。不过许多开发者在熟悉 JSX 后认为其更易读写，因此《区块编辑器手册》中的所有代码示例均采用此语法。
+
+## 即将构建的内容
+
+通过本指南，您将创建一个（近乎）功能完整的区块编辑器实例。最终效果如下所示：
+
+
+
+虽然外观相似，但这个编辑器并非您在WordPress中创建文章和页面时熟悉的那个*区块编辑器*，而是一个完全自定义的实例，将存在于名为"区块编辑器"的自定义WordPress管理页面中。
+
+该编辑器将具备以下特性：
+
+- 支持添加和编辑所有核心区块
+- 熟悉的视觉样式和主界面/侧边栏布局
+- 页面刷新后保持*基础*的区块持久化
+
+## 插件设置与组织架构
+
+自定义编辑器将以WordPress插件形式构建。为简化概念，插件将命名为 `Standalone Block Editor Demo`（独立区块编辑器演示），这正是其功能体现。
+
+插件文件结构如下所示：
+
+
+
+以下是核心文件说明：
+
+- `plugin.php` – 包含注释元数据的标准插件入口文件，负责引入 `init.php`
+- `init.php` - 处理主插件逻辑的初始化
+- `src/` (目录) - 存放 JavaScript 和 CSS 源文件的位置（这些文件*不*由插件直接加载）
+- `webpack.config.js` - 自定义 Webpack 配置，扩展了 [`@wordpress/scripts`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-scripts/) npm 包提供的默认配置，以支持自定义CSS样式（通过Sass实现）
+
+未在上图显示的是 `build/` 目录，该目录用于存放通过 `@wordpress/scripts` 编译输出的 JS 和 CSS 文件。这些文件由插件单独加载。
+
+
+ 在本指南中，每个代码片段的顶部都会以注释形式标注文件名引用，方便您对照学习。
+
+
+基础文件结构就绪后，接下来让我们了解需要哪些软件包。
+
+### 键盘导航
+
+完成基础组件结构搭建后，最后一步是将所有内容包裹在 [`navigateRegions` 高阶组件](https://github.com/WordPress/gutenberg/tree/e38dbe958c04d8089695eb686d4f5caff2707505/packages/components/src/higher-order/navigate-regions) 中，为布局中的不同"区域"提供键盘导航功能。
+
+```jsx
+// 文件：src/editor.js
+
+export default navigateRegions( Editor );
+```
+
+## 自定义 `
+
+
+
+
+
+);
+```
+
+其中的关键组件是 `
+ 如果您已熟悉在 WordPress 中创建自定义后台页面的流程，可以直接跳至后续步骤。
+
+
+### 注册页面
+
+您需要使用标准的 WordPress [`add_menu_page()`](https://developer.wordpress.org/reference/functions/add_menu_page/) 辅助函数来[注册自定义后台页面](https://developer.wordpress.org/reference/functions/add_menu_page/)：
+
+```php
+// 文件：init.php
+
+add_menu_page(
+ '独立区块编辑器', // 页面可见名称
+ '区块编辑器', // 菜单标签
+ 'edit_posts', // 所需权限
+ 'getdavesbe', // 页面钩子/别名
+ 'getdave_sbe_render_block_editor', // 页面渲染函数
+ 'dashicons-welcome-widgets-menus' // 自定义图标
+);
+```
+
+`getdave_sbe_render_block_editor` 函数将用于渲染后台页面的内容。温馨提示：每个步骤的源代码均可在[配套插件](https://github.com/getdave/standalone-block-editor)中查看。
+
+### 添加目标 HTML
+
+由于区块编辑器是基于 React 的应用程序，您需要在自定义页面中输出 HTML 容器，以便 JavaScript 渲染区块编辑器。
+
+让我们使用上一步中引用的 `getdave_sbe_render_block_editor` 函数：
+
+```php
+// 文件：init.php
+
+function getdave_sbe_render_block_editor() {
+ ?>
+
+ 编辑器加载中...
+
+ ` 组件渲染到自定义管理页面的等待 `` 中。
+
+```jsx
+domReady( function () {
+ const root = createRoot( document.getElementById( 'getdave-sbe-block-editor' ) );
+ const settings = window.getdaveSbeSettings || {};
+ registerCoreBlocks();
+ root.render(
+ ` 组件
+
+让我们仔细看看上面代码中使用的 `` 组件，它位于[配套插件](https://github.com/getdave/standalone-block-editor)的 `src/editor.js` 文件中。
+
+尽管名称如此，但这并不是块编辑器的实际核心。相反，它是一个*包装器*组件，将包含构成自定义编辑器主体的组件。
+
+### 依赖项
+
+在 `` 中的第一件事是引入一些依赖项。
+
+```jsx
+// 文件：src/editor.js
+
+import Notices from 'components/notices';
+import Header from 'components/header';
+import Sidebar from 'components/sidebar';
+import BlockEditor from 'components/block-editor';
+```
+
+其中最重要的是内部组件 `BlockEditor` 和 `Sidebar`，稍后将详细介绍。
+
+其余组件主要包括构成编辑器布局和周围用户界面（UI）的静态元素，包括标题和通知区域等。
+
+### 编辑器渲染
+
+有了这些组件后，您可以定义 `` 组件。
+
+```jsx
+// 文件：src/editor.js
+
+function Editor( { settings } ) {
+ return (
+
+
+ );
+}
+```
+
+在此过程中，编辑器的核心布局以及一些专门的[上下文提供者](https://react.dev/reference/react/createContext#provider)被搭建起来，这些提供者使特定功能在整个组件层次结构中可用。
+
+让我们更详细地研究这些：
+
+- `` – 启用[拖放功能的放置区域](https://github.com/WordPress/gutenberg/tree/e38dbe958c04d8089695eb686d4f5caff2707505/packages/components/src/drop-zone)
+- `` – 提供一个“消息栏”通知，如果有任何消息发送到 `core/notices` 存储，则会渲染该通知
+- `` – 在编辑器 UI 顶部渲染静态标题“独立块编辑器”
+- `` – 自定义块编辑器组件
+
+### 理解 `` 组件
+
+除了 `` 之外，下一个最有趣的组件是 [``](https://github.com/WordPress/gutenberg/blob/e38dbe958c04d8089695eb686d4f5caff2707505/packages/block-editor/src/components/block-list/index.js)。
+
+这是最重要的组件之一，其作用是**将区块列表渲染到编辑器中**。
+
+它能够实现这一功能，部分原因在于它被放置为 `` 的子组件，这使得它可以完全访问编辑器中当前区块状态的所有信息。
+
+#### `BlockList` 是如何工作的？
+
+在底层，`` 依赖于其他几个低级组件来渲染区块列表。
+
+这些组件的层次结构可以*近似*如下：
+
+```jsx
+// 以下为伪代码，仅作示例。
+
+
+ /* 从 rootClientId 渲染区块列表。 */
+
+ /* 从 BlockList 渲染单个区块。 */
+
+ /* 渲染区块的标准可编辑区域。 */
+
+
+
+```
+
+以下是这些组件如何协同工作以渲染区块列表的大致过程：
+
+- `` 遍历所有区块的 `clientIds`，并通过 [``](https://github.com/WordPress/gutenberg/blob/def076809d25e2ad680beda8b9205ab9dea45a0f/packages/block-editor/src/components/block-edit/index.js) 渲染单个区块。
+- 最后，[区块本身](https://github.com/WordPress/gutenberg/blob/def076809d25e2ad680beda8b9205ab9dea45a0f/packages/block-editor/src/components/block-edit/edit.js) 使用 `Component` 占位符组件进行渲染。
+
+`@wordpress/block-editor` 包中的组件是最复杂且涉及最多的组件之一。如果你想从根本上理解编辑器的工作原理，理解这些组件至关重要。强烈建议研究这些组件。
+
+## 审查侧边栏
+
+在 `` 的渲染中，还有一个 `` 组件。
+
+```jsx
+// 文件：src/components/block-editor/index.js
+
+return (
+ ` 组件显示高级区块设置。
+
+```jsx
+
+
+```
+
+然而，细心的读者可能已经注意到，在 ``（`src/editor.js`）组件的布局中已经存在一个 `` 组件：
+
+```jsx
+// 文件：src/editor.js
+` 中渲染的组件。然而，该实现使用了 Slot/Fill 来暴露一个 `Fill`（``），随后该 `Fill` 被导入并在 `` 组件中渲染（见上文）。
+
+通过这种方式，你可以将 `` 的 React 上下文中保留 ``，同时允许它在 DOM 中的另一个位置（即 `` 中）渲染。
+
+这可能看起来过于复杂，但这是为了让 `` 能够访问当前区块的信息所必需的。如果没有 Slot/Fill，这种设置将极难实现。
+
+至此，你已经了解了自定义 `` 的渲染过程。
+
+`类，并加入以下样式：
+
+```css
+.wp-element- a { color: <用户颜色值> !important; }
+```
+
+虽然这种方式始终保留了用户偏好设置，但过高的特异性会导致与某些合法使用HTML元素的区块产生冲突。为解决该问题，WordPress 5.9版本移除了`!important`声明，并更新了相关区块的样式设置，使其具有比用户链接颜色设置更高的特异性。调整后的样式为：
+
+```css
+.wp-element- a { color: <用户颜色值>; }
+```
+
+此项调整后，区块开发者和主题开发者需要确保用户设置始终生效，避免用户提供的链接颜色（特异性值为011）被意外覆盖。
+
+### 什么是blockGap及其应用方式
+
+对于包含内部区块的组件（如群组、列、按钮组、社交图标等），`blockGap`用于控制内部区块之间的间距。要使`blockGap`生效，区块必须启用布局区块支持功能，该功能提供可通过区块间距控件调整的布局样式。根据区块布局的不同，`blockGap`值将作为垂直边距或CSS网格间隙值输出。在编辑器中，`blockGap`的控制选项名为"区块间距"，位于尺寸设置面板中。
+
+```json
+{
+ "version": 3,
+ "settings": {
+ "spacing": {
+ "blockGap": true,
+ }
+ },
+ "styles": {
+ "spacing": {
+ "blockGap": "1.5rem"
+ }
+ }
+}
+```
+
+`blockGap`设置支持布尔值或`null`，默认值为`null`，这为样式输出提供了更精细的控制层级。在`theme.json`文件中，`settings.spacing.blockGap`设置接受以下参数：
+
+- `true`：启用编辑器界面中的"区块间距"控件，并输出`blockGap`样式
+- `false`：禁用编辑器界面中的"区块间距"控件，但仍会渲染存储在`theme.json`中的`blockGap`样式，允许主题使用`blockGap`值的同时限制用户在编辑器中进行修改
+- `null`（默认值）：同时禁用"区块间距"控件和`blockGap`样式输出
+
+根级别`styles.spacing.blockGap`样式定义的值同时会作为CSS自定义属性输出，其命名为`--wp--style--block-gap`。
+
+### 浏览器样式更新延迟的原因分析
+
+在使用theme.json进行主题开发时，您可能会注意到样式更改需要30秒以上才能在浏览器中显示，这是因为`theme.json`存在缓存机制。要解决此缓存问题，请在`wp-config.php`文件中将`WP_DEBUG`或`SCRIPT_DEBUG`设置为'true'。这将指示WordPress跳过缓存并始终使用最新数据。
+
+# 全局设置与样式 (theme.json)
+
+WordPress 5.8 引入了一套[全新机制](https://make.wordpress.org/core/2021/06/25/introducing-theme-json-in-wordpress-5-8/)来配置编辑器，该机制支持更精细化的控制，并为未来WordPress版本的样式管理迈出了第一步：即通过`theme.json`文件实现。
+
+## 设计理念
+
+区块编辑器API在不同层面的演进速度不一，尤其在影响主题功能的领域出现了一些发展阵痛。例如：[通过编程方式控制编辑器](https://make.wordpress.org/core/2020/01/23/controlling-the-block-editor/)的能力，或是能够协调用户、主题和核心样式偏好的[区块样式系统](https://github.com/WordPress/gutenberg/issues/9534)。
+
+当前我们正致力于将多个与样式相关的API整合至统一入口——即放置在主题目录根路径下的`theme.json`文件。
+
+### 区块编辑器设置
+
+相较于不断新增的主题支持标志或替代方案，`theme.json`文件提供了定义区块编辑器设置的标准化方式。这些设置包括：
+
+- 应向用户显示或隐藏哪些自定义选项
+- 用户可使用的默认颜色、字体大小等配置
+- 定义编辑器的默认布局（宽度和对齐方式）
+
+### 支持按区块精细控制
+
+为实现更精细的调控，这些设置同样支持在`theme.json`中针对特定区块进行配置。例如：
+
+- 为特定区块（如表格）使用专属预设，其余区块使用通用预设
+- 为除标题区块外的所有区块启用字体大小UI控件
+- 等等
+
+### 集中化管理样式
+
+通过结构化方式在`theme.json`文件中设置样式属性，区块编辑器能够统筹管理来自不同来源（用户、主题和核心CSS）的CSS。例如当主题和用户同时设置段落字体大小时，系统只会加载用户设置的样式而非主题样式。
+
+这样做的好处包括：
+
+- 减少CSS加载量
+- 避免样式优先级冲突
+
+### CSS自定义属性：预设与自定义
+
+某些样式领域需要通过共享值来实现全站统一调整，为此我们开始在部分场景中实验CSS自定义属性（即CSS变量）：
+
+- **预设配置**：主题声明的[色彩调色板](/docs/how-to-guides/themes/theme-support.md#block-color-palettes)、[字体尺寸](/docs/how-to-guides/themes/theme-support.md#block-font-sizes)或[渐变效果](/docs/how-to-guides/themes/theme-support.md#block-gradient-presets)会被转换为CSS自定义属性，同时在前端和编辑器中加载。
+
+{% codetabs %}
+{% 输入 %}
+
+```json
+{
+ "version": 3,
+ "settings": {
+ "color": {
+ "palette": [
+ {
+ "name": "黑色",
+ "slug": "black",
+ "color": "#000000"
+ },
+ {
+ "name": "白色",
+ "slug": "white",
+ "color": "#ffffff"
+ }
+ ]
+ }
+ }
+}
+```
+
+{% 输出 %}
+
+```css
+body {
+ --wp--preset--color--black: #000000;
+ --wp--preset--color--white: #ffffff;
+}
+```
+
+{% end %}
+
+- **自定义属性**：系统还提供了创建自定义CSS属性的机制。
+
+{% codetabs %}
+{% 输入 %}
+
+```json
+{
+ "version": 3,
+ "settings": {
+ "custom": {
+ "line-height": {
+ "body": 1.7,
+ "heading": 1.3
+ }
+ }
+ }
+}
+```
+
+{% 输出 %}
+
+```css
+body {
+ --wp--custom--line-height--body: 1.7;
+ --wp--custom--line-height--heading: 1.3;
+}
+```
+
+{% end %}
+
+## 技术规范
+
+本规范适用于使用此格式的三大来源：核心系统、主题和用户。主题可通过创建`theme.json`文件来覆盖核心默认设置。用户则可通过正在开发中的站点编辑器界面，覆盖主题或核心的预设配置。
+
+```json
+{
+ "version": 3,
+ "settings": {},
+ "styles": {},
+ "customTemplates": {},
+ "templateParts": {}
+}
+```
+
+### 自定义模板
+
+ a {
+ color: !important;
+}
+```
+
+其中：
+- `` 为随机生成的数字
+- `` 可以是 `var(--wp--preset--color--slug)`（当用户选择预设值时）或原始颜色值（当用户选择自定义值时）
+
+区块将被附加 `.wp-elements-` 类名。
+
+## 外观工具
+
+通过此设置启用以下全局样式配置项：
+
+- 边框：颜色、圆角、样式、宽度
+- 颜色：链接色彩
+- 间距：区块间隙、外边距、内边距
+- 排版：行高
+- 尺寸：宽高比、最小高度
+- 定位：粘性定位
+
+```php
+add_theme_support( 'appearance-tools' );
+```
+
+## 边框
+
+启用完整边框设置功能：
+
+```php
+add_theme_support( 'border' );
+```
+
+## 链接颜色
+
+启用链接颜色设置功能：
+
+```php
+add_theme_support( 'link-color' );
+```
+
+## 区块化模板部件
+
+区块化模板部件允许管理员使用区块编辑网站局部组件。此功能默认关闭，需要主题通过声明支持来启用：
+
+```php
+add_theme_support( 'block-template-parts' );
+```
+
+该功能仅对非区块主题有实际意义，因为区块主题已通过站点编辑器原生支持区块化模板部件。
+
+独立模板部件编辑器不允许编辑者创建新模板部件或删除现有模板部件，这是因为主题需要手动在 PHP 模板中包含模板部件。
+
+您可在[主题手册的区块模板与模板部件章节](https://developer.wordpress.org/themes/block-themes/templates-and-template-parts/#block-c5fa39a2-a27d-4bd2-98d0-dc6249a0801a)中了解更多关于区块化模板部件的信息。
+
+# 主题支持
+
+新版区块功能为所有主题提供了基础支持，同时包含可选的增强功能以及扩展和自定义能力。
+
+构建主题时需要考虑以下几个新概念：
+
+- **编辑器调色板** - 系统提供默认颜色集，但主题可以注册自己的颜色，并可选地将用户选择限制在预设调色板范围内。
+- **编辑器字号面板** - 系统提供默认字号集，但主题可以注册自己的字号，并可选地将用户选择限制在预设字号范围内。
+- **响应式嵌入内容** - 主题需主动启用响应式嵌入功能。
+- **前端与编辑器样式** - 为充分发挥区块功能，主题开发者需确保核心样式正常显示并启用，或编写与自身主题最适配的自定义样式。
+- **区块工具** - 主题可选择启用多种区块工具，如行高设置、自定义单位等。
+- **核心区块模式** - 主题可选择禁用默认区块模式。
+
+默认情况下，区块会提供自身样式以确保在未修改的主题中正常显示。同时它们还[提供可选的预设样式](#默认区块样式)。主题可以添加/覆盖这些样式，也可以完全不提供样式，完全依赖区块自带的样式。
+
+某些高级区块功能需要主题本身启用支持，因为这些样式难以由区块直接提供，可能需要主题本身进行架构层面的调整才能完美适配。
+
+要启用这些功能，请在主题的 `functions.php` 文件中调用 `add_theme_support`。例如：
+
+```php
+function mytheme_setup_theme_supported_features() {
+ add_theme_support( 'editor-color-palette', array(
+ array(
+ 'name' => esc_attr__( '强品红色', 'themeLangDomain' ),
+ 'slug' => 'strong-magenta',
+ 'color' => '#a156b4',
+ ),
+ array(
+ 'name' => esc_attr__( '浅灰品红色', 'themeLangDomain' ),
+ 'slug' => 'light-grayish-magenta',
+ 'color' => '#d0a5db',
+ ),
+ array(
+ 'name' => esc_attr__( '极浅灰色', 'themeLangDomain' ),
+ 'slug' => 'very-light-gray',
+ 'color' => '#eee',
+ ),
+ array(
+ 'name' => esc_attr__( '深灰色', 'themeLangDomain' ),
+ 'slug' => 'very-dark-gray',
+ 'color' => '#444',
+ ),
+ ) );
+}
+
+add_action( 'after_setup_theme', 'mytheme_setup_theme_supported_features' );
+```
+
+## 可选功能
+
+## 默认区块样式
+
+核心区块包含默认的结构样式。这些样式默认会在编辑器和前端同时加载。例如控制分栏区块的CSS规则，若缺少这些规则，该区块将呈现破碎布局且无法显示分栏效果。
+
+### 预设区块样式
+
+区块编辑器允许主题为前端启用更具设计主张的样式。例如引用区块左侧的默认彩色条。若要在经典主题中使用这些预设样式，请添加对 `wp-block-styles` 的主题支持：
+
+```php
+add_theme_support( 'wp-block-styles' );
+```
+
+您可以在[区块库主题文件](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/theme.scss)中查看将被引入的CSS代码。
+
+对于区块主题或提供 `theme.json` 文件的主题，不建议使用此主题支持功能。为确保全局样式规则与区块样式之间不存在样式冲突，请将所需的区块样式添加到主题的 `theme.json` 文件中。
+
+### 宽对齐功能：
+
+某些区块（如图像区块）可通过向区块包装器添加对应类名（`alignwide` 或 `alignfull`）来定义“宽”或“全宽”对齐方式。主题可通过以下调用启用此功能：
+
+```php
+add_theme_support( 'align-wide' );
+```
+
+有关此功能的更多信息，请参阅[关于 `add_theme_support()` 的开发文档](https://developer.wordpress.org/reference/functions/add_theme_support/)。
+
+### 支持自定义单位
+
+除了像素单位外，用户还可使用其他单位定义尺寸、内边距等。可用单位包括：px、em、rem、vh、vw。主题可通过以下代码禁用此功能：
+
+```php
+add_theme_support( 'custom-units', array() );
+```
+
+主题还可对可用自定义单位进行筛选。
+
+```php
+add_theme_support( 'custom-units', 'rem', 'em' );
+```
+
+### 禁用默认区块模式
+
+WordPress 内置了多种区块模式，主题可通过以下代码选择不启用捆绑模式，转而提供自有模式集：
+
+```php
+remove_theme_support( 'core-block-patterns' );
+```
+
+## 编辑器样式
+
+区块编辑器支持主题的[编辑器样式](https://codex.wordpress.org/Editor_Style)，但其运作方式与经典编辑器略有不同。
+
+在经典编辑器中，编辑器样式表会直接加载到所见即所得编辑器的iframe内，不做任何更改。而区块编辑器并不使用iframe。为确保样式仅应用于编辑器内容，系统会通过选择性重写或调整特定CSS选择器来自动转换编辑器样式。这也使得区块编辑器可以在区块变体预览中利用您的编辑器样式。
+
+例如，如果您在编辑器样式中编写`body { ... }`，这将被重写为`.editor-styles-wrapper { ... }`。这也意味着您不应直接针对任何编辑器类名进行样式设定。
+
+由于其运作方式不同，您需要在`add_editor_style`函数之外，额外在主题中添加以下代码片段来启用此功能：
+
+```php
+add_theme_support( 'editor-styles' );
+```
+
+您无需过多调整编辑器样式；大多数主题只需添加上述代码片段，即可在经典编辑器和区块编辑器中获得相似效果。
+
+### 载入编辑器样式
+
+使用`add_editor_style`函数在编辑器界面载入CSS样式。对于经典编辑器，这是为编辑器添加样式的唯一必要函数。对于新版区块编辑器，您需要先添加前述的`add_theme_support( 'editor-styles');`。
+
+```php
+add_editor_style( 'style-editor.css' );
+```
+
+将此代码添加到`functions.php`文件后，会将`style-editor.css`样式表加入编辑器待加载样式表队列。
+
+### 基础色彩
+
+您可以像设置普通网页那样设置编辑器样式。以下是将背景色和字体颜色改为蓝色的方法：
+
+```css
+/* 将此代码添加至`style-editor.css`文件 */
+body {
+ background-color: #d3ebf3;
+ color: #00005d;
+}
+```
+
+### 调整编辑器宽度
+
+要更改编辑器的主列宽，请将以下CSS添加至`style-editor.css`：
+
+```css
+/* 主列宽度 */
+.wp-block {
+ max-width: 720px;
+}
+
+/* "宽版"区块宽度 */
+.wp-block[data-align='wide'] {
+ max-width: 1080px;
+}
+
+/* "全宽"区块宽度 */
+.wp-block[data-align='full'] {
+ max-width: none;
+}
+```
+
+您可以使用这些编辑器宽度值来匹配主题设置。可使用任何CSS宽度单位，包括`%`或`px`。
+
+扩展阅读：[使用样式表应用样式](/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md)。
+
+## 响应式嵌入内容
+
+嵌入区块会自动为嵌入内容应用样式，以反映在iFrame中嵌入内容的长宽比。应用长宽比响应式样式的区块显示效果如下：
+
+```html
+...
+```
+
+为使内容在保持长宽比的同时自适应尺寸，``元素需要具有`wp-embed-responsive`类。该样式类默认未设置，需要主题通过声明支持`responsive-embeds`功能来启用：
+
+```php
+add_theme_support( 'responsive-embeds' );
+```
+
+## 间距控制
+
+部分区块可配备内边距控制功能。此功能默认关闭，需要主题通过声明支持来启用：
+
+```php
+add_theme_support( 'custom-spacing' );
+```
+
+### 区块字体大小
+
+区块可能允许用户配置所使用的字体大小，例如段落区块。区块提供一组默认字体大小，但主题可以覆盖并提供自己的设置：
+
+```php
+add_theme_support( 'editor-font-sizes', array(
+ array(
+ 'name' => esc_attr__( '小号', 'themeLangDomain' ),
+ 'size' => 12,
+ 'slug' => 'small'
+ ),
+ array(
+ 'name' => esc_attr__( '常规', 'themeLangDomain' ),
+ 'size' => 16,
+ 'slug' => 'regular'
+ ),
+ array(
+ 'name' => esc_attr__( '大号', 'themeLangDomain' ),
+ 'size' => 36,
+ 'slug' => 'large'
+ ),
+ array(
+ 'name' => esc_attr__( '超大号', 'themeLangDomain' ),
+ 'size' => 50,
+ 'slug' => 'huge'
+ )
+) );
+```
+
+字体大小将按照主题提供的顺序显示在字体大小选择器中。
+
+主题负责创建应用正确字体大小样式的类。类名通过添加 'has-'，后接使用短横线命名法的字体大小名称，并以 `-font-size` 结尾来构建。
+
+以常规字体大小为例，主题可提供以下类：
+
+```css
+.has-regular-font-size {
+ font-size: 16px;
+}
+```
+
+`。更多信息请参阅[此开发说明](https://make.wordpress.org/core/2022/01/08/updates-for-settings-styles-and-theme-json/)。例如：
+
+```css
+:root {
+ --wp--preset--font-size--small: <新值>;
+ --wp--preset--font-size--large: <新值>;
+}
+```
+
+### 禁用自定义字体大小
+
+主题可通过以下代码禁用设置自定义字体大小的功能：
+
+```php
+add_theme_support( 'disable-custom-font-sizes' );
+```
+
+设置后，用户将被限制使用区块编辑器提供的默认大小或通过 `editor-font-sizes` 主题支持设置提供的大小。
+
+### 禁用区块调色板中的自定义颜色
+
+默认情况下，提供给区块的调色板允许用户选择与编辑器或主题默认颜色不同的自定义颜色。
+
+主题可通过以下方式禁用此功能：
+
+```php
+add_theme_support( 'disable-custom-colors' );
+```
+
+此标志将确保用户只能从主题提供的 `editor-color-palette` 中选择颜色，或者如果主题未提供，则从编辑器的默认颜色中选择。
+
+### 禁用自定义渐变
+
+主题可通过以下代码禁用设置自定义渐变的功能：
+
+```php
+add_theme_support( 'disable-custom-gradients' );
+```
+
+设置后，用户将被限制使用区块编辑器提供的默认渐变或通过 `editor-gradient-presets` 主题支持设置提供的渐变。
+
+### 禁用基础布局样式
+
+_**注意：**自 WordPress 6.1 起。_
+
+主题可以选择退出生成的区块布局样式，这些样式为核心区块（包括群组、列、按钮和社交图标）提供默认结构样式。通过使用以下代码，这些主题承诺提供自己的结构样式，因为使用此功能将导致核心区块在编辑器和站点前端显示不正确：
+
+```php
+add_theme_support( 'disable-layout-styles' );
+```
+
+对于希望自定义 `blockGap` 样式或区块间距的主题，请参阅[关于全局设置和样式的开发者文档](/docs/how-to-guides/themes/global-settings-and-styles.md#what-is-blockgap-and-how-can-i-use-it)。
+
+### 支持自定义行高
+
+某些区块（如段落和标题）支持自定义行高。主题可通过以下代码启用对此功能的支持：
+
+```php
+add_theme_support( 'custom-line-height' );
+```
+
+### 宽对齐与浮动元素
+
+要创建一个能够同时适应宽幅图像、侧边栏、居中列以及限定在居中列内的浮动元素的响应式布局，可能会遇到一些困难。
+
+区块编辑器为浮动图像添加了额外的标记，以便更轻松地设置样式。
+
+以下是一个带标题的 `Image` 标记示例：
+
+```html
+
+ 
+ 简短图片标题。
+
+```
+
+以下是一个左浮动图像的标记示例：
+
+```html
+`。更多信息请参阅 [此开发说明](https://make.wordpress.org/core/2022/01/08/updates-for-settings-styles-and-theme-json/)。例如：
+
+```css
+:root {
+ --wp--preset--color--cyan-bluish-gray: <新值>;
+ --wp--preset--color--pale-pink: <新值>;
+}
+```
+
+### 区块渐变预设
+
+不同区块可以从预定义的渐变列表中选择。区块编辑器提供了默认的渐变预设，但主题可以覆盖它们并提供自己的预设：
+
+```php
+add_theme_support(
+ 'editor-gradient-presets',
+ array(
+ array(
+ 'name' => esc_attr__( '鲜艳的蓝绿色到鲜艳的紫色', 'themeLangDomain' ),
+ 'gradient' => 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)',
+ 'slug' => 'vivid-cyan-blue-to-vivid-purple'
+ ),
+ array(
+ 'name' => esc_attr__( '鲜艳的绿青色到鲜艳的蓝绿色', 'themeLangDomain' ),
+ 'gradient' => 'linear-gradient(135deg,rgba(0,208,132,1) 0%,rgba(6,147,227,1) 100%)',
+ 'slug' => 'vivid-green-cyan-to-vivid-cyan-blue',
+ ),
+ array(
+ 'name' => esc_attr__( '浅绿青色到鲜艳的绿青色', 'themeLangDomain' ),
+ 'gradient' => 'linear-gradient(135deg,rgb(122,220,180) 0%,rgb(0,208,130) 100%)',
+ 'slug' => 'light-green-cyan-to-vivid-green-cyan',
+ ),
+ array(
+ 'name' => esc_attr__( '明亮鲜艳的琥珀色到明亮鲜艳的橙色', 'themeLangDomain' ),
+ 'gradient' => 'linear-gradient(135deg,rgba(252,185,0,1) 0%,rgba(255,105,0,1) 100%)',
+ 'slug' => 'luminous-vivid-amber-to-luminous-vivid-orange',
+ ),
+ array(
+ 'name' => esc_attr__( '明亮鲜艳的橙色到鲜艳的红色', 'themeLangDomain' ),
+ 'gradient' => 'linear-gradient(135deg,rgba(255,105,0,1) 0%,rgb(207,46,46) 100%)',
+ 'slug' => 'luminous-vivid-orange-to-vivid-red',
+ ),
+ )
+);
+```
+
+`name` 是一个易于理解的标签（如上所示），它会显示在工具提示中，并为用户提供渐变的有意义的描述。这对于依赖屏幕阅读器或难以感知颜色的用户尤其重要。`gradient` 是应用于区块背景图像的渐变的 CSS 值。有效渐变类型的详细信息可以在 [mozilla 文档](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Images/Using_CSS_gradients) 中找到。`slug` 是渐变的唯一标识符，用于生成区块编辑器使用的 CSS 类。
+
+主题负责创建应用渐变的类。因此，要正确应用“鲜艳的蓝绿色到鲜艳的紫色”，主题应实现以下类：
+
+```css
+.has-vivid-cyan-blue-to-vivid-purple-gradient-background {
+ background: linear-gradient(
+ 135deg,
+ rgba( 6, 147, 227, 1 ) 0%,
+ rgb( 155, 81, 224 ) 100%
+ );
+}
+```
+
+从 WordPress 5.9 开始，要覆盖核心定义的渐变值，没有 `theme.json` 的主题必须通过 CSS 自定义属性设置其值，而不是提供类。CSS 自定义属性使用以下命名方式：`--wp--preset--gradient--`。更多信息请参阅 [此开发说明](https://make.wordpress.org/core/2022/01/08/updates-for-settings-styles-and-theme-json/)。例如：
+
+```css
+:root {
+ --wp--preset--gradient--vivid-cyan-blue-to-vivid-purple: <新值>;
+ --wp--preset--gradient--light-green-cyan-to-vivid-green-cyan: <新值>;
+}
+```
\ No newline at end of file
diff --git a/how-to-guides/thunks.md b/how-to-guides/thunks.md
new file mode 100644
index 0000000..be8a16c
--- /dev/null
+++ b/how-to-guides/thunks.md
@@ -0,0 +1,225 @@
+## Thunks API
+
+thunk 函数接收一个包含以下键的单一对象参数：
+
+### select
+
+一个包含与状态预绑定的存储选择器的对象，这意味着您无需提供状态，只需提供额外参数。`select` 会触发相关的解析器（如果存在），但不会等待其完成。即使当前值为空，它也会直接返回当前值。
+
+如果某个选择器是公共 API 的一部分，它将以方法形式存在于 select 对象上：
+
+```js
+const thunk = () => ( { select } ) => {
+ // select 是该存储选择器的对象，已预绑定到当前状态：
+ const temperature = select.getTemperature();
+}
+```
+
+由于并非所有选择器都在存储中公开，`select` 同时支持以函数形式传递选择器作为参数：
+
+```js
+const thunk = () => ( { select } ) => {
+ // select 支持私有选择器：
+ const doubleTemperature = select( ( temperature ) => temperature * 2 );
+}
+```
+
+### resolveSelect
+
+`resolveSelect` 与 `select` 相同，但它返回一个 Promise，该 Promise 会通过相关解析器提供的值进行解析。
+
+```js
+const thunk = () => ( { resolveSelect } ) => {
+ const temperature = await resolveSelect.getTemperature();
+}
+```
+
+### dispatch
+
+一个包含存储操作的对象
+
+如果某个操作是公共 API 的一部分，它将以方法形式存在于 `dispatch` 对象上：
+
+```js
+const thunk = () => ( { dispatch } ) => {
+ // dispatch 是该存储操作的对象：
+ const temperature = await dispatch.retrieveTemperature();
+}
+```
+
+由于并非所有操作都在存储中公开，`dispatch` 同时支持以函数形式传递 Redux 操作作为参数：
+
+```js
+const thunk = () => async ( { dispatch } ) => {
+ // dispatch 也是一个接受内联操作的函数：
+ dispatch({ type: 'SET_TEMPERATURE', temperature: result.value });
+
+ // thunk 可与操作互换使用
+ dispatch( updateTemperature( 100 ) );
+
+ // thunk 也可以是异步的。当它们是异步时，dispatch 会返回一个 Promise
+ await dispatch( ( ) => window.fetch( /* ... */ ) );
+}
+```
+
+### registry
+
+注册表通过其 `dispatch`、`select` 和 `resolveSelect` 方法提供对其他存储的访问。
+这些方法与上述方法非常相似，但略有不同。调用 `registry.select( storeName )` 会返回一个函数，该函数返回来自 `storeName` 的选择器对象。当您需要与另一个存储交互时，这会非常方便。例如：
+
+```js
+const thunk = () => ( { registry } ) => {
+ const error = registry.select( 'core' ).getLastEntitySaveError( 'root', 'menu', menuId );
+ /* ... */
+}
+```
+
+# Core-Data 中的 Thunk 函数
+
+[Gutenberg 11.6](https://github.com/WordPress/gutenberg/pull/27276) 新增了对 _thunk_ 的支持。您可以将 thunk 理解为可被调度的函数：
+
+```js
+// actions.js
+export const myThunkAction = () => ( { select, dispatch } ) => {
+ return "我是一个 thunk！我可以被调度，使用选择器，甚至调度其他动作。";
+};
+```
+
+## Thunk 函数的优势何在？
+
+Thunk [拓展了 Redux 动作的定义边界](https://jsnajdr.wordpress.com/2021/10/04/motivation-for-thunks/)。在 thunk 出现之前，动作是纯函数化的，只能返回和生成数据。常见的应用场景（例如在动作中与存储库交互或请求 API 数据）需要使用独立的 [control](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data/#controls)。您经常会看到这样的代码：
+
+```js
+export function* saveRecordAction( id ) {
+ const record = yield controls.select( 'current-store', 'getRecord', id );
+ yield { type: 'BEFORE_SAVE', id, record };
+ const results = yield controls.fetch({ url: 'https://...', method: 'POST', data: record });
+ yield { type: 'AFTER_SAVE', id, results };
+ return results;
+}
+
+const controls = {
+ select: // ...,
+ fetch: // ...,
+};
+```
+
+像存储库操作和 fetch 函数这样的副作用需要在动作之外实现。Thunk 为这种方法提供了替代方案，允许您直接内联处理副作用：
+
+```js
+export const saveRecordAction = ( id ) => async ({ select, dispatch }) => {
+ const record = select( 'current-store', 'getRecord', id );
+ dispatch({ type: 'BEFORE_SAVE', id, record });
+ const response = await fetch({ url: 'https://...', method: 'POST', data: record });
+ const results = await response.json();
+ dispatch({ type: 'AFTER_SAVE', id, results });
+ return results;
+}
+```
+
+这样就无需再单独实现 controls。
+
+### Thunk 可访问存储库辅助工具
+
+让我们看一个 Gutenberg 核心代码中的例子。在 thunk 出现之前，`@wordpress/interface` 包中的 `toggleFeature` 动作是这样实现的：
+
+```js
+export function* toggleFeature( scope, featureName ) {
+ const currentValue = yield controls.select(
+ interfaceStoreName,
+ 'isFeatureActive',
+ scope,
+ featureName
+ );
+
+ yield controls.dispatch(
+ interfaceStoreName,
+ 'setFeatureValue',
+ scope,
+ featureName,
+ ! currentValue
+ );
+}
+```
+
+Controls 曾是唯一能调度动作和从存储库选择数据的方式。
+
+通过 thunk，现在有了更简洁的实现方式。这是 `toggleFeature` 当前的实现：
+
+```js
+export function toggleFeature( scope, featureName ) {
+ return function ( { select, dispatch } ) {
+ const currentValue = select.isFeatureActive( scope, featureName );
+ dispatch.setFeatureValue( scope, featureName, ! currentValue );
+ };
+}
+```
+
+借助 `select` 和 `dispatch` 参数，thunk 可以直接使用存储库，无需依赖生成器和 controls。
+
+### Thunk 支持异步操作
+
+假设有个简单的 React 应用，允许您设置恒温器温度。它只有一个输入框和一个按钮。点击按钮会调用携带输入值的 `saveTemperatureToAPI` 动作。
+
+若使用 controls 保存温度，存储库定义如下所示：
+
+```js
+const store = wp.data.createReduxStore( 'my-store', {
+ actions: {
+ saveTemperatureToAPI: function*( temperature ) {
+ const result = yield { type: 'FETCH_JSON', url: 'https://...', method: 'POST', data: { temperature } };
+ return result;
+ }
+ },
+ controls: {
+ async FETCH_JSON( action ) {
+ const response = await window.fetch( action.url, {
+ method: action.method,
+ body: JSON.stringify( action.data ),
+ } );
+ return response.json();
+ }
+ },
+ // reducers, selectors, ...
+} );
+```
+
+虽然代码逻辑清晰，但存在一层间接调用。`saveTemperatureToAPI` 动作并不直接与 API 通信，而是需要通过 `FETCH_JSON` control 中转。
+
+让我们看看如何用 thunk 消除这层间接调用：
+
+```js
+const store = wp.data.createReduxStore( 'my-store', {
+ actions: {
+ saveTemperatureToAPI: ( temperature ) => async () => {
+ const response = await window.fetch( 'https://...', {
+ method: 'POST',
+ body: JSON.stringify( { temperature } ),
+ } );
+ return await response.json();
+ }
+ },
+ // reducers, selectors, ...
+} );
+```
+
+这非常简洁！更棒的是，resolvers 也同样支持这种写法：
+
+```js
+const store = wp.data.createReduxStore( 'my-store', {
+ // ...
+ selectors: {
+ getTemperature: ( state ) => state.temperature
+ },
+ resolvers: {
+ getTemperature: () => async ( { dispatch } ) => {
+ const response = await window.fetch( 'https://...' );
+ const result = await response.json();
+ dispatch.receiveCurrentTemperature( result.temperature );
+ }
+ },
+ // ...
+} );
+```
+
+与（现已过时的）生成器和 controls 支持一样，所有数据存储库默认都包含对 thunk 的支持。
\ No newline at end of file
diff --git a/how-to-guides/widgets/README.md b/how-to-guides/widgets/README.md
new file mode 100644
index 0000000..27e4103
--- /dev/null
+++ b/how-to-guides/widgets/README.md
@@ -0,0 +1,9 @@
+# 小工具
+
+Gutenberg插件将WP管理后台中的小工具编辑器界面替换为基于WordPress区块编辑器的全新界面。
+
+**目录**
+
+- [小工具区块编辑器概述](/docs/how-to-guides/widgets/overview.md)
+- [恢复旧版小工具编辑器](/docs/how-to-guides/widgets/opting-out.md)
+- [确保与旧版小工具区块的兼容性](/docs/how-to-guides/widgets/legacy-widget-block.md)
\ No newline at end of file
diff --git a/how-to-guides/widgets/legacy-widget-block.md b/how-to-guides/widgets/legacy-widget-block.md
new file mode 100644
index 0000000..6aed223
--- /dev/null
+++ b/how-to-guides/widgets/legacy-widget-block.md
@@ -0,0 +1,188 @@
+# 关于传统小工具区块
+
+传统小工具区块允许用户添加、编辑和预览由插件注册的第三方小工具，以及使用经典小工具编辑器添加的小工具。
+
+可通过区块插入器添加传统小工具区块，并从该区块的下拉菜单中选择小工具来添加第三方小工具。
+
+也可通过在区块插入器中搜索小工具名称并选择该小工具来添加第三方小工具。系统将插入一个传统小工具区块的变体。
+
+## 与传统小工具区块的兼容性
+
+### `widget-added` 事件
+
+传统小工具区块将以类似于定制器的方式显示小工具的表单，因此与大多数第三方小工具兼容。
+
+如果小工具在其表单中使用 JavaScript，则必须在 `document` 上触发 `'widget-added'` jQuery 事件后，将事件添加到 DOM 中。
+
+例如，当“更改密码”复选框被勾选时，小工具可能希望显示一个“密码”字段。
+
+```js
+( function ( $ ) {
+ $( document ).on( 'widget-added', function ( $event, $control ) {
+ $control.find( '.change-password' ).on( 'change', function () {
+ var isChecked = $( this ).prop( 'checked' );
+ $control.find( '.password' ).toggleClass( 'hidden', ! isChecked );
+ } );
+ } );
+} )( jQuery );
+```
+
+请注意，所有小工具的事件处理程序都在 `widget-added` 回调中添加。
+
+### 显示“无预览可用”
+
+当未选择传统小工具区块时，该区块将显示小工具的预览。
+
+当小工具的 `widget()` 函数未呈现任何内容或仅呈现空的 HTML 元素时，传统小工具区块会自动显示“无预览可用”的消息。
+
+小工具可以通过在不应显示预览时从 `widget()` 提前返回来利用这一点。
+
+```php
+class ExampleWidget extends WP_Widget {
+ ...
+ public function widget( $instance ) {
+ if ( ! isset( $instance['name'] ) ) {
+ // 名称为必填项，如果没有则什么都不显示。
+ return;
+ }
+ ?>
+ 
+ )
+}
+```
+
+保存的HTML将在注释分隔符中包含`title`和`size`，在`img`节点中包含`url`。
+
+```html
+
+
+
+```
+
+若属性随时间变化，可通过[区块弃用](/docs/reference-guides/block-api/block-deprecation.md)来迁移旧属性或完全移除。
+
+## 类型验证
+
+`type`指明属性存储的数据类型。它不表示数据存储位置（由`source`字段定义）。
+
+除非提供`enum`，否则`type`是必需的。`type`可与`enum`同时使用。
+
+`type`字段必须是以下之一：
+
+- `null`
+- `boolean`
+- `object`
+- `array`
+- `string`
+- `integer`
+- `number`（与`integer`相同）
+
+注意：`object`的有效性由您的`source`决定。示例可参阅下文的`query`详情。
+
+## 枚举验证
+
+属性可定义为固定值集合中的一个值。通过包含允许值数组的`enum`来指定：
+
+*示例*：`enum`示例。
+
+```js
+{
+ size: {
+ enum: [ 'large', 'small', 'tiny' ]
+ }
+}
+```
+
+## 值来源
+
+属性来源用于定义如何从已保存的文章内容中提取属性值。它们提供了一种从已保存标记到区块JavaScript表示的映射机制。
+
+可用的`source`值包括：
+- `（无值）`- 未指定`source`时，数据存储在区块的[注释分隔符](/docs/explanations/architecture/key-concepts.md#data-attributes)中
+- `attribute`- 数据存储在HTML元素属性中
+- `text`- 数据存储在HTML文本中
+- `html`- 数据以HTML形式存储（通常由`RichText`使用）
+- `query`- 数据以对象数组形式存储
+- `meta`- 数据存储在文章元数据中（已弃用）
+
+`source`字段通常与`selector`字段结合使用。若未指定选择器参数，源定义将针对区块根节点运行。若指定选择器参数，则将针对区块内的匹配元素运行。
+
+`selector`可以是HTML标签，或任何可通过[querySelector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector)查询的内容，例如类或id属性。下方提供了示例。
+
+例如，`img`选择器将匹配`img`元素，而`img.class`将匹配具有`class`类的`img`元素。
+
+在底层实现中，属性来源是[hpq](https://github.com/aduth/hpq)库功能的超集，该小型库用于将HTML标记解析和查询为对象形态。
+
+总结而言，`source`决定数据在内容中的存储位置，而`type`决定数据的类型。为减少存储数据量，通常建议尽可能将数据存储在HTML中而非注释分隔符内的属性中。
+
+### 元数据源（已弃用）
+
+
+
+
+ figcaption 元素的内部文本
+
+```
+
+属性定义：
+```js
+{
+ content: {
+ type: 'string',
+ source: 'text',
+ selector: 'figcaption',
+ }
+}
+```
+
+区块中可用的属性：
+```js
+{ "content": "figcaption 元素的内部文本" }
+```
+
+另一个使用 `text` 数据源，通过 `.my-content` 类选择器提取文本的示例：
+
+_示例_：从区块标记中具有 `.my-content` 类的元素提取 `content` 属性。
+
+保存内容：
+```html
+
+
+
+ figcaption 元素的内部文本
+
+```
+
+属性定义：
+```js
+{
+ content: {
+ type: 'string',
+ source: 'html',
+ selector: 'figcaption',
+ }
+}
+```
+
+区块中可用的属性：
+```js
+{ "content": "figcaption 元素的内部文本" }
+```
+
+### `query` 数据源
+
+使用 `query` 可从标记中提取值数组。数组条目由 `selector` 参数决定，区块内每个匹配元素都会对应一个条目，其结构由第二个参数（属性源对象）定义。
+
+`query` 字段实际上是嵌套的区块属性定义。虽然可以进一步嵌套（但不一定推荐这样做）。
+
+_示例_：从区块标记中的每个图片元素提取 `src` 和 `alt` 属性。
+
+保存内容：
+```html
+
+ 无需创建不必要的 JS 全局变量，即可从 PHP 渲染编辑器。请查看 Gutenberg 插件中的 编辑站点 包以获取示例。
+
+
+## 审查 `
+
+
+
+ /* <-- 侧边栏 */
+
+
+
+);
+```
+
+这部分用于通过 `
+
\ No newline at end of file
diff --git a/how-to-guides/plugin-sidebar-0.md b/how-to-guides/plugin-sidebar-0.md
new file mode 100644
index 0000000..abc4c53
--- /dev/null
+++ b/how-to-guides/plugin-sidebar-0.md
@@ -0,0 +1,409 @@
+### 步骤三：注册元字段
+
+若要在 `post_meta` 表中操作字段，请使用 [register_post_meta](https://developer.wordpress.org/reference/functions/register_post_meta/) 函数创建名为 `sidebar_plugin_meta_block_field` 的新字段。
+
+注意：此字段需对 REST API 可用，因为区块编辑器通过该接口访问数据。
+
+将以下 PHP 代码添加到插件的 `init` 回调函数中：
+
+```php
+register_post_meta( 'post', 'sidebar_plugin_meta_block_field', array(
+ 'show_in_rest' => true,
+ 'single' => true,
+ 'type' => 'string',
+) );
+```
+
+可通过查询区块编辑器存储空间来验证字段是否加载成功。实现后，重新加载编辑器页面并打开浏览器开发者控制台，在控制台中执行以下 JavaScript 代码片段进行确认：
+
+```js
+wp.data.select( 'core/editor' ).getCurrentPost().meta;
+```
+
+该函数将返回包含已注册元字段的对象。
+
+若代码返回 `undefined`，请确保文章类型支持 `custom-fields`。可通过[注册文章类型](https://developer.wordpress.org/reference/functions/register_post_type/#supports)时设置，或使用 [add_post_type_support 函数](https://developer.wordpress.org/reference/functions/add_post_type_support/)实现。
+
+### 步骤四：初始化输入控件
+
+当字段在编辑器存储中就绪后，即可将其呈现在用户界面中。我们将输入控件提取为独立函数以保持代码整洁，便于后续功能扩展。
+
+```js
+( function ( wp ) {
+ var el = React.createElement;
+ var registerPlugin = wp.plugins.registerPlugin;
+ var PluginSidebar = wp.editor.PluginSidebar;
+ var TextControl = wp.components.TextControl;
+
+ var MetaBlockField = function () {
+ return el( TextControl, {
+ label: '元区块字段',
+ value: '初始值',
+ onChange: function ( content ) {
+ console.log( '内容已更改为 ', content );
+ },
+ } );
+ };
+
+ registerPlugin( 'my-plugin-sidebar', {
+ render: function () {
+ return el(
+ PluginSidebar,
+ {
+ name: 'my-plugin-sidebar',
+ icon: 'admin-post',
+ title: '我的插件侧边栏',
+ },
+ el(
+ 'div',
+ { className: 'plugin-sidebar-content' },
+ el( MetaBlockField )
+ )
+ );
+ },
+ } );
+} )( window.wp );
+```
+
+我们需要将 `MetaBlockField` 组件的初始值设为 `sidebar_plugin_meta_block_field` 的值，并在该值变化时保持同步更新。
+
+`useSelect` 函数用于在组件加载时获取数据，并在数据变更时自动更新。以下是使用 `useSelect` 的代码更新版本：
+
+```js
+( function ( wp ) {
+ var el = React.createElement;
+ var registerPlugin = wp.plugins.registerPlugin;
+ var PluginSidebar = wp.editor.PluginSidebar;
+ var Text = wp.components.TextControl;
+ var useSelect = wp.data.useSelect;
+
+ var MetaBlockField = function () {
+ var metaFieldValue = useSelect( function ( select ) {
+ return select( 'core/editor' ).getEditedPostAttribute(
+ 'meta'
+ )[ 'sidebar_plugin_meta_block_field' ];
+ }, [] );
+
+ return el( Text, {
+ label: '元区块字段',
+ value: metaFieldValue,
+ onChange: function ( content ) {
+ console.log( '内容已更改为 ', content );
+ },
+ } );
+ };
+
+ registerPlugin( 'my-plugin-sidebar', {
+ render: function () {
+ return el(
+ PluginSidebar,
+ {
+ name: 'my-plugin-sidebar',
+ icon: 'admin-post',
+ title: '我的插件侧边栏',
+ },
+ el(
+ 'div',
+ { className: 'plugin-sidebar-content' },
+ el( MetaBlockField )
+ )
+ );
+ },
+ } );
+} )( window.wp );
+```
+
+`wp.data.useSelect` 函数来自 `@wordpress/data` 包，因此需要在 PHP 的 `wp_register_script` 函数中将 `wp-data` 添加为依赖项。
+
+注意：`getEditedPostAttribute` 调用用于获取文章的最新值，包括用户尚未保存的编辑内容。
+
+更新代码后重新加载并打开侧边栏即可验证功能。此时输入框内容不再是「初始值」而显示为空字符串。虽然用户暂时还无法输入值，但可以验证当存储中的值发生变化时组件是否会更新。打开浏览器控制台执行：
+
+```js
+wp.data
+ .dispatch( 'core/editor' )
+ .editPost( { meta: { sidebar_plugin_meta_block_field: 'hello world!' } } );
+```
+
+即可观察到输入组件中的内容实时更新。
+
+### 步骤5：在输入内容变化时更新元字段
+
+最后一步是在输入内容发生变化时更新元字段。
+`useDispatch` 函数接收一个存储名称作为唯一参数，并返回可用于更新存储的方法，这里我们将使用 `editPost`。
+
+```js
+( function ( wp ) {
+ var el = React.createElement;
+ var registerPlugin = wp.plugins.registerPlugin;
+ var PluginSidebar = wp.editor.PluginSidebar;
+ var TextControl = wp.components.TextControl;
+ var useSelect = wp.data.useSelect;
+ var useDispatch = wp.data.useDispatch;
+
+ var MetaBlockField = function ( props ) {
+ var metaFieldValue = useSelect( function ( select ) {
+ return select( 'core/editor' ).getEditedPostAttribute(
+ 'meta'
+ )[ 'sidebar_plugin_meta_block_field' ];
+ }, [] );
+
+ var editPost = useDispatch( 'core/editor' ).editPost;
+
+ return el( TextControl, {
+ label: '元区块字段',
+ value: metaFieldValue,
+ onChange: function ( content ) {
+ editPost( {
+ meta: { sidebar_plugin_meta_block_field: content },
+ } );
+ },
+ } );
+ };
+
+ registerPlugin( 'my-plugin-sidebar', {
+ render: function () {
+ return el(
+ PluginSidebar,
+ {
+ name: 'my-plugin-sidebar',
+ icon: 'admin-post',
+ title: '我的插件侧边栏',
+ },
+ el(
+ 'div',
+ { className: 'plugin-sidebar-content' },
+ el( MetaBlockField )
+ )
+ );
+ },
+ } );
+} )( window.wp );
+```
+
+更新后，当用户输入时，输入控件会调用 `editPost` 并在每次按键时更新编辑器存储。
+
+更新 JavaScript 代码，加载侧边栏并在输入框中输入内容。您可以通过在输入控件中输入内容并在浏览器的开发控制台中执行以下 JavaScript 代码片段来确认内容已保存：
+
+```js
+wp.data.select( 'core/editor' ).getEditedPostAttribute( 'meta' )[
+ 'sidebar_plugin_meta_block_field'
+];
+```
+
+显示的消息应该是您在输入框中输入的内容。
+
+在保存文章时，您可以通过保存后重新加载页面并确认输入控件已初始化为您最后输入的值，来验证内容是否正确存储到数据库中。
+
+## 附加资源
+
+有关使用 [@wordpress/data 包](/packages/data/README.md) 的文档。
+
+本指南中使用的函数：
+
+- [useSelect](/packages/data/README.md#useselect)
+- [getEditedPostAttribute](/docs/reference-guides/data/data-core-editor.md#geteditedpostattribute)
+- [useDispatch](/packages/data/README.md#usedispatch)
+
+## 总结
+
+您现在拥有一个自定义侧边栏，可用于更新 `post_meta` 内容。
+
+完整示例可在 [block-development-examples](https://github.com/WordPress/block-development-examples) 代码库中下载 [plugin-sidebar 示例](https://github.com/WordPress/block-development-examples/tree/trunk/plugins/plugin-sidebar-9ee4a6)。
+
+### 注意
+
+如果您在编辑器“偏好设置”的“面板”页面中启用了“自定义字段”（通过右上角的三个点），与 TextControl 同名的字段（在本例中为 `sidebar_plugin_meta_block_field`）也会出现在编辑器窗口底部的自定义字段面板中。这两个字段可以访问相同的元属性。
+
+
+
+在保存文章时，TextControl 中的值会先保存，而自定义字段中的值会后保存，因此最终保存到数据库的是自定义字段中的值。因此，如果您更改了 TextControl 中的值，最终保存的仍然是自定义字段中的值。
+
+如果未启用自定义字段，则不会出现此问题。
+
+如果您需要启用自定义字段并在侧边栏中显示文章元数据，有两种可能的解决方案：
+
+1. 在元字段名称前添加下划线，例如上述示例中的名称改为 `_sidebar_plugin_meta_block_field`。这表示该文章元数据应视为私有，不会在文章的自定义字段部分显示。使用此解决方案时，除非您在传递给 `register_post_meta` 的 `args` 数组中添加一个 `auth_callback` 属性，并提供一个最终返回 `true` 的函数，否则在保存文章时会生成错误。有关更多信息，请参阅 [post_meta](https://developer.wordpress.org/reference/functions/register_meta/#parameters) 页面中的 `args` 文档。
+2. 在 TextControl 的 `onChange` 函数中，将目标指向值字段的文本区域，并将其值设置为与 TextControl 元字段中的值相同。这样，两个位置的值将保持一致，因此您可以确保即使更改了 TextControl 中的值，它仍然会被保存到数据库中。
+
+```js
+return el( TextControl, {
+ label: '元区块字段',
+ value: metaFieldValue,
+ onChange: function ( content ) {
+ editPost( {
+ meta: { sidebar_plugin_meta_block_field: content }
+ })
+ document.querySelector( {值字段文本区域} ).innerHTML = content;
+ },
+} );
+```
+
+# 插件侧边栏
+
+## 概述
+
+如何为插件添加侧边栏。侧边栏位于编辑器最右侧区域。您的插件可以在检查器控件（齿轮图标）旁添加额外图标，该图标可展开显示。
+
+
+
+*注意：本教程主要讲解自定义侧边栏，如需在侧边栏添加控件请参阅[区块工具栏与设置侧边栏](/docs/getting-started/fundamentals/block-in-the-editor.md)*
+
+## 准备工作
+
+本教程假设您已具备插件基础环境，并准备添加PHP和JavaScript代码。请先参阅[JavaScript入门指南](/docs/getting-started/fundamentals/javascript-in-the-block-editor.md)了解WordPress插件基础知识及如何使用JavaScript扩展区块编辑器。
+
+## 分步指南
+
+### 步骤1：启动侧边栏
+
+首先需要告知编辑器存在包含独立侧边栏的新插件。请分别使用`@wordpress/plugins`、`@wordpress/editor`和`react`包提供的[registerPlugin](/packages/plugins/README.md)、[PluginSidebar](/packages/editor/README.md#pluginsidebar)和[createElement](/packages/element/README.md)工具。
+
+将以下代码添加至名为`plugin-sidebar.js`的JavaScript文件，并保存到插件目录：
+
+```js
+( function ( wp, React ) {
+ var el = React.createElement;
+ var registerPlugin = wp.plugins.registerPlugin;
+ var PluginSidebar = wp.editor.PluginSidebar;
+
+ registerPlugin( 'my-plugin-sidebar', {
+ render: function () {
+ return el(
+ PluginSidebar,
+ {
+ name: 'my-plugin-sidebar',
+ icon: 'admin-post',
+ title: '我的插件侧边栏',
+ },
+ '元字段'
+ );
+ },
+ } );
+} )( window.wp, window.React );
+```
+
+为使代码正常运行，需确保这些工具在浏览器中可用，因此必须将`wp-plugins`、`wp-editor`和`react`指定为脚本依赖项。
+
+以下是注册脚本并声明依赖项的PHP代码：
+
+```php
+
+<BlockInspector>
+本身实际上渲染了一个用于 <InspectorControls> 的 Slot。这使你可以在区块的 edit() 定义中渲染一个 <InspectorControls>> 组件，并在编辑器的侧边栏中显示它。建议进一步探索该组件的更多细节。
+
+
+
+
+```
+
+这种方法并非万无一失，用户仍可通过编辑器界面修改类名。但由于该设置位于“高级”面板下，大多数情况下会保持原样。这为主题开发者提供了一定程度的CSS控制权，使其能更新现有使用实例，但无法阻止用户进行无法更新的重大修改。
+
+### 同步模式
+
+顾名思义，这类模式天然支持全站同步。需注意，依赖同步模式处理特定更新目前存在局限——更新时内容、HTML结构和样式将保持同步。若需要更精细的控制，这是需要考量的关键因素，此时动态区块可能是更优选择。
+
+### 模板部件与模板
+
+由于区块主题允许用户直接编辑模板和模板部件，管理变更的方式需根据用户更高权限进行调整。具体来说，当用户修改模板或模板部件后，主题更新提供的新模板将不会对已修改用户显示。只有新主题用户或未编辑过模板的用户会体验到更新后的模板。若用户未修改文件，您在文件系统中的变更将直接体现在用户站点上——只需更新文件即可生效。但若用户已修改模板，则更新其模板的唯一方式是：
+
+- 回滚所有用户修改
+- 更新数据库中的模板和模板部件
+
+一般而言，若用户已修改模板，建议维持现状（除非在代理场景中与用户达成共识）。
+
+更新模板时需注意对新增或不同模板部件的引用。例如 page.html 模板在1.0版本中引用 parts/header.html，而在2.0版本中改为引用 parts/header-alt.html。某些开发者可能将此视为用户修改原 header.html 时的“解决方案”，但这很可能破坏用户的定制设计，因为 page.html 模板将不再引用正确部件（除非用户也修改并保存了页面模板）。
+
+同样地，在主题更新中删除模板部件通常不可取。这种情况下，用户可能创建了引用该部件的自定义顶层模板，并预期其持续存在。
+
+## 相关资源
+
+- [模式、模板部件与可重用区块对比](https://wordpress.org/documentation/article/comparing-patterns-template-parts-and-reusable-blocks/)
+- [区块弃用机制](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/)
+- [Create Block 工具](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/)
\ No newline at end of file
diff --git a/how-to-guides/themes/README.md b/how-to-guides/themes/README.md
new file mode 100644
index 0000000..aaf61d7
--- /dev/null
+++ b/how-to-guides/themes/README.md
@@ -0,0 +1,22 @@
+# 主题
+
+区块编辑器为主题设计师和开发者提供了多种交互选项，包括主题定义的颜色设置、字体大小控制等功能。
+
+## 主题类型
+
+### 经典主题
+
+在区块编辑器的术语体系中，指那些采用传统`.php`文件格式定义模板，且在`/block-templates`或`/templates`文件夹中不包含`index.html`格式模板的主题。经典主题可通过[主题支持功能](/docs/how-to-guides/themes/theme-support.md)或引入[theme.json](/docs/how-to-guides/themes/global-settings-and-styles.md)文件，为区块编辑器及区块内容提供配置与样式选项。即使不是区块主题，也能通过使用`theme.json`文件获得灵活配置能力。
+
+### 区块主题
+
+指至少在`/block-templates`或`/templates`文件夹中包含`index.html`格式模板，并以区块内容标记形式提供模板的主题。虽然多数区块主题会使用`theme.json`文件进行配置和样式设置，但该文件并非区块主题的必备要素。区块主题的优势在于可以通过区块编辑器编辑网站所有区域：页眉、页脚、侧边栏等。
+
+### 全站编辑（FSE）
+
+并不存在特定的FSE主题类型。在WordPress 5.9及以上版本中，所有区块主题（即在`/block-templates`或`/templates`文件夹中包含`index.html`格式模板的主题）均支持全站编辑功能。
+
+**目录**
+
+- [全局设置（theme.json）](/docs/how-to-guides/themes/global-settings-and-styles.md)
+- [主题支持](/docs/how-to-guides/themes/theme-support.md)
\ No newline at end of file
diff --git a/how-to-guides/themes/global-settings-and-styles.md b/how-to-guides/themes/global-settings-and-styles.md
new file mode 100644
index 0000000..fc74782
--- /dev/null
+++ b/how-to-guides/themes/global-settings-and-styles.md
@@ -0,0 +1,1410 @@
+### 用户自定义链接颜色的特异性处理
+
+在WordPress 5.8版本中，当用户为特定区块选择链接颜色时，系统会为该区块附加一个`.wp-element-自 WordPress 5.9 版本起支持。
+
+在此字段中，主题可以列出 `templates` 文件夹中的自定义模板。例如，对于名为 `my-custom-template.html` 的自定义模板，`theme.json` 可以声明哪些文章类型可以使用它以及向用户显示的标题：
+
+- name：必需。
+- title：必需，可翻译。
+- postTypes：可选，默认仅适用于 `page`。
+
+```json
+{
+ "version": 3,
+ "customTemplates": [
+ {
+ "name": "my-custom-template",
+ "title": "模板标题",
+ "postTypes": [
+ "page",
+ "post",
+ "my-cpt"
+ ]
+ }
+ ]
+}
+```
+
+### 模板部件
+
+自 WordPress 5.9 版本起支持。
+
+在此字段中，主题可以列出 `parts` 文件夹中的模板部件。例如，对于名为 `my-template-part.html` 的模板部件，`theme.json` 可以声明模板部件实体的区域术语，该术语负责在编辑器中渲染相应的区块变体（如页眉区块、页脚区块等）。在 JSON 中定义此区域术语将使该设置在该模板部件实体的所有使用中保持一致，而区块属性仅影响单个区块。不建议将区域作为区块属性定义，因为这仅用于“幕后”辅助占位符流程与实体创建之间的衔接。
+
+目前，区域术语的“header”和“footer”值存在区块变体，任何其他值以及未在 JSON 中定义的模板部件将默认为通用模板部件区块。变体将在编辑器界面中通过特定图标表示，默认使用对应的语义化 HTML 元素作为包装器（这也可以通过模板部件区块上设置的 `tagName` 属性覆盖），并将模板部件上下文化，以便在未来的编辑器改进中实现更自定义的流程。
+
+- name：必需。
+- title：可选，可翻译。
+- area：可选，默认为 `uncategorized`，且不会触发区块变体。
+
+```json
+{
+ "version": 3,
+ "templateParts": [
+ {
+ "name": "my-template-part",
+ "title": "页眉",
+ "area": "header"
+ }
+ ]
+}
+```
+
+### 模式
+
+自 WordPress 6.0 版本起支持。
+
+在此字段中，主题可以列出要从[模式目录](https://wordpress.org/patterns/)注册的模式。`patterns` 字段是模式目录中的模式 `slugs` 数组。模式 slugs 可以从模式目录中单个模式视图的 `url` 中提取。例如，在 URL `https://wordpress.org/patterns/pattern/partner-logos` 中，slug 为 `partner-logos`。
+
+```json
+{
+ "version": 3,
+ "patterns": [ "short-text-surrounded-by-round-images", "partner-logos" ]
+}
+```
+
+## 使用 theme.json 进行开发
+
+在开发过程中，可能难以记住 theme.json 的设置和属性以及不同 WordPress 版本支持哪些设置，因此使用提供的 theme.json JSON 模式会很有帮助。
+
+许多代码编辑器支持 JSON 模式，并可以在编辑器中提供工具提示、自动完成或模式验证等帮助。
+
+每个 WordPress 版本的 theme.json 模式均可在 `https://schemas.wp.org/wp/{{version}}/theme.json` 获取。例如，WordPress 5.8 的模式可在 `https://schemas.wp.org/wp/5.8/theme.json` 获取。为确保仅使用对用户可用的功能，最好使用主题支持的最旧版本。
+
+包含 Gutenberg 插件所有最新更改的最新模式可在 `https://schemas.wp.org/trunk/theme.json` 获取。
+
+请查阅编辑器的文档以了解 JSON 模式支持。例如，在 Visual Studio Code 中，您需要在 theme.json 文件的顶级属性中添加 `"$schema": "https://schemas.wp.org/wp/x.x/theme.json"`，但其他编辑器的配置可能不同。
+
+
+
+## 常见问题解答
+
+### CSS自定义属性的命名规范
+
+您可能已经注意到系统创建的CSS自定义属性采用了特定的命名规范，包括使用双连字符`--`来分隔不同"概念"。请看以下示例：
+
+**预设属性**（如`--wp--preset--color--black`）可拆分为以下部分：
+- `--wp`：命名空间前缀
+- `preset`：标识属于预设值的CSS变量
+- `color`：指示变量所属的预设类别（可以是`color`、`font-size`、`gradients`）
+- `black`：特定预设值的标识符
+
+**自定义属性**（如`--wp--custom--line-height--body`）可拆分为：
+- `--wp`：命名空间前缀
+- `custom`：标识由主题创建的"自由形式"CSS变量
+- `line-height--body`：将"custom"对象键名转换后的字符串结果
+
+双连字符`--`作为分隔符具有双重作用：
+- 增强人类可读性：类似于BEM命名规范，用于区分不同"类别"
+- 提升机器可解析性：通过既定结构让机器理解属性含义，例如能识别`--wp--preset--color--black`是绑定到标识符为"black"的色彩预设值，为后续操作留出空间
+
+### 为何选用`--`作为分隔符？
+
+理论上可以使用其他分隔符（如单连字符`-`），但这会产生问题：除非强制主题作者不在变量名中使用`-`，否则无法将`--wp-custom-line-height-template-header`准确转换回对象形式。
+
+通过保留`--`作为类别分隔符，并允许主题作者使用`-`作为单词边界，命名将更加清晰：`--wp--custom--line-height--template-header`
+
+### "custom"配置如何生成CSS自定义属性
+
+从"custom"配置项生成CSS变量的算法原理如下（以示例说明）：
+
+{% codetabs %}
+{% 输入 %}
+
+```json
+{
+ "version": 3,
+ "settings": {
+ "custom": {
+ "lineHeight": {
+ "body": 1.7
+ },
+ "font-primary": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif"
+ }
+ }
+}
+```
+
+{% 输出 %}
+
+```css
+body {
+ --wp--custom--line-height--body: 1.7;
+ --wp--custom--font-primary: "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen-Sans, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif";
+}
+```
+{% end %}
+
+注意事项：
+- 驼峰式命名的键名会转换为短横线命名法（如`lineHeight`转为`line-height`），遵循CSS属性命名规范
+- 不同层级的键名通过`--`分隔（这就是`line-height`与`body`之间使用`--`的原因）
+- 禁止在`custom`对象的键名中使用`--`（错误示例如下）：
+
+```json
+{
+ "version": 3,
+ "settings": {
+ "custom": {
+ "line--height": { // 禁止此种写法
+ "body": 1.7
+ }
+ }
+ }
+}
+```
+
+### 全局样式表
+
+WordPress 5.8版本中，WordPress定义的预设样式（字体大小、颜色和渐变）在多数主题中会重复加载：既通过区块库样式表加载，又通过全局样式表加载，且两处CSS存在细微差异。
+
+WordPress 5.9版本将预设样式的CSS统一整合到全局样式表中，该样式表现已为所有主题加载。每个预设值会生成单个CSS自定义属性和对应类：
+
+```css
+/* 预设值的CSS自定义属性 */
+body {
+ --wp--preset--<预设类型>--<预设标识>: <默认值>;
+ --wp--preset--color--pale-pink: #f78da7;
+ --wp--preset--font-size--large: 36px;
+ /* 其他属性 */
+}
+
+/* 预设值的CSS类 */
+.has-<预设标识>-<预设类型> { ... }
+.has-pale-pink-color { color: var(--wp--preset--color--pale-pink) !important; }
+.has-large-font-size { font-size: var(--wp--preset--font-size--large) !important; }
+```
+
+主题如需覆盖默认值，可通过`theme.json`文件提供相同标识符进行配置。未使用`theme.json`的主题仍可通过加载CSS来设置对应的CSS自定义属性实现覆盖。
+
+示例（修改默认大字号的值）：
+```css
+body {
+ --wp--preset--font-size--large: <新值>;
+}
+```
+
+##### 元素伪类选择器
+
+古腾堡编辑器支持伪类选择器 `:hover`、`:focus`、`:focus-visible`、`:visited`、`:active`、`:link`、`:any-link`。
+
+```json
+"elements": {
+ "link": {
+ "color": {
+ "text": "绿色"
+ },
+ ":hover": {
+ "color": {
+ "text": "亮粉色"
+ }
+ }
+ }
+ }
+```
+
+#### 样式变体
+
+区块可以拥有“样式变体”，具体定义参见[block.json规范](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-registration/#styles-optional)。主题开发者可以通过`theme.json`文件为已存在的样式变体定义样式属性。未注册样式变体的样式配置将被忽略。
+
+需注意：变体是“区块概念”——仅当与区块绑定时才存在。`theme.json`规范遵循这一特性，只允许在区块层级而非顶层配置`variations`。特别需要强调的是，只有通过区块`block.json`文件或服务端`register_block_style`注册的变体，才会被视作`theme.json`样式配置中的“已注册变体”。
+
+例如，以下是为`core/quote`区块现有`plain`变体定义样式的方式：
+
+```json
+{
+ "version": 3,
+ "styles": {
+ "blocks": {
+ "core/quote": {
+ "variations": {
+ "plain": {
+ "color": {
+ "background": "红色"
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+最终输出的CSS为：
+
+```css
+.wp-block-quote.is-style-plain {
+ background-color: red;
+}
+```
+
+多个区块类型也可以共享相同的变体样式。推荐以下两种定义共享样式的方法：
+
+1. `theme.json`分部文件
+2. 通过`register_block_style`编程注册
+
+##### 变体Theme.json分部文件
+
+与主题样式变体分部文件类似，区块样式变体分部文件也存放在主题的`/styles`目录中。但通过顶层属性`blockTypes`与主题样式变体进行区分。`blockTypes`属性是一个数组，包含已注册该区块样式变体的所有区块类型。
+
+此外，通过`slug`属性可确保不同来源定义的区块样式变体保持一致性，并将可翻译的`title`属性与`slug`解耦。
+
+以下是一个`theme.json`分部文件示例，为Group、Columns和Media & Text区块类型定义“变体A”区块样式：
+
+```json
+{
+ "$schema": "https://schemas.wp.org/trunk/theme.json",
+ "version": 3,
+ "title": "变体A",
+ "slug": "variation-a",
+ "blockTypes": [ "core/group", "core/columns", "core/media-text" ],
+ "styles": {
+ "color": {
+ "background": "#eed8d3",
+ "text": "#201819"
+ },
+ "elements": {
+ "heading": {
+ "color": {
+ "text": "#201819"
+ }
+ }
+ },
+ "blocks": {
+ "core/group": {
+ "color": {
+ "background": "#825f58",
+ "text": "#eed8d3"
+ },
+ "elements": {
+ "heading": {
+ "color": {
+ "text": "#eed8d3"
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+##### 编程注册变体样式
+
+除了使用`theme.json`分部文件，您还可以在通过`register_block_style`注册变体时同步注册样式。该方法通过为区块数组注册区块样式，并在`style_data`参数中传入“样式对象”实现。
+
+以下示例为Group和Columns区块注册“绿色”变体。注意通过`style_data`传递的样式对象结构与`theme.json`分部文件中的`styles`属性结构一致。
+
+```php
+register_block_style(
+ array( 'core/group', 'core/columns' ),
+ array(
+ 'name' => 'green',
+ 'label' => __( '绿色' ),
+ 'style_data' => array(
+ 'color' => array(
+ 'background' => '#4f6f52',
+ 'text' => '#d2e3c8',
+ ),
+ 'blocks' => array(
+ 'core/group' => array(
+ 'color' => array(
+ 'background' => '#739072',
+ 'text' => '#e3eedd',
+ ),
+ ),
+ ),
+ 'elements' => array(
+ 'link' => array(
+ 'color' => array(
+ 'text' => '#ead196',
+ ),
+ ':hover' => array(
+ 'color' => array(
+ 'text' => '#ebd9b4',
+ ),
+ ),
+ ),
+ ),
+ ),
+ )
+);
+```
+
+### 顶层样式
+
+位于顶层的样式将使用 `body` 选择器进行注册。
+
+{% codetabs %}
+{% Input %}
+
+```json
+{
+ "version": 3,
+ "styles": {
+ "color": {
+ "text": "var(--wp--preset--color--primary)"
+ }
+ }
+}
+```
+
+{% Output %}
+
+```css
+body {
+ color: var( --wp--preset--color--primary );
+}
+```
+
+{% end %}
+### 区块样式
+
+位于区块内的样式将使用区块选择器进行注册。
+
+默认情况下，区块选择器会根据其名称生成，例如 `.wp-block-<不含命名空间的区块名称>`。例如，`core/group` 区块对应 `.wp-block-group`。某些区块可以选择退出此默认行为，只需在其 `block.json` 文件的 `supports` 部分通过 `__experimentalSelector` 键明确指定要使用的选择器即可。需要注意的是，区块必须在服务端注册，样式引擎才能使用 `__experimentalSelector` 字段。
+
+{% codetabs %}
+{% Input %}
+
+```json
+{
+ "version": 3,
+ "styles": {
+ "color": {
+ "text": "var(--wp--preset--color--primary)"
+ },
+ "blocks": {
+ "core/paragraph": {
+ "color": {
+ "text": "var(--wp--preset--color--secondary)"
+ }
+ },
+ "core/group": {
+ "color": {
+ "text": "var(--wp--preset--color--tertiary)"
+ }
+ }
+ }
+ }
+}
+```
+
+{% Output %}
+
+```css
+body {
+ color: var( --wp--preset--color--primary );
+}
+p { /* core/paragraph 区块选择退出默认行为，使用 p 作为选择器。 */
+ color: var( --wp--preset--color--secondary );
+}
+.wp-block-group {
+ color: var( --wp--preset--color--tertiary );
+}
+```
+{% end %}
+
+#### 引用样式
+
+区块可以通过引用根层级样式来进行样式设置。此功能由 Gutenberg 支持。
+如果使用 `styles.color.background` 为根层级注册背景颜色：
+
+```JSON
+"styles": {
+ "color": {
+ "background": "var(--wp--preset--color--primary)"
+ }
+ }
+```
+
+你可以使用 `ref: "styles.color.background"` 来为区块复用该样式：
+
+```JSON
+{
+ "color": {
+ "text": { "ref": "styles.color.background" }
+ }
+}
+```
+
+#### 元素样式
+
+除了顶层样式和区块层级样式外，还有一种元素的概念，可以在两个地方使用。它们是一个封闭集合：
+
+Gutenberg 支持的：
+
+- `button`：映射到 `wp-element-button` CSS 类。同时为了向后兼容，也映射到 `wp-block-button__link`。
+- `caption`：映射到 `.wp-element-caption, .wp-block-audio figcaption, .wp-block-embed figcaption, .wp-block-gallery figcaption, .wp-block-image figcaption, .wp-block-table figcaption, .wp-block-video figcaption` CSS 类。
+- `heading`：映射到所有标题，即 `h1 到 h6` CSS 选择器。
+
+WordPress 支持的：
+
+- `h1`：映射到 `h1` CSS 选择器。
+- `h2`：映射到 `h2` CSS 选择器。
+- `h3`：映射到 `h3` CSS 选择器。
+- `h4`：映射到 `h4` CSS 选择器。
+- `h5`：映射到 `h5` CSS 选择器。
+- `h6`：映射到 `h6` CSS 选择器。
+- `link`：映射到 `a` CSS 选择器。
+
+如果在顶层找到元素样式，将使用元素选择器。如果在区块内找到，使用的选择器将是该元素附加到对应区块的选择器。
+
+{% codetabs %}
+{% Input %}
+
+```json
+{
+ "version": 3,
+ "styles": {
+ "typography": {
+ "fontSize": "var(--wp--preset--font-size--normal)"
+ },
+ "elements": {
+ "h1": {
+ "typography": {
+ "fontSize": "var(--wp--preset--font-size--huge)"
+ }
+ },
+ "h2": {
+ "typography": {
+ "fontSize": "var(--wp--preset--font-size--big)"
+ }
+ },
+ "h3": {
+ "typography": {
+ "fontSize": "var(--wp--preset--font-size--medium)"
+ }
+ }
+ },
+ "blocks": {
+ "core/group": {
+ "elements": {
+ "h2": {
+ "typography": {
+ "fontSize": "var(--wp--preset--font-size--small)"
+ }
+ },
+ "h3": {
+ "typography": {
+ "fontSize": "var(--wp--preset--font-size--smaller)"
+ }
+ }
+ }
+ }
+ }
+ }
+}
+```
+
+{% Output %}
+
+```css
+body {
+ font-size: var( --wp--preset--font-size--normal );
+}
+h1 {
+ font-size: var( --wp--preset--font-size--huge );
+}
+h2 {
+ font-size: var( --wp--preset--font-size--big );
+}
+h3 {
+ font-size: var( --wp--preset--font-size--medium );
+}
+.wp-block-group h2 {
+ font-size: var( --wp--preset--font-size--small );
+}
+.wp-block-group h3 {
+ font-size: var( --wp--preset--font-size--smaller );
+}
+```
+{% end %}
+
+### 版本说明
+
+此字段用于描述 `theme.json` 文件的格式规范。最新版本为 WordPress 6.6 推出的[版本 3](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/)。
+
+当需进行破坏性变更时，会发布新版本。这允许主题开发者自主选择何时启用破坏性变更，并将其 theme.json 文件迁移至新格式。
+
+旧版 `theme.json` 均具有向后兼容性，可继续在新版 WordPress 和 Gutenberg 插件中正常使用。但新功能将基于最新版本进行开发。
+
+请参照[版本迁移指南](https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-migrations/)了解升级至最新版本的具体操作。
+
+### 设置项
+
+
+Gutenberg 插件扩展了 WordPress 5.8 支持的设置项，使其可兼容其他 WordPress 版本。这些扩展功能需经过成熟度测试后才会被移植至核心代码。
+
+下方选项卡分别展示 WordPress 5.8 支持的设置项与 Gutenberg 插件支持的设置项。
+
+
+设置项章节采用以下结构：
+
+{% codetabs %}
+{% WordPress %}
+
+```json
+{
+ "version": 3,
+ "settings": {
+ "border": {
+ "radius": false,
+ "color": false,
+ "style": false,
+ "width": false
+ },
+ "color": {
+ "custom": true,
+ "customDuotone": true,
+ "customGradient": true,
+ "duotone": [],
+ "gradients": [],
+ "link": false,
+ "palette": [],
+ "text": true,
+ "background": true,
+ "defaultGradients": true,
+ "defaultPalette": true
+ },
+ "custom": {},
+ "layout": {
+ "contentSize": "800px",
+ "wideSize": "1000px"
+ },
+ "spacing": {
+ "margin": false,
+ "padding": false,
+ "blockGap": null,
+ "units": [ "px", "em", "rem", "vh", "vw" ]
+ },
+ "typography": {
+ "customFontSize": true,
+ "lineHeight": false,
+ "dropCap": true,
+ "fluid": false,
+ "fontStyle": true,
+ "fontWeight": true,
+ "letterSpacing": true,
+ "textDecoration": true,
+ "textTransform": true,
+ "fontSizes": [],
+ "fontFamilies": []
+ },
+ "blocks": {
+ "core/paragraph": {
+ "color": {},
+ "custom": {},
+ "layout": {},
+ "spacing": {},
+ "typography": {}
+ },
+ "core/heading": {},
+ "etc": {}
+ }
+ }
+}
+```
+
+{% Gutenberg %}
+
+```json
+{
+ "version": 3,
+ "settings": {
+ "appearanceTools": false,
+ "border": {
+ "color": false,
+ "radius": false,
+ "style": false,
+ "width": false
+ },
+ "color": {
+ "background": true,
+ "custom": true,
+ "customDuotone": true,
+ "customGradient": true,
+ "defaultGradients": true,
+ "defaultPalette": true,
+ "duotone": [],
+ "gradients": [],
+ "link": false,
+ "palette": [],
+ "text": true
+ },
+ "custom": {},
+ "dimensions": {
+ "aspectRatio": false,
+ "minHeight": false,
+ },
+ "layout": {
+ "contentSize": "800px",
+ "wideSize": "1000px"
+ },
+ "spacing": {
+ "blockGap": null,
+ "margin": false,
+ "padding": false,
+ "customSpacingSize": true,
+ "units": [ "px", "em", "rem", "vh", "vw" ],
+ "spacingScale": {
+ "operator": "*",
+ "increment": 1.5,
+ "steps": 7,
+ "mediumStep": 1.5,
+ "unit": "rem"
+ },
+ "spacingSizes": []
+ },
+ "typography": {
+ "customFontSize": true,
+ "dropCap": true,
+ "fluid": false,
+ "fontFamilies": [],
+ "fontSizes": [],
+ "fontStyle": true,
+ "fontWeight": true,
+ "letterSpacing": true,
+ "lineHeight": false,
+ "textAlign": true,
+ "textColumns": false,
+ "textDecoration": true,
+ "textTransform": true
+ },
+ "blocks": {
+ "core/paragraph": {
+ "border": {},
+ "color": {},
+ "custom": {},
+ "layout": {},
+ "spacing": {},
+ "typography": {}
+ },
+ "core/heading": {},
+ "etc": {}
+ }
+ }
+}
+```
+{% end %}
+
+每个区块均可独立配置这些设置项，实现比 `add_theme_support` 更精细的控制粒度。顶层声明的设置项将影响所有区块，除非特定区块对其进行覆盖。这种机制既提供了配置继承性，也支持一次性配置所有区块。
+
+需要注意的是，并非所有设置项都适用于每个区块。设置项章节为主题提供启用/禁用机制，但具体功能支持仍需由区块自行实现。例如，若某区块未实现 `dropCap` 首字下沉功能，则主题无法通过 `theme.json` 为该区块启用此功能。
+
+```
+{% end %}
+
+为保持向后兼容性，通过 `add_theme_support` 声明的预设也会生成 CSS 自定义属性。若 `theme.json` 包含任何预设，这些预设将优先于通过 `add_theme_support` 声明的预设。
+
+预设类通过用户操作附加到文章内容。因此引擎会为这些类添加 `!important` 声明，因为用户样式应优先于主题样式。
+
+#### 自定义配置
+
+除了为预设创建 CSS 自定义属性外，`theme.json` 还允许主题创建自定义属性，无需单独排队加载。在 `custom` 字段内声明的任何值都将按以下命名模式转换为 CSS 自定义属性：`--wp--custom--<变量名称>`。
+
+例如：
+
+{% codetabs %}
+{% 输入 %}
+
+```json
+{
+ "version": 3,
+ "settings": {
+ "custom": {
+ "baseFont": 16,
+ "lineHeight": {
+ "small": 1.2,
+ "medium": 1.4,
+ "large": 1.8
+ }
+ },
+ "blocks": {
+ "core/group": {
+ "custom": {
+ "baseFont": 32
+ }
+ }
+ }
+ }
+}
+```
+
+{% 输出 %}
+
+```css
+body {
+ --wp--custom--base-font: 16;
+ --wp--custom--line-height--small: 1.2;
+ --wp--custom--line-height--medium: 1.4;
+ --wp--custom--line-height--large: 1.8;
+}
+.wp-block-group {
+ --wp--custom--base-font: 32;
+}
+```
+
+{% end %}
+
+请注意，变量名称通过在每个嵌套层级间添加 `--` 来创建，且 `camelCase` 格式的字段会转换为 `kebab-case` 格式。
+
+#### 设置示例
+
+- 仅对段落区块启用自定义颜色：
+
+```json
+{
+ "version": 3,
+ "settings": {
+ "color": {
+ "custom": false
+ },
+ "blocks": {
+ "core/paragraph": {
+ "color": {
+ "custom": true
+ }
+ }
+ }
+ }
+}
+```
+
+- 禁用按钮区块的边框圆角：
+
+```json
+{
+ "version": 3,
+ "settings": {
+ "blocks": {
+ "core/button": {
+ "border": {
+ "radius": false
+ }
+ }
+ }
+ }
+}
+```
+
+- 为群组区块提供与其他区块不同的调色板：
+
+```json
+{
+ "version": 3,
+ "settings": {
+ "color": {
+ "palette": [
+ {
+ "slug": "black",
+ "color": "#000000",
+ "name": "黑色"
+ },
+ {
+ "slug": "white",
+ "color": "#FFFFFF",
+ "name": "白色"
+ },
+ {
+ "slug": "red",
+ "color": "#FF0000",
+ "name": "红色"
+ },
+ {
+ "slug": "green",
+ "color": "#00FF00",
+ "name": "绿色"
+ },
+ {
+ "slug": "blue",
+ "color": "#0000FF",
+ "name": "蓝色"
+ }
+ ]
+ },
+ "blocks": {
+ "core/group": {
+ "color": {
+ "palette": [
+ {
+ "slug": "black",
+ "color": "#000000",
+ "name": "黑色"
+ },
+ {
+ "slug": "white",
+ "color": "#FFF",
+ "name": "白色"
+ }
+ ]
+ }
+ }
+ }
+ }
+}
+```
+
+### 样式
+
+
+Gutenberg 插件扩展了 WordPress 5.8 的可用样式，使其可与其他 WordPress 版本兼容，这些样式在移植到核心版本前需经过成熟度验证。
+
+下方标签页分别展示 WordPress 5.8 支持的样式与 Gutenberg 插件支持的样式。
+
+
+每个区块通过[区块支持机制](/docs/reference-guides/block-api/block-supports.md)声明其暴露的样式属性。这些支持声明用于在编辑器中自动生成区块的 UI 控件。主题可通过 `theme.json` 为任何区块使用样式属性——但需由主题自行验证这些样式是否能根据区块标记等要素正常生效。
+
+{% codetabs %}
+{% WordPress %}
+
+```json
+{
+ "version": 3,
+ "styles": {
+ "border": {
+ "radius": "value",
+ "color": "value",
+ "style": "value",
+ "width": "value"
+ },
+ "filter": {
+ "duotone": "value"
+ },
+ "color": {
+ "background": "value",
+ "gradient": "value",
+ "text": "value"
+ },
+ "spacing": {
+ "blockGap": "value",
+ "margin": {
+ "top": "value",
+ "right": "value",
+ "bottom": "value",
+ "left": "value",
+ },
+ "padding": {
+ "top": "value",
+ "right": "value",
+ "bottom": "value",
+ "left": "value"
+ }
+ },
+ "typography": {
+ "fontSize": "value",
+ "fontStyle": "value",
+ "fontWeight": "value",
+ "letterSpacing": "value",
+ "lineHeight": "value",
+ "textDecoration": "value",
+ "textTransform": "value"
+ },
+ "elements": {
+ "link": {
+ "border": {},
+ "color": {},
+ "spacing": {},
+ "typography": {}
+ },
+ "h1": {},
+ "h2": {},
+ "h3": {},
+ "h4": {},
+ "h5": {},
+ "h6": {}
+ },
+ "blocks": {
+ "core/group": {
+ "border": {},
+ "color": {},
+ "spacing": {},
+ "typography": {},
+ "elements": {
+ "link": {},
+ "h1": {},
+ "h2": {},
+ "h3": {},
+ "h4": {},
+ "h5": {},
+ "h6": {}
+ }
+ },
+ "etc": {}
+ }
+ }
+}
+```
+{% Gutenberg %}
+
+```json
+{
+ "version": 3,
+ "styles": {
+ "border": {
+ "color": "value",
+ "radius": "value",
+ "style": "value",
+ "width": "value"
+ },
+ "color": {
+ "background": "value",
+ "gradient": "value",
+ "text": "value"
+ },
+ "dimensions": {
+ "aspectRatio": "value",
+ "minHeight": "value"
+ },
+ "filter": {
+ "duotone": "value"
+ },
+ "spacing": {
+ "blockGap": "value",
+ "margin": {
+ "top": "value",
+ "right": "value",
+ "bottom": "value",
+ "left": "value"
+ },
+ "padding": {
+ "top": "value",
+ "right": "value",
+ "bottom": "value",
+ "left": "value"
+ }
+ },
+ "typography": {
+ "fontFamily": "value",
+ "fontSize": "value",
+ "fontStyle": "value",
+ "fontWeight": "value",
+ "letterSpacing": "value",
+ "lineHeight": "value",
+ "textColumns": "value",
+ "textDecoration": "value",
+ "textTransform": "value"
+ },
+ "elements": {
+ "link": {
+ "border": {},
+ "color": {},
+ "spacing": {},
+ "typography": {}
+ },
+ "h1": {},
+ "h2": {},
+ "h3": {},
+ "h4": {},
+ "h5": {},
+ "h6": {},
+ "heading": {},
+ "button": {},
+ "caption": {}
+ },
+ "blocks": {
+ "core/group": {
+ "border": {},
+ "color": {},
+ "dimensions": {},
+ "spacing": {},
+ "typography": {},
+ "elements": {
+ "link": {},
+ "h1": {},
+ "h2": {},
+ "h3": {},
+ "h4": {},
+ "h5": {},
+ "h6": {}
+ }
+ },
+ "etc": {}
+ }
+ }
+}
+```
+{% end %}
+
+### 启用UI控件选项
+
+存在一个特殊的设置属性 `appearanceTools`，它是一个布尔值，默认值为 false。主题可以通过此设置启用以下选项：
+
+- 背景：backgroundImage、backgroundSize
+- 边框：color、radius、style、width
+- 颜色：link
+- 尺寸：aspectRatio、minHeight
+- 位置：sticky
+- 间距：blockGap、margin、padding
+- 排版：lineHeight
+
+#### 与 add_theme_support 的向后兼容性
+
+为了保持向后兼容性，现有的用于配置区块编辑器的 `add_theme_support` 声明已被适配到顶层部分的适当类别中。例如，如果主题使用 `add_theme_support('disable-custom-colors')`，则等同于将 `settings.color.custom` 设置为 `false`。如果 `theme.json` 包含任何设置，这些设置将优先于通过 `add_theme_support` 声明的值。以下是完整的等效关系列表：
+
+| add_theme_support | theme.json 设置 |
+| --------------------------- | ------------------------------------------------------------ |
+| `custom-line-height` | 将 `typography.lineHeight` 设置为 `true`。 |
+| `custom-spacing` | 将 `spacing.padding` 设置为 `true`。 |
+| `custom-units` | 通过 `spacing.units` 提供单位列表。 |
+| `disable-custom-colors` | 将 `color.custom` 设置为 `false`。 |
+| `disable-custom-font-sizes` | 将 `typography.customFontSize` 设置为 `false`。 |
+| `disable-custom-gradients` | 将 `color.customGradient` 设置为 `false`。 |
+| `editor-color-palette` | 通过 `color.palette` 提供颜色列表。 |
+| `editor-font-sizes` | 通过 `typography.fontSizes` 提供字体大小列表。 |
+| `editor-gradient-presets` | 通过 `color.gradients` 提供渐变列表。 |
+| `editor-spacing-sizes` | 通过 `spacing.spacingSizes` 提供间距尺寸列表。 |
+| `appearance-tools` | 将 `appearanceTools` 设置为 `true`。 |
+| `border` | 将 `border: color, radius, style, width` 设置为 `true`。 |
+| `link-color ` | 将 `color.link` 设置为 `true`。 |
+
+#### 预设
+
+预设是设置部分的一部分。它们是通过某些UI控件向用户显示的值。通过 `theme.json` 定义这些值，引擎可以为主题提供更多功能，例如自动翻译预设名称或排队相应的CSS类和自定义属性。
+
+可以通过 `theme.json` 定义以下预设：
+
+- `color.duotone`：不生成类或自定义属性。
+- `color.gradients`：为每个预设值生成一个类和一个自定义属性。
+- `color.palette`：
+ - 为每个预设值生成3个类：color、background-color 和 border-color。
+ - 为每个预设值生成一个自定义属性。
+- `spacing.spacingSizes`/`spacing.spacingScale`：为每个预设值生成一个自定义属性。
+- `typography.fontSizes`：为每个预设值生成一个类和一个自定义属性。
+- `typography.fontFamilies`：为每个预设值生成一个自定义属性。
+
+类和自定义属性的命名规则如下：
+
+- 自定义属性：`--wp--preset--{preset-category}--{preset-slug}`，例如 `--wp--preset--color--black`
+- 类：`.has-{preset-slug}-{preset-category}`，例如 `.has-black-color`
+
+{% codetabs %}
+{% 输入 %}
+
+```json
+{
+ "version": 3,
+ "settings": {
+ "color": {
+ "duotone": [
+ {
+ "colors": [ "#000", "#FFF" ],
+ "slug": "black-and-white",
+ "name": "Black and White"
+ }
+ ],
+ "gradients": [
+ {
+ "slug": "blush-bordeaux",
+ "gradient": "linear-gradient(135deg,rgb(254,205,165) 0%,rgb(254,45,45) 50%,rgb(107,0,62) 100%)",
+ "name": "Blush bordeaux"
+ },
+ {
+ "slug": "blush-light-purple",
+ "gradient": "linear-gradient(135deg,rgb(255,206,236) 0%,rgb(152,150,240) 100%)",
+ "name": "Blush light purple"
+ }
+ ],
+ "palette": [
+ {
+ "slug": "strong-magenta",
+ "color": "#a156b4",
+ "name": "Strong magenta"
+ },
+ {
+ "slug": "very-dark-grey",
+ "color": "rgb(131, 12, 8)",
+ "name": "Very dark grey"
+ }
+ ]
+ },
+ "typography": {
+ "fontFamilies": [
+ {
+ "fontFamily": "-apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Oxygen-Sans,Ubuntu,Cantarell, \"Helvetica Neue\",sans-serif",
+ "slug": "system-font",
+ "name": "System Font"
+ },
+ {
+ "fontFamily": "Helvetica Neue, Helvetica, Arial, sans-serif",
+ "slug": "helvetica-arial",
+ "name": "Helvetica or Arial"
+ }
+ ],
+ "fontSizes": [
+ {
+ "slug": "big",
+ "size": 32,
+ "name": "Big"
+ },
+ {
+ "slug": "x-large",
+ "size": 46,
+ "name": "Large"
+ }
+ ]
+ },
+ "spacing": {
+ "spacingScale": {
+ "operator": "*",
+ "increment": 1.5,
+ "steps": 7,
+ "mediumStep": 1.5,
+ "unit": "rem"
+ },
+ "spacingSizes": [
+ {
+ "slug": "40",
+ "size": "1rem",
+ "name": "Small"
+ },
+ {
+ "slug": "50",
+ "size": "1.5rem",
+ "name": "Medium"
+ },
+ {
+ "slug": "60",
+ "size": "2rem",
+ "name": "Large"
+ }
+ ]
+ },
+ "blocks": {
+ "core/group": {
+ "color": {
+ "palette": [
+ {
+ "slug": "black",
+ "color": "#000000",
+ "name": "Black"
+ },
+ {
+ "slug": "white",
+ "color": "#ffffff",
+ "name": "White"
+ }
+ ]
+ }
+ }
+ }
+ }
+}
+```
+
+{% 输出 %}
+
+```css
+/* 顶层自定义属性 */
+body {
+ --wp--preset--color--strong-magenta: #a156b4;
+ --wp--preset--color--very-dark-grey: #444;
+ --wp--preset--gradient--blush-bordeaux: linear-gradient( 135deg, rgb( 254, 205, 165 ) 0%, rgb( 254, 45, 45 ) 50%, rgb( 107, 0, 62 ) 100% );
+ --wp--preset--gradient--blush-light-purple: linear-gradient( 135deg, rgb( 255, 206, 236 ) 0%, rgb( 152, 150, 240 ) 100% );
+ --wp--preset--font-size--x-large: 46;
+ --wp--preset--font-size--big: 32;
+ --wp--preset--font-family--helvetica-arial: Helvetica Neue, Helvetica, Arial, sans-serif;
+ --wp--preset--font-family--system: -apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Oxygen-Sans,Ubuntu,Cantarell, \"Helvetica Neue\",sans-serif;
+ --wp--preset--spacing--20: 0.44rem;
+ --wp--preset--spacing--30: 0.67rem;
+ --wp--preset--spacing--40: 1rem;
+ --wp--preset--spacing--50: 1.5rem;
+ --wp--preset--spacing--60: 2.25rem;
+ --wp--preset--spacing--70: 3.38rem;
+ --wp--preset--spacing--80: 5.06rem;
+}
+
+/* 区块级自定义属性（绑定到群组区块） */
+.wp-block-group {
+ --wp--preset--color--black: #000000;
+ --wp--preset--color--white: #ffffff;
+}
+
+/* 顶层类 */
+.has-strong-magenta-color { color: #a156b4 !important; }
+.has-strong-magenta-background-color { background-color: #a156b4 !important; }
+.has-strong-magenta-border-color { border-color: #a156b4 !important; }
+.has-very-dark-grey-color { color: #444 !important; }
+.has-very-dark-grey-background-color { background-color: #444 !important; }
+.has-very-dark-grey-border-color { border-color: #444 !important; }
+.has-blush-bordeaux-background { background: linear-gradient( 135deg, rgb( 254, 205, 165 ) 0%, rgb( 254, 45, 45 ) 50%, rgb( 107, 0, 62 ) 100% ) !important; }
+.has-blush-light-purple-background { background: linear-gradient( 135deg, rgb( 255, 206, 236 ) 0%, rgb( 152, 150, 240 ) 100% ) !important; }
+.has-big-font-size { font-size: 32; }
+.has-normal-font-size { font-size: 16; }
+
+/* 区块级类（绑定到群组区块） */
+.wp-block-group.has-black-color { color: #a156b4 !important; }
+.wp-block-group.has-black-background-color { background-color: #a156b4 !important; }
+.wp-block-group.has-black-border-color { border-color: #a156b4 !important; }
+.wp-block-group.has-white-color { color: #444 !important; }
+.wp-block-group.has-white-background-color { background-color: #444 !important; }
+.wp-block-group.has-white-border-color { border-color: #444 !important; }
+```
\ No newline at end of file
diff --git a/how-to-guides/themes/theme-support.md b/how-to-guides/themes/theme-support.md
new file mode 100644
index 0000000..4b9c125
--- /dev/null
+++ b/how-to-guides/themes/theme-support.md
@@ -0,0 +1,511 @@
+## 链接颜色控制
+
+链接颜色支持已在 WordPress 5.8 版本中趋于稳定。该功能默认处于关闭状态（`false`），主题可通过 [theme.json 文件](/docs/how-to-guides/curating-the-editor-experience/theme-json.md)启用：
+
+```json
+{
+ "settings": {
+ "color": {
+ "link": true
+ }
+ }
+}
+```
+
+> 替代方案：若已启用 Gutenberg 插件，传统的实验性支持 `add_theme_support( 'experimental-link-color' )` 仍可生效。当 Gutenberg 插件要求最低 WordPress 版本为 5.9 时，此备用方案将被移除。
+
+当用户设置区块的链接颜色时，系统将以如下形式添加新样式：
+
+```css
+.wp-elements-
+注意：标识符 `default` 和 `custom` 为保留字，主题不可使用。
+
+
+自 WordPress 5.9 起，要覆盖核心定义的字体大小值，没有 `theme.json` 的主题必须通过 CSS 自定义属性设置其值，而非提供类。CSS 自定义属性使用以下命名方式 `--wp--preset--font-size--
+
+
+ 简短图片标题。
+
+
+```
+
+这里有一个使用上述标记实现响应式布局的 [codepen](https://codepen.io/joen/pen/zLWvrW) 示例，该布局包含侧边栏、宽幅图像以及带有限定标题的浮动元素。
+
+### 区块调色板
+
+不同区块可以自定义颜色。区块编辑器提供了默认调色板，但主题可以覆盖它并提供自己的调色板：
+
+```php
+add_theme_support( 'editor-color-palette', array(
+ array(
+ 'name' => esc_attr__( '强品红色', 'themeLangDomain' ),
+ 'slug' => 'strong-magenta',
+ 'color' => '#a156b4',
+ ),
+ array(
+ 'name' => esc_attr__( '浅灰品红色', 'themeLangDomain' ),
+ 'slug' => 'light-grayish-magenta',
+ 'color' => '#d0a5db',
+ ),
+ array(
+ 'name' => esc_attr__( '极浅灰色', 'themeLangDomain' ),
+ 'slug' => 'very-light-gray',
+ 'color' => '#eee',
+ ),
+ array(
+ 'name' => esc_attr__( '极深灰色', 'themeLangDomain' ),
+ 'slug' => 'very-dark-gray',
+ 'color' => '#444',
+ ),
+) );
+```
+
+`name` 是一个易于理解的标签（如上所示），它会显示在工具提示中，并为用户提供颜色的有意义的描述。这对于依赖屏幕阅读器或难以感知颜色的用户尤其重要。`slug` 是颜色的唯一标识符，用于生成区块编辑器调色板的 CSS 类。`color` 是指定颜色的十六进制代码。
+
+某些颜色会动态变化，例如“主色”和“辅色”，例如在 Twenty Nineteen 主题中，这些颜色无法通过编程方式描述。尽管如此，建议在适用时为至少默认值提供有意义的 `name`。
+
+颜色将按顺序显示在调色板上，并且可以指定的颜色数量没有限制。
+
+主题负责创建在不同上下文中应用颜色的类。核心区块使用“颜色”、“背景颜色”和“边框颜色”上下文。因此，为了正确地将“强品红色”应用于核心区块的所有上下文，主题应自行实现这些类。类名的构建方式是在“has-”后附加使用短横线命名法的类名，并以上下文名称结尾。
+
+```css
+.has-strong-magenta-color {
+ color: #a156b4;
+}
+
+.has-strong-magenta-background-color {
+ background-color: #a156b4;
+}
+
+.has-strong-magenta-border-color {
+ border-color: #a156b4;
+}
+```
+
+从 WordPress 5.9 开始，要覆盖核心定义的颜色值，没有 `theme.json` 的主题必须通过 CSS 自定义属性设置其值，而不是提供类。CSS 自定义属性使用以下命名方式：`--wp--preset--color--名称：
+ ... + true, + // ...其他选项 + ); + parent::__construct( 'example_widget', 'ExampleWidget', $widget_ops ); + } + ... +} +``` + +这允许区块编辑器和其他 REST API 客户端通过访问 REST API 响应中的 `instance.raw` 来查看您的小工具的实例数组。 + +请注意，[WordPress 5.8.0 之前的版本允许您通过在扩展 `WP_Widget` 的类中将 `$show_instance_in_rest` 设置为 `true`](https://core.trac.wordpress.org/ticket/53332) 来启用此功能。 + +```php +class ExampleWidget extends WP_Widget { + ... + public $show_instance_in_rest = true; + ... +} +``` + +现在已不推荐使用此方法，建议改用小工具选项方法。 + +#### 2) 添加区块转换 + +现在，我们可以定义一个[区块转换](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-transforms/)，告诉区块编辑器用什么替换包含您小工具的传统小工具区块。 + +这是通过向区块定义中添加 JavaScript 代码来实现的。在此示例中，我们定义了一个转换，将 ID 为 `'example_widget'` 的小工具转换为名称为 `'example/block'` 的区块。 + +```js +transforms: { + from: [ + { + type: 'block', + blocks: [ 'core/legacy-widget' ], + isMatch: ( { idBase, instance } ) => { + if ( ! instance?.raw ) { + // 如果原始实例未在 REST API 中显示，则无法转换。 + return false; + } + return idBase === 'example_widget'; + }, + transform: ( { instance } ) => { + return createBlock( 'example/block', { + name: instance.raw.name, + } ); + }, + }, + ] +}, +``` + +#### 3) 在传统小工具区块中隐藏小工具 + +最后，我们可以告诉传统小工具区块在“选择小工具”下拉列表和区块插入器中隐藏您的小工具。这鼓励用户使用替换您小工具的区块。 + +可以使用 `widget_types_to_hide_from_legacy_widget_block` 过滤器来实现这一点。 + +```php +function hide_example_widget( $widget_types ) { + $widget_types[] = 'example_widget'; + return $widget_types; +} +add_filter( 'widget_types_to_hide_from_legacy_widget_block', 'hide_example_widget' ); +``` + +## 在其他区块编辑器中使用传统小工具区块（高级） + +您可以选择允许在其他区块编辑器（例如 WordPress 文章编辑器）中使用传统小工具区块。默认情况下，此功能未启用。 + +首先，确保页面上加载了传统小工具所需的任何样式和脚本。一种便捷的方法是手动执行用户浏览小工具 WP 管理屏幕时通常运行的所有钩子。 + +```php +add_action( 'admin_print_styles', function() { + if ( get_current_screen()->is_block_editor() ) { + do_action( 'admin_print_styles-widgets.php' ); + } +} ); +add_action( 'admin_print_scripts', function() { + if ( get_current_screen()->is_block_editor() ) { + do_action( 'load-widgets.php' ); + do_action( 'widgets.php' ); + do_action( 'sidebar_admin_setup' ); + do_action( 'admin_print_scripts-widgets.php' ); + } +} ); +add_action( 'admin_print_footer_scripts', function() { + if ( get_current_screen()->is_block_editor() ) { + do_action( 'admin_print_footer_scripts-widgets.php' ); + } +} ); +add_action( 'admin_footer', function() { + if ( get_current_screen()->is_block_editor() ) { + do_action( 'admin_footer-widgets.php' ); + } +} ); +``` + +然后，使用 `@wordpress/widgets` 包中定义的 `registerLegacyWidgetBlock` 注册传统小工具区块。 + +```php +add_action( 'enqueue_block_editor_assets', function() { + wp_enqueue_script( 'wp-widgets' ); + wp_add_inline_script( 'wp-widgets', 'wp.widgets.registerLegacyWidgetBlock()' ); +} ); +``` \ No newline at end of file diff --git a/how-to-guides/widgets/opting-out.md b/how-to-guides/widgets/opting-out.md new file mode 100644 index 0000000..cd46919 --- /dev/null +++ b/how-to-guides/widgets/opting-out.md @@ -0,0 +1,44 @@ +# 恢复经典小工具编辑器 + +有多种方法可以禁用新的小工具区块编辑器。 + +## 使用 `remove_theme_support` + +主题可以通过调用 `remove_theme_support( 'widgets-block-editor' )` 来禁用小工具区块编辑器。 + +例如，主题可以在 `functions.php` 文件中添加以下 PHP 代码： + +```php +function example_theme_support() { + remove_theme_support( 'widgets-block-editor' ); +} +add_action( 'after_setup_theme', 'example_theme_support' ); +``` + +## 使用经典小工具插件 + +最终用户可以通过安装并激活[经典小工具插件](https://wordpress.org/plugins/classic-widgets/)来禁用小工具区块编辑器。 + +安装此插件后，可以通过停用和激活插件来切换小工具区块编辑器的开关状态。 + +## 使用过滤器 + +`use_widgets_block_editor` 过滤器用于控制是否启用小工具区块编辑器。 + +例如，网站管理员可以在 Must-Use 插件中添加以下 PHP 代码来禁用小工具区块编辑器： + +```php +add_filter( 'use_widgets_block_editor', '__return_false' ); +``` + +对于更高级的用法，您可以提供自定义函数。以下示例展示了如何为特定用户禁用小工具区块编辑器： + +```php +function example_use_widgets_block_editor( $use_widgets_block_editor ) { + if ( 123 === get_current_user_id() ) { + return false; + } + return $use_widgets_block_editor; +} +add_filter( 'use_widgets_block_editor', 'example_use_widgets_block_editor' ); +``` \ No newline at end of file diff --git a/how-to-guides/widgets/overview.md b/how-to-guides/widgets/overview.md new file mode 100644 index 0000000..27e52dd --- /dev/null +++ b/how-to-guides/widgets/overview.md @@ -0,0 +1,31 @@ +# 小工具区块编辑器概述 + +## 小工具区块编辑器 + +全新小工具编辑器是WordPress的一项功能升级，它将小工具区域升级为支持区块与小工具并存使用。这项功能通过大家熟悉的WordPress区块编辑器，提供了全新小工具管理体验。 + +您可以通过访问外观→小工具或外观→自定义→小工具并选择小工具区域，来使用全新小工具编辑器。 + +小工具区块编辑器允许您通过独立编辑器或自定义器，将区块和小工具插入当前启用主题定义的任意[小工具区域或侧边栏](https://developer.wordpress.org/themes/functionality/sidebars/)。 + +### 自定义器小工具区块编辑器 + +全新小工具编辑器同时取代了自定义器中的小工具版块，采用基于区块的全新编辑器。 + +您可以通过访问外观→自定义，选择小工具，然后选择小工具区域来使用自定义器小工具区块编辑器。 + +通过自定义器使用全新小工具编辑器不仅支持将区块和小工具插入选定的小工具区域，还能利用编辑器右侧的实时预览功能，以及所有其他自定义器专属功能（如变更排程与共享）。 + +## 兼容性 + +在新版小工具编辑器推出前已添加到小工具区域的传统小工具，将通过传统小工具区块继续正常工作。 + +传统小工具区块作为兼容机制，允许我们在基于区块的全新小工具编辑器中编辑和预览传统小工具的变更。 + +通过插件注册的第三方小工具仍可通过添加和设置传统小工具区块，插入到小工具区域中。 + +小工具编辑器使用用户不可见的底层“区块”小工具来存储区块数据。这意味着插件和主题将继续正常工作，且停用小工具区块编辑器不会造成任何数据丢失。 + +主题可通过`remove_theme_support( 'widgets-block-editor' )`代码禁用小工具区块编辑器。 + +用户可通过安装[经典小工具插件](https://wordpress.org/plugins/classic-widgets/)来禁用小工具区块编辑器。 \ No newline at end of file diff --git a/manifest.json b/manifest.json new file mode 100644 index 0000000..1a15556 --- /dev/null +++ b/manifest.json @@ -0,0 +1,2438 @@ +[ + { + "title": "Block Editor Handbook", + "slug": "handbook", + "markdown_source": "../docs/README.md", + "parent": null + }, + { + "title": "Getting Started", + "slug": "getting-started", + "markdown_source": "../docs/getting-started/README.md", + "parent": null + }, + { + "title": "Block Development Environment", + "slug": "devenv", + "markdown_source": "../docs/getting-started/devenv/README.md", + "parent": "getting-started" + }, + { + "title": "Node.js development environment", + "slug": "nodejs-development-environment", + "markdown_source": "../docs/getting-started/devenv/nodejs-development-environment.md", + "parent": "devenv" + }, + { + "title": "Get started with wp-env", + "slug": "get-started-with-wp-env", + "markdown_source": "../docs/getting-started/devenv/get-started-with-wp-env.md", + "parent": "devenv" + }, + { + "title": "Get started with create-block", + "slug": "get-started-with-create-block", + "markdown_source": "../docs/getting-started/devenv/get-started-with-create-block.md", + "parent": "devenv" + }, + { + "title": "Get started with wp-scripts", + "slug": "get-started-with-wp-scripts", + "markdown_source": "../docs/getting-started/devenv/get-started-with-wp-scripts.md", + "parent": "devenv" + }, + { + "title": "Quick Start Guide", + "slug": "quick-start-guide", + "markdown_source": "../docs/getting-started/quick-start-guide.md", + "parent": "getting-started" + }, + { + "title": "Tutorial: Build your first block", + "slug": "tutorial", + "markdown_source": "../docs/getting-started/tutorial.md", + "parent": "getting-started" + }, + { + "title": "Fundamentals of Block Development", + "slug": "fundamentals", + "markdown_source": "../docs/getting-started/fundamentals/README.md", + "parent": "getting-started" + }, + { + "title": "File structure of a block", + "slug": "file-structure-of-a-block", + "markdown_source": "../docs/getting-started/fundamentals/file-structure-of-a-block.md", + "parent": "fundamentals" + }, + { + "title": "block.json", + "slug": "block-json", + "markdown_source": "../docs/getting-started/fundamentals/block-json.md", + "parent": "fundamentals" + }, + { + "title": "Registration of a block", + "slug": "registration-of-a-block", + "markdown_source": "../docs/getting-started/fundamentals/registration-of-a-block.md", + "parent": "fundamentals" + }, + { + "title": "The block wrapper", + "slug": "block-wrapper", + "markdown_source": "../docs/getting-started/fundamentals/block-wrapper.md", + "parent": "fundamentals" + }, + { + "title": "The block in the Editor", + "slug": "block-in-the-editor", + "markdown_source": "../docs/getting-started/fundamentals/block-in-the-editor.md", + "parent": "fundamentals" + }, + { + "title": "Markup representation of a block", + "slug": "markup-representation-block", + "markdown_source": "../docs/getting-started/fundamentals/markup-representation-block.md", + "parent": "fundamentals" + }, + { + "title": "Static or Dynamic rendering of a block", + "slug": "static-dynamic-rendering", + "markdown_source": "../docs/getting-started/fundamentals/static-dynamic-rendering.md", + "parent": "fundamentals" + }, + { + "title": "Working with JavaScript for the Block Editor", + "slug": "javascript-in-the-block-editor", + "markdown_source": "../docs/getting-started/fundamentals/javascript-in-the-block-editor.md", + "parent": "fundamentals" + }, + { + "title": "Glossary", + "slug": "glossary", + "markdown_source": "../docs/getting-started/glossary.md", + "parent": "getting-started" + }, + { + "title": "Frequently Asked Questions", + "slug": "faq", + "markdown_source": "../docs/getting-started/faq.md", + "parent": "getting-started" + }, + { + "title": "How-to Guides", + "slug": "how-to-guides", + "markdown_source": "../docs/how-to-guides/README.md", + "parent": null + }, + { + "title": "Accessibility", + "slug": "accessibility", + "markdown_source": "../docs/how-to-guides/accessibility.md", + "parent": "how-to-guides" + }, + { + "title": "Blocks", + "slug": "block-tutorial", + "markdown_source": "../docs/how-to-guides/block-tutorial/README.md", + "parent": "how-to-guides" + }, + { + "title": "Use styles and stylesheets", + "slug": "applying-styles-with-stylesheets", + "markdown_source": "../docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md", + "parent": "block-tutorial" + }, + { + "title": "Creating dynamic blocks", + "slug": "creating-dynamic-blocks", + "markdown_source": "../docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md", + "parent": "block-tutorial" + }, + { + "title": "Nested Blocks: Using InnerBlocks", + "slug": "nested-blocks-inner-blocks", + "markdown_source": "../docs/how-to-guides/block-tutorial/nested-blocks-inner-blocks.md", + "parent": "block-tutorial" + }, + { + "title": "Extending the Query Loop block", + "slug": "extending-the-query-loop-block", + "markdown_source": "../docs/how-to-guides/block-tutorial/extending-the-query-loop-block.md", + "parent": "block-tutorial" + }, + { + "title": "Development Platform", + "slug": "platform", + "markdown_source": "../docs/how-to-guides/platform/README.md", + "parent": "how-to-guides" + }, + { + "title": "Building a custom block editor", + "slug": "custom-block-editor", + "markdown_source": "../docs/how-to-guides/platform/custom-block-editor.md", + "parent": "platform" + }, + { + "title": "Create your First App with Gutenberg Data", + "slug": "data-basics", + "markdown_source": "../docs/how-to-guides/data-basics/README.md", + "parent": "how-to-guides" + }, + { + "title": "Setup", + "slug": "1-data-basics-setup", + "markdown_source": "../docs/how-to-guides/data-basics/1-data-basics-setup.md", + "parent": "data-basics" + }, + { + "title": "Building a list of pages", + "slug": "2-building-a-list-of-pages", + "markdown_source": "../docs/how-to-guides/data-basics/2-building-a-list-of-pages.md", + "parent": "data-basics" + }, + { + "title": "Building an edit form", + "slug": "3-building-an-edit-form", + "markdown_source": "../docs/how-to-guides/data-basics/3-building-an-edit-form.md", + "parent": "data-basics" + }, + { + "title": "Building a Create page form", + "slug": "4-building-a-create-page-form", + "markdown_source": "../docs/how-to-guides/data-basics/4-building-a-create-page-form.md", + "parent": "data-basics" + }, + { + "title": "Adding a delete button", + "slug": "5-adding-a-delete-button", + "markdown_source": "../docs/how-to-guides/data-basics/5-adding-a-delete-button.md", + "parent": "data-basics" + }, + { + "title": "Curating the Editor Experience", + "slug": "curating-the-editor-experience", + "markdown_source": "../docs/how-to-guides/curating-the-editor-experience/README.md", + "parent": "how-to-guides" + }, + { + "title": "Block Locking API", + "slug": "block-locking", + "markdown_source": "../docs/how-to-guides/curating-the-editor-experience/block-locking.md", + "parent": "curating-the-editor-experience" + }, + { + "title": "Patterns", + "slug": "patterns", + "markdown_source": "../docs/how-to-guides/curating-the-editor-experience/patterns.md", + "parent": "curating-the-editor-experience" + }, + { + "title": "theme.json", + "slug": "theme-json", + "markdown_source": "../docs/how-to-guides/curating-the-editor-experience/theme-json.md", + "parent": "curating-the-editor-experience" + }, + { + "title": "Filters and hooks", + "slug": "filters-and-hooks", + "markdown_source": "../docs/how-to-guides/curating-the-editor-experience/filters-and-hooks.md", + "parent": "curating-the-editor-experience" + }, + { + "title": "Disable Editor functionality", + "slug": "disable-editor-functionality", + "markdown_source": "../docs/how-to-guides/curating-the-editor-experience/disable-editor-functionality.md", + "parent": "curating-the-editor-experience" + }, + { + "title": "Enqueueing assets in the Editor", + "slug": "enqueueing-assets-in-the-editor", + "markdown_source": "../docs/how-to-guides/enqueueing-assets-in-the-editor.md", + "parent": "how-to-guides" + }, + { + "title": "Feature Flags", + "slug": "feature-flags", + "markdown_source": "../docs/how-to-guides/feature-flags.md", + "parent": "how-to-guides" + }, + { + "title": "Formatting Toolbar API", + "slug": "format-api", + "markdown_source": "../docs/how-to-guides/format-api.md", + "parent": "how-to-guides" + }, + { + "title": "Internationalization", + "slug": "internationalization", + "markdown_source": "../docs/how-to-guides/internationalization.md", + "parent": "how-to-guides" + }, + { + "title": "Meta Boxes", + "slug": "metabox", + "markdown_source": "../docs/how-to-guides/metabox.md", + "parent": "how-to-guides" + }, + { + "title": "Notices", + "slug": "notices", + "markdown_source": "../docs/how-to-guides/notices/README.md", + "parent": "how-to-guides" + }, + { + "title": "Plugin Sidebar", + "slug": "plugin-sidebar-0", + "markdown_source": "../docs/how-to-guides/plugin-sidebar-0.md", + "parent": "how-to-guides" + }, + { + "title": "Propagating updates for block types", + "slug": "propagating-updates", + "markdown_source": "../docs/how-to-guides/propagating-updates.md", + "parent": "how-to-guides" + }, + { + "title": "Themes", + "slug": "themes", + "markdown_source": "../docs/how-to-guides/themes/README.md", + "parent": "how-to-guides" + }, + { + "title": "Global Settings & Styles (theme.json)", + "slug": "global-settings-and-styles", + "markdown_source": "../docs/how-to-guides/themes/global-settings-and-styles.md", + "parent": "themes" + }, + { + "title": "Theme Support", + "slug": "theme-support", + "markdown_source": "../docs/how-to-guides/themes/theme-support.md", + "parent": "themes" + }, + { + "title": "Thunks in Core-Data", + "slug": "thunks", + "markdown_source": "../docs/how-to-guides/thunks.md", + "parent": "how-to-guides" + }, + { + "title": "Widgets", + "slug": "widgets", + "markdown_source": "../docs/how-to-guides/widgets/README.md", + "parent": "how-to-guides" + }, + { + "title": "Widgets Block Editor overview", + "slug": "overview", + "markdown_source": "../docs/how-to-guides/widgets/overview.md", + "parent": "widgets" + }, + { + "title": "Restoring the classic Widgets Editor", + "slug": "opting-out", + "markdown_source": "../docs/how-to-guides/widgets/opting-out.md", + "parent": "widgets" + }, + { + "title": "About the Legacy Widget block", + "slug": "legacy-widget-block", + "markdown_source": "../docs/how-to-guides/widgets/legacy-widget-block.md", + "parent": "widgets" + }, + { + "title": "Reference Guides", + "slug": "reference-guides", + "markdown_source": "../docs/reference-guides/README.md", + "parent": null + }, + { + "title": "Block API Reference", + "slug": "block-api", + "markdown_source": "../docs/reference-guides/block-api/README.md", + "parent": "reference-guides" + }, + { + "title": "Annotations", + "slug": "block-annotations", + "markdown_source": "../docs/reference-guides/block-api/block-annotations.md", + "parent": "block-api" + }, + { + "title": "API Versions", + "slug": "block-api-versions", + "markdown_source": "../docs/reference-guides/block-api/block-api-versions.md", + "parent": "block-api" + }, + { + "title": "Attributes", + "slug": "block-attributes", + "markdown_source": "../docs/reference-guides/block-api/block-attributes.md", + "parent": "block-api" + }, + { + "title": "Bindings", + "slug": "block-bindings", + "markdown_source": "../docs/reference-guides/block-api/block-bindings.md", + "parent": "block-api" + }, + { + "title": "Context", + "slug": "block-context", + "markdown_source": "../docs/reference-guides/block-api/block-context.md", + "parent": "block-api" + }, + { + "title": "Deprecation", + "slug": "block-deprecation", + "markdown_source": "../docs/reference-guides/block-api/block-deprecation.md", + "parent": "block-api" + }, + { + "title": "Edit and Save", + "slug": "block-edit-save", + "markdown_source": "../docs/reference-guides/block-api/block-edit-save.md", + "parent": "block-api" + }, + { + "title": "Metadata in block.json", + "slug": "block-metadata", + "markdown_source": "../docs/reference-guides/block-api/block-metadata.md", + "parent": "block-api" + }, + { + "title": "Patterns", + "slug": "block-patterns", + "markdown_source": "../docs/reference-guides/block-api/block-patterns.md", + "parent": "block-api" + }, + { + "title": "Registration", + "slug": "block-registration", + "markdown_source": "../docs/reference-guides/block-api/block-registration.md", + "parent": "block-api" + }, + { + "title": "Selectors", + "slug": "block-selectors", + "markdown_source": "../docs/reference-guides/block-api/block-selectors.md", + "parent": "block-api" + }, + { + "title": "Styles", + "slug": "block-styles", + "markdown_source": "../docs/reference-guides/block-api/block-styles.md", + "parent": "block-api" + }, + { + "title": "Supports", + "slug": "block-supports", + "markdown_source": "../docs/reference-guides/block-api/block-supports.md", + "parent": "block-api" + }, + { + "title": "Templates", + "slug": "block-templates", + "markdown_source": "../docs/reference-guides/block-api/block-templates.md", + "parent": "block-api" + }, + { + "title": "Transforms", + "slug": "block-transforms", + "markdown_source": "../docs/reference-guides/block-api/block-transforms.md", + "parent": "block-api" + }, + { + "title": "Variations", + "slug": "block-variations", + "markdown_source": "../docs/reference-guides/block-api/block-variations.md", + "parent": "block-api" + }, + { + "title": "Core Blocks Reference", + "slug": "core-blocks", + "markdown_source": "../docs/reference-guides/core-blocks.md", + "parent": "reference-guides" + }, + { + "title": "Hooks Reference", + "slug": "filters", + "markdown_source": "../docs/reference-guides/filters/README.md", + "parent": "reference-guides" + }, + { + "title": "Block Filters", + "slug": "block-filters", + "markdown_source": "../docs/reference-guides/filters/block-filters.md", + "parent": "filters" + }, + { + "title": "Editor Hooks", + "slug": "editor-filters", + "markdown_source": "../docs/reference-guides/filters/editor-filters.md", + "parent": "filters" + }, + { + "title": "i18n Filters", + "slug": "i18n-filters", + "markdown_source": "../docs/reference-guides/filters/i18n-filters.md", + "parent": "filters" + }, + { + "title": "Parser Filters", + "slug": "parser-filters", + "markdown_source": "../docs/reference-guides/filters/parser-filters.md", + "parent": "filters" + }, + { + "title": "Autocomplete", + "slug": "autocomplete-filters", + "markdown_source": "../docs/reference-guides/filters/autocomplete-filters.md", + "parent": "filters" + }, + { + "title": "Global Styles Filters", + "slug": "global-styles-filters", + "markdown_source": "../docs/reference-guides/filters/global-styles-filters.md", + "parent": "filters" + }, + { + "title": "Interactivity API Reference", + "slug": "interactivity-api", + "markdown_source": "../docs/reference-guides/interactivity-api/README.md", + "parent": "reference-guides" + }, + { + "title": "Core Concepts", + "slug": "core-concepts", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/README.md", + "parent": "interactivity-api" + }, + { + "title": "The Reactive and Declarative mindset", + "slug": "the-reactive-and-declarative-mindset", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/the-reactive-and-declarative-mindset.md", + "parent": "core-concepts" + }, + { + "title": "Understanding global state, local context and derived state", + "slug": "undestanding-global-state-local-context-and-derived-state", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/undestanding-global-state-local-context-and-derived-state.md", + "parent": "core-concepts" + }, + { + "title": "Server-side rendering: Processing directives on the server", + "slug": "server-side-rendering", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/server-side-rendering.md", + "parent": "core-concepts" + }, + { + "title": "Using TypeScript", + "slug": "using-typescript", + "markdown_source": "../docs/reference-guides/interactivity-api/core-concepts/using-typescript.md", + "parent": "core-concepts" + }, + { + "title": "Quick start guide", + "slug": "iapi-quick-start-guide", + "markdown_source": "../docs/reference-guides/interactivity-api/iapi-quick-start-guide.md", + "parent": "interactivity-api" + }, + { + "title": "API Reference", + "slug": "api-reference", + "markdown_source": "../docs/reference-guides/interactivity-api/api-reference.md", + "parent": "interactivity-api" + }, + { + "title": "About the Interactivity API", + "slug": "iapi-about", + "markdown_source": "../docs/reference-guides/interactivity-api/iapi-about.md", + "parent": "interactivity-api" + }, + { + "title": "Frequently Asked Questions", + "slug": "iapi-faq", + "markdown_source": "../docs/reference-guides/interactivity-api/iapi-faq.md", + "parent": "interactivity-api" + }, + { + "title": "SlotFills Reference", + "slug": "slotfills", + "markdown_source": "../docs/reference-guides/slotfills/README.md", + "parent": "reference-guides" + }, + { + "title": "MainDashboardButton", + "slug": "main-dashboard-button", + "markdown_source": "../docs/reference-guides/slotfills/main-dashboard-button.md", + "parent": "slotfills" + }, + { + "title": "PluginBlockSettingsMenuItem", + "slug": "plugin-block-settings-menu-item", + "markdown_source": "../docs/reference-guides/slotfills/plugin-block-settings-menu-item.md", + "parent": "slotfills" + }, + { + "title": "PluginDocumentSettingPanel", + "slug": "plugin-document-setting-panel", + "markdown_source": "../docs/reference-guides/slotfills/plugin-document-setting-panel.md", + "parent": "slotfills" + }, + { + "title": "PluginMoreMenuItem", + "slug": "plugin-more-menu-item", + "markdown_source": "../docs/reference-guides/slotfills/plugin-more-menu-item.md", + "parent": "slotfills" + }, + { + "title": "PluginPostPublishPanel", + "slug": "plugin-post-publish-panel", + "markdown_source": "../docs/reference-guides/slotfills/plugin-post-publish-panel.md", + "parent": "slotfills" + }, + { + "title": "PluginPostStatusInfo", + "slug": "plugin-post-status-info", + "markdown_source": "../docs/reference-guides/slotfills/plugin-post-status-info.md", + "parent": "slotfills" + }, + { + "title": "PluginPrePublishPanel", + "slug": "plugin-pre-publish-panel", + "markdown_source": "../docs/reference-guides/slotfills/plugin-pre-publish-panel.md", + "parent": "slotfills" + }, + { + "title": "PluginSidebar", + "slug": "plugin-sidebar", + "markdown_source": "../docs/reference-guides/slotfills/plugin-sidebar.md", + "parent": "slotfills" + }, + { + "title": "PluginSidebarMoreMenuItem", + "slug": "plugin-sidebar-more-menu-item", + "markdown_source": "../docs/reference-guides/slotfills/plugin-sidebar-more-menu-item.md", + "parent": "slotfills" + }, + { + "title": "RichText Reference", + "slug": "richtext", + "markdown_source": "../docs/reference-guides/richtext.md", + "parent": "reference-guides" + }, + { + "title": "Theme.json Reference", + "slug": "theme-json-reference", + "markdown_source": "../docs/reference-guides/theme-json-reference/README.md", + "parent": "reference-guides" + }, + { + "title": "Theme.json Version 3 Reference (latest)", + "slug": "theme-json-living", + "markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-living.md", + "parent": "theme-json-reference" + }, + { + "title": "Theme.json Version 1 Reference", + "slug": "theme-json-v1", + "markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-v1.md", + "parent": "theme-json-reference" + }, + { + "title": "Theme.json Version 2 Reference", + "slug": "theme-json-v2", + "markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-v2.md", + "parent": "theme-json-reference" + }, + { + "title": "Migrating Theme.json to Newer Versions", + "slug": "theme-json-migrations", + "markdown_source": "../docs/reference-guides/theme-json-reference/theme-json-migrations.md", + "parent": "theme-json-reference" + }, + { + "title": "Available Styles Options", + "slug": "styles-versions", + "markdown_source": "../docs/reference-guides/theme-json-reference/styles-versions.md", + "parent": "theme-json-reference" + }, + { + "title": "Component Reference", + "slug": "components", + "markdown_source": "../packages/components/README.md", + "parent": "reference-guides" + }, + { + "title": "AlignmentMatrixControl", + "slug": "alignment-matrix-control", + "markdown_source": "../packages/components/src/alignment-matrix-control/README.md", + "parent": "components" + }, + { + "title": "AnglePickerControl", + "slug": "angle-picker-control", + "markdown_source": "../packages/components/src/angle-picker-control/README.md", + "parent": "components" + }, + { + "title": "Animate", + "slug": "animate", + "markdown_source": "../packages/components/src/animate/README.md", + "parent": "components" + }, + { + "title": "Autocomplete", + "slug": "autocomplete", + "markdown_source": "../packages/components/src/autocomplete/README.md", + "parent": "components" + }, + { + "title": "BaseControl", + "slug": "base-control", + "markdown_source": "../packages/components/src/base-control/README.md", + "parent": "components" + }, + { + "title": "BorderBoxControl", + "slug": "border-box-control", + "markdown_source": "../packages/components/src/border-box-control/border-box-control/README.md", + "parent": "components" + }, + { + "title": "BorderControl", + "slug": "border-control", + "markdown_source": "../packages/components/src/border-control/border-control/README.md", + "parent": "components" + }, + { + "title": "BoxControl", + "slug": "box-control", + "markdown_source": "../packages/components/src/box-control/README.md", + "parent": "components" + }, + { + "title": "ButtonGroup", + "slug": "button-group", + "markdown_source": "../packages/components/src/button-group/README.md", + "parent": "components" + }, + { + "title": "Button", + "slug": "button", + "markdown_source": "../packages/components/src/button/README.md", + "parent": "components" + }, + { + "title": "DateCalendar", + "slug": "date-calendar", + "markdown_source": "../packages/components/src/calendar/date-calendar/README.md", + "parent": "components" + }, + { + "title": "DateRangeCalendar", + "slug": "date-range-calendar", + "markdown_source": "../packages/components/src/calendar/date-range-calendar/README.md", + "parent": "components" + }, + { + "title": "CardBody", + "slug": "card-body", + "markdown_source": "../packages/components/src/card/card-body/README.md", + "parent": "components" + }, + { + "title": "CardDivider", + "slug": "card-divider", + "markdown_source": "../packages/components/src/card/card-divider/README.md", + "parent": "components" + }, + { + "title": "CardFooter", + "slug": "card-footer", + "markdown_source": "../packages/components/src/card/card-footer/README.md", + "parent": "components" + }, + { + "title": "CardHeader", + "slug": "card-header", + "markdown_source": "../packages/components/src/card/card-header/README.md", + "parent": "components" + }, + { + "title": "CardMedia", + "slug": "card-media", + "markdown_source": "../packages/components/src/card/card-media/README.md", + "parent": "components" + }, + { + "title": "Card", + "slug": "card", + "markdown_source": "../packages/components/src/card/card/README.md", + "parent": "components" + }, + { + "title": "CheckboxControl", + "slug": "checkbox-control", + "markdown_source": "../packages/components/src/checkbox-control/README.md", + "parent": "components" + }, + { + "title": "CircularOptionPicker", + "slug": "circular-option-picker", + "markdown_source": "../packages/components/src/circular-option-picker/README.md", + "parent": "components" + }, + { + "title": "ClipboardButton", + "slug": "clipboard-button", + "markdown_source": "../packages/components/src/clipboard-button/README.md", + "parent": "components" + }, + { + "title": "ColorIndicator", + "slug": "color-indicator", + "markdown_source": "../packages/components/src/color-indicator/README.md", + "parent": "components" + }, + { + "title": "ColorPalette", + "slug": "color-palette", + "markdown_source": "../packages/components/src/color-palette/README.md", + "parent": "components" + }, + { + "title": "ColorPicker", + "slug": "color-picker", + "markdown_source": "../packages/components/src/color-picker/README.md", + "parent": "components" + }, + { + "title": "ComboboxControl", + "slug": "combobox-control", + "markdown_source": "../packages/components/src/combobox-control/README.md", + "parent": "components" + }, + { + "title": "Composite", + "slug": "composite", + "markdown_source": "../packages/components/src/composite/README.md", + "parent": "components" + }, + { + "title": "ConfirmDialog", + "slug": "confirm-dialog", + "markdown_source": "../packages/components/src/confirm-dialog/README.md", + "parent": "components" + }, + { + "title": "CustomSelectControl", + "slug": "custom-select-control", + "markdown_source": "../packages/components/src/custom-select-control/README.md", + "parent": "components" + }, + { + "title": "Dashicon", + "slug": "dashicon", + "markdown_source": "../packages/components/src/dashicon/README.md", + "parent": "components" + }, + { + "title": "DateTime", + "slug": "date-time", + "markdown_source": "../packages/components/src/date-time/README.md", + "parent": "components" + }, + { + "title": "DimensionControl", + "slug": "dimension-control", + "markdown_source": "../packages/components/src/dimension-control/README.md", + "parent": "components" + }, + { + "title": "Disabled", + "slug": "disabled", + "markdown_source": "../packages/components/src/disabled/README.md", + "parent": "components" + }, + { + "title": "Divider", + "slug": "divider", + "markdown_source": "../packages/components/src/divider/README.md", + "parent": "components" + }, + { + "title": "Draggable", + "slug": "draggable", + "markdown_source": "../packages/components/src/draggable/README.md", + "parent": "components" + }, + { + "title": "DropZone", + "slug": "drop-zone", + "markdown_source": "../packages/components/src/drop-zone/README.md", + "parent": "components" + }, + { + "title": "DropdownMenu", + "slug": "dropdown-menu", + "markdown_source": "../packages/components/src/dropdown-menu/README.md", + "parent": "components" + }, + { + "title": "Dropdown", + "slug": "dropdown", + "markdown_source": "../packages/components/src/dropdown/README.md", + "parent": "components" + }, + { + "title": "DuotonePicker", + "slug": "duotone-picker", + "markdown_source": "../packages/components/src/duotone-picker/README.md", + "parent": "components" + }, + { + "title": "Elevation", + "slug": "elevation", + "markdown_source": "../packages/components/src/elevation/README.md", + "parent": "components" + }, + { + "title": "ExternalLink", + "slug": "external-link", + "markdown_source": "../packages/components/src/external-link/README.md", + "parent": "components" + }, + { + "title": "FlexBlock", + "slug": "flex-block", + "markdown_source": "../packages/components/src/flex/flex-block/README.md", + "parent": "components" + }, + { + "title": "FlexItem", + "slug": "flex-item", + "markdown_source": "../packages/components/src/flex/flex-item/README.md", + "parent": "components" + }, + { + "title": "Flex", + "slug": "flex", + "markdown_source": "../packages/components/src/flex/flex/README.md", + "parent": "components" + }, + { + "title": "FocalPointPicker", + "slug": "focal-point-picker", + "markdown_source": "../packages/components/src/focal-point-picker/README.md", + "parent": "components" + }, + { + "title": "FocusableIframe", + "slug": "focusable-iframe", + "markdown_source": "../packages/components/src/focusable-iframe/README.md", + "parent": "components" + }, + { + "title": "FontSizePicker", + "slug": "font-size-picker", + "markdown_source": "../packages/components/src/font-size-picker/README.md", + "parent": "components" + }, + { + "title": "FormFileUpload", + "slug": "form-file-upload", + "markdown_source": "../packages/components/src/form-file-upload/README.md", + "parent": "components" + }, + { + "title": "FormToggle", + "slug": "form-toggle", + "markdown_source": "../packages/components/src/form-toggle/README.md", + "parent": "components" + }, + { + "title": "FormTokenField", + "slug": "form-token-field", + "markdown_source": "../packages/components/src/form-token-field/README.md", + "parent": "components" + }, + { + "title": "GradientPicker", + "slug": "gradient-picker", + "markdown_source": "../packages/components/src/gradient-picker/README.md", + "parent": "components" + }, + { + "title": "Grid", + "slug": "grid", + "markdown_source": "../packages/components/src/grid/README.md", + "parent": "components" + }, + { + "title": "Guide", + "slug": "guide", + "markdown_source": "../packages/components/src/guide/README.md", + "parent": "components" + }, + { + "title": "HStack", + "slug": "h-stack", + "markdown_source": "../packages/components/src/h-stack/README.md", + "parent": "components" + }, + { + "title": "Heading", + "slug": "heading", + "markdown_source": "../packages/components/src/heading/README.md", + "parent": "components" + }, + { + "title": "NavigateRegions", + "slug": "navigate-regions", + "markdown_source": "../packages/components/src/higher-order/navigate-regions/README.md", + "parent": "components" + }, + { + "title": "HigherOrder", + "slug": "higher-order", + "markdown_source": "../packages/components/src/higher-order/README.md", + "parent": "components" + }, + { + "title": "WithConstrainedTabbing", + "slug": "with-constrained-tabbing", + "markdown_source": "../packages/components/src/higher-order/with-constrained-tabbing/README.md", + "parent": "components" + }, + { + "title": "WithFallbackStyles", + "slug": "with-fallback-styles", + "markdown_source": "../packages/components/src/higher-order/with-fallback-styles/README.md", + "parent": "components" + }, + { + "title": "WithFilters", + "slug": "with-filters", + "markdown_source": "../packages/components/src/higher-order/with-filters/README.md", + "parent": "components" + }, + { + "title": "WithFocusOutside", + "slug": "with-focus-outside", + "markdown_source": "../packages/components/src/higher-order/with-focus-outside/README.md", + "parent": "components" + }, + { + "title": "WithFocusReturn", + "slug": "with-focus-return", + "markdown_source": "../packages/components/src/higher-order/with-focus-return/README.md", + "parent": "components" + }, + { + "title": "WithNotices", + "slug": "with-notices", + "markdown_source": "../packages/components/src/higher-order/with-notices/README.md", + "parent": "components" + }, + { + "title": "WithSpokenMessages", + "slug": "with-spoken-messages", + "markdown_source": "../packages/components/src/higher-order/with-spoken-messages/README.md", + "parent": "components" + }, + { + "title": "Icon", + "slug": "icon", + "markdown_source": "../packages/components/src/icon/README.md", + "parent": "components" + }, + { + "title": "InputControl", + "slug": "input-control", + "markdown_source": "../packages/components/src/input-control/README.md", + "parent": "components" + }, + { + "title": "IsolatedEventContainer", + "slug": "isolated-event-container", + "markdown_source": "../packages/components/src/isolated-event-container/README.md", + "parent": "components" + }, + { + "title": "ItemGroup", + "slug": "item-group", + "markdown_source": "../packages/components/src/item-group/item-group/README.md", + "parent": "components" + }, + { + "title": "Item", + "slug": "item", + "markdown_source": "../packages/components/src/item-group/item/README.md", + "parent": "components" + }, + { + "title": "KeyboardShortcuts", + "slug": "keyboard-shortcuts", + "markdown_source": "../packages/components/src/keyboard-shortcuts/README.md", + "parent": "components" + }, + { + "title": "MenuGroup", + "slug": "menu-group", + "markdown_source": "../packages/components/src/menu-group/README.md", + "parent": "components" + }, + { + "title": "MenuItem", + "slug": "menu-item", + "markdown_source": "../packages/components/src/menu-item/README.md", + "parent": "components" + }, + { + "title": "MenuItemsChoice", + "slug": "menu-items-choice", + "markdown_source": "../packages/components/src/menu-items-choice/README.md", + "parent": "components" + }, + { + "title": "Modal", + "slug": "modal", + "markdown_source": "../packages/components/src/modal/README.md", + "parent": "components" + }, + { + "title": "NavigableContainer", + "slug": "navigable-container", + "markdown_source": "../packages/components/src/navigable-container/README.md", + "parent": "components" + }, + { + "title": "Navigation", + "slug": "navigation", + "markdown_source": "../packages/components/src/navigation/README.md", + "parent": "components" + }, + { + "title": "Navigator", + "slug": "navigator", + "markdown_source": "../packages/components/src/navigator/README.md", + "parent": "components" + }, + { + "title": "Notice", + "slug": "notice", + "markdown_source": "../packages/components/src/notice/README.md", + "parent": "components" + }, + { + "title": "NumberControl", + "slug": "number-control", + "markdown_source": "../packages/components/src/number-control/README.md", + "parent": "components" + }, + { + "title": "Panel", + "slug": "panel", + "markdown_source": "../packages/components/src/panel/README.md", + "parent": "components" + }, + { + "title": "Placeholder", + "slug": "placeholder", + "markdown_source": "../packages/components/src/placeholder/README.md", + "parent": "components" + }, + { + "title": "Popover", + "slug": "popover", + "markdown_source": "../packages/components/src/popover/README.md", + "parent": "components" + }, + { + "title": "ProgressBar", + "slug": "progress-bar", + "markdown_source": "../packages/components/src/progress-bar/README.md", + "parent": "components" + }, + { + "title": "QueryControls", + "slug": "query-controls", + "markdown_source": "../packages/components/src/query-controls/README.md", + "parent": "components" + }, + { + "title": "RadioControl", + "slug": "radio-control", + "markdown_source": "../packages/components/src/radio-control/README.md", + "parent": "components" + }, + { + "title": "RadioGroup", + "slug": "radio-group", + "markdown_source": "../packages/components/src/radio-group/README.md", + "parent": "components" + }, + { + "title": "RangeControl", + "slug": "range-control", + "markdown_source": "../packages/components/src/range-control/README.md", + "parent": "components" + }, + { + "title": "ResizableBox", + "slug": "resizable-box", + "markdown_source": "../packages/components/src/resizable-box/README.md", + "parent": "components" + }, + { + "title": "ResizeTooltip", + "slug": "resize-tooltip", + "markdown_source": "../packages/components/src/resizable-box/resize-tooltip/README.md", + "parent": "components" + }, + { + "title": "ResponsiveWrapper", + "slug": "responsive-wrapper", + "markdown_source": "../packages/components/src/responsive-wrapper/README.md", + "parent": "components" + }, + { + "title": "Sandbox", + "slug": "sandbox", + "markdown_source": "../packages/components/src/sandbox/README.md", + "parent": "components" + }, + { + "title": "ScrollLock", + "slug": "scroll-lock", + "markdown_source": "../packages/components/src/scroll-lock/README.md", + "parent": "components" + }, + { + "title": "Scrollable", + "slug": "scrollable", + "markdown_source": "../packages/components/src/scrollable/README.md", + "parent": "components" + }, + { + "title": "SearchControl", + "slug": "search-control", + "markdown_source": "../packages/components/src/search-control/README.md", + "parent": "components" + }, + { + "title": "SelectControl", + "slug": "select-control", + "markdown_source": "../packages/components/src/select-control/README.md", + "parent": "components" + }, + { + "title": "SlotFill", + "slug": "slot-fill", + "markdown_source": "../packages/components/src/slot-fill/README.md", + "parent": "components" + }, + { + "title": "Snackbar", + "slug": "snackbar", + "markdown_source": "../packages/components/src/snackbar/README.md", + "parent": "components" + }, + { + "title": "Spacer", + "slug": "spacer", + "markdown_source": "../packages/components/src/spacer/README.md", + "parent": "components" + }, + { + "title": "Spinner", + "slug": "spinner", + "markdown_source": "../packages/components/src/spinner/README.md", + "parent": "components" + }, + { + "title": "Surface", + "slug": "surface", + "markdown_source": "../packages/components/src/surface/README.md", + "parent": "components" + }, + { + "title": "TabPanel", + "slug": "tab-panel", + "markdown_source": "../packages/components/src/tab-panel/README.md", + "parent": "components" + }, + { + "title": "TextControl", + "slug": "text-control", + "markdown_source": "../packages/components/src/text-control/README.md", + "parent": "components" + }, + { + "title": "TextHighlight", + "slug": "text-highlight", + "markdown_source": "../packages/components/src/text-highlight/README.md", + "parent": "components" + }, + { + "title": "Text", + "slug": "text", + "markdown_source": "../packages/components/src/text/README.md", + "parent": "components" + }, + { + "title": "TextareaControl", + "slug": "textarea-control", + "markdown_source": "../packages/components/src/textarea-control/README.md", + "parent": "components" + }, + { + "title": "ToggleControl", + "slug": "toggle-control", + "markdown_source": "../packages/components/src/toggle-control/README.md", + "parent": "components" + }, + { + "title": "ToggleGroupControlOptionBase", + "slug": "toggle-group-control-option-base", + "markdown_source": "../packages/components/src/toggle-group-control/toggle-group-control-option-base/README.md", + "parent": "components" + }, + { + "title": "ToggleGroupControlOptionIcon", + "slug": "toggle-group-control-option-icon", + "markdown_source": "../packages/components/src/toggle-group-control/toggle-group-control-option-icon/README.md", + "parent": "components" + }, + { + "title": "ToggleGroupControlOption", + "slug": "toggle-group-control-option", + "markdown_source": "../packages/components/src/toggle-group-control/toggle-group-control-option/README.md", + "parent": "components" + }, + { + "title": "ToggleGroupControl", + "slug": "toggle-group-control", + "markdown_source": "../packages/components/src/toggle-group-control/toggle-group-control/README.md", + "parent": "components" + }, + { + "title": "ToolbarButton", + "slug": "toolbar-button", + "markdown_source": "../packages/components/src/toolbar/toolbar-button/README.md", + "parent": "components" + }, + { + "title": "ToolbarDropdownMenu", + "slug": "toolbar-dropdown-menu", + "markdown_source": "../packages/components/src/toolbar/toolbar-dropdown-menu/README.md", + "parent": "components" + }, + { + "title": "ToolbarGroup", + "slug": "toolbar-group", + "markdown_source": "../packages/components/src/toolbar/toolbar-group/README.md", + "parent": "components" + }, + { + "title": "ToolbarItem", + "slug": "toolbar-item", + "markdown_source": "../packages/components/src/toolbar/toolbar-item/README.md", + "parent": "components" + }, + { + "title": "Toolbar", + "slug": "toolbar", + "markdown_source": "../packages/components/src/toolbar/toolbar/README.md", + "parent": "components" + }, + { + "title": "ToolsPanelHeader", + "slug": "tools-panel-header", + "markdown_source": "../packages/components/src/tools-panel/tools-panel-header/README.md", + "parent": "components" + }, + { + "title": "ToolsPanelItem", + "slug": "tools-panel-item", + "markdown_source": "../packages/components/src/tools-panel/tools-panel-item/README.md", + "parent": "components" + }, + { + "title": "ToolsPanel", + "slug": "tools-panel", + "markdown_source": "../packages/components/src/tools-panel/tools-panel/README.md", + "parent": "components" + }, + { + "title": "Tooltip", + "slug": "tooltip", + "markdown_source": "../packages/components/src/tooltip/README.md", + "parent": "components" + }, + { + "title": "TreeGrid", + "slug": "tree-grid", + "markdown_source": "../packages/components/src/tree-grid/README.md", + "parent": "components" + }, + { + "title": "TreeSelect", + "slug": "tree-select", + "markdown_source": "../packages/components/src/tree-select/README.md", + "parent": "components" + }, + { + "title": "Truncate", + "slug": "truncate", + "markdown_source": "../packages/components/src/truncate/README.md", + "parent": "components" + }, + { + "title": "UnitControl", + "slug": "unit-control", + "markdown_source": "../packages/components/src/unit-control/README.md", + "parent": "components" + }, + { + "title": "VStack", + "slug": "v-stack", + "markdown_source": "../packages/components/src/v-stack/README.md", + "parent": "components" + }, + { + "title": "VisuallyHidden", + "slug": "visually-hidden", + "markdown_source": "../packages/components/src/visually-hidden/README.md", + "parent": "components" + }, + { + "title": "ZStack", + "slug": "z-stack", + "markdown_source": "../packages/components/src/z-stack/README.md", + "parent": "components" + }, + { + "title": "Package Reference", + "slug": "packages", + "markdown_source": "../docs/reference-guides/packages.md", + "parent": "reference-guides" + }, + { + "title": "@wordpress/a11y", + "slug": "packages-a11y", + "markdown_source": "../packages/a11y/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/admin-ui", + "slug": "packages-admin-ui", + "markdown_source": "../packages/admin-ui/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/annotations", + "slug": "packages-annotations", + "markdown_source": "../packages/annotations/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/api-fetch", + "slug": "packages-api-fetch", + "markdown_source": "../packages/api-fetch/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/autop", + "slug": "packages-autop", + "markdown_source": "../packages/autop/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/babel-plugin-import-jsx-pragma", + "slug": "packages-babel-plugin-import-jsx-pragma", + "markdown_source": "../packages/babel-plugin-import-jsx-pragma/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/babel-plugin-makepot", + "slug": "packages-babel-plugin-makepot", + "markdown_source": "../packages/babel-plugin-makepot/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/babel-preset-default", + "slug": "packages-babel-preset-default", + "markdown_source": "../packages/babel-preset-default/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/base-styles", + "slug": "packages-base-styles", + "markdown_source": "../packages/base-styles/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/blob", + "slug": "packages-blob", + "markdown_source": "../packages/blob/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/block-directory", + "slug": "packages-block-directory", + "markdown_source": "../packages/block-directory/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/block-editor", + "slug": "packages-block-editor", + "markdown_source": "../packages/block-editor/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/block-library", + "slug": "packages-block-library", + "markdown_source": "../packages/block-library/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/block-serialization-default-parser", + "slug": "packages-block-serialization-default-parser", + "markdown_source": "../packages/block-serialization-default-parser/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/block-serialization-spec-parser", + "slug": "packages-block-serialization-spec-parser", + "markdown_source": "../packages/block-serialization-spec-parser/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/blocks", + "slug": "packages-blocks", + "markdown_source": "../packages/blocks/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/browserslist-config", + "slug": "packages-browserslist-config", + "markdown_source": "../packages/browserslist-config/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/commands", + "slug": "packages-commands", + "markdown_source": "../packages/commands/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/components", + "slug": "packages-components", + "markdown_source": "../packages/components/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/compose", + "slug": "packages-compose", + "markdown_source": "../packages/compose/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/core-commands", + "slug": "packages-core-commands", + "markdown_source": "../packages/core-commands/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/core-data", + "slug": "packages-core-data", + "markdown_source": "../packages/core-data/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/create-block-interactive-template", + "slug": "packages-create-block-interactive-template", + "markdown_source": "../packages/create-block-interactive-template/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/create-block-tutorial-template", + "slug": "packages-create-block-tutorial-template", + "markdown_source": "../packages/create-block-tutorial-template/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/create-block", + "slug": "packages-create-block", + "markdown_source": "../packages/create-block/README.md", + "parent": "packages" + }, + { + "title": "External Project Templates", + "slug": "packages-create-block-external-template", + "markdown_source": "../packages/create-block/docs/external-template.md", + "parent": "packages-create-block" + }, + { + "title": "@wordpress/customize-widgets", + "slug": "packages-customize-widgets", + "markdown_source": "../packages/customize-widgets/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/data-controls", + "slug": "packages-data-controls", + "markdown_source": "../packages/data-controls/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/data", + "slug": "packages-data", + "markdown_source": "../packages/data/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/dataviews", + "slug": "packages-dataviews", + "markdown_source": "../packages/dataviews/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/date", + "slug": "packages-date", + "markdown_source": "../packages/date/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/dependency-extraction-webpack-plugin", + "slug": "packages-dependency-extraction-webpack-plugin", + "markdown_source": "../packages/dependency-extraction-webpack-plugin/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/deprecated", + "slug": "packages-deprecated", + "markdown_source": "../packages/deprecated/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/docgen", + "slug": "packages-docgen", + "markdown_source": "../packages/docgen/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/dom-ready", + "slug": "packages-dom-ready", + "markdown_source": "../packages/dom-ready/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/dom", + "slug": "packages-dom", + "markdown_source": "../packages/dom/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/e2e-test-utils-playwright", + "slug": "packages-e2e-test-utils-playwright", + "markdown_source": "../packages/e2e-test-utils-playwright/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/e2e-test-utils", + "slug": "packages-e2e-test-utils", + "markdown_source": "../packages/e2e-test-utils/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/e2e-tests", + "slug": "packages-e2e-tests", + "markdown_source": "../packages/e2e-tests/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/edit-post", + "slug": "packages-edit-post", + "markdown_source": "../packages/edit-post/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/edit-site", + "slug": "packages-edit-site", + "markdown_source": "../packages/edit-site/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/edit-widgets", + "slug": "packages-edit-widgets", + "markdown_source": "../packages/edit-widgets/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/editor", + "slug": "packages-editor", + "markdown_source": "../packages/editor/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/element", + "slug": "packages-element", + "markdown_source": "../packages/element/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/env", + "slug": "packages-env", + "markdown_source": "../packages/env/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/escape-html", + "slug": "packages-escape-html", + "markdown_source": "../packages/escape-html/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/eslint-plugin", + "slug": "packages-eslint-plugin", + "markdown_source": "../packages/eslint-plugin/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/fields", + "slug": "packages-fields", + "markdown_source": "../packages/fields/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/format-library", + "slug": "packages-format-library", + "markdown_source": "../packages/format-library/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/hooks", + "slug": "packages-hooks", + "markdown_source": "../packages/hooks/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/html-entities", + "slug": "packages-html-entities", + "markdown_source": "../packages/html-entities/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/i18n", + "slug": "packages-i18n", + "markdown_source": "../packages/i18n/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/icons", + "slug": "packages-icons", + "markdown_source": "../packages/icons/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/interactivity-router", + "slug": "packages-interactivity-router", + "markdown_source": "../packages/interactivity-router/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/interactivity", + "slug": "packages-interactivity", + "markdown_source": "../packages/interactivity/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/interface", + "slug": "packages-interface", + "markdown_source": "../packages/interface/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/is-shallow-equal", + "slug": "packages-is-shallow-equal", + "markdown_source": "../packages/is-shallow-equal/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/jest-console", + "slug": "packages-jest-console", + "markdown_source": "../packages/jest-console/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/jest-preset-default", + "slug": "packages-jest-preset-default", + "markdown_source": "../packages/jest-preset-default/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/jest-puppeteer-axe", + "slug": "packages-jest-puppeteer-axe", + "markdown_source": "../packages/jest-puppeteer-axe/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/keyboard-shortcuts", + "slug": "packages-keyboard-shortcuts", + "markdown_source": "../packages/keyboard-shortcuts/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/keycodes", + "slug": "packages-keycodes", + "markdown_source": "../packages/keycodes/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/latex-to-mathml", + "slug": "packages-latex-to-mathml", + "markdown_source": "../packages/latex-to-mathml/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/lazy-import", + "slug": "packages-lazy-import", + "markdown_source": "../packages/lazy-import/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/list-reusable-blocks", + "slug": "packages-list-reusable-blocks", + "markdown_source": "../packages/list-reusable-blocks/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/media-utils", + "slug": "packages-media-utils", + "markdown_source": "../packages/media-utils/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/notices", + "slug": "packages-notices", + "markdown_source": "../packages/notices/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/npm-package-json-lint-config", + "slug": "packages-npm-package-json-lint-config", + "markdown_source": "../packages/npm-package-json-lint-config/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/nux", + "slug": "packages-nux", + "markdown_source": "../packages/nux/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/patterns", + "slug": "packages-patterns", + "markdown_source": "../packages/patterns/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/plugins", + "slug": "packages-plugins", + "markdown_source": "../packages/plugins/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/postcss-plugins-preset", + "slug": "packages-postcss-plugins-preset", + "markdown_source": "../packages/postcss-plugins-preset/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/postcss-themes", + "slug": "packages-postcss-themes", + "markdown_source": "../packages/postcss-themes/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/preferences-persistence", + "slug": "packages-preferences-persistence", + "markdown_source": "../packages/preferences-persistence/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/preferences", + "slug": "packages-preferences", + "markdown_source": "../packages/preferences/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/prettier-config", + "slug": "packages-prettier-config", + "markdown_source": "../packages/prettier-config/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/primitives", + "slug": "packages-primitives", + "markdown_source": "../packages/primitives/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/priority-queue", + "slug": "packages-priority-queue", + "markdown_source": "../packages/priority-queue/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/private-apis", + "slug": "packages-private-apis", + "markdown_source": "../packages/private-apis/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/project-management-automation", + "slug": "packages-project-management-automation", + "markdown_source": "../packages/project-management-automation/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/react-i18n", + "slug": "packages-react-i18n", + "markdown_source": "../packages/react-i18n/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/readable-js-assets-webpack-plugin", + "slug": "packages-readable-js-assets-webpack-plugin", + "markdown_source": "../packages/readable-js-assets-webpack-plugin/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/redux-routine", + "slug": "packages-redux-routine", + "markdown_source": "../packages/redux-routine/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/reusable-blocks", + "slug": "packages-reusable-blocks", + "markdown_source": "../packages/reusable-blocks/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/rich-text", + "slug": "packages-rich-text", + "markdown_source": "../packages/rich-text/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/router", + "slug": "packages-router", + "markdown_source": "../packages/router/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/scripts", + "slug": "packages-scripts", + "markdown_source": "../packages/scripts/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/server-side-render", + "slug": "packages-server-side-render", + "markdown_source": "../packages/server-side-render/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/shortcode", + "slug": "packages-shortcode", + "markdown_source": "../packages/shortcode/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/style-engine", + "slug": "packages-style-engine", + "markdown_source": "../packages/style-engine/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/style-engine Using the Style Engine to generate block supports styles", + "slug": "using-the-style-engine-with-block-supports", + "markdown_source": "../packages/style-engine/docs/using-the-style-engine-with-block-supports.md", + "parent": "packages-style-engine" + }, + { + "title": "@wordpress/stylelint-config", + "slug": "packages-stylelint-config", + "markdown_source": "../packages/stylelint-config/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/sync", + "slug": "packages-sync", + "markdown_source": "../packages/sync/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/token-list", + "slug": "packages-token-list", + "markdown_source": "../packages/token-list/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/undo-manager", + "slug": "packages-undo-manager", + "markdown_source": "../packages/undo-manager/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/upload-media", + "slug": "packages-upload-media", + "markdown_source": "../packages/upload-media/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/url", + "slug": "packages-url", + "markdown_source": "../packages/url/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/viewport", + "slug": "packages-viewport", + "markdown_source": "../packages/viewport/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/views", + "slug": "packages-views", + "markdown_source": "../packages/views/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/warning", + "slug": "packages-warning", + "markdown_source": "../packages/warning/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/widgets", + "slug": "packages-widgets", + "markdown_source": "../packages/widgets/README.md", + "parent": "packages" + }, + { + "title": "@wordpress/wordcount", + "slug": "packages-wordcount", + "markdown_source": "../packages/wordcount/README.md", + "parent": "packages" + }, + { + "title": "Data Module Reference", + "slug": "data", + "markdown_source": "../docs/reference-guides/data/README.md", + "parent": "reference-guides" + }, + { + "title": "WordPress Core Data", + "slug": "data-core", + "markdown_source": "../docs/reference-guides/data/data-core.md", + "parent": "data" + }, + { + "title": "Annotations", + "slug": "data-core-annotations", + "markdown_source": "../docs/reference-guides/data/data-core-annotations.md", + "parent": "data" + }, + { + "title": "Block directory", + "slug": "data-core-block-directory", + "markdown_source": "../docs/reference-guides/data/data-core-block-directory.md", + "parent": "data" + }, + { + "title": "The Block Editor’s Data", + "slug": "data-core-block-editor", + "markdown_source": "../docs/reference-guides/data/data-core-block-editor.md", + "parent": "data" + }, + { + "title": "Block Types Data", + "slug": "data-core-blocks", + "markdown_source": "../docs/reference-guides/data/data-core-blocks.md", + "parent": "data" + }, + { + "title": "The Commands Data", + "slug": "data-core-commands", + "markdown_source": "../docs/reference-guides/data/data-core-commands.md", + "parent": "data" + }, + { + "title": "Customize Widgets", + "slug": "data-core-customize-widgets", + "markdown_source": "../docs/reference-guides/data/data-core-customize-widgets.md", + "parent": "data" + }, + { + "title": "The Editor’s UI Data", + "slug": "data-core-edit-post", + "markdown_source": "../docs/reference-guides/data/data-core-edit-post.md", + "parent": "data" + }, + { + "title": "Edit Site", + "slug": "data-core-edit-site", + "markdown_source": "../docs/reference-guides/data/data-core-edit-site.md", + "parent": "data" + }, + { + "title": "Edit Widgets", + "slug": "data-core-edit-widgets", + "markdown_source": "../docs/reference-guides/data/data-core-edit-widgets.md", + "parent": "data" + }, + { + "title": "The Post Editor’s Data", + "slug": "data-core-editor", + "markdown_source": "../docs/reference-guides/data/data-core-editor.md", + "parent": "data" + }, + { + "title": "The Keyboard Shortcuts Data", + "slug": "data-core-keyboard-shortcuts", + "markdown_source": "../docs/reference-guides/data/data-core-keyboard-shortcuts.md", + "parent": "data" + }, + { + "title": "Notices Data", + "slug": "data-core-notices", + "markdown_source": "../docs/reference-guides/data/data-core-notices.md", + "parent": "data" + }, + { + "title": "The NUX (New User Experience) Data", + "slug": "data-core-nux", + "markdown_source": "../docs/reference-guides/data/data-core-nux.md", + "parent": "data" + }, + { + "title": "Preferences", + "slug": "data-core-preferences", + "markdown_source": "../docs/reference-guides/data/data-core-preferences.md", + "parent": "data" + }, + { + "title": "Reusable blocks", + "slug": "data-core-reusable-blocks", + "markdown_source": "../docs/reference-guides/data/data-core-reusable-blocks.md", + "parent": "data" + }, + { + "title": "Rich Text", + "slug": "data-core-rich-text", + "markdown_source": "../docs/reference-guides/data/data-core-rich-text.md", + "parent": "data" + }, + { + "title": "The Viewport Data", + "slug": "data-core-viewport", + "markdown_source": "../docs/reference-guides/data/data-core-viewport.md", + "parent": "data" + }, + { + "title": "Explanations", + "slug": "explanations", + "markdown_source": "../docs/explanations/README.md", + "parent": null + }, + { + "title": "Architecture", + "slug": "architecture", + "markdown_source": "../docs/explanations/architecture/README.md", + "parent": "explanations" + }, + { + "title": "Key Concepts", + "slug": "key-concepts", + "markdown_source": "../docs/explanations/architecture/key-concepts.md", + "parent": "architecture" + }, + { + "title": "Data Flow and Data Format", + "slug": "data-flow", + "markdown_source": "../docs/explanations/architecture/data-flow.md", + "parent": "architecture" + }, + { + "title": "Entities and Undo/Redo", + "slug": "entities", + "markdown_source": "../docs/explanations/architecture/entities.md", + "parent": "architecture" + }, + { + "title": "Modularity", + "slug": "modularity", + "markdown_source": "../docs/explanations/architecture/modularity.md", + "parent": "architecture" + }, + { + "title": "Performance", + "slug": "performance", + "markdown_source": "../docs/explanations/architecture/performance.md", + "parent": "architecture" + }, + { + "title": "Automated Testing", + "slug": "automated-testing", + "markdown_source": "../docs/explanations/architecture/automated-testing.md", + "parent": "architecture" + }, + { + "title": "Site Editing Templates", + "slug": "full-site-editing-templates", + "markdown_source": "../docs/explanations/architecture/full-site-editing-templates.md", + "parent": "architecture" + }, + { + "title": "Styles in the Editor", + "slug": "styles", + "markdown_source": "../docs/explanations/architecture/styles.md", + "parent": "architecture" + }, + { + "title": "User Interface", + "slug": "user-interface", + "markdown_source": "../docs/explanations/user-interface/README.md", + "parent": "explanations" + }, + { + "title": "Block Design", + "slug": "block-design", + "markdown_source": "../docs/explanations/user-interface/block-design.md", + "parent": "user-interface" + }, + { + "title": "Animation", + "slug": "animation", + "markdown_source": "../docs/explanations/user-interface/animation.md", + "parent": "user-interface" + }, + { + "title": "Resources", + "slug": "design-resources", + "markdown_source": "../docs/explanations/user-interface/design-resources.md", + "parent": "user-interface" + }, + { + "title": "History", + "slug": "history", + "markdown_source": "../docs/explanations/history.md", + "parent": "explanations" + }, + { + "title": "Contributor Guide", + "slug": "contributors", + "markdown_source": "../docs/contributors/README.md", + "parent": null + }, + { + "title": "Code Contributions", + "slug": "code", + "markdown_source": "../docs/contributors/code/README.md", + "parent": "contributors" + }, + { + "title": "Getting Started With Code Contribution", + "slug": "getting-started-with-code-contribution", + "markdown_source": "../docs/contributors/code/getting-started-with-code-contribution.md", + "parent": "code" + }, + { + "title": "Git Workflow", + "slug": "git-workflow", + "markdown_source": "../docs/contributors/code/git-workflow.md", + "parent": "code" + }, + { + "title": "Coding Guidelines", + "slug": "coding-guidelines", + "markdown_source": "../docs/contributors/code/coding-guidelines.md", + "parent": "code" + }, + { + "title": "Testing Overview", + "slug": "testing-overview", + "markdown_source": "../docs/contributors/code/testing-overview.md", + "parent": "code" + }, + { + "title": "End-to-End Testing", + "slug": "e2e", + "markdown_source": "../docs/contributors/code/e2e/README.md", + "parent": "testing-overview" + }, + { + "title": "Migration guide", + "slug": "migration", + "markdown_source": "../docs/contributors/code/e2e/migration.md", + "parent": "e2e" + }, + { + "title": "Overusing snapshots", + "slug": "overusing-snapshots", + "markdown_source": "../docs/contributors/code/e2e/overusing-snapshots.md", + "parent": "e2e" + }, + { + "title": "Scripts", + "slug": "scripts", + "markdown_source": "../docs/contributors/code/scripts.md", + "parent": "code" + }, + { + "title": "Managing Packages", + "slug": "managing-packages", + "markdown_source": "../docs/contributors/code/managing-packages.md", + "parent": "code" + }, + { + "title": "Gutenberg Release Process", + "slug": "release", + "markdown_source": "../docs/contributors/code/release/README.md", + "parent": "code" + }, + { + "title": "Gutenberg plugin releases", + "slug": "plugin-release", + "markdown_source": "../docs/contributors/code/release/plugin-release.md", + "parent": "release" + }, + { + "title": "Packages releases to NPM and WordPress Core updates", + "slug": "package-release-and-core-updates", + "markdown_source": "../docs/contributors/code/release/package-release-and-core-updates.md", + "parent": "release" + }, + { + "title": "Cherry-picking automation", + "slug": "auto-cherry-picking", + "markdown_source": "../docs/contributors/code/auto-cherry-picking.md", + "parent": "release" + }, + { + "title": "React Native mobile editor", + "slug": "react-native", + "markdown_source": "../docs/contributors/code/react-native/README.md", + "parent": "code" + }, + { + "title": "Getting Started for the React Native based Mobile Gutenberg", + "slug": "getting-started-react-native", + "markdown_source": "../docs/contributors/code/react-native/getting-started-react-native.md", + "parent": "react-native" + }, + { + "title": "Setup guide for React Native development (macOS)", + "slug": "osx-setup-guide", + "markdown_source": "../docs/contributors/code/react-native/osx-setup-guide.md", + "parent": "react-native" + }, + { + "title": "React Native Integration Test Guide", + "slug": "integration-test-guide", + "markdown_source": "../docs/contributors/code/react-native/integration-test-guide.md", + "parent": "react-native" + }, + { + "title": "React Native Internationalization Guide", + "slug": "internationalization-guide", + "markdown_source": "../docs/contributors/code/react-native/internationalization-guide.md", + "parent": "react-native" + }, + { + "title": "Backward Compatibility", + "slug": "backward-compatibility", + "markdown_source": "../docs/contributors/code/backward-compatibility.md", + "parent": "code" + }, + { + "title": "Deprecations", + "slug": "deprecations", + "markdown_source": "../docs/contributors/code/deprecations.md", + "parent": "code" + }, + { + "title": "How To Get Your Pull Request Reviewed?", + "slug": "how-to-get-your-pull-request-reviewed", + "markdown_source": "../docs/contributors/code/how-to-get-your-pull-request-reviewed.md", + "parent": "code" + }, + { + "title": "Design Contributions", + "slug": "design", + "markdown_source": "../docs/contributors/design/README.md", + "parent": "contributors" + }, + { + "title": "Blocks are the Interface", + "slug": "the-block", + "markdown_source": "../docs/contributors/design/the-block.md", + "parent": "design" + }, + { + "title": "Documentation Contributions", + "slug": "documentation", + "markdown_source": "../docs/contributors/documentation/README.md", + "parent": "contributors" + }, + { + "title": "Copy Guidelines", + "slug": "copy-guide", + "markdown_source": "../docs/contributors/documentation/copy-guide.md", + "parent": "documentation" + }, + { + "title": "Triage", + "slug": "triage", + "markdown_source": "../docs/contributors/triage.md", + "parent": "contributors" + }, + { + "title": "Localizing Gutenberg", + "slug": "localizing", + "markdown_source": "../docs/contributors/localizing.md", + "parent": "contributors" + }, + { + "title": "Accessibility Testing", + "slug": "accessibility-testing", + "markdown_source": "../docs/contributors/accessibility-testing.md", + "parent": "contributors" + }, + { + "title": "Repository Management", + "slug": "repository-management", + "markdown_source": "../docs/contributors/repository-management.md", + "parent": "contributors" + }, + { + "title": "Folder Structure", + "slug": "folder-structure", + "markdown_source": "../docs/contributors/folder-structure.md", + "parent": "contributors" + }, + { + "title": "Gutenberg versions in WordPress", + "slug": "versions-in-wordpress", + "markdown_source": "../docs/contributors/versions-in-wordpress.md", + "parent": "contributors" + } +] diff --git a/private-apis.md b/private-apis.md new file mode 100644 index 0000000..206b7d6 --- /dev/null +++ b/private-apis.md @@ -0,0 +1,340 @@ +### `core/edit-post` 存储库 + +私有选择器： +- `getEditedPostTemplateId` + +## edit-site + +### `core/edit-site` 存储库 + +私有操作： +- `registerRoute` +- `setEditorCanvasContainerView` + +私有选择器： +- `getRoutes` +- `getEditorCanvasContainerView` + +# Gutenberg 私有 API + +本文概述了 Gutenberg 包暴露的私有 API。这些 API 用于实现 Gutenberg 编辑器（文章编辑器、站点编辑器、核心区块及其他功能）的组成部分，但未向插件和主题开发者或自定义 Gutenberg 集成的开发者公开。 + +本文档旨在展示我们拥有多少私有 API，以及如何利用 `@wordpress/*` 系列包提供的库和框架来构建 Gutenberg 编辑器应用。 + +## data + +注册器包含两个私有方法： +- `privateActionsOf` +- `privateSelectorsOf` + +每个存储库均提供用于注册私有选择器/操作的私有 API： +- `privateActions` +- `registerPrivateActions` +- `privateSelectors` +- `registerPrivateSelectors` + +## blocks + +### `core/blocks` 存储库 + +私有操作： +- `addBlockBindingsSource` +- `removeBlockBindingsSource` +- `addBootstrappedBlockType` +- `addUnprocessedBlockType` + +私有选择器： +- `getAllBlockBindingsSources` +- `getBlockBindingsSource` +- `getBootstrappedBlockType` +- `getSupportedStyles` +- `getUnprocessedBlockTypes` +- `hasContentRoleAttribute` + +## components + +私有导出项： +- `__experimentalPopoverLegacyPositionToPlacement` +- `ComponentsContext` +- `Tabs` +- `Theme` +- `Menu` +- `kebabCase` + +## commands + +私有导出项： +- `useCommandContext`（2023 年 5 月通过 #50543 添加） + +### `core/commands` 存储库 + +私有操作： +- `setContext`（与 `useCommandContext` 同时添加） + +## preferences + +私有导出项（2024 年 1 月通过 #57639 添加）： +- `PreferenceBaseOption` +- `PreferenceToggleControl` +- `PreferencesModal` +- `PreferencesModalSection` +- `PreferencesModalTabs` + +仅有一个公开导出的组件！ +- `PreferenceToggleMenuItem` + +## block-editor + +私有导出项： +- `AdvancedPanel` +- `BackgroundPanel` +- `BorderPanel` +- `ColorPanel` +- `DimensionsPanel` +- `FiltersPanel` +- `GlobalStylesContext` +- `ImageSettingsPanel` +- `TypographyPanel` +- `areGlobalStyleConfigsEqual` +- `getBlockCSSSelector` +- `getBlockSelectors` +- `getGlobalStylesChanges` +- `getLayoutStyles` +- `toStyles` +- `useGlobalSetting` +- `useGlobalStyle` +- `useGlobalStylesOutput` +- `useGlobalStylesOutputWithConfig` +- `useGlobalStylesReset` +- `useHasBackgroundPanel` +- `useHasBorderPanel` +- `useHasBorderPanelControls` +- `useHasColorPanel` +- `useHasDimensionsPanel` +- `useHasFiltersPanel` +- `useHasImageSettingsPanel` +- `useHasTypographyPanel` +- `useSettingsForBlockElement` +- `ExperimentalBlockCanvas`：公共 `BlockCanvas` 的变体，包含多个额外属性：`contentRef`、`shouldIframe`、`iframeProps`。 +- `ExperimentalBlockEditorProvider`：公共 `BlockEditorProvider` 的变体，过滤掉若干私有/实验性设置。另请参阅 `__experimentalUpdateSettings`。 +- `getDuotoneFilter` +- `getRichTextValues` +- `PrivateQuickInserter` +- `extractWords` +- `getNormalizedSearchTerms` +- `normalizeString` +- `PrivateListView` +- `ResizableBoxPopover` +- `BlockInfo` +- `useHasBlockToolbar` +- `cleanEmptyObject` +- `BlockQuickNavigation` +- `LayoutStyle` +- `BlockRemovalWarningModal` +- `useLayoutClasses` +- `useLayoutStyles` +- `DimensionsTool` +- `ResolutionTool` +- `TabbedSidebar` +- `TextAlignmentControl` +- `usesContextKey` +- `useFlashEditableBlocks` +- `useZoomOut` +- `globalStylesDataKey` +- `globalStylesLinksDataKey` +- `selectBlockPatternsKey` +- `requiresWrapperOnCopy` +- `PrivateRichText`：额外属性 `readOnly` 于 #58916 和 #60327（2024 年 2 月和 3 月）添加。 +- `PrivateInserterLibrary`：额外属性 `onPatternCategorySelection` 于 #62130（2024 年 5 月）添加。 +- `reusableBlocksSelectKey` +- `PrivateBlockPopover`：包含两个额外属性 `__unstableContentRef` 和 `__unstablePopoverSlot`。 +- `PrivatePublishDateTimePicker`：公共 `PublishDateTimePicker` 的变体，包含两个额外属性：`isCompact` 和 `showPopoverHeaderActions`。 +- `useSpacingSizes` +- `useBlockDisplayTitle` +- `__unstableBlockStyleVariationOverridesWithConfig` +- `setBackgroundStyleDefaults` +- `sectionRootClientIdKey` +- `__unstableCommentIconFill` +- `__unstableCommentIconToolbarFill` + +### `core/block-editor` 存储库 + +私有操作： +- `__experimentalUpdateSettings`：公共 `updateSettings` 操作的实验版本，用于过滤部分私有/实验性设置。 +- `clearBlockRemovalPrompt`：清除区块移除提示 +- `deleteStyleOverride`：删除样式覆盖 +- `ensureDefaultBlock`：确保默认区块存在 +- `expandBlock`：展开区块 +- `hideBlockInterface`：隐藏区块界面 +- `modifyContentLockBlock`：修改内容锁定区块 +- `privateRemoveBlocks`：私有移除区块 +- `resetZoomLevel`：重置缩放级别 +- `setBlockRemovalRules`：设置区块移除规则 +- `setInsertionPoint`：设置插入点 +- `setLastFocus`：设置最后焦点 +- `setOpenedBlockSettingsMenu`：设置已打开的区块设置菜单 +- `setStyleOverride`：设置样式覆盖 +- `setZoomLevel`：设置缩放级别 +- `showBlockInterface`：显示区块界面 +- `startDragging`：开始拖拽 +- `stopDragging`：停止拖拽 +- `stopEditingAsBlocks`：停止以区块形式编辑 + +私有选择器： +- `getAllPatterns`：获取所有模式 +- `getBlockRemovalRules`：获取区块移除规则 +- `getBlockSettings`：获取区块设置 +- `getBlockStyles`：获取区块样式 +- `getBlockWithoutAttributes`：获取无属性区块 +- `getClosestAllowedInsertionPoint`：获取最近允许插入点 +- `getClosestAllowedInsertionPointForPattern`：获取模式最近允许插入点 +- `getContentLockingParent`：获取内容锁定父级 +- `getEnabledBlockParents`：获取启用区块父级 +- `getEnabledClientIdsTree`：获取启用的客户端ID树 +- `getExpandedBlock`：获取已展开区块 +- `getInserterMediaCategories`：获取插入器媒体分类 +- `getInsertionPoint`：获取插入点 +- `getLastFocus`：获取最后焦点 +- `getLastInsertedBlocksClientIds`：获取最后插入区块客户端ID +- `getOpenedBlockSettingsMenu`：获取已打开区块设置菜单 +- `getParentSectionBlock`：获取父级区块区域 +- `getPatternBySlug`：通过别名获取模式 +- `getRegisteredInserterMediaCategories`：获取已注册插入器媒体分类 +- `getRemovalPromptData`：获取移除提示数据 +- `getReusableBlocks`：获取可重用区块 +- `getSectionRootClientId`：获取区域根客户端ID +- `getStyleOverrides`：获取样式覆盖 +- `getTemporarilyEditingAsBlocks`：获取临时以区块形式编辑状态 +- `getTemporarilyEditingFocusModeToRevert`：获取待恢复的临时编辑焦点模式 +- `getZoomLevel`：获取缩放级别 +- `hasAllowedPatterns`：检查是否存在允许模式 +- `isBlockInterfaceHidden`：检查区块界面是否隐藏 +- `isBlockSubtreeDisabled`：检查区块子树是否禁用 +- `isDragging`：检查是否正在拖拽 +- `isResolvingPatterns`：检查是否正在解析模式 +- `isSectionBlock`：检查是否为区域区块 +- `isZoomOut`：检查是否处于缩小状态 + +## core-data + +私有导出： +- `useEntityRecordsWithPermissions`：带权限的实体记录钩子 + +### `core` 存储库 + +私有操作： +- `receiveRegisteredPostMeta`：接收已注册文章元数据 +- `editMediaEntity`：编辑媒体实体 + +私有选择器： +- `getBlockPatternsForPostType`：获取文章类型区块模式 +- `getEntityRecordPermissions`：获取实体记录权限 +- `getEntityRecordsPermissions`：获取实体记录集权限 +- `getNavigationFallbackId`：获取导航回退ID +- `getRegisteredPostMeta`：获取已注册文章元数据 +- `getUndoManager`：获取撤销管理器 + +## patterns（2023年8月创建的包，无公开导出，所有内容均为私有） + +私有导出： +- `OverridesPanel`：覆盖面板 +- `CreatePatternModal`：创建模式模态框 +- `CreatePatternModalContents`：创建模式模态框内容 +- `DuplicatePatternModal`：复制模式模态框 +- `isOverridableBlock`：检查是否为可覆盖区块 +- `hasOverridableBlocks`：检查是否存在可覆盖区块 +- `useDuplicatePatternProps`：复制模式属性钩子 +- `RenamePatternModal`：重命名模式模态框 +- `PatternsMenuItems`：模式菜单项 +- `RenamePatternCategoryModal`：重命名模式分类模态框 +- `PatternOverridesControls`：模式覆盖控件 +- `ResetOverridesControl`：重置覆盖控件 +- `PatternOverridesBlockControls`：模式覆盖区块控件 +- `useAddPatternCategory`：添加模式分类钩子 +- `PATTERN_TYPES`：模式类型 +- `PATTERN_DEFAULT_CATEGORY`：模式默认分类 +- `PATTERN_USER_CATEGORY`：模式用户分类 +- `EXCLUDED_PATTERN_SOURCES`：排除的模式来源 +- `PATTERN_SYNC_TYPES`：模式同步类型 +- `PARTIAL_SYNCING_SUPPORTED_BLOCKS`：支持部分同步的区块 + +### `core/patterns` 存储库 + +私有操作： +- `convertSyncedPatternToStatic`：将同步模式转换为静态 +- `createPattern`：创建模式 +- `createPatternFromFile`：从文件创建模式 +- `setEditingPattern`：设置编辑模式 + +私有选择器： +- `isEditingPattern`：检查是否正在编辑模式 + +## block-library + +私有导出： +- `BlockKeyboardShortcuts`：区块键盘快捷键 + +## router（仅私有导出） + +私有导出： +- `useHistory`：历史记录钩子 +- `useLocation`：位置钩子 +- `RouterProvider`：路由提供者 + +## core-commands（仅私有导出） + +私有导出： +- `useCommands`：命令钩子 + +## editor + +私有导出： +- `CreateTemplatePartModal`：创建模板部件模态框 +- `BackButton`：返回按钮 +- `EntitiesSavedStatesExtensible`：可扩展实体保存状态 +- `Editor`：编辑器 +- `EditorContentSlotFill`：编辑器内容插槽填充 +- `GlobalStylesProvider`：全局样式提供者 +- `mergeBaseAndUserConfigs`：合并基础与用户配置 +- `PluginPostExcerpt`：插件文章摘要 +- `PostCardPanel`：文章卡片面板 +- `PreferencesModal`：偏好设置模态框 +- `usePostActions`：文章操作钩子 +- `ToolsMoreMenuGroup`：工具更多菜单组 +- `ViewMoreMenuGroup`：视图更多菜单组 +- `ResizableEditor`：可调整大小编辑器 +- `registerCoreBlockBindingsSources`：注册核心区块绑定源 +- `interfaceStore`：界面存储库 +- `ActionItem`：操作项 +- `ComplementaryArea`：补充区域 +- `ComplementaryAreaMoreMenuItem`：补充区域更多菜单项 +- `FullscreenMode`：全屏模式 +- `InterfaceSkeleton`：界面骨架 +- `PinnedItems`：固定项目 + +### `core/editor` 存储库 + +私有操作： +- `createTemplate`：创建模板 +- `hideBlockTypes`：隐藏区块类型 +- `registerEntityAction`：注册实体操作 +- `registerPostTypeActions`：注册文章类型操作 +- `removeTemplates`：移除模板 +- `revertTemplate`：恢复模板 +- `saveDirtyEntities`：保存未保存实体 +- `setCurrentTemplateId`：设置当前模板ID +- `setIsReady`：设置就绪状态 +- `showBlockTypes`：显示区块类型 +- `unregisterEntityAction`：取消注册实体操作 + +私有选择器： +- `getEntityActions`：获取实体操作 +- `getInserter`：获取插入器 +- `getInserterSidebarToggleRef`：获取插入器侧边栏切换引用 +- `getListViewToggleRef`：获取列表视图切换引用 +- `getPostBlocksByName`：通过名称获取文章区块 +- `getPostIcon`：获取文章图标 +- `hasPostMetaChanges`：检查文章元数据是否有变更 +- `isEntityReady`：检查实体是否就绪 + +## edit-post \ No newline at end of file diff --git a/reference-guides/README.md b/reference-guides/README.md new file mode 100644 index 0000000..d579e7d --- /dev/null +++ b/reference-guides/README.md @@ -0,0 +1,71 @@ +# 参考指南 + +## [区块 API 参考](/docs/reference-guides/block-api/README.md) + +- [注释](/docs/reference-guides/block-api/block-annotations.md) +- [API 版本](/docs/reference-guides/block-api/block-api-versions.md) +- [属性](/docs/reference-guides/block-api/block-attributes.md) +- [上下文](/docs/reference-guides/block-api/block-context.md) +- [弃用说明](/docs/reference-guides/block-api/block-deprecation.md) +- [编辑与保存](/docs/reference-guides/block-api/block-edit-save.md) +- [模式](/docs/reference-guides/block-api/block-patterns.md) +- [注册](/docs/reference-guides/block-api/block-registration.md) +- [功能支持](/docs/reference-guides/block-api/block-supports.md) +- [模板](/docs/reference-guides/block-api/block-templates.md) +- [转换功能](/docs/reference-guides/block-api/block-transforms.md) +- [元数据](/docs/reference-guides/block-api/block-metadata.md) +- [变体](/docs/reference-guides/block-api/block-variations.md) + +## [钩子参考](/docs/reference-guides/filters/README.md) + +- [区块过滤器](/docs/reference-guides/filters/block-filters.md) +- [编辑器钩子](/docs/reference-guides/filters/editor-filters.md) +- [国际化钩子](/docs/reference-guides/filters/i18n-filters.md) +- [解析器钩子](/docs/reference-guides/filters/parser-filters.md) +- [自动补全](/docs/reference-guides/filters/autocomplete-filters.md) +- [全局样式钩子](/docs/reference-guides/filters/global-styles-filters.md) + +## [插槽填充参考](/docs/reference-guides/slotfills/README.md) + +- [主仪表板按钮](/docs/reference-guides/slotfills/main-dashboard-button.md) +- [插件区块设置菜单项](/docs/reference-guides/slotfills/plugin-block-settings-menu-item.md) +- [插件文档设置面板](/docs/reference-guides/slotfills/plugin-document-setting-panel.md) +- [插件更多菜单项](/docs/reference-guides/slotfills/plugin-more-menu-item.md) +- [插件文章发布后面板](/docs/reference-guides/slotfills/plugin-post-publish-panel.md) +- [插件文章状态信息](/docs/reference-guides/slotfills/plugin-post-status-info.md) +- [插件文章发布前面板](/docs/reference-guides/slotfills/plugin-pre-publish-panel.md) +- [插件侧边栏](/docs/reference-guides/slotfills/plugin-sidebar.md) +- [插件侧边栏更多菜单项](/docs/reference-guides/slotfills/plugin-sidebar-more-menu-item.md) + +## [主题配置参考](/docs/reference-guides/theme-json-reference/README.md) + +- [版本 3（最新）](/docs/reference-guides/theme-json-reference/theme-json-living.md) +- [版本 2](/docs/reference-guides/theme-json-reference/theme-json-v2.md) +- [版本 1](/docs/reference-guides/theme-json-reference/theme-json-v1.md) +- [迁移至新版本](/docs/reference-guides/theme-json-reference/theme-json-migrations.md) + +## [富文本参考](/docs/reference-guides/richtext.md) + +## [组件参考](/packages/components/README.md) + +## [包参考](/docs/reference-guides/packages.md) + +## [数据模块参考](/docs/reference-guides/data/README.md) + +- [**core**：WordPress 核心数据](/docs/reference-guides/data/data-core.md) + - [**core/annotations**：注释](/docs/reference-guides/data/data-core-annotations.md) + - [**core/block-directory**：区块目录](/docs/reference-guides/data/data-core-block-directory.md) + - [**core/block-editor**：区块编辑器数据](/docs/reference-guides/data/data-core-block-editor.md) + - [**core/blocks**：区块类型数据](/docs/reference-guides/data/data-core-blocks.md) + - [**core/customize-widgets**：自定义小工具](/docs/reference-guides/data/data-core-customize-widgets.md) + - [**core/edit-post**：编辑器界面数据](/docs/reference-guides/data/data-core-edit-post.md) + - [**core/edit-site**：站点编辑](/docs/reference-guides/data/data-core-edit-site.md) + - [**core/edit-widgets**：小工具编辑](/docs/reference-guides/data/data-core-edit-widgets.md) + - [**core/editor**：文章编辑器数据](/docs/reference-guides/data/data-core-editor.md) + - [**core/keyboard-shortcuts**：键盘快捷键数据](/docs/reference-guides/data/data-core-keyboard-shortcuts.md) + - [**core/notices**：通知数据](/docs/reference-guides/data/data-core-notices.md) + - [**core/nux**：新用户体验数据](/docs/reference-guides/data/data-core-nux.md) + - [**core/preferences**：偏好设置](/docs/reference-guides/data/data-core-preferences.md) + - [**core/reusable-blocks**：可复用区块](/docs/reference-guides/data/data-core-reusable-blocks.md) + - [**core/rich-text**：富文本](/docs/reference-guides/data/data-core-rich-text.md) + - [**core/viewport**：视口数据](/docs/reference-guides/data/data-core-viewport.md) \ No newline at end of file diff --git a/reference-guides/block-api/README.md b/reference-guides/block-api/README.md new file mode 100644 index 0000000..3f1351b --- /dev/null +++ b/reference-guides/block-api/README.md @@ -0,0 +1,22 @@ +# 区块 API 参考 + +区块是编辑器的基本组成单元，也是插件和主题注册自身功能、扩展编辑器能力的主要方式。 + +以下章节将引导您了解现有的区块 API： + +- [注释](/docs/reference-guides/block-api/block-annotations.md) +- [API 版本](/docs/reference-guides/block-api/block-api-versions.md) +- [属性](/docs/reference-guides/block-api/block-attributes.md) +- [绑定](/docs/reference-guides/block-api/block-bindings.md) +- [上下文](/docs/reference-guides/block-api/block-context.md) +- [弃用说明](/docs/reference-guides/block-api/block-deprecation.md) +- [编辑与保存](/docs/reference-guides/block-api/block-edit-save.md) +- [block.json 中的元数据](/docs/reference-guides/block-api/block-metadata.md) +- [模式](/docs/reference-guides/block-api/block-patterns.md) +- [注册](/docs/reference-guides/block-api/block-registration.md) +- [选择器](/docs/reference-guides/block-api/block-selectors.md) +- [样式](/docs/reference-guides/block-api/block-styles.md) +- [支持特性](/docs/reference-guides/block-api/block-supports.md) +- [转换功能](/docs/reference-guides/block-api/block-transforms.md) +- [模板](/docs/reference-guides/block-api/block-templates.md) +- [变体](/docs/reference-guides/block-api/block-variations.md) \ No newline at end of file diff --git a/reference-guides/block-api/block-annotations.md b/reference-guides/block-api/block-annotations.md new file mode 100644 index 0000000..bb1c211 --- /dev/null +++ b/reference-guides/block-api/block-annotations.md @@ -0,0 +1,61 @@ +# 标注功能 + +
+注意： 此 API 为实验性功能，这意味着在未来的任何版本中可能会发生不向后兼容的变更或被移除。
+
+
+标注是一种高亮区块编辑器中创建的文章特定片段的方式。典型应用包括文本批注与拼写检查，两者均可通过标注 API 对文本片段进行标记。
+
+## API
+
+要直观了解 API，最简便的方式是创建一个至少包含 200 个无格式字符的区块，并在控制台中执行以下代码：
+
+```js
+wp.data.dispatch( 'core/annotations' ).addAnnotation( {
+ source: 'my-annotations-plugin',
+ blockClientId: wp.data.select( 'core/block-editor' ).getBlockOrder()[ 0 ],
+ richTextIdentifier: 'content',
+ range: {
+ start: 50,
+ end: 100,
+ },
+} );
+```
+
+范围起始点与结束点的计算应仅基于相应 `RichText` 的纯文本内容。例如在以下 HTML 中，位置 0 将指向大写字母 S 之前的位置：
+
+```html
+加粗文本
+```
+
+为帮助确定正确位置，可使用 `wp.richText.create` 方法。该方法会将 HTML 片段拆分为文本内容与格式标记。
+
+所有可用属性均可在 `addAnnotation` 操作的 API 文档中查阅。
+
+`richTextIdentifier` 属性用于指定标注所应用的富文本实例标识符。由于区块可能包含多个用于管理不同属性数据的富文本实例，必须传入此参数才能确保在正确的实例中高亮文本。
+
+例如段落区块仅包含单个标识符为 `content` 的富文本实例。引述区块类型则拥有 2 个富文本实例，若需在引注部分高亮文本，添加标注时需将 `citation` 作为 `richTextIdentifier` 传入；若需定位引述内容，则需使用标识符 `value`。具体标识符请参考区块类型的源代码。
+
+## 区块标注
+
+也可对完整区块进行标注。此时只需提供值为 `block` 的 `selector` 属性。默认的 `selector` 为 `range`，适用于文本标注场景。
+
+```js
+wp.data.dispatch( 'core/annotations' ).addAnnotation( {
+ source: 'my-annotations-plugin',
+ blockClientId: wp.data.select( 'core/block-editor' ).getBlockOrder()[ 0 ],
+ selector: 'block',
+} );
+```
+
+此操作不会自动提供样式支持，因此需要额外添加 CSS 以确保标注可见：
+
+```css
+.is-annotated-by-my-annotations-plugin {
+ outline: 1px solid black;
+}
+```
+
+## 文本标注
+
+文本标注通过 `start` 与 `end` 属性进行控制。由于简单的起止位置属性无法直接适用于 HTML 环境，这两个属性被设计为 `rich-text` 内部结构中的偏移量。为简化理解，可将其视为去除所有 HTML 标记后，在纯文本环境中计算的标注起止位置。
\ No newline at end of file
diff --git a/reference-guides/block-api/block-api-versions.md b/reference-guides/block-api/block-api-versions.md
new file mode 100644
index 0000000..0a3021b
--- /dev/null
+++ b/reference-guides/block-api/block-api-versions.md
@@ -0,0 +1,16 @@
+# API 版本说明
+
+本文档记录了不同 API 版本之间的变更内容。
+
+## 版本 3（适用于 WordPress 6.3 及以上版本）
+- 当所有已注册区块均采用区块 API 第 3 版或更高版本时，文章编辑器将采用 iframe 内嵌模式。支持第 3 版意味着区块应能在 iframe 内正常工作，但若存在不支持第 3 版的区块，该区块仍可能在 iframe 外渲染。
+- 请参阅[本文](https://make.wordpress.org/core/2021/06/29/blocks-in-an-iframed-template-editor/)获取迁移指南，了解如何将 API 版本升级至第 3 版并确保在 iframe 编辑器中正常运行。
+
+## 版本 2（适用于 WordPress 5.6 及以上版本）
+
+- 区块开发者必须使用 `useBlockProps()` 钩子函数来渲染区块 `edit` 实现的包装元素。
+- 在处理 `save` 功能时，生成的类名和样式不再自动添加到静态区块的保存标记中。如需保留这些样式，区块开发者必须显式调用 `useBlockProps.save()` 并将其添加到区块包装器中。
+
+## 版本 1
+
+初始版本。
\ No newline at end of file
diff --git a/reference-guides/block-api/block-attributes.md b/reference-guides/block-api/block-attributes.md
new file mode 100644
index 0000000..ae2810f
--- /dev/null
+++ b/reference-guides/block-api/block-attributes.md
@@ -0,0 +1,495 @@
+# 属性
+
+区块属性提供了关于区块存储数据的信息。例如：富文本内容、图片URL列表、背景色或按钮标题。
+
+一个区块可以包含任意数量的属性，这些属性通过`attributes`字段指定——该对象中的每个键都是属性名称，值则是属性定义。
+
+属性定义至少包含`type`或`enum`之一，也可能包含其他字段。
+
+*示例*：定义三个属性（`url`、`title`和`size`）的属性对象。
+
+```js
+{
+ url: {
+ type: 'string',
+ source: 'attribute',
+ selector: 'img',
+ attribute: 'src',
+ },
+ title: {
+ type: 'string',
+ },
+ size: {
+ enum: [ 'large', 'small' ],
+ },
+}
+```
+
+当区块被解析时，此定义将用于从区块内容中提取数据。所有匹配项都会通过`attributes`属性提供给您的区块。
+
+该解析过程可概括为：
+
+1. 从`source`中提取值
+2. 检查值是否匹配`type`，或是`enum`值之一
+
+*示例*：使用上述属性定义，在`edit`函数中可用的属性。
+
+```js
+function YourBlockEdit( { attributes } ) {
+ return (
+ URL是{ attributes.url }，标题是{ attributes.title }，尺寸是{ attributes.size }。
+ ) +} +``` + +区块需负责使用`save`函数确保所有带`source`字段的属性按照属性定义保存。此过程非自动执行。 + +没有`source`的属性将自动保存在区块[注释分隔符](/docs/explanations/architecture/key-concepts.md#data-attributes)中。 + +例如，使用上述属性定义时，您需要确保`save`函数包含与`url`属性对应的img标签。`title`和`size`属性将保存在注释分隔符中。 + +*示例*：包含`url`属性的`save`函数示例 + +```js +function YourBlockSave( { attributes } ) { + return ( +
+
+```
+
+若属性随时间变化，可通过[区块弃用](/docs/reference-guides/block-api/block-deprecation.md)来迁移旧属性或完全移除。
+
+## 类型验证
+
+`type`指明属性存储的数据类型。它不表示数据存储位置（由`source`字段定义）。
+
+除非提供`enum`，否则`type`是必需的。`type`可与`enum`同时使用。
+
+`type`字段必须是以下之一：
+
+- `null`
+- `boolean`
+- `object`
+- `array`
+- `string`
+- `integer`
+- `number`（与`integer`相同）
+
+注意：`object`的有效性由您的`source`决定。示例可参阅下文的`query`详情。
+
+## 枚举验证
+
+属性可定义为固定值集合中的一个值。通过包含允许值数组的`enum`来指定：
+
+*示例*：`enum`示例。
+
+```js
+{
+ size: {
+ enum: [ 'large', 'small', 'tiny' ]
+ }
+}
+```
+
+## 值来源
+
+属性来源用于定义如何从已保存的文章内容中提取属性值。它们提供了一种从已保存标记到区块JavaScript表示的映射机制。
+
+可用的`source`值包括：
+- `（无值）`- 未指定`source`时，数据存储在区块的[注释分隔符](/docs/explanations/architecture/key-concepts.md#data-attributes)中
+- `attribute`- 数据存储在HTML元素属性中
+- `text`- 数据存储在HTML文本中
+- `html`- 数据以HTML形式存储（通常由`RichText`使用）
+- `query`- 数据以对象数组形式存储
+- `meta`- 数据存储在文章元数据中（已弃用）
+
+`source`字段通常与`selector`字段结合使用。若未指定选择器参数，源定义将针对区块根节点运行。若指定选择器参数，则将针对区块内的匹配元素运行。
+
+`selector`可以是HTML标签，或任何可通过[querySelector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector)查询的内容，例如类或id属性。下方提供了示例。
+
+例如，`img`选择器将匹配`img`元素，而`img.class`将匹配具有`class`类的`img`元素。
+
+在底层实现中，属性来源是[hpq](https://github.com/aduth/hpq)库功能的超集，该小型库用于将HTML标记解析和查询为对象形态。
+
+总结而言，`source`决定数据在内容中的存储位置，而`type`决定数据的类型。为减少存储数据量，通常建议尽可能将数据存储在HTML中而非注释分隔符内的属性中。
+
+### 元数据源（已弃用）
+
+
+虽然属性可从文章的元数据中获取，但元数据属性源已被视为弃用；应改用 EntityProvider 及相关钩子 API，如 创建元数据块指南 中所示。
+
+
+属性可从文章的元数据中获取，而非从已保存文章内容中的块表示中获取。为此，需要为属性在 `meta` 键下指定其对应的元数据键。
+
+属性定义：
+```js
+{
+ author: {
+ type: 'string',
+ source: 'meta',
+ meta: 'author'
+ },
+},
+```
+
+从此处开始，元数据属性可以通过与任何属性相同的接口由块读取和写入：
+
+```js
+edit( { attributes, setAttributes } ) {
+ function onChange( event ) {
+ setAttributes( { author: event.target.value } );
+ }
+
+ return ;
+},
+```
+
+#### 注意事项
+
+默认情况下，元字段将从文章对象的元数据中排除。可以通过显式使字段可见来规避此问题：
+
+```php
+function gutenberg_my_block_init() {
+ register_post_meta( 'post', 'author', array(
+ 'show_in_rest' => true,
+ ) );
+}
+add_action( 'init', 'gutenberg_my_block_init' );
+```
+
+此外，请注意 WordPress 默认行为为：
+
+- 不将元数据视为唯一，而是返回值的数组；
+- 将该数据视为字符串。
+
+如果不希望出现上述任一行为，可以在相同的 `register_post_meta` 调用中补充 `single` 和/或 `type` 参数，如下所示：
+
+```php
+function gutenberg_my_block_init() {
+ register_post_meta( 'post', 'author_count', array(
+ 'show_in_rest' => true,
+ 'single' => true,
+ 'type' => 'integer',
+ ) );
+}
+add_action( 'init', 'gutenberg_my_block_init' );
+```
+
+如果希望在属性中使用对象或数组，可以注册一个 `string` 属性类型并使用 JSON 作为中间格式。在保存之前将结构化数据序列化为 JSON，然后在服务器上反序列化 JSON 字符串。请注意，您需要负责数据的完整性；确保正确清理数据、处理缺失数据等。
+
+最后，请确保在设置属性时尊重数据的类型，因为框架不会自动执行元数据的类型转换。块属性中的类型错误将导致文章即使在保存后仍保持“脏”状态（参见 `isEditedPostDirty`、`hasEditedAttributes`）。例如，如果 `authorCount` 是整数类型，请记住事件处理程序可能会传递不同类型的数据，因此应显式转换值：
+
+```js
+function onChange( event ) {
+ props.setAttributes( { authorCount: Number( event.target.value ) } );
+}
+```
+
+## 默认值
+
+块属性可以包含默认值，当 `type` 和 `source` 与块内容中的任何内容不匹配时，将使用该值。
+
+该值由 `default` 字段提供，并且该值应与属性的预期格式匹配。
+
+_示例_：`default` 值的示例。
+
+```js
+{
+ type: 'string',
+ default: 'hello world'
+}
+```
+
+```js
+{
+ type: 'array',
+ default: [
+ { "url": "https://lorempixel.com/1200/800/", "alt": "大图" },
+ { "url": "https://lorempixel.com/50/50/", "alt": "小图" }
+ ]
+}
+```
+
+```js
+{
+ type: 'object',
+ default: {
+ width: 100,
+ title: '标题'
+ }
+}
+```
+
+## 角色
+
+`role` 属性将属性指定为特定概念类型。此属性可应用于任何属性，以提供关于应如何处理该属性的语义含义。
+
+使用 `content` 将属性指定为用户可编辑的内容。在特殊情况下（例如仅内容锁定），标记为 `content` 的块可能被启用为特权编辑。
+使用 `local` 将属性标记为临时且不可持久化的。标记为 `local` 的属性会被块序列化器忽略，并且永远不会保存到文章内容中。
+
+_示例_：段落块使用的 `content` 角色
+
+```js
+{
+ content: {
+ type: 'string',
+ source: 'html',
+ selector: 'p',
+ role: 'content',
+ }
+}
+```
+
+_示例_：用于临时数据的 `local` 角色。
+
+```js
+{
+ blob: {
+ type: 'string',
+ role: 'local',
+ }
+}
+```
+
+更多信息请参阅 [WordPress 6.7 开发说明](https://make.wordpress.org/core/2024/10/20/miscellaneous-block-editor-changes-in-wordpress-6-7/#stabilized-role-property-for-block-attributes)。
+
+### `attribute` 数据源
+
+使用 `attribute` 数据源可从标记中提取属性值。通过必须提供的 `attribute` 字段指定需要提取的属性。
+
+_示例_：从区块标记中的图片元素提取 `src` 属性。
+
+保存内容：
+```html
+
+ 区块内容
+
+ 
+
+```
+
+属性定义：
+```js
+{
+ url: {
+ type: 'string',
+ source: 'attribute',
+ selector: 'img',
+ attribute: 'src',
+ }
+}
+```
+
+区块中可用的属性：
+```js
+{ "url": "https://lorempixel.com/1200/800/" }
+```
+
+大多数标记中的属性都是字符串类型。HTML中的数值属性仍会以字符串形式存储，且不会自动转换。
+
+_示例_：从区块标记中的图片元素提取 `width` 属性。
+
+保存内容：
+```html
+
+ 区块内容
+
+
+
+```
+
+属性定义：
+```js
+{
+ width: {
+ type: 'string',
+ source: 'attribute',
+ selector: 'img',
+ attribute: 'width',
+ }
+}
+```
+
+区块中可用的属性：
+```js
+{ "width": "50" }
+```
+
+唯一例外是检查属性是否存在的情况（例如检查 `button` 上的 `disabled` 属性）。此时可使用 `boolean` 类型，存储值将转换为布尔值。
+
+_示例_：从区块标记中的按钮元素提取 `disabled` 属性。
+
+保存内容：
+```html
+
+ 区块内容
+
+
+
+```
+
+属性定义：
+```js
+{
+ disabled: {
+ type: 'boolean',
+ source: 'attribute',
+ selector: 'button',
+ attribute: 'disabled',
+ }
+}
+```
+
+区块中可用的属性：
+```js
+{ "disabled": true }
+```
+
+### `text` 数据源
+
+使用 `text` 可从标记中提取内部文本。注意返回的HTML内容遵循 [`textContent`](https://developer.mozilla.org/zh-CN/docs/Web/API/Node/textContent) 规则。
+
+_示例_：从区块标记中的 figcaption 元素提取 `content` 属性。
+
+保存内容：
+```html
+
+
+
+
+
+
+```
+
+属性定义：
+```js
+{
+ content: {
+ type: 'string',
+ source: 'text',
+ selector: '.my-content',
+ }
+}
+```
+
+区块中可用的属性：
+```js
+{ "content": ".my-content 类的内部文本" }
+```
+
+### `html` 数据源
+
+使用 `html` 可从标记中提取内部HTML。注意返回的文本内容遵循 [`innerHTML`](https://developer.mozilla.org/zh-CN/docs/Web/API/Element/innerHTML) 规则。
+
+_示例_：从区块标记中的 figcaption 元素提取 `content` 属性。
+
+保存内容：
+```html
+
+
+ .my-content 类的内部文本
+
+
+
+
+ 
+
+```
+
+属性定义：
+```js
+{
+ images: {
+ type: 'array',
+ source: 'query',
+ selector: 'img',
+ query: {
+ url: {
+ type: 'string',
+ source: 'attribute',
+ attribute: 'src',
+ },
+ alt: {
+ type: 'string',
+ source: 'attribute',
+ attribute: 'alt',
+ },
+ }
+ }
+}
+```
+
+区块中可用的属性：
+```js
+{
+ "images": [
+ { "url": "https://lorempixel.com/1200/800/", "alt": "大图" },
+ { "url": "https://lorempixel.com/50/50/", "alt": "小图" }
+ ]
+}
+```
\ No newline at end of file
diff --git a/reference-guides/block-api/block-bindings.md b/reference-guides/block-api/block-bindings.md
new file mode 100644
index 0000000..444fd87
--- /dev/null
+++ b/reference-guides/block-api/block-bindings.md
@@ -0,0 +1,327 @@
+#### setValues 函数
+
+`setValues` 函数用于更新绑定区块源的所有值。它接收一个包含以下属性的 `object` 作为参数：
+
+- `bindings` 返回特定源的绑定对象。该对象必须以属性作为键，值可以是 `string` 或包含参数的 `object`。此对象包含一个 `newValue` 属性，用于存储用户的输入。
+- `clientId` 返回一个 `string`，表示当前区块的客户端 ID。
+- `context` 返回一个 `object`，表示当前区块的上下文，定义在 `usesContext` 属性中。[关于区块上下文的更多信息](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-context/)。
+- `dispatch` 返回一个 `object`，包含存储的操作创建器。[关于 dispatch 的更多信息](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data/#dispatch)。
+- `select` 返回一个 `object`，包含给定存储的选择器。[更多信息请参阅文档](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data/#select)。
+
+#### 编辑器注册核心示例
+
+核心中有几个示例可供参考：
+
+- 文章元数据。[源代码](https://github.com/WordPress/gutenberg/blob/5afd6c27bfba2be2e06b502257753fbfff1ae9f0/packages/editor/src/bindings/post-meta.js#L74-L146)
+- 模式覆盖。[源代码](https://github.com/WordPress/gutenberg/blob/5afd6c27bfba2be2e06b502257753fbfff1ae9f0/packages/editor/src/bindings/pattern-overrides.js#L8-L100)
+
+## 注销源
+
+_**注意：**自 WordPress 6.7 起。_
+
+`unregisterBlockBindingsSource` 通过提供名称注销一个区块绑定源。
+
+```js
+import { unregisterBlockBindingsSource } from '@wordpress/blocks';
+
+unregisterBlockBindingsSource( 'plugin/my-custom-source' );
+```
+
+## 获取所有源
+
+_**注意：**自 WordPress 6.7 起。_
+
+`getBlockBindingsSources` 返回所有已注册的区块绑定源。
+
+```js
+import { getBlockBindingsSources } from '@wordpress/blocks';
+
+const registeredSources = getBlockBindingsSources();
+```
+
+## 获取特定源
+
+_**注意：**自 WordPress 6.7 起。_
+
+`getBlockBindingsSource` 通过名称返回特定的区块绑定源。
+
+```js
+import { getBlockBindingsSource } from '@wordpress/blocks';
+
+const blockBindingsSource = getBlockBindingsSource( 'plugin/my-custom-source' );
+```
+
+## 区块绑定工具
+
+_**注意：**自 WordPress 6.7 起。_
+
+`useBlockBindingUtils` 是一个包含两个辅助函数的钩子，允许开发者轻松编辑 `metadata.bindings` 属性。
+
+它接受一个 `clientId` 字符串作为参数，如果未设置，函数将使用上下文中的当前区块客户端 ID。
+
+示例：
+
+```js
+import { useBlockBindingsUtils } from '@wordpress/block-editor';
+
+const { updateBlockBindings } = useBlockBindingsUtils('my-block-client-id-12345');
+...
+```
+
+### updateBlockBindings
+
+`updateBlockBindings` 的工作方式类似于 `updateBlockAttributes`，可用于创建、更新或删除特定连接。
+
+```js
+import { useBlockBindingsUtils } from '@wordpress/block-editor';
+
+const { updateBlockBindings } = useBlockBindingsUtils();
+
+function updateBlockBindingsURLSource( url ) {
+ updateBlockBindings({
+ url: {
+ source: 'myplugin/new-source',
+ }
+ })
+}
+
+// 从 url 属性中移除绑定。
+function removeBlockBindingsURLSource() {
+ updateBlockBindings( { url: undefined } );
+}
+```
+
+### removeAllBlockBindings
+
+`removeAllBlockBindings` 将通过移除 `metadata.bindings` 属性来删除区块中的所有现有连接。
+
+```js
+import { useBlockBindingsUtils } from '@wordpress/block-editor';
+
+const { removeAllBlockBindings } = useBlockBindingsUtils();
+
+function clearBlockBindings() {
+ removeAllBlockBindings();
+}
+```
+
+#### 服务器注册核心示例
+
+核心代码库中有几个可用作参考的示例：
+
+- 文章元数据。[源代码](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-bindings/post-meta.php)
+- 模式覆盖。[源代码](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-includes/block-bindings/pattern-overrides.php)
+- 二十五主题。[源代码](https://github.com/WordPress/wordpress-develop/blob/trunk/src/wp-content/themes/twentytwentyfive/functions.php)
+
+### 编辑器注册
+
+_**注意：** 自WordPress 6.7起支持_
+
+客户端编辑器注册允许定义绑定区块在获取值或编辑值时的行为。
+
+注册自定义源的函数是 `registerBlockBindingsSource( args )`：
+
+- `args`：包含以下结构的`对象`：
+ - `name`：具有唯一性且机器可读名称的`字符串`
+ - `label`：自定义源的人类可读名称`字符串`。若已在服务器端定义，服务器标签将被此标签覆盖，此时不建议在此重复定义（可选）
+ - `usesContext`：自定义源可能需要的区块上下文`数组`。若已在服务器端定义，则不应在此重复定义（可选）
+ - `getValues`：从源获取值的`函数`（可选）
+ - `setValues`：允许更新与源连接值的`函数`（可选）
+ - `canUserEditValue`：判断用户是否可以编辑值的`函数`。默认情况下用户无法编辑（可选）
+
+此示例将在编辑器中显示自定义文章元数据日期，若不存在则显示当前日期。用户可以编辑日期值。（注意：此示例未将用户输入格式化为日期——仅用于教学目的）
+
+```js
+import {
+ registerBlockBindingsSource,
+} from '@wordpress/blocks';
+import { __ } from '@wordpress/i18n';
+import { store as coreDataStore } from '@wordpress/core-data';
+
+registerBlockBindingsSource( {
+ name: 'wpmovies/visualization-date',
+ label: __( '观影日期', 'custom-bindings' ), // 可跳过标签定义，因已在前面示例的服务器端定义
+ usesContext: [ 'postType' ], // 可跳过postId定义，因已在前面示例的服务器端定义
+ getValues( { select, context } ) {
+ let wpMoviesVisualizationDate;
+ const { getEditedEntityRecord } = select( coreDataStore );
+ if ( context?.postType && context?.postId ) {
+ wpMoviesVisualizationDate = getEditedEntityRecord(
+ 'postType',
+ context?.postType,
+ context?.postId
+ ).meta?.wp_movies_visualization_date;
+ }
+ if ( wpMoviesVisualizationDate ) {
+ return {
+ content: wpMoviesVisualizationDate,
+ };
+ }
+
+ return {
+ content: new Date().toLocaleDateString( 'zh-CN' ),
+ };
+ },
+ setValues( { select, dispatch, context, bindings } ) {
+ dispatch( coreDataStore ).editEntityRecord(
+ 'postType',
+ context?.postType,
+ context?.postId,
+ {
+ meta: {
+ wp_movies_visualization_date: bindings?.content?.newValue,
+ },
+ }
+ );
+ },
+ canUserEditValue( { select, context } ) {
+ return true;
+ },
+} );
+```
+
+#### getValues函数
+
+`getValues`函数在区块加载时从源获取值。它接收包含以下属性的`对象`作为参数：
+
+- `bindings` 返回特定源的绑定对象。必须以属性为键，值可以是`字符串`或带参数的`对象`
+- `clientId` 返回当前区块客户端ID的`字符串`
+- `context` 返回在`usesContext`属性中定义的当前区块上下文`对象`。[关于区块上下文的更多信息](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-context/)
+- `select` 返回给定存储库选择器的`对象`。[详细文档](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-data/#select)
+
+该函数必须返回具有以下结构的`对象`：
+`{ '区块属性': 值 }`
+
+# 数据绑定
+
+
+区块绑定 API 仅适用于 WordPress 6.5 及以上版本。
+
+
+区块绑定 API 允许您将动态数据"绑定"到区块的属性上，这些数据最终会反映在输出到前端浏览器的 HTML 标记中。
+
+例如，可以将图片区块的 `url` 属性连接到从外部 API 返回随机图片的函数。
+
+```html
+
+```
+
+## 兼容区块及其属性
+
+目前并非所有区块属性都支持数据绑定。虽然正在努力提升兼容性，但当前支持的列表如下：
+
+| 支持区块 | 支持属性 |
+| ---------------- | -------------------- |
+| 段落 | content |
+| 标题 | content |
+| 图片 | id, url, title, alt |
+| 按钮 | text, url, linkTarget, rel |
+
+## 注册自定义数据源
+
+注册数据源需要至少定义 `name`（名称）、`label`（标签）和 `callback`（回调函数），该函数从数据源获取值并传递给区块属性。
+
+数据源注册后，任何支持的区块都可以通过配置 `metadata.bindings` 属性来读取该数据源的值。
+
+注册可以通过 PHP 在服务器端完成，也可以通过 JavaScript 在编辑器端完成，两者可以共存。
+
+服务器端注册定义的标签将被编辑器端定义的标签覆盖。
+
+### 服务器端注册
+
+服务器端注册允许应用一个回调函数，该函数将在前端为绑定属性执行。
+
+注册自定义数据源的函数是 `register_block_bindings_source($name, $args)`：
+
+- `name`：`string`，设置自定义数据源的唯一 ID。
+- `args`：`array`，包含：
+ - `label`：`string`，自定义数据源的可读名称。
+ - `uses_context`：`array`，传递给回调函数的区块上下文（可选）。
+ - `get_value_callback`：`function`，在绑定区块的渲染函数中运行。它接受三个参数：`source_args`、`block_instance` 和 `attribute_name`。此值可以通过 `block_bindings_source_value` 过滤器进行修改。
+
+注意，`register_block_bindings_source()` 应通过附加到 `init` 钩子的处理程序调用。
+
+以下是一个示例：
+
+```php
+add_action(
+ 'init',
+ function () {
+ register_block_bindings_source(
+ 'wpmovies/visualization-date',
+ array(
+ 'label' => __( 'Visualization Date', 'custom-bindings' ),
+ 'get_value_callback' => function ( array $source_args, $block_instance ) {
+ $post_id = $block_instance->context['postId'];
+ if ( isset( $source_args['key'] ) ) {
+ return get_post_meta( $post_id, $source_args['key'], true );
+ }
+ },
+ 'uses_context' => array( 'postId' ),
+ )
+ );
+ }
+);
+```
+
+此示例需要注册一个 `post_meta`，并且可以使用过滤器返回默认的 `$visualization_date` 值，该值将在下一个标题中显示。
+
+```php
+add_action(
+ 'init',
+ function () {
+ register_meta(
+ 'post',
+ 'wp_movies_visualization_date',
+ array(
+ 'show_in_rest' => true,
+ 'single' => true,
+ 'type' => 'string',
+ 'label' => __( 'Movie visualization date', 'custom-bindings' ),
+ )
+ );
+ }
+);
+```
+
+
+注意：以下划线开头的文章元键（例如 `_example_key`）是受保护的，不能用于区块绑定。此外，文章元必须通过 `show_in_rest = true` 注册才能在区块绑定 API 中使用。
+
+
+#### 区块绑定数据源值过滤器
+
+_**注意：**自 WordPress 6.7 起。_
+
+`get_value_callback` 返回的值可以通过 `block_bindings_source_value` 过滤器进行修改。
+该过滤器具有以下参数：
+
+- `value`：要过滤的值。
+- `name`：数据源的名称。
+- `source_args`：包含数据源参数的 `array`。
+- `block_instance`：区块实例对象。
+- `attribute_name`：属性名称。
+
+示例：
+
+```php
+function wpmovies_format_visualization_date( $value, $name ) {
+ // 防止此过滤器应用于其他数据源。
+ if ( $name !== 'wpmovies/visualization-date' ) {
+ return $value;
+ }
+ if ( ! $value ) {
+ return date( 'm/d/Y' );
+ }
+ return date( 'm/d/Y', strtotime( $value ) );
+}
+
+add_filter( 'block_bindings_source_value', 'wpmovies_format_visualization_date', 10, 2 );
+```
\ No newline at end of file
diff --git a/reference-guides/block-api/block-context.md b/reference-guides/block-api/block-context.md
new file mode 100644
index 0000000..f57c9b1
--- /dev/null
+++ b/reference-guides/block-api/block-context.md
@@ -0,0 +1,168 @@
+# 上下文
+
+区块上下文是一项功能，允许祖先区块提供可供其自身层次结构内的后代区块使用的值。这些后代区块可以继承这些值，而无需依赖硬编码值，也无需明确知晓提供这些值的区块。
+
+这在全站编辑中尤其有用。例如，某个区块的内容可能取决于显示它的文章上下文。博客目录模板可能显示许多不同文章的摘要。通过使用区块上下文，仍然可以有一个单一的“文章摘要”区块，根据继承的文章ID显示文章内容。
+
+如果您熟悉 [React Context](https://react.dev/learn/passing-data-deeply-with-context)，区块上下文采用了许多相同的理念。实际上，客户端区块编辑器对区块上下文的实现是 React Context 的一个非常简单的应用。区块上下文在服务器端 `render_callback` 实现中也受支持，如下面的示例所示。
+
+## 定义区块上下文
+
+区块上下文在区块的注册设置中定义。一个区块可以提供一个上下文值，或者使用它希望继承的值。
+
+### 提供区块上下文
+
+区块可以通过在其注册设置中分配一个 `providesContext` 属性来提供上下文值。这是一个将上下文名称映射到区块自身某个属性的对象。该属性值对应的值将提供给后代区块，并可以通过相同的上下文名称引用。目前，区块上下文仅支持源自区块自身属性的值。未来可能会增强以支持其他上下文值来源。
+
+```js
+ attributes: {
+ recordId: {
+ type: 'number',
+ },
+ },
+
+ providesContext: {
+ 'my-plugin/recordId': 'recordId',
+ },
+```
+
+有关完整示例，请参阅下面的部分。
+
+#### 包含命名空间
+
+如上例所示，建议您在上下文键的名称中包含命名空间，以避免与其他插件或 WordPress 提供的默认上下文值发生潜在冲突。上下文命名空间应特定于您的插件，并且在大多数情况下可以与区块本身的名称相同。
+
+### 使用区块上下文
+
+区块可以通过在其注册设置中分配一个 `usesContext` 属性来从祖先提供者继承上下文值。这应分配为区块希望继承的上下文名称数组。
+
+```js
+registerBlockType('my-plugin/record-title', {
+ title: 'Record Title',
+ category: 'widgets',
+
+ usesContext: ['my-plugin/recordId'],
+
+```
+
+## 使用区块上下文
+
+一旦区块定义了它希望继承的上下文，就可以在 `edit`（JavaScript）和 `render_callback`（PHP）的实现中访问它。它作为上下文值的对象（JavaScript）或关联数组（PHP）提供，这些值已为区块定义。请注意，只有在区块明确定义了希望继承该值的情况下，上下文值才会可用。
+
+注意：区块上下文不适用于 `save`。
+
+### JavaScript
+
+```js
+registerBlockType('my-plugin/record-title', {
+
+ edit({ context }) {
+ return 'The record ID: ' + context['my-plugin/recordId'];
+ },
+
+```
+
+### PHP
+
+区块的上下文值可以从 `$block` 参数的 `context` 属性中获取，该参数作为第三个参数传递给 `render_callback` 函数。
+
+```php
+register_block_type( 'my-plugin/record-title', array(
+ 'render_callback' => function( $attributes, $content, $block ) {
+ return 'The current record ID is: ' . $block->context['my-plugin/recordId'];
+ },
+) );
+```
+
+## 示例
+
+1. 创建一个 `record` 区块。
+
+```
+npm init @wordpress/block --namespace my-plugin record
+cd record
+```
+
+2. 编辑 `src/index.js`。在 `registerBlockType` 函数中插入 `recordId` 属性和 `providesContext` 属性，并在底部添加 `record-title` 区块的注册：
+
+```js
+registerBlockType( 'my-plugin/record', {
+ // ... 省略 ...
+
+ attributes: {
+ recordId: {
+ type: 'number',
+ },
+ },
+
+ providesContext: {
+ 'my-plugin/recordId': 'recordId',
+ },
+
+ /**
+ * @see ./edit.js
+ */
+ edit: Edit,
+
+ /**
+ * @see ./save.js
+ */
+ save,
+} );
+
+registerBlockType( 'my-plugin/record-title', {
+ title: 'Record Title',
+ category: 'widgets',
+
+ usesContext: [ 'my-plugin/recordId' ],
+
+ edit( { context } ) {
+ return 'The record ID: ' + context[ 'my-plugin/recordId' ];
+ },
+
+ save() {
+ return null;
+ },
+} );
+```
+
+3. 编辑 `record` 区块的 `src/edit.js`。将 `Edit` 函数替换为以下代码：
+
+```js
+import { TextControl } from '@wordpress/components';
+import { InnerBlocks } from '@wordpress/block-editor';
+
+export default function Edit( props ) {
+ const MY_TEMPLATE = [ [ 'my-plugin/record-title', {} ] ];
+ const {
+ attributes: { recordId },
+ setAttributes,
+ } = props;
+ return (
+
+
+ setAttributes( { recordId: Number( val ) } )
+ }
+ />
+
+ );
+}
+```
+
+4. 编辑 `record` 区块的 `src/save.js`。将 `save` 函数替换为以下代码：
+
+```js
+export default function save( props ) {
+ return The record ID: { props.attributes.recordId }
; +} +``` + +5. 创建一篇新文章并添加 `record` 区块。如果您在文本框中输入一个数字，您会看到其下方的 `record-title` 区块中显示相同的数字。 + + \ No newline at end of file diff --git a/reference-guides/block-api/block-deprecation.md b/reference-guides/block-api/block-deprecation.md new file mode 100644 index 0000000..d18bb7d --- /dev/null +++ b/reference-guides/block-api/block-deprecation.md @@ -0,0 +1,203 @@ +## 修改属性集 + +有时需要更新属性集，以重命名或修改旧属性。 + +**示例** + +```js +const { registerBlockType } = wp.blocks; + +registerBlockType( 'gutenberg/block-with-deprecated-version', { + // ... 其他区块属性 + + attributes: { + content: { + type: 'string', + default: '随机值', + }, + }, + + save( props ) { + return{ props.attributes.content }
;
+ },
+
+ deprecated: [
+ {
+ attributes: {
+ text: {
+ type: 'string',
+ default: '随机值',
+ },
+ },
+
+ migrate( { text } ) {
+ return {
+ content: text,
+ };
+ },
+
+ save( props ) {
+ return { props.attributes.text }
; + }, + }, + ], +} ); +``` + +在上方示例中，我们将区块的标记从 `p` 更新为 `div`，并将 `text` 属性重命名为 `content`。 + +## 修改内部区块 + +某些情况下，在迁移区块时可能需要添加或移除内部区块。 +例如：某个区块需要将标题属性迁移至段落内部区块。 + +**示例** + +```js +const { registerBlockType } = wp.blocks; + +registerBlockType( 'gutenberg/block-with-deprecated-version', { + // ... 区块属性 + + save( props ) { + return{ props.attributes.title }
; + }, + + deprecated: [ + { + attributes: { + title: { + type: 'string', + source: 'html', + selector: 'p', + }, + }, + + migrate( attributes, innerBlocks ) { + const { title, ...restAttributes } = attributes; + + return [ + restAttributes, + [ + createBlock( 'core/paragraph', { + content: attributes.title, + fontSize: 'large', + } ), + ...innerBlocks, + ], + ]; + }, + + save( props ) { + return{ props.attributes.title }
; + }, + }, + ], +} ); +``` + +在上方示例中，我们将区块更新为使用带标题的内部段落区块，而非标题属性。 + +_以上是区块弃用的示例案例。如需查看真实场景的示例，请参阅[核心区块库](https://github.com/WordPress/gutenberg/tree/HEAD/packages/block-library/src)中的弃用实现。核心区块在版本迭代中持续更新，包含简单与复杂的弃用方案。_ + +# 弃用说明 + +> 本页面提供了关于弃用API原理与使用的完整指南。入门教程请参阅[开发者博客](https://developer.wordpress.org/news/)上的[区块弃用基础教程](https://developer.wordpress.org/news/2023/03/block-deprecation-a-tutorial/)。 + +当更新静态区块标记与属性时，区块开发者需要考虑使用旧版区块的现有文章。为提供平滑的升级路径，您可选择以下策略之一： + +- 不弃用原区块，创建新区块（使用不同名称） +- 提供区块的"弃用"版本，允许用户在区块编辑器中打开旧版内容时使用更新后的区块进行编辑。 + +一个区块可包含多个弃用版本。当解析后的区块当前状态无效，或弃用版本定义了返回true的`isEligible`函数时，将尝试执行弃用流程。 + +弃用机制并非像数据库迁移等软件数据更新那样以链式更新方式运作。初看容易认为每个弃用版本会对数据执行必要修改，然后将新形态的区块传递给下一个弃用版本继续处理。但实际流程是： + +1. 若当前`save`方法无法生成有效区块，弃用数组中的第一个弃用版本将接收原始保存内容 +2. 若该版本的`save`方法能生成有效内容，则使用此弃用版本来解析区块属性。若其包含`migrate`方法，系统将使用弃用版本解析的属性运行该方法 +3. 若首个弃用版本的`save`方法无法生成有效区块，则依次尝试数组中后续弃用版本，直到找到能生成有效区块的版本 +4. 首个生成有效区块的弃用版本对应的属性及innerBlocks，将被传回当前`save`方法以生成新的有效区块内容 +5. 此时当前区块应处于有效状态，弃用工作流程随即终止 + +需特别注意：若弃用版本的`save`方法无法生成有效区块，则其`migrate`方法也会被完全跳过——即使`isEligible`函数对给定属性返回true。这意味着若区块存在多个弃用版本且需执行新迁移（如将内容移至`InnerBlocks`），可能需要更新多个弃用版本中的`migrate`方法，以确保所有历史版本都能应用必要更改。 + +另需注意：若弃用版本的`save`方法从其他文件导入额外函数，对这些文件的修改可能意外改变弃用行为。建议将这些函数的快照副本添加到弃用文件中，而非直接导入，以避免意外破坏弃用功能。 + +对于含多个弃用版本的区块，建议将每个弃用版本保存为对应区块版本的常量，再将其添加到区块的`deprecated`数组。数组中的弃用版本应按时间倒序排列，这样区块编辑器会优先尝试应用最新且最可能的弃用版本，避免不必要的性能损耗。 + +**示例** + +```js +const v1 = {}; +const v2 = {}; +const v3 = {}; +const deprecated = [ v3, v2, v1 ]; +``` + +同时建议维护包含不同版本区块内容的[测试固件](https://github.com/WordPress/gutenberg/blob/HEAD/test/integration/fixtures/blocks/README.md)，以便轻松验证新弃用版本和迁移功能在所有历史版本中的运行情况。 + +弃用定义位于区块类型的`deprecated`属性中，这是一个弃用对象数组，每个对象包含以下形式： + +- `attributes` (对象)：区块弃用版本的[属性定义](/docs/reference-guides/block-api/block-attributes.md) +- `supports` (对象)：区块弃用版本的[支持定义](/docs/reference-guides/block-api/block-registration.md) +- `save` (函数)：区块弃用版本的[save实现](/docs/reference-guides/block-api/block-edit-save.md) +- `migrate`：(函数，可选)。接收旧属性与内部区块后，应返回新属性或与区块兼容的属性元组数组。如前所述，若弃用版本的`save`函数未返回有效区块，其`migrate`将不会运行，因此需确保迁移功能在所有相关弃用版本中均可用。 + - _参数_ + - `attributes`: 区块旧属性 + - `innerBlocks`: 区块旧内部区块 + - _返回值_ + - `Object | Array`: 更新后的区块属性或元组数组`[attributes, innerBlocks]` +- `isEligible`：(函数，可选)。当函数返回`true`时，即使区块有效仍可由该弃用版本处理迁移。这在区块技术上有效但仍需更新属性或内部区块时特别有用。**注意**：当所有先前弃用版本的save函数结果均无效时，此函数不会被调用。 + - _参数_ + - `attributes`: 从序列化HTML解析得到的原始区块属性（在应用区块类型代码之前） + - `innerBlocks`: 区块当前内部区块 + - `data`: 包含代表区块节点及其结果区块对象属性的对象 + - `data.blockNode`: 解析序列化HTML后得到的区块原始形态 + - `data.block`: 对`blockNode`应用区块类型后得到的区块对象 + - _返回值_ + - `boolean`: 指示此有效区块是否符合该弃用版本的迁移条件 + +
+重要提示：由于
+
+**示例**
+
+```js
+const { registerBlockType } = wp.blocks;
+const attributes = {
+ text: {
+ type: 'string',
+ default: 'some random value',
+ },
+};
+const supports = {
+ className: false,
+};
+
+registerBlockType( 'gutenberg/block-with-deprecated-version', {
+ // ... 其他区块属性
+
+ attributes,
+
+ supports,
+
+ save( props ) {
+ return attributes、supports和save会影响区块的解析与序列化，它们不会自动从当前版本继承，必须在弃用对象中明确定义才能在迁移过程中被处理。
+{ props.attributes.text }
;
+ },
+
+ deprecated: [
+ {
+ attributes,
+
+ supports,
+
+ save( props ) {
+ return { props.attributes.text }
; + }, + }, + ], +} ); +``` + +以上示例中，我们将区块标记从`p`标签更新为`div`标签。 \ No newline at end of file diff --git a/reference-guides/block-api/block-edit-save.md b/reference-guides/block-api/block-edit-save.md new file mode 100644 index 0000000..d0bd72d --- /dev/null +++ b/reference-guides/block-api/block-edit-save.md @@ -0,0 +1,328 @@ +### 验证常见问题解答 + +**区块如何变为无效状态？** + +导致区块失效最常见的两种原因是： + +1. 区块代码存在缺陷，导致内容被意外修改。插件开发者可参阅下文了解如何调试区块失效问题。 +2. 您或外部编辑器对区块的HTML标记进行了更改，导致其不再符合规范。 + +**作为插件开发者，应如何调试区块被标记为无效的问题？** + +开始调试前，请务必先了解上文所述的验证步骤，该步骤记录了检测区块是否无效的流程。当区块重新生成的标记与文章内容中保存的标记不匹配时，该区块即被视为无效，这通常是由于区块属性未能从已保存内容中正确解析所致。 + +若您正在使用[属性源](/docs/reference-guides/block-api/block-attributes.md)，请确保从标记中提取的属性完全符合预期，且类型正确（通常应为`'字符串'`或`'数字'`类型）。 + +当检测到区块无效时，浏览器开发者工具控制台会记录警告信息。该警告会包含标记差异具体位置的详细信息。请仔细比对预期标记与实际标记的差异，定位问题根源。 + +**更改区块的`save`行为后，旧内容中出现无效区块应如何修复？** + +请参阅[过时区块处理指南](/docs/reference-guides/block-api/block-deprecation.md)，了解如何在主动调整标记时兼容历史内容。 + +## 示例 + +以下是结合使用属性、编辑和保存功能的几个示例。 + +### 将属性保存至子元素 + +```jsx +attributes: { + content: { + type: 'string', + source: 'html', + selector: 'div' + } +}, + +edit: ( { attributes, setAttributes } ) => { + const blockProps = useBlockProps(); + const updateFieldValue = ( val ) => { + setAttributes( { content: val } ); + } + return ( +
+
+ );
+},
+
+save: ( { attributes } ) => {
+ const blockProps = useBlockProps.save();
+
+ return { attributes.content }
;
+},
+```
+
+### 通过序列化保存属性
+
+理想情况下，已保存的属性应包含在标记中。但有时这并不现实，因此如果未指定属性来源，该属性会被序列化并保存到块的注释分隔符中。
+
+此示例适用于动态块（例如[最新文章块](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-library/src/latest-posts/index.js)），其标记在服务器端渲染。虽然仍需保存函数，但此时仅返回 null，因为该块并不保存编辑器中的内容。
+
+```jsx
+attributes: {
+ postsToShow: {
+ type: 'number',
+ }
+},
+
+edit: ( { attributes, setAttributes } ) => {
+ const blockProps = useBlockProps();
+
+ return (
+
+ {
+ setAttributes( { postsToShow: parseInt( val ) } );
+ }}
+ />
+
+ );
+},
+
+save: () => {
+ return null;
+}
+```
+
+## 验证
+
+当编辑器加载时，会对文章内容中的所有块进行验证以确定其准确性，从而防止内容丢失。这与块的保存实现密切相关，因为如果编辑器无法正确恢复块，用户可能会无意中删除或修改其内容。在编辑器初始化期间，使用从文章内容解析出的属性重新生成每个块的已保存标记。如果新生成的标记与文章内容中已存储的标记不匹配，则该块将被标记为无效。这是因为我们假设除非用户进行编辑，否则标记应与已保存内容保持一致。
+
+如果检测到某个块无效，系统将提示用户选择如何处理无效情况：
+
+
+
+点击**尝试恢复块**按钮将尽可能执行恢复操作。
+
+点击块侧边的"三点"菜单会显示三个选项：
+
+- **解决**：打开解决块对话框，其中包含两个按钮：
+ - **转换为 HTML**：保护已保存文章内容中的原始标记，并将块从其原始类型转换为 HTML 块类型，使用户能够直接修改 HTML 标记。
+ - **转换为块**：保护已保存文章内容中的原始标记，并将块从其原始类型转换为经过验证的块类型。
+- **转换为 HTML**：保护已保存文章内容中的原始标记，并将块从其原始类型转换为 HTML 块类型，使用户能够直接修改 HTML 标记。
+- **转换为经典块**：将已保存文章内容中的原始标记视为正确。由于块将从其原始类型转换为经典块类型，因此无法再使用原始块类型的控件来编辑内容。
+
+## 保存函数
+
+`save` 函数定义了如何将不同属性组合成最终标记，随后将其序列化到 `post_content` 中。
+
+```jsx
+save: () => {
+ const blockProps = useBlockProps.save();
+
+ return 您的区块内容
;
+};
+```
+
+对于大多数区块而言，`save` 的返回值应是一个 [WordPress 元素实例](/packages/element/README.md)，用于表征区块在前端站点的呈现效果。
+
+_注意：_ 虽然可以从 `save` 返回字符串值，但该值*会被转义处理*。若字符串包含 HTML 标记，这些标记将在前端站点以字面形式显示，而不会解析为等效的 HTML 节点内容。如必须从 `save` 返回原始 HTML，请使用 `wp.element.RawHTML`。但正如其名所示，这种方式易受[跨站脚本攻击](https://en.wikipedia.org/wiki/Cross-site_scripting)，因此建议尽可能使用 WordPress 元素层级结构。
+
+_注意：_ 保存函数应是纯函数且无状态，仅依赖于调用时传入的属性。它不应使用任何类似 `useState` 或 `useEffect` 的 API，也不应从其他来源获取信息；例如，无法在函数内部使用数据模块 - `select( store ).selector( ... )`。
+这是因为当外部信息发生变化时，后续编辑文章时可能会导致区块被标记为无效状态（[了解更多验证信息](#validation)）。
+
+若需要将其他信息纳入保存过程，开发者可考虑以下两种方案：
+
+- 使用[动态区块](/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md)并在服务器端动态获取所需信息
+- 将外部值存储为属性，并在区块的 `edit` 函数中随变更动态更新
+
+对于[动态区块](/docs/how-to-guides/block-tutorial/creating-dynamic-blocks.md)，`save` 的返回值可表征区块内容的缓存副本，仅当实现区块的插件被禁用时显示。
+
+若未明确指定，默认实现将不会在文章内容中保存动态区块的标记，而是始终在区块前端显示时实时计算。
+
+### 区块包装器属性
+
+与 `edit` 函数类似，在渲染静态区块时，必须将 `useBlockProps.save()` 返回的区块属性添加到区块的包装元素。这能确保区块类名正确渲染，同时包含由区块支持 API 注入的所有 HTML 属性。
+
+### 属性参数
+
+与 `edit` 相同，`save` 函数也会接收包含属性的对象参数，这些属性可插入到标记中。
+
+```jsx
+save: ( { attributes } ) => {
+ const blockProps = useBlockProps.save();
+
+ return { attributes.content }
;
+};
+```
+
+保存区块时，需按照属性源定义规定的相同格式保存属性。若未指定属性源，属性将保存至区块的注释分隔符。详见[区块属性文档](/docs/reference-guides/block-api/block-attributes.md)获取更多信息。
+
+### 内部区块
+
+传递给 `save` 函数的参数中还存在第二个属性 `innerBlocks`。该属性通常用于内部操作，实际需要使用的情况极为罕见。
+
+初始化时，`innerBlocks` 是一个包含嵌套区块对象表征的数组。在极少数需要使用此属性的场景中，它可帮助您调整区块的渲染方式。例如，您可以根据嵌套区块的数量或特定区块类型的存在情况来差异化渲染区块。
+
+```jsx
+save: ( { attributes, innerBlocks } ) => {
+ const { className, ...rest } = useBlockProps.save();
+
+ // 初始化期间 innerBlocks 也可能是对象 - React 元素
+ const numberOfInnerBlocks = innerBlocks?.length;
+ if ( numberOfInnerBlocks > 1 ) {
+ className = className + ( className ? ' ' : '' ) + 'more-than-one';
+ };
+ const blockProps = { ...rest, className };
+
+ return { attributes.content }
;
+};
+```
+
+此示例中，当内部区块数量超过一个时，会为区块添加额外类名，从而实现区块的差异化样式设计。
+
+# 编辑与保存
+
+当在客户端使用 JavaScript 注册区块时，`edit` 和 `save` 函数定义了区块在编辑器中的渲染方式、操作逻辑以及保存机制。
+
+## 编辑函数
+
+`edit` 函数描述了区块在编辑器上下文中的结构，决定了编辑器在使用该区块时的渲染内容。
+
+```jsx
+import { useBlockProps } from '@wordpress/block-editor';
+
+// ...
+const blockSettings = {
+ apiVersion: 3,
+
+ // ...
+
+ edit: () => {
+ const blockProps = useBlockProps();
+
+ return 您的区块内容
;
+ },
+};
+```
+
+### 区块包装器属性
+
+首先需要注意的是在区块包装元素上使用的 `useBlockProps` React 钩子。上例中区块包装器在编辑器内渲染为「div」元素，但为了让 Gutenberg 编辑器能够操作区块、添加必要的额外类名...区块包装元素必须应用从 `useBlockProps` React 钩子调用中获取的属性。区块包装元素应是原生 DOM 元素（如 `` 和 ``），或是能将附加属性传递至原生 DOM 元素的 React 组件。而使用 `