组件
每次构建时,Blockstudio都会附带 59 个UI组件。它们会自动注册,使用设计令牌设置样式,并采用与其他区块相同的标签语法编写。
Blockstudio 7.3 随附一组由 WordPress 交互性 API 提供支持的无头 UI 区块。它们注册在 bsui/* 命名空间下,可在模板、基于文件的页面、模式和文章内容中组合使用。
注意
UI 组件目前处于测试阶段,我们正在收集有关组件集合、命名、行为和项目使用模式的反馈。它们已可在 7.3 中试用,但在标记为稳定版之前,API 表面可能还会调整。
启用 UI 组件
随附的 UI 组件需选择启用。可在主题的 blockstudio.json 中启用:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"ui": {
"enabled": true
}
}
也可以使用过滤器启用:
add_filter('blockstudio/settings/ui/enabled', '__return_true');
启用后,Blockstudio 会从 includes/ui/blocks 注册随附的组件库。
公共清单和示例
随附的实现区块仍是普通的 bsui/* 注册项,但构建组件图库时,使用者应采用公共组件系列清单:
use Blockstudio\Ui;
$families = Ui::inventory();
$examples = Ui::examples();
Ui::inventory() 会按公共根组件归类所有复合组件,并列出该组件系列所需的实现注册项。Ui::examples() 会添加一份经过规范化、顺序确定的声明,其中包含默认数据和示例数据。它会保留必需的根组件与子组件关系,因此结果可以直接传给 Blockstudio\Render::document()。
公共 Canvas 清单会在其 ui 类型中公开这些示例,并从常规 blocks 类型中省略随附的实现注册项。这样,每个公共组件系列都会有一个完整示例,而不是由内部根组件、触发器、弹出层和分层片段组成的图库。
组装已渲染的文档时,Ui::global_assets($block_names, $html) 仅当所选输出实际使用 UI 组件时,才会返回其对应的随附全局样式和脚本。
渲染
使用常规区块标签语法:
<block name="bsui/button" label="Save" variant="default"></block>
较短的 <bs:> 语法也可以使用:
<bs:bsui-button label="Save" variant="default" />
在 Blockstudio 模板中,区块标签会自动渲染。在基于文件的页面和模式中,它们会同步为原生 WordPress 区块。如果要从文章内容或小工具区域直接渲染 UI 组件,请启用页面级区块标签:
{
"ui": {
"enabled": true
},
"blockTags": {
"enabled": true,
"allow": ["bsui/*", "app/*"]
}
}
基础组件
简单组件会渲染为单个区块:
<block name="bsui/button" label="Continue" variant="default"></block>
<block name="bsui/badge" label="Beta"></block>
<block
name="bsui/input"
nameAlt="email"
type="email"
placeholder="Email"
></block>
<block name="bsui/textarea" name="message" placeholder="Message"></block>
<block name="bsui/spinner"></block>
属性会直接映射到各组件的 block.json 属性。例如,bsui/button 支持 label、icon、iconPosition、href、variant、size 和 disabled。
bs_render_block([
'name' => 'bsui/button',
'data' => [
'label' => 'Continue',
'icon' => [
'set' => 'heroicons',
'subSet' => 'outline',
'icon' => 'arrow-right',
],
'iconPosition' => 'right',
],
]);
复合组件
许多 UI 组件都是复合区块。根区块负责管理状态,子区块则声明其父区块。
选项卡
<block name="bsui/tabs" defaultValue="tab1">
<block name="bsui/tabs-list">
<block name="bsui/tabs-trigger" value="tab1" title="Features"></block>
<block name="bsui/tabs-trigger" value="tab2" title="Pricing"></block>
<block name="bsui/tabs-trigger" value="tab3" title="FAQ"></block>
</block>
<block name="bsui/tabs-panel" value="tab1">
<p>Features content.</p>
</block>
<block name="bsui/tabs-panel" value="tab2">
<p>Pricing content.</p>
</block>
<block name="bsui/tabs-panel" value="tab3">
<p>FAQ content.</p>
</block>
</block>
对话框
<block name="bsui/dialog">
<block name="bsui/dialog-trigger" label="Open Dialog"></block>
<block name="bsui/dialog-backdrop"></block>
<block name="bsui/dialog-popup">
<p>Dialog content.</p>
<block name="bsui/dialog-close" label="Close"></block>
</block>
</block>
下拉选择框
<block name="bsui/select" placeholder="Choose a fruit" nameAlt="fruit">
<block name="bsui/select-trigger"></block>
<block name="bsui/select-popup">
<block name="bsui/select-option" value="apple" label="Apple"></block>
<block name="bsui/select-option" value="banana" label="Banana"></block>
<block name="bsui/select-option" value="cherry" label="Cherry"></block>
</block>
</block>
表单字段
<block name="bsui/form" block="contact/form" successMessage="Thank you!">
<block name="bsui/field">
<block name="bsui/field-label" text="Email"></block>
<block name="bsui/input" nameAlt="email" type="email"></block>
<block name="bsui/field-error"></block>
</block>
</block>
可用区块
随附的 UI 库包括:
| 区域 | 区块 |
|---|---|
| 布局 | bsui/aspect-ratio、bsui/card、bsui/separator、bsui/stack、bsui/table |
| 操作 | bsui/button、bsui/button-group、bsui/toggle、bsui/toggle-group、bsui/toolbar |
| 输入 | bsui/checkbox、bsui/color-picker、bsui/date-input、bsui/file-upload、bsui/input、bsui/number-field、bsui/otp-input、bsui/password-input、bsui/phone-input、bsui/radio-group、bsui/rating、bsui/select、bsui/slider、bsui/switch、bsui/textarea、bsui/time-picker |
| 覆盖层 | bsui/alert-dialog、bsui/dialog、bsui/drawer、bsui/menu、bsui/menubar、bsui/popover、bsui/preview-card、bsui/tooltip |
| 导航 | bsui/accordion、bsui/breadcrumb、bsui/carousel、bsui/collapsible、bsui/context-menu、bsui/navigation-menu、bsui/pagination、bsui/tabs |
| 反馈 | bsui/badge、bsui/kbd、bsui/meter、bsui/progress、bsui/skeleton、bsui/spinner、bsui/text、bsui/toast |
| 表单 | bsui/field、bsui/field-group、bsui/form |
复合组件还会公开一些子区块,例如 bsui/dialog-trigger、bsui/dialog-popup、bsui/tabs-list、bsui/tabs-trigger、bsui/tabs-panel、bsui/select-trigger、bsui/select-popup 和 bsui/select-option。
样式
UI 组件自带 CSS 自定义属性,使用 --bs-ui-* 前缀。你可以在主题 CSS 中覆盖它们:
:root {
--bs-ui-radius: 0.5rem;
--bs-ui-primary: oklch(0.45 0.18 260);
--bs-ui-primary-foreground: white;
}
这些组件在行为上没有预设样式,但默认设置足够完善,开箱即可使用。先覆盖令牌,再根据需要添加组件专属的 CSS。
随附组件 CSS 会输出到指定的 bsui 级联层中。未分层的主题 CSS 可直接覆盖组件规则,无需 !important:
.button-brand {
background: var(--brand-primary);
}
要添加自定义 bsui/button 变体,请使用现有属性过滤器追加一个下拉选择选项,并通过 blockstudio/ui/button/variants-style 提供该变体的 CSS:
add_filter('blockstudio/blocks/attributes', function($attribute, $block) {
if (($block['name'] ?? '') === 'bsui/button' && ($attribute['id'] ?? '') === 'variant') {
$attribute['options'][] = [
'label' => 'Brand',
'value' => 'brand',
];
}
return $attribute;
}, 10, 2);
add_filter('blockstudio/ui/button/variants-style', function($css) {
return $css . '
[data-bsui-button][data-variant="brand"] {
background: var(--brand-primary);
color: white;
}';
});