docs
This commit is contained in:
25
docs/how-to-guides/curating-the-editor-experience/README.md
Normal file
25
docs/how-to-guides/curating-the-editor-experience/README.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# 优化编辑器使用体验
|
||||
|
||||
优化WordPress编辑器体验至关重要，它能让您简化编辑流程，确保内容与网站风格及品牌指南保持一致。同时，这也能让用户更轻松高效地创建和管理内容，避免意外修改或布局变动，从而打造更高效、更个性化的使用体验。
|
||||
|
||||
本指南旨在介绍多种锁定和优化WordPress使用体验的方法，特别是在引入更多设计工具和站点编辑器之后。
|
||||
|
||||
在本节中，您将了解：
|
||||
|
||||
1. [**区块锁定**](https://developer.wordpress.org/block-editor/how-to-guides/curating-the-editor-experience/block-locking)：如何通过限制用户在编辑器中对特定区块的交互来实现更好的内容控制
|
||||
2. [**模式**](https://developer.wordpress.org/block-editor/how-to-guides/curating-the-editor-experience/patterns)：关于创建和实现预定义区块布局以确保设计与内容的统一性
|
||||
3. [**theme.json**](https://developer.wordpress.org/block-editor/how-to-guides/curating-the-editor-experience/theme-json)：通过theme.json文件配置主题的全局样式和设置
|
||||
4. [**过滤器和钩子**](https://developer.wordpress.org/block-editor/how-to-guides/curating-the-editor-experience/filters-and-hooks)：用于修改编辑器的核心过滤器和钩子
|
||||
5. [**禁用编辑器功能**](https://developer.wordpress.org/block-editor/how-to-guides/curating-the-editor-experience/disable-editor-functionality)：选择性禁用编辑器功能或组件的其他方法，以优化用户体验
|
||||
|
||||
## 组合运用多种方法
|
||||
|
||||
请注意，上述文档中提供的方法可以根据需要组合使用。例如，您可以在创建新页面时提供自定义模式，同时限制对这些模式的某些方面进行自定义，比如仅允许对封面区块背景使用特定的预设颜色，或锁定可删除的区块。
|
||||
|
||||
在考虑采用哪些方法时，请思考您希望以何种具体方式既开放使用体验又进行精心管控。
|
||||
|
||||
## 扩展资源
|
||||
|
||||
- [构建器基础——全站编辑中的模板运用（第三部分）](https://wordpress.tv/2022/05/24/nick-diego-builder-basics-working-with-templates-in-full-site-editing-part-3/)
|
||||
- [核心编辑器改进：通过锁定API和theme.json实现定制化体验](https://make.wordpress.org/core/2022/02/09/core-editor-improvement-curated-experiences-with-locking-apis-theme-json/)
|
||||
- [关于优化编辑器体验的WordPress学习课程](https://wordpress.tv/2022/07/22/nick-diego-curating-the-editor-experience/)
|
||||
@@ -0,0 +1,69 @@
|
||||
# 区块锁定 API
|
||||
|
||||
区块锁定 API 允许您限制编辑器内特定区块的操作。该 API 可用于防止用户移动、删除或编辑某些区块，从而确保布局一致性和内容完整性。
|
||||
|
||||
## 锁定移动或删除特定区块的功能
|
||||
|
||||
用户可通过编辑器锁定和解锁区块。锁定界面提供防止区块在内容画布内移动或被删除的选项：
|
||||
|
||||
|
||||
|
||||
请注意，通过启用"应用于内部所有区块"选项，您可以将锁定选项应用于容器区块内的嵌套区块。但除此之外，无法批量锁定区块。
|
||||
|
||||
## 锁定编辑特定区块的功能
|
||||
|
||||
除了锁定移动或删除区块的功能外，[导航区块](https://github.com/WordPress/gutenberg/pull/44739)和[可重用区块](https://github.com/WordPress/gutenberg/pull/39950)还具备额外功能：锁定编辑区块内容的能力。这将禁止对这两种区块类型内部的任何区块进行修改。
|
||||
|
||||
## 对模式或模板应用区块锁定
|
||||
|
||||
在构建模式或模板时，主题作者可以使用相同的界面工具设置区块的默认锁定状态。例如，主题作者可以锁定页眉的不同组成部分。请注意，默认情况下具有编辑权限的用户可以解锁这些区块。[这里有一个包含不同锁定方式区块的模式示例](https://gist.github.com/annezazu/acee30f8b6e8995e1b1a52796e6ef805)，以及关于[创建包含锁定区块的模板](https://make.wordpress.org/core/2022/02/09/core-editor-improvement-curated-experiences-with-locking-apis-theme-json/)的更多背景信息。您可以在编辑器内直接构建这些模式（包括添加锁定选项），然后按照[注册文档](/docs/reference-guides/block-api/block-patterns.md)进行操作。
|
||||
|
||||
## 在模式或模板中应用仅内容编辑
|
||||
|
||||
此功能在 WordPress 6.1 中引入。与禁用移动或删除区块功能的区块锁定不同，仅内容编辑功能专为模式或模板层级设计，它会隐藏所有设计工具，同时仍允许编辑区块内容。这为简化用户界面和保留设计提供了绝佳方案。启用该选项后会发生以下变化：
|
||||
|
||||
- 非内容子区块（容器、间距器、列等）将从列表视图隐藏，在画布上不可点击，且完全不可编辑。
|
||||
- 检查器将显示所有"内容"子区块列表，点击列表中的区块可显示其设置面板。
|
||||
- 主列表视图仅显示内容区块，所有区块均处于同一层级（忽略实际嵌套关系）。
|
||||
- 整体内容锁定容器内的子区块会自动启用移动/删除锁定。
|
||||
- 无法插入额外子区块，进一步保护设计和布局。
|
||||
- 区块工具栏设有"修改"链接，用户可切换此选项来获取更全面的设计工具。目前无法通过编程方式移除该选项。
|
||||
|
||||
该选项可应用于 Columns、Cover 和 Group 区块，以及在其 block.json 中具有 templateLock 属性的第三方区块。要启用此功能，需使用 `"templateLock":"contentOnly"`。[此处是具备此功能的模式示例](https://gist.github.com/annezazu/d62acd2514cea558be6cea97fe28ff3c)。更多信息请[查阅相关文档](/docs/reference-guides/block-api/block-templates.md#locking)。
|
||||
|
||||
注意：目前没有管理内容锁定的可视化界面，必须通过代码层级进行管理。
|
||||
|
||||
## 更改权限以控制锁定能力
|
||||
|
||||
机构和插件开发者可通过限制用户[锁定和解锁区块的权限](https://make.wordpress.org/core/2022/05/05/block-locking-settings-in-wordpress-6-0/)，提供更精细的定制体验。默认情况下，所有管理员都具备锁定和解锁区块的权限。
|
||||
|
||||
开发者可通过向 [block_editor_settings_all](https://developer.wordpress.org/reference/hooks/block_editor_settings_all/) 钩子添加过滤器来配置区块锁定权限。该钩子向回调函数传递两个参数：
|
||||
|
||||
- `$settings` - 编辑器的可配置设置数组
|
||||
- `$context` - WP_Block_Editor_Context 实例，包含当前编辑器信息的对象
|
||||
|
||||
具体而言，开发者可通过设置 `$settings['canLockBlocks']` 值为 `true` 或 `false` 来修改权限，通常需要执行一个或多个条件判断。
|
||||
|
||||
以下示例在编辑页面时为所有用户禁用区块锁定权限：
|
||||
|
||||
```php
|
||||
add_filter( 'block_editor_settings_all', function( $settings, $context ) {
|
||||
if ( $context->post && 'page' === $context->post->post_type ) {
|
||||
$settings['canLockBlocks'] = false;
|
||||
}
|
||||
|
||||
return $settings;
|
||||
}, 10, 2 );
|
||||
```
|
||||
|
||||
另一种常见使用场景是仅允许可编辑网站视觉设计（主题编辑）的用户锁定或解锁区块。目前最佳方案是通过检测 `edit_theme_options` 权限来实现，如下列代码片段所示：
|
||||
|
||||
```php
|
||||
add_filter( 'block_editor_settings_all', function( $settings ) {
|
||||
$settings['canLockBlocks'] = current_user_can( 'edit_theme_options' );
|
||||
|
||||
return $settings;
|
||||
} );
|
||||
```
|
||||
|
||||
开发者可使用任何类型的条件判断来确定锁定/解锁区块的权限。这仅是通过过滤钩子实现功能的冰山一角。
|
||||
@@ -0,0 +1,125 @@
|
||||
# 禁用编辑器功能
|
||||
|
||||
本文专门介绍在文章编辑器和站点编辑器中禁用特定功能的多种方法，这些内容未包含在管理文档的其他部分。
|
||||
|
||||
## 限制区块选项
|
||||
|
||||
有时您可能希望完全禁止用户使用某些区块。要控制插入器中可用的内容，您可以采用两种方法：[允许列表](/docs/reference-guides/filters/block-filters.md#using-an-allow-list)（仅启用列表中的区块）或[拒绝列表](/docs/reference-guides/filters/block-filters.md#using-a-deny-list)（取消注册特定区块）。
|
||||
|
||||
## 管理标题层级
|
||||
|
||||
具有标题层级下拉菜单的WordPress核心区块支持`levelOptions`属性。这适用于标题、站点标题、站点标语、查询标题、文章标题和评论标题区块。`levelOptions`属性接受对应标题层级的数字数组，其中`1`代表H1，`2`代表H2，依此类推。
|
||||
|
||||
此属性允许您指定哪些标题层级应出现在下拉UI中，提供了一种轻量级的管理方法，无需弃用区块。现有标题层级会在标记中保留，而`levelOptions`仅影响UI显示。
|
||||
|
||||
您可以直接在区块标记中应用此属性，这种技术将常用于区块模板、模板部件和模式。例如，以下标记通过设置`"levelOptions":[3,4,5]`在标题区块中禁用H1、H2和H6。
|
||||
|
||||
```html
|
||||
<!-- wp:heading {"level":3,"levelOptions":[3,4,5],"className":"wp-block-heading"} -->
|
||||
<h3 class="wp-block-heading">标记示例</h3>
|
||||
<!-- /wp:heading -->
|
||||
```
|
||||
|
||||
您也可以使用[区块过滤器](/docs/reference-guides/filters/block-filters.md)全局或为特定区块设置此属性的默认值。以下示例为所有标题区块禁用H1、H2和H6。您可以通过基于用户权限等条件限制特定标题层级来进一步自定义。
|
||||
|
||||
```php
|
||||
function example_modify_heading_levels_globally( $args, $block_type ) {
|
||||
|
||||
if ( 'core/heading' !== $block_type ) {
|
||||
return $args;
|
||||
}
|
||||
|
||||
// 移除H1、H2和H6
|
||||
$args['attributes']['levelOptions']['default'] = [ 3, 4, 5 ];
|
||||
|
||||
return $args;
|
||||
}
|
||||
add_filter( 'register_block_type_args', 'example_modify_heading_levels_globally', 10, 2 );
|
||||
```
|
||||
|
||||
## 禁用模式目录
|
||||
|
||||
要从插入器中完全移除WordPress核心捆绑的模式，可将以下代码添加到您的`functions.php`文件：
|
||||
|
||||
```php
|
||||
function example_theme_support() {
|
||||
remove_theme_support( 'core-block-patterns' );
|
||||
}
|
||||
add_action( 'after_setup_theme', 'example_theme_support' );
|
||||
```
|
||||
|
||||
## 禁用区块变体
|
||||
|
||||
某些核心区块实际上是[区块变体](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-variations/)。一个很好的例子是行和堆栈区块，它们实际上是群组区块的变体。如果您想禁用这些"区块"，实际上需要禁用相应的变体。
|
||||
|
||||
区块变体使用JavaScript注册，需要使用JavaScript禁用。以下代码将禁用行变体。
|
||||
|
||||
```js
|
||||
wp.domReady( () => {
|
||||
wp.blocks.unregisterBlockVariation( 'core/group', 'group-row' );
|
||||
});
|
||||
```
|
||||
|
||||
假设代码放置在主题文件夹根目录的`disable-variations.js`文件中，您可以使用以下代码在主题的`functions.php`中加载此文件。
|
||||
|
||||
```php
|
||||
function example_disable_variations_script() {
|
||||
wp_enqueue_script(
|
||||
'example-disable-variations-script',
|
||||
get_template_directory_uri() . '/disable-variations.js',
|
||||
array( 'wp-dom-ready' ),
|
||||
wp_get_theme()->get( 'Version' ),
|
||||
true
|
||||
);
|
||||
}
|
||||
add_action( 'enqueue_block_editor_assets', 'example_disable_variations_script' );
|
||||
```
|
||||
|
||||
## 禁用区块样式
|
||||
|
||||
有几个核心区块包含自己的[区块样式](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-styles/)。例如图像区块包含一个名为"圆形"的圆角图像样式。您可能不希望用户使用圆形图像，或者更倾向于使用边框半径控件而非区块样式。无论哪种情况，都可以轻松禁用不需要的区块样式。
|
||||
|
||||
与区块变体不同，您可以使用JavaScript或PHP注册样式。如果样式是用JavaScript注册的，必须用JavaScript禁用。如果使用PHP注册，可以用任一方法禁用样式。所有核心区块样式都是用JavaScript注册的。
|
||||
|
||||
因此，您可以使用以下代码禁用图像区块的"圆形"样式。
|
||||
|
||||
```js
|
||||
wp.domReady( () => {
|
||||
wp.blocks.unregisterBlockStyle( 'core/image', 'rounded' );
|
||||
});
|
||||
```
|
||||
|
||||
此JavaScript的加载方式与上面的区块变体示例类似。有关使用PHP注册和取消注册样式的方法，请参阅[区块样式](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-styles/)文档。
|
||||
|
||||
## 禁用代码编辑器访问权限
|
||||
|
||||
代码编辑器允许您查看页面或文章的底层区块标记。虽然此视图对有经验的用户很方便，但编辑内容可能会意外破坏区块标记。将以下代码添加到`functions.php`文件以限制访问。
|
||||
|
||||
```php
|
||||
function example_restrict_code_editor_access( $settings, $context ) {
|
||||
$settings[ 'codeEditingEnabled' ] = false;
|
||||
|
||||
return $settings;
|
||||
}
|
||||
add_filter( 'block_editor_settings_all', 'example_restrict_code_editor_access', 10, 2 );
|
||||
```
|
||||
|
||||
此代码阻止所有用户访问代码编辑器。您也可以添加[权限](https://wordpress.org/documentation/article/roles-and-capabilities/)检查来为特定用户禁用访问。
|
||||
|
||||
## 禁用富文本区块的格式化选项
|
||||
|
||||
支持[富文本](https://developer.wordpress.org/block-editor/reference-guides/richtext/)的区块附带WordPress提供的默认格式化选项。
|
||||
|
||||
需要使用`unregisterFormatType`通过JavaScript禁用格式化选项。以下代码将全局禁用内联图像、语言、键盘输入、下标和上标选项。
|
||||
|
||||
```js
|
||||
wp.domReady( () => {
|
||||
wp.richText.unregisterFormatType( 'core/image' );
|
||||
wp.richText.unregisterFormatType( 'core/language' );
|
||||
wp.richText.unregisterFormatType( 'core/keyboard' );
|
||||
wp.richText.unregisterFormatType( 'core/subscript' );
|
||||
wp.richText.unregisterFormatType( 'core/superscript' );
|
||||
});
|
||||
```
|
||||
|
||||
此JavaScript的加载方式与上面的区块变体示例类似。
|
||||
@@ -0,0 +1,178 @@
|
||||
## 更多资源
|
||||
|
||||
- [如何使用服务器端过滤器修改 theme.json 数据](https://developer.wordpress.org/news/2023/07/05/how-to-modify-theme-json-data-using-server-side-filters/)（WordPress 开发者博客）
|
||||
- [通过客户端过滤器定制编辑器体验](https://developer.wordpress.org/news/2023/05/24/curating-the-editor-experience-with-client-side-filters/)（WordPress 开发者博客）
|
||||
|
||||
## 客户端（编辑器）过滤器
|
||||
|
||||
WordPress 6.2 引入了一个全新的客户端过滤器，允许您在编辑器渲染前修改区块层级的 [theme.json 设置](/docs/reference-guides/theme-json-reference/theme-json-living.md#settings)。
|
||||
|
||||
该过滤器名为 `blockEditor.useSetting.before`，可通过以下方式在 JavaScript 代码中使用：
|
||||
|
||||
```js
|
||||
import { addFilter } from '@wordpress/hooks';
|
||||
|
||||
/**
|
||||
* 将栏目区块的间距选项限制为像素单位。
|
||||
*/
|
||||
addFilter(
|
||||
'blockEditor.useSetting.before',
|
||||
'example/useSetting.before',
|
||||
( settingValue, settingName, clientId, blockName ) => {
|
||||
if ( blockName === 'core/column' && settingName === 'spacing.units' ) {
|
||||
return [ 'px' ];
|
||||
}
|
||||
return settingValue;
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
此示例将把栏目区块的可用间距单位限制为仅像素单位。如前所述，类似的限制也可以通过 theme.json 过滤器或直接在主题的 theme.json 文件中使用区块层级设置来实现。
|
||||
|
||||
但 `blockEditor.useSetting.before` 过滤器的独特之处在于，它允许您根据区块位置、相邻区块、当前用户角色等条件动态修改设置，定制可能性极为丰富。
|
||||
|
||||
下面这个示例展示了当标题区块被放置在「媒体与文本」区块内部时，会自动禁用其文字颜色控制功能：
|
||||
|
||||
```js
|
||||
import { select } from '@wordpress/data';
|
||||
import { addFilter } from '@wordpress/hooks';
|
||||
|
||||
/**
|
||||
* 当标题区块置于媒体与文本区块内时，禁用其文字颜色控制功能。
|
||||
*/
|
||||
addFilter(
|
||||
'blockEditor.useSetting.before',
|
||||
'example/useSetting.before',
|
||||
( settingValue, settingName, clientId, blockName ) => {
|
||||
if ( blockName === 'core/heading' ) {
|
||||
const { getBlockParents, getBlockName } = select( 'core/block-editor' );
|
||||
const blockParents = getBlockParents( clientId, true );
|
||||
const inMediaText = blockParents.some( ( ancestorId ) => getBlockName( ancestorId ) === 'core/media-text' );
|
||||
|
||||
if ( inMediaText && settingName === 'color.text' ) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
return settingValue;
|
||||
}
|
||||
);
|
||||
```
|
||||
|
||||
## 区块过滤器
|
||||
|
||||
除了优化编辑器界面外，您还可以通过多种方式修改单个区块。比如禁用特定区块支持功能（如背景色），或定义特定区块默认显示的设置项。
|
||||
|
||||
其中最常用的过滤器之一是 [`block_type_metadata`](https://developer.wordpress.org/reference/hooks/block_type_metadata/)。当区块类型在服务器端通过 PHP 注册时，该过滤器允许您拦截从区块 `block.json` 文件加载的原始元数据。
|
||||
|
||||
该过滤器接收一个参数：
|
||||
|
||||
- `$metadata` (`array`) – 从 `block.json` 加载的区块类型注册元数据。
|
||||
|
||||
`$metadata` 数组包含您可能需要了解的所有区块信息，从描述和[属性](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/)到区块[支持功能](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/)。
|
||||
|
||||
以下示例演示了如何禁用标题区块的背景色与渐变支持：
|
||||
|
||||
```php
|
||||
function example_disable_heading_background_color_and_gradients( $metadata ) {
|
||||
|
||||
// 仅对标题区块应用此过滤器
|
||||
if ( ! isset( $metadata['name'] ) || 'core/heading' !== $metadata['name'] ) {
|
||||
return $metadata;
|
||||
}
|
||||
|
||||
// 检查是否存在支持功能配置
|
||||
if ( isset( $metadata['supports'] ) && isset( $metadata['supports']['color'] ) ) {
|
||||
|
||||
// 移除背景色与渐变支持
|
||||
$metadata['supports']['color']['background'] = false;
|
||||
$metadata['supports']['color']['gradients'] = false;
|
||||
}
|
||||
|
||||
return $metadata;
|
||||
}
|
||||
add_filter( 'block_type_metadata', 'example_disable_heading_background_color_and_gradients' );
|
||||
```
|
||||
|
||||
您可以通过[区块过滤器文档](https://developer.wordpress.org/block-editor/reference-guides/filters/block-filters/)了解更多可用过滤器。
|
||||
|
||||
# 过滤器与钩子
|
||||
|
||||
编辑器提供了丰富的过滤器和钩子，让您可以自定义编辑体验。以下列举部分功能：
|
||||
|
||||
## 编辑器设置
|
||||
|
||||
最常见的编辑器修改方式是通过 [`block_editor_settings_all`](https://developer.wordpress.org/reference/hooks/block_editor_settings_all/) PHP 过滤器，该过滤器会在设置发送到初始化编辑器之前生效。
|
||||
|
||||
`block_editor_settings_all` 钩子会向回调函数传递两个参数：
|
||||
|
||||
- `$settings` - 编辑器[可配置设置](https://developer.wordpress.org/block-editor/reference-guides/filters/editor-filters/#editor-settings)的数组
|
||||
- `$context` - [`WP_Block_Editor_Context`](https://developer.wordpress.org/reference/classes/wp_block_editor_context/) 实例，包含当前编辑器信息的对象
|
||||
|
||||
以下示例将为无法激活插件的用户（管理员除外）禁用代码编辑器。将此代码添加到插件或主题的 `functions.php` 文件中进行测试：
|
||||
|
||||
```php
|
||||
add_filter( 'block_editor_settings_all', 'example_restrict_code_editor' );
|
||||
|
||||
function example_restrict_code_editor( $settings ) {
|
||||
$can_active_plugins = current_user_can( 'activate_plugins' );
|
||||
|
||||
// 对无法激活插件的用户禁用代码编辑器
|
||||
if ( ! $can_active_plugins ) {
|
||||
$settings[ 'codeEditingEnabled' ] = false;
|
||||
}
|
||||
|
||||
return $settings;
|
||||
}
|
||||
```
|
||||
|
||||
更多示例请参阅[编辑器钩子](https://developer.wordpress.org/block-editor/reference-guides/filters/editor-filters/)文档，包含以下用例：
|
||||
|
||||
- [设置默认图片尺寸](https://developer.wordpress.org/block-editor/reference-guides/filters/editor-filters/#set-a-default-image-size)
|
||||
- [禁用 Openverse](https://developer.wordpress.org/block-editor/reference-guides/filters/editor-filters/#disable-openverse)
|
||||
- [禁用字体库](https://developer.wordpress.org/block-editor/reference-guides/filters/editor-filters/#disable-the-font-library)
|
||||
- [禁用区块检查器标签页](https://developer.wordpress.org/block-editor/reference-guides/filters/editor-filters/#disable-block-inspector-tabs)
|
||||
|
||||
## 服务端 theme.json 过滤器
|
||||
|
||||
theme.json 文件是控制界面选项的重要方式，但它仅支持全局或区块层级的修改，在某些场景下可能受限。
|
||||
|
||||
例如在前述章节中，我们使用 theme.json 全局禁用了颜色和版式控制。但假设您需要为管理员用户启用颜色设置。
|
||||
|
||||
为提供更灵活的配置，WordPress 6.1 引入了服务端过滤器，允许在四个数据层自定义 theme.json 数据：
|
||||
|
||||
- [`wp_theme_json_data_default`](https://developer.wordpress.org/reference/hooks/wp_theme_json_data_default/) - 挂钩 WordPress 提供的默认数据
|
||||
- [`wp_theme_json_data_blocks`](https://developer.wordpress.org/reference/hooks/wp_theme_json_data_blocks/) - 挂钩区块提供的数据
|
||||
- [`wp_theme_json_data_theme`](https://developer.wordpress.org/reference/hooks/wp_theme_json_data_theme/) - 挂钩当前主题提供的数据
|
||||
- [`wp_theme_json_data_user`](https://developer.wordpress.org/reference/hooks/wp_theme_json_data_user/) - 挂钩用户提供的数据
|
||||
|
||||
以下示例使用 `wp_theme_json_data_theme` 过滤器更新当前主题的 theme.json 数据。如果当前用户是管理员，则会恢复颜色控制功能：
|
||||
|
||||
```php
|
||||
// 为除管理员外的所有用户禁用颜色控制
|
||||
function example_filter_theme_json_data_theme( $theme_json ){
|
||||
$is_administrator = current_user_can( 'edit_theme_options' );
|
||||
|
||||
if ( $is_administrator ) {
|
||||
$new_data = array(
|
||||
'version' => 2,
|
||||
'settings' => array(
|
||||
'color' => array(
|
||||
'background' => true,
|
||||
'custom' => true,
|
||||
'customDuotone' => true,
|
||||
'customGradient' => true,
|
||||
'defaultGradients' => true,
|
||||
'defaultPalette' => true,
|
||||
'text' => true,
|
||||
),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
return $theme_json->update_with( $new_data );
|
||||
}
|
||||
add_filter( 'wp_theme_json_data_theme', 'example_filter_theme_json_data_theme' );
|
||||
```
|
||||
|
||||
该过滤器会接收到包含对应数据层数据的 `WP_Theme_JSON_Data` 类实例。随后您需要向 `update_with( $new_data )` 方法传入符合 theme.json 规范的新数据。注意 `$new_data` 中必须包含 theme.json 版本号。
|
||||
@@ -0,0 +1,90 @@
|
||||
# 模式
|
||||
|
||||
区块[模式](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-patterns/)是为用户提供独特定制编辑体验的最佳方式之一。
|
||||
|
||||
## 为所有文章类型优先设置起始模式
|
||||
|
||||
当用户创建新内容时，无论文章类型如何，都会面对一个空白画布。然而，通过设置特定类型的模式在创建新内容时优先显示，可以改善这一体验。当网站中存在声明支持`core/post-content`区块类型的模式时，用户每次创建新项目都会出现模态窗口。默认情况下，WordPress不包含任何此类模式，因此除非至少添加了两个此类文章内容模式，否则模态窗口不会出现。
|
||||
|
||||
要启用此功能，请在模式的区块类型中包含`core/post-content`。然后，可以通过文章类型选项控制模式应显示的文章类型。以下是一个在创建新文章时出现的模式示例：
|
||||
|
||||
```php
|
||||
<?php
|
||||
/**
|
||||
* 标题：新活动公告
|
||||
* 别名：twentytwentytwo/new-event-announcement
|
||||
* 区块类型：core/post-content
|
||||
* 文章类型：post
|
||||
* 分类：featured, text
|
||||
*/
|
||||
?>
|
||||
|
||||
<!-- wp:heading {"lock":{"move":false,"remove":true}} -->
|
||||
<h2>详情</h2>
|
||||
<!-- /wp:heading -->
|
||||
|
||||
<!-- wp:heading {"lock":{"move":false,"remove":true}} -->
|
||||
<h2>路线指引</h2>
|
||||
<!-- /wp:heading -->
|
||||
|
||||
<!-- wp:heading {"lock":{"move":false,"remove":true}} -->
|
||||
<h2>预约确认</h2>
|
||||
<!-- /wp:heading -->
|
||||
|
||||
<!-- wp:paragraph {"lock":{"move":true,"remove":true}} -->
|
||||
<p>如需确认预约，请加入Make Slack中的#fse-outreach-experiment频道。</p>
|
||||
<!-- /wp:paragraph -->
|
||||
|
||||
<!-- wp:buttons -->
|
||||
<div class="wp-block-buttons"><!-- wp:button {"lock":{"move":true,"remove":false}} -->
|
||||
<div class="wp-block-button"><a class="wp-block-button__link wp-element-button">了解更多</a></div>
|
||||
<!-- /wp:button --></div>
|
||||
<!-- /wp:buttons -->
|
||||
|
||||
<!-- wp:cover {"useFeaturedImage":true,"dimRatio":80,"overlayColor":"primary","contentPosition":"center center","align":"full"} -->
|
||||
<div class="wp-block-cover alignfull"><span aria-hidden="true" class="wp-block-cover__background has-primary-background-color has-background-dim-80 has-background-dim"></span><div class="wp-block-cover__inner-container"><!-- wp:paragraph {"align":"center","placeholder":"输入标题…","fontSize":"large"} -->
|
||||
<p class="has-text-align-center has-large-font-size">期待您的参与！</p>
|
||||
<!-- /wp:paragraph --></div></div>
|
||||
<!-- /wp:cover -->
|
||||
```
|
||||
|
||||
在[WordPress 6.0开发说明中的页面创建模式](https://make.wordpress.org/core/2022/05/03/page-creation-patterns-in-wordpress-6-0/)中了解更多关于此功能的信息，并[注意WordPress 6.1将此功能扩展到所有文章类型](https://make.wordpress.org/core/2022/10/10/miscellaneous-editor-changes-for-wordpress-6-1/#start-content-patterns-for-all-post-types)。
|
||||
|
||||
## 为模板创建优先设置起始模式
|
||||
|
||||
与为新文章或页面优先设置模式类似，同样的体验可以添加到模板创建过程中。当模式声明支持'templateTypes'属性时，只要创建了符合指定条件的模板，这些模式就会出现，同时提供从空白状态开始或使用当前模板回退选项的选择。默认情况下，WordPress不包含任何此类模式。
|
||||
|
||||
要启用此功能，模式需要指定一个名为`templateTypes`的属性，这是一个包含可使用该模式作为完整内容的模板数组。以下是一个在创建404模板时出现的模式示例：
|
||||
|
||||
```php
|
||||
register_block_pattern(
|
||||
'wp-my-theme/404-template-pattern',
|
||||
array(
|
||||
'title' => __( '404专用模板模式', 'wp-my-theme' ),
|
||||
'templateTypes' => array( '404' ),
|
||||
'content' => '<!-- wp:paragraph {"align":"center","fontSize":"x-large"} --><p class="has-text-align-center has-x-large-font-size">404模式</p><!-- /wp:paragraph -->',
|
||||
)
|
||||
);
|
||||
```
|
||||
|
||||
在[WordPress 6.3开发说明中的新建模板模态窗口模式](https://make.wordpress.org/core/2023/07/18/miscellaneous-editor-changes-in-wordpress-6-3/#patterns-on-the-create-a-new-template-modal)中了解更多关于此功能的信息。
|
||||
|
||||
## 锁定模式
|
||||
|
||||
如先前关于锁定API的部分所述，模式本身的某些方面可以被锁定，以保护设计的重要部分。[这里有一个模式示例](https://gist.github.com/annezazu/acee30f8b6e8995e1b1a52796e6ef805)，其中包含以不同方式锁定的各种区块。您可以在编辑器中构建这些模式，包括添加锁定选项，然后[按照文档注册它们](/docs/reference-guides/block-api/block-patterns.md)。
|
||||
|
||||
## 从模式目录中优先选择特定模式
|
||||
|
||||
从WordPress 6.0开始，主题可以通过theme.json从[模式目录](https://wordpress.org/patterns/)注册模式。为实现这一点，主题应使用theme.json中新的patterns顶级键。在此字段中，主题可以列出要从模式目录注册的模式。patterns字段是模式目录中模式别名的数组。模式别名可以从模式目录中单个模式视图的URL中提取。例如：此URL https://wordpress.org/patterns/pattern/partner-logos 的别名是partner-logos。
|
||||
|
||||
```json
|
||||
{
|
||||
"patterns": [ "short-text-surrounded-by-round-images", "partner-logos" ]
|
||||
}
|
||||
```
|
||||
|
||||
内容创建者随后将在插入器的“模式”选项卡中，找到与模式目录分类匹配的相应模式。
|
||||
|
||||
## 附加资源
|
||||
|
||||
- [使用模板模式构建多个首页设计](https://developer.wordpress.org/news/2023/04/13/using-template-patterns-to-build-multiple-homepage-designs/)（WordPress开发者博客）
|
||||
206
docs/how-to-guides/curating-the-editor-experience/theme-json.md
Normal file
206
docs/how-to-guides/curating-the-editor-experience/theme-json.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# theme.json
|
||||
|
||||
主题的 theme.json 文件是定制编辑器体验的最佳方式之一，很可能是在使用更复杂解决方案之前最先用到的工具。
|
||||
|
||||
## 提供默认控件/选项
|
||||
|
||||
由于 theme.json 作为配置工具，可通过多种方式精细定义可用选项。本节将以双色调为例进行说明，该功能横跨多个区块并支持不同层级的访问权限。
|
||||
|
||||
*为所有图片相关区块启用核心双色调选项和自定义功能：*
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 3,
|
||||
"settings": {
|
||||
"color": {
|
||||
"customDuotone": true,
|
||||
"duotone": [
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
*为所有图片相关区块提供主题预定义色彩选项、核心选项及自定义功能：*
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 3,
|
||||
"settings": {
|
||||
"color": {
|
||||
"duotone": [
|
||||
{
|
||||
"colors": [ "#000000", "#ffffff" ],
|
||||
"slug": "foreground-and-background",
|
||||
"name": "前景色与背景色"
|
||||
},
|
||||
{
|
||||
"colors": [ "#000000", "#ff0200" ],
|
||||
"slug": "foreground-and-secondary",
|
||||
"name": "前景色与辅助色"
|
||||
},
|
||||
{
|
||||
"colors": [ "#000000", "#7f5dee" ],
|
||||
"slug": "foreground-and-tertiary",
|
||||
"name": "前景色与第三色"
|
||||
},
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
*为文章特色图片区块提供预定义默认选项并开放全部自定义功能：*
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 3,
|
||||
"settings": {
|
||||
"color": {
|
||||
"custom": true,
|
||||
"customDuotone": true
|
||||
},
|
||||
"blocks": {
|
||||
"core/post-featured-image": {
|
||||
"color": {
|
||||
"duotone": [
|
||||
{
|
||||
"colors": [ "#282828", "#ff5837" ],
|
||||
"slug": "black-and-orange",
|
||||
"name": "黑橙配色"
|
||||
},
|
||||
{
|
||||
"colors": [ "#282828", "#0288d1" ],
|
||||
"slug": "black-and-blue",
|
||||
"name": "黑蓝配色"
|
||||
}
|
||||
],
|
||||
"customDuotone": true,
|
||||
"custom": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
*为文章特色图片区块仅提供预定义默认选项和核心选项（禁用自定义功能）：*
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 3,
|
||||
"settings": {
|
||||
"color": {
|
||||
"custom": true,
|
||||
"customDuotone": true
|
||||
},
|
||||
"blocks": {
|
||||
"core/post-featured-image": {
|
||||
"color": {
|
||||
"duotone": [
|
||||
{
|
||||
"colors": [ "#282828", "#ff5837" ],
|
||||
"slug": "black-and-orange",
|
||||
"name": "黑橙配色"
|
||||
},
|
||||
{
|
||||
"colors": [ "#282828", "#0288d1" ],
|
||||
"slug": "black-and-blue",
|
||||
"name": "黑蓝配色"
|
||||
}
|
||||
],
|
||||
"customDuotone": false,
|
||||
"custom": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 使用 theme.json 限制界面选项
|
||||
|
||||
### 按区块限制选项
|
||||
|
||||
除了定义默认值，使用 theme.json 还可以完全移除某些选项，转而依赖主题预设配置。下图直观展示了同一段落区块的两种极端设置：
|
||||
|
||||
|
||||
|
||||
延续双色调的示例，这意味着您可以对图片区块开放全部双色调功能，而仅限制文章特色图片区块的权限：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 3,
|
||||
"settings": {
|
||||
"color": {
|
||||
"custom": true,
|
||||
"customDuotone": true
|
||||
},
|
||||
"blocks": {
|
||||
"core/image": {
|
||||
"color": {
|
||||
"duotone": [],
|
||||
"customDuotone": true,
|
||||
"custom": true
|
||||
}
|
||||
},
|
||||
"core/post-featured-image": {
|
||||
"color": {
|
||||
"duotone": [],
|
||||
"customDuotone": false,
|
||||
"custom": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
您可阅读[此文档](/docs/how-to-guides/themes/global-settings-and-styles.md)深入了解如何通过 theme.json 启用/禁用选项。
|
||||
|
||||
### 禁用继承默认布局
|
||||
|
||||
如需对群组区块等容器区块禁用“继承默认布局”设置，请移除以下配置段：
|
||||
|
||||
```json
|
||||
"layout": {
|
||||
"contentSize": null,
|
||||
"wideSize": null
|
||||
},
|
||||
```
|
||||
|
||||
### 全局限制选项
|
||||
|
||||
在区块主题或经典主题中使用 theme.json 时，以下设置将全局禁用默认颜色与排版控件，大幅限制可用功能：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 3,
|
||||
"settings": {
|
||||
"layout": {
|
||||
"contentSize": "750px"
|
||||
},
|
||||
"color": {
|
||||
"background": false,
|
||||
"custom": false,
|
||||
"customDuotone": false,
|
||||
"customGradient": false,
|
||||
"defaultGradients": false,
|
||||
"defaultPalette": false,
|
||||
"text": false
|
||||
},
|
||||
"typography": {
|
||||
"customFontSize": false,
|
||||
"dropCap": false,
|
||||
"fontStyle": false,
|
||||
"fontWeight": false,
|
||||
"letterSpacing": false,
|
||||
"lineHeight": false,
|
||||
"textDecoration": false,
|
||||
"textTransform": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
若需启用上述某项功能，只需将对应值改为 `true` 即可实现更精细的控制。
|
||||
Reference in New Issue
Block a user