跳转到正文

组件

每次构建时,Blockstudio都会附带 59 个UI组件。它们会自动注册,使用设计令牌设置样式,并采用与其他区块相同的标签语法编写。

Blockstudio 7.3 随附一组由 WordPress 交互性 API 提供支持的无头 UI 区块。它们注册在 bsui/* 命名空间下,可在模板、基于文件的页面、模式和文章内容中组合使用。

注意

UI 组件目前处于测试阶段,我们正在收集有关组件集合、命名、行为和项目使用模式的反馈。它们已可在 7.3 中试用,但在标记为稳定版之前,API 表面可能还会调整。

启用 UI 组件

随附的 UI 组件需选择启用。可在主题的 blockstudio.json 中启用:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "ui": {
    "enabled": true
  }
}

也可以使用过滤器启用:

PHP
add_filter('blockstudio/settings/ui/enabled', '__return_true');

启用后,Blockstudio 会从 includes/ui/blocks 注册随附的组件库。

公共清单和示例

随附的实现区块仍是普通的 bsui/* 注册项,但构建组件图库时,使用者应采用公共组件系列清单:

PHP
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 组件时,才会返回其对应的随附全局样式和脚本。

渲染

使用常规区块标签语法:

HTML
<block name="bsui/button" label="Save" variant="default"></block>

较短的 <bs:> 语法也可以使用:

HTML
<bs:bsui-button label="Save" variant="default" />

在 Blockstudio 模板中,区块标签会自动渲染。在基于文件的页面和模式中,它们会同步为原生 WordPress 区块。如果要从文章内容或小工具区域直接渲染 UI 组件,请启用页面级区块标签:

JSON
{
  "ui": {
    "enabled": true
  },
  "blockTags": {
    "enabled": true,
    "allow": ["bsui/*", "app/*"]
  }
}

基础组件

简单组件会渲染为单个区块:

HTML
<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。

PHP
bs_render_block([
  'name' => 'bsui/button',
  'data' => [
    'label' => 'Continue',
    'icon' => [
      'set' => 'heroicons',
      'subSet' => 'outline',
      'icon' => 'arrow-right',
    ],
    'iconPosition' => 'right',
  ],
]);

复合组件

许多 UI 组件都是复合区块。根区块负责管理状态,子区块则声明其父区块。

选项卡

HTML
<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>

对话框

HTML
<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>

下拉选择框

HTML
<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>

表单字段

HTML
<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 中覆盖它们:

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:

CSS
.button-brand {
  background: var(--brand-primary);
}

要添加自定义 bsui/button 变体,请使用现有属性过滤器追加一个下拉选择选项,并通过 blockstudio/ui/button/variants-style 提供该变体的 CSS:

PHP
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;
}';
});

所有组件

手风琴 纵向堆叠的区段,每次展开一个面板。 警告对话框 会打断当前流程、必须先作答才能关闭的模态框。 宽高比 将内容锁定为固定的宽高比。 头像 加载失败时会回退显示姓名首字母的用户图片。 徽标 用于显示状态、数量和类别的小标签。 面包屑 显示当前页面在层级结构中的位置。 按钮 触发操作,并提供适用于不同强调程度的变体。 按钮组 将相关按钮组合成一个分段控件。 日历 用于选择单日的日期网格。 卡片 用于组合页眉、主体和页脚的容器。 轮播 支持键盘操作的可滑动幻灯片轨道。 复选框 支持不确定状态的二元选择控件。 可折叠区域 隐藏或显示单个内容区域。 颜色选择器 选择颜色,并将其与周围表单一起提交。 组合框 输入文字时筛选选项列表的文本输入框。 上下文菜单 右键时显示并锚定在指针位置的操作菜单。 日期输入框 无需日期选择器即可输入日期的掩码字段。 对话框 用于聚焦任务和确认操作的模态层。 抽屉 从屏幕任意边缘滑入的面板。 字段 将控件与其标签、说明和错误信息组合在一起。 字段组 在共同标题下归组相关字段。 文件上传 支持多文件的拖放区域和文件选择器。 表单 提交字段并报告成功,无需重新加载页面。 输入 适用于各种常见输入类型的单行文本字段。 键盘快捷键 将键盘快捷键显示在独立的按键帽中。 标签 供所有带标签组件共用的控件说明。 菜单 锚定在触发器上的操作下拉列表。 菜单栏 类似桌面应用程序的水平菜单栏。 仪表 在已知范围内显示测量值。 导航菜单 带嵌套链接和悬停面板的网站导航。 数字字段 带步进按钮和范围限制的数字输入框。 一次性密码输入框 用于输入一次性密码的分格输入框。 分页 带有上一页、下一页和省略号的页面链接。 密码输入框 带显示切换按钮的密码字段。 电话号码输入框 带国家/地区选择和格式设置的电话字段。 弹出框 锚定在触发器上的富内容,点击外部区域即可关闭。 预览卡片 悬停时预览链接目标的卡片。 进度 显示任务进度。 单选按钮组 一组选项中只能选择一个。 评分 用于评分的星级控件。 滚动区域 带样式化覆盖滚动条的滚动容器。 选择 用于从选项列表中进行选择的下拉菜单。 分隔线 用于分隔内容或控件组的线条。 骨架屏 内容加载时显示的占位形状。 滑块 沿轨道拖动以选择一个值或一个范围。 间距 来自间距刻度的固定垂直节奏步长。 加载指示器 表示正在进行的工作,时长未知。 堆叠布局 以一致的间距将子元素排列成行或列。 开关 切换一项会立即生效的设置。 表格 支持可选排序和隔行样式的表格数据。 标签页 在占据同一空间的面板之间切换。 Text 以指定尺寸和语义标签呈现文本内容。 文本域 会随行数增长的多行文本字段。 时间选择器 按指定步长选择一天中的时间。 Toast 提供器 在屏幕角落显示临时通知。 切换按钮 按下后保持按压状态以表示开启的按钮。 切换组 一组可执行单选或多选的切换控件。 工具栏 一排控件,焦点可在其中依次移动。 工具提示 悬停或聚焦时显示的简短提示。