142 lines
5.6 KiB
Markdown
142 lines
5.6 KiB
Markdown
# 样式
|
||
|
||
区块样式允许为现有区块应用替代样式。其实现原理是向区块包装器添加 className。当用户选中某个区块样式时，该 className 可用于为区块提供替代样式。关于如何为区块应用样式的完整示例，请参阅[使用样式和样式表](/docs/how-to-guides/block-tutorial/applying-styles-with-stylesheets.md)。
|
||
|
||
_示例：_
|
||
|
||
```js
|
||
wp.blocks.registerBlockStyle( 'core/quote', {
|
||
name: 'fancy-quote',
|
||
label: '花式引用',
|
||
} );
|
||
```
|
||
|
||
以上示例为 `core/quote` 区块注册了名为 `fancy-quote` 的区块样式。当用户从样式选择器中选中此区块样式时，区块包装器将添加 `is-style-fancy-quote` 的 className。
|
||
|
||
通过设置 `isDefault: true`，可将注册的区块样式标记为未提供自定义类名时的默认激活样式。这也意味着标记为默认的样式不会在 HTML 输出中添加自定义类名。
|
||
|
||
如需移除区块样式，请使用 `wp.blocks.unregisterBlockStyle()`。
|
||
|
||
_示例：_
|
||
|
||
```js
|
||
wp.blocks.unregisterBlockStyle( 'core/quote', 'large' );
|
||
```
|
||
|
||
以上代码将从 `core/quote` 区块中移除名为 `large` 的区块样式。
|
||
|
||
**重要提示：** 在取消注册区块样式时，可能存在[竞态条件](https://en.wikipedia.org/wiki/Race_condition)——注册样式和取消注册样式的代码执行顺序不确定。为确保取消注册代码最后执行，需将注册样式的组件（本例中为 `wp-edit-post`）指定为依赖项。此外，使用 `wp.domReady()` 可确保取消注册代码在 DOM 加载完成后执行。
|
||
|
||
通过以下 PHP 代码加载你的 JavaScript：
|
||
|
||
```php
|
||
function myguten_enqueue() {
|
||
wp_enqueue_script(
|
||
'myguten-script',
|
||
plugins_url( 'myguten.js', __FILE__ ),
|
||
array( 'wp-blocks', 'wp-dom-ready', 'wp-edit-post' ),
|
||
filemtime( plugin_dir_path( __FILE__ ) . '/myguten.js' )
|
||
);
|
||
}
|
||
add_action( 'enqueue_block_editor_assets', 'myguten_enqueue' );
|
||
```
|
||
|
||
`myguten.js` 中的 JavaScript 代码：
|
||
|
||
```js
|
||
wp.domReady( function () {
|
||
wp.blocks.unregisterBlockStyle( 'core/quote', 'large' );
|
||
} );
|
||
```
|
||
|
||
## 服务端注册辅助函数
|
||
|
||
虽然提供的示例能完全控制区块样式，但需要编写大量代码。
|
||
|
||
为简化注册和取消注册区块样式的流程，还提供了两个服务端函数：`register_block_style` 和 `unregister_block_style`。
|
||
|
||
### register_block_style
|
||
|
||
`register_block_style` 函数的第一个参数接收区块名称，第二个参数接收描述样式属性的数组。
|
||
|
||
样式数组的属性必须包含 `name` 和 `label`：
|
||
|
||
- `name`：用于计算 CSS 类的样式标识符
|
||
- `label`：用户可读的样式标签
|
||
|
||
除了这两个必需属性外，样式属性数组还应包含 `inline_style`、`style_handle` 或 `style_data` 属性之一：
|
||
|
||
- `inline_style`：包含注册样式所需 CSS 类的内联 CSS 代码
|
||
- `style_handle`：包含已注册样式句柄，该样式将在需要区块样式的地方被加载
|
||
- `style_data`：包含 theme.json 风格的样式属性数组（自 WordPress 6.6 起可用）
|
||
|
||
还可以将 `is_default` 属性设置为 `true`，将某个区块样式标记为默认样式。
|
||
|
||
以下代码示例为引用区块注册名为“蓝色引用”的样式，并提供内联样式使采用“蓝色引用”样式的引用区块显示为蓝色：
|
||
|
||
```php
|
||
register_block_style(
|
||
'core/quote',
|
||
array(
|
||
'name' => 'blue-quote',
|
||
'label' => __( '蓝色引用', 'textdomain' ),
|
||
'inline_style' => '.wp-block-quote.is-style-blue-quote { color: blue; }',
|
||
)
|
||
);
|
||
```
|
||
|
||
如果已注册包含区块样式 CSS 的样式表，只需传递样式表句柄，`register_block_style` 函数将确保其被加载：
|
||
|
||
```php
|
||
wp_register_style( 'myguten-style', get_template_directory_uri() . '/custom-style.css' );
|
||
|
||
// ...
|
||
|
||
register_block_style(
|
||
'core/quote',
|
||
array(
|
||
'name' => 'fancy-quote',
|
||
'label' => __( '花式引用', 'textdomain' ),
|
||
'style_handle' => 'myguten-style',
|
||
)
|
||
);
|
||
```
|
||
|
||
另一种方式是使用 `style_data` 属性（如下例），为图片区块添加带橙色边框和微圆角的样式：
|
||
|
||
```php
|
||
register_block_style(
|
||
array( 'core/image' ),
|
||
array(
|
||
'name' => 'orange-border',
|
||
'label' => __( '橙色边框', 'pauli' ),
|
||
'style_data'=> array(
|
||
'border' => array(
|
||
'color' => '#f5bc42',
|
||
'style' => 'solid',
|
||
'width' => '4px',
|
||
'radius' => '15px'
|
||
)
|
||
)
|
||
)
|
||
);
|
||
```
|
||
|
||
使用 `style_data` 属性允许用户通过**编辑器 > 样式**中的全局样式界面进行修改。该属性自 WordPress 6.6 版本开始提供。
|
||
|
||
更多信息请参阅 WordPress 6.6 开发说明：[区块样式章节](https://make.wordpress.org/core/2024/06/24/section-styles/)。
|
||
另见 WordPress 开发者博客：[在 WordPress 6.6 中使用区块样式变体为区块区域、嵌套元素等设置样式](https://developer.wordpress.org/news/2024/06/styling-sections-nested-elements-and-more-with-block-style-variations-in-wordpress-6-6/)。
|
||
|
||
### unregister_block_style
|
||
|
||
`unregister_block_style` 用于取消注册之前通过 `register_block_style` 在服务端注册的区块样式。
|
||
|
||
函数的第一个参数是区块的注册名称，第二个参数是样式名称。
|
||
|
||
以下代码示例从引用区块中取消注册名为 'fancy-quote' 的样式：
|
||
|
||
```php
|
||
unregister_block_style( 'core/quote', 'fancy-quote' );
|
||
```
|
||
|
||
**重要说明：** `unregister_block_style` 函数仅取消注册通过 `register_block_style` 在服务端注册的样式，不会取消注册通过客户端代码注册的样式。 |