跳转到正文

组件

组合

内置UI组件是为组合使用而设计的,不适合单独使用。选择框会在对话框中打开,表单会在抽屉面板中验证,菜单则位于表格行内。本页将说明让这些部分协同工作的机制:复合组件族的结构、触发器如何转发按钮属性、交互性 API 在底层的作用,以及让层叠界面保持协调的分层模型。

复合组件族

复合组件由一个根区块和子区块组成。根区块管理状态;每个子区块通过其 parent 和 usesContext 在 block.json 中声明自己在组件族中的位置:

JSON
{
  "name": "bsui/select-option",
  "parent": ["bsui/select-popup"],
  "usesContext": ["bsui/select"]
}

根区块会提供一个 InnerBlocks 区域,其中包含一个 allowedBlocks 列表和起始 template。因此,在编辑器中插入对话框时,会自动搭建其触发器、背景遮罩和弹出层;无论是在编辑器、基于文件的页面还是标签中组合,组件族的行为都一致:

HTML
<bs:bsui-select name="role" placeholder="Pick a role">
  <bs:bsui-select-trigger />
  <bs:bsui-select-popup>
    <bs:bsui-select-option value="viewer" label="Viewer" />
    <bs:bsui-select-option value="editor" label="Editor" />
  </bs:bsui-select-popup>
</bs:bsui-select>

弹出层和面板都是真正的 InnerBlocks 区域,不是带有特殊语法的插槽。bsui/dialog-popup 接受嵌套区块的方式与组区块相同,因此可以在其中放置表单、选择框或另一个对话框,组合起来就像普通操作一样简单。

扁平数据或组合子项

有些组件族接受数据作为内容,而非子项。传入一个 options JSON 数组后,选择框会自行渲染触发器和列表框,适合选项来自 PHP 的情况:

PHP
bs_render_block([
  'name' => 'bsui/select',
  'data' => [
    'name' => 'role',
    'placeholder' => 'Pick a role',
    'options' => wp_json_encode([
      ['value' => 'viewer', 'label' => 'Viewer'],
      ['value' => 'editor', 'label' => 'Editor'],
    ]),
  ],
]);

两种形式生成相同的标记约定和运行时行为。结构由作者编写时使用子项;结构由程序计算时使用 options。

触发器转发

覆盖层组件通过按钮打开,而这个按钮应当是系统按钮。bsui/dialog、bsui/alert-dialog、bsui/drawer、bsui/menu、bsui/popover、bsui/collapsible 和 bsui/tooltip 的触发器区块不会各自重新实现按钮,而是通过一个 区块字段嵌入 bsui/button:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "trigger",
        "type": "block",
        "block": "bsui/button",
        "idStructure": "trigger_{id}"
      }
    ]
  }
}

idStructure 会将按钮的字段展开到触发器上,并添加 trigger_ 前缀。所有按钮属性均可使用:trigger_label、trigger_variant、trigger_size、trigger_icon、trigger_iconPosition、trigger_href、trigger_disabled。

HTML
<bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />

在触发器模板中,$a['trigger'] 是完整渲染的按钮,因此按钮的样式表和未来的改进都会随之生效。运行时,共享辅助函数会将包装器的 ARIA 关联属性(aria-haspopup、aria-expanded、aria-controls、aria-describedby、aria-labelledby、id)转发到内部按钮,并通过 MutationObserver 保持同步,让辅助技术将其识别为一个连贯的控件。

底层的交互性 API

每个交互式组件族都是一个 WordPress 交互性 API store,名称取自其根区块:bsui/dialog、bsui/select、bsui/form、bsui/tabs 等。由此带来三点影响。

状态在服务器端预置。 根模板会直接根据区块属性,将初始状态输出为 data-wp-context:

HTML
<div
  data-wp-interactive="bsui/select"
  data-wp-context='{"open":false,"value":"","placeholder":"Pick a role", ...}'
  data-bsui-select-root
>

首次渲染的结果正确 HTML,不会出现客户端水合闪烁;弹出层初始为 hidden;由于上下文不依赖仅前端运行的状态处理,同一标记也能在编辑器画布中正常工作。

行为通过指令连接,而不是通过你的 JavaScript。 模板以声明方式将标记连接到 store。去掉 PHP 后,选择框的触发器就只剩下这些指令:

HTML
<button
  data-wp-interactive="bsui/select"
  data-wp-on--click="actions.toggle"
  data-wp-on--keydown="actions.handleTriggerKeyDown"
  data-wp-bind--aria-expanded="state.ariaExpanded"
  data-wp-text="state.displayValue"
  data-bsui-select-trigger
  aria-haspopup="listbox"
>

data-wp-on 将事件路由到操作,data-wp-bind 使属性与派生状态保持同步,data-wp-text 将状态渲染为文本,而 data-wp-on-document--click 让根区块支持点击外部区域后关闭。组合组件时无需编写事件处理器;store 会以内联模块的形式随区块一同提供。

你的 store 可以接入这些接口。 表单控件接受作为属性的指令表达式,而交互性 API 的命名空间语法可以将它们指向任意 store。onChange 会将变更处理路由到你的某个操作,checked 会将控件状态绑定到你的状态,而 bindText 会将标签渲染为绑定到任意状态路径的 data-wp-text span:

HTML
<bs:bsui-switch label="Notifications" checked="myPlugin::state.notifications" onChange="myPlugin::actions.toggleNotifications" />
<bs:bsui-checkbox label="0 selected" bindText="myPlugin::state.selectionSummary" />

bindText 适用于 bsui/label、bsui/checkbox、bsui/switch、bsui/toggle 和 bsui/radio-group 项目。在复选框、开关和单选框项目中,它会传递到共享的标签原语,因此由状态驱动的文本会保持系统标签的准确排版。选择框和其他输入还会从其根元素分发冒泡的 change 事件,并在 detail 中携带新值,以便进行更宽泛的集成。

受控值

对于自行管理值的控件,请将 value 或 checked 留空。初始选项请使用 defaultValue、defaultChecked 或 Toggle 的 defaultPressed。独立的 Toggle 无需使用者存储即可处理鼠标和键盘输入。

若要通过自己的存储控制字段,请同时提供绑定和一个用于更新绑定值的 onChange 操作。value 是指令路径,而不是字面默认值。Input、Textarea、Password Input、Number Field、Slider、Radio Group、Color Picker、Rating 和 Time Picker 支持 value。Checkbox、Switch 和 Toggle 则使用 checked。

请使用所属命名空间限定路径,例如 my/settings::context.quantity 或 my/settings::state.quantity。复合控件有自己的命名空间;未限定的路径指向该控件,而不会自动指向你的父级存储。复合值绑定支持指向上下文或状态的点分路径,包括数字数组键;不支持 JavaScript 表达式或函数调用。

以下是在启用了 Interactivity API 支持的自定义区块中,完整绑定 Number Field 的示例:

PHP
<div
  data-wp-interactive="my/settings"
  data-wp-context='<?php echo esc_attr(wp_json_encode(['quantity' => 2])); ?>'
>
  <bs:bsui-number-field
    nameAlt="quantity"
    defaultValue="2"
    value="my/settings::context.quantity"
    onChange="my/settings::actions.setQuantity"
  />
  <output data-wp-text="context.quantity"></output>
</div>
JavaScript
import { getContext, store } from '@wordpress/interactivity';

store('my/settings', {
  actions: {
    setQuantity(event) {
      // Compound controls publish their normalized value in a custom change event.
      if (event.detail?.value !== undefined) {
        getContext().quantity = event.detail.value;
      }
    },
  },
});

为服务器渲染的初始值设置匹配的默认值。完成水合后,父级的更改会更新每个绑定实例,包括零、false 和空值。Checkbox 和 Switch 的隐藏表单输入也会遵循其 checked 绑定。Time Picker 的值使用 24 小时制 HH:MM 或空字符串。对于原生 Input、Textarea 和 Password Input 处理器,请读取 event.target.value;复合值控件会发布 event.detail.value。 Number Field 的上下限均为可选项:省略 min 和 max 时不设限制,而显式指定零仍是有效的边界值。

Select、Date Input、Phone Input 和 OTP Input 通过 onChange 发布更改,但不提供此受控的 value 绑定。初始值请使用文档中说明的默认属性。

使用你自己的区块进行组合

组合不局限于页面。区块标签会在区块模板中自动渲染,因此项目区块可以直接输出 bsui 组件,并将它们包裹在自己的结构中:

PHP
<div useBlockProps class="settings-panel">
  <bs:bsui-switch label="Public profile" name="public" />
  <bs:bsui-space size="4" />
  <bs:bsui-button label="Save" variant="default" />
</div>

也可以在 PHP 中通过 bs_block() 实现相同效果,包括通过 content 键进行嵌套,详情请参阅程序化渲染。无论采用哪种方式,组件的样式表和 store 都会随之加载,而你的区块只需在系统部件外添加一层简单的布局结构。

要让组件并排排列,bsui/stack 是通用的 flex 行或列:direction、间距刻度中的 gap、align、justify,以及一个 wrap 开关。默认情况下,子项保留自然尺寸;grow 开关会将它们拉伸到等分堆叠的长度,因此页脚中的两个按钮可以平分宽度,而不是挤在一端。

字段组和卡片

bsui/field-group 会渲染一个字段集。默认变体会将相关字段分组,但不添加背景区域。使用 variant="card" 添加低调的外框,然后将字段放入 bsui/field-group-content,即可获得内嵌内容区域。标题和描述应置于该内容块之外:

HTML
<bs:bsui-field-group variant="card">
  <bs:bsui-field-group-title text="Account settings" />
  <bs:bsui-field-group-description text="Manage your account preferences." />
  <bs:bsui-field-group-content>
    <bs:bsui-field>
      <bs:bsui-field-label text="Display name" />
      <bs:bsui-input nameAlt="display_name" placeholder="Enter display name" />
    </bs:bsui-field>
    <bs:bsui-field>
      <bs:bsui-field-label text="Email" />
      <bs:bsui-input nameAlt="email" type="email" placeholder="Enter email" />
    </bs:bsui-field>
  </bs:bsui-field-group-content>
</bs:bsui-field-group>

disabled="true" 所在的分组使用原生 fieldset 行为来禁用其表单控件。卡片样式不会更改默认变体。

工具栏分隔符

将 bsui/toolbar-separator 放在工具栏项目之间。它遵循父工具栏的 orientation:水平工具栏会显示全高的垂直分隔符,垂直工具栏会显示全宽的水平分隔符。分隔符会延伸至工具栏边框内侧边缘,且不会更改控件高度。当内容超出可用宽度时,水平工具栏会滚动。

分层模型

界面层叠是组件库通常容易出问题的地方。内置组件遵循一套简明规则,适用于构建真实 UI 的场景。

模态框会通过 portal 挂载到 body

对话框、警告对话框或抽屉面板打开时,其弹出层和背景遮罩会移动到 document.body,并留下一个占位注释,标记关闭时应返回的位置。通过 portal 挂载,模态框不受任何祖先元素的 overflow、变换或堆叠上下文影响。打开时还会锁定页面滚动:所有覆盖层组件共享引用计数的滚动锁,并补偿滚动条宽度,避免页面发生位移。背景遮罩位于 z-index: 50,弹出层位于 51,焦点会移入弹出层,Tab 键焦点会被限制在其中,关闭时焦点则返回触发器。

模态框可以层叠。从一个对话框内打开另一个对话框时,新对话框会加入共享堆栈:只有最外层对话框显示背景遮罩,顶层之后的对话框会缩小并从后方露出一部分。堆栈会为每个背景弹出层设置一个 --bs-ui-nested-dialogs 自定义属性,使露出偏移和缩放随层级逐渐加深;父级还会将高度调整为与子级一致,让各层均匀露出。关闭时,所有状态都会逐层按相反顺序恢复。

关闭模态框时,焦点会返回其触发器,并定位到正确的元素。共享的 getAnchor 辅助函数会将触发器包装器解析为其中的系统按钮,让获得焦点的是可见控件,而不是不可见的包装器。

顶层模态框永远不会经过变换

这种窥视效果只会转换背景对话框。最上层的模态框会刻意保持不转换,因为转换后的元素会成为 position: fixed 后代元素的包含块,从而破坏其中打开的所有浮动弹出层。

这条规则让整个分层模型能够协同工作。所有浮动层都使用固定坐标定位;只要没有经过转换的祖先元素,这些坐标就以视口为基准:

  • 菜单和组合框会使用 Floating UI 的 fixed 策略,依据触发器计算位置,将弹出层放在其下方,并在视口空间不足时翻转或移动。
  • 未选择任何选项时,下拉选择框也采用相同方式。已有选项时,它会调整弹出层的位置,让所选选项正好显示在触发器上方,并将位置限制在视口范围内,表现与 macOS 上的原生下拉选择框一致。
  • 上下文菜单会在指针的 clientX/clientY 处打开。

由于最上层的模态框未经转换,这些弹出层无论嵌套多深,都能在对话框、警示对话框或抽屉中正确锚定到各自的触发器。弹出层无需知道自己位于模态框内,也无需做任何特殊处理。

Escape 键先关闭最内层

按一次 Escape 键,只会从内向外关闭一层:

  1. 首先关闭已打开的浮动层(例如下拉选择列表框、菜单、弹出框、日期或电话弹出层),并将焦点返回其触发器。下拉选择框会阻止事件继续传播;只要有浮动层处于打开状态,模态框处理器也会暂停处理,因此下方的对话框不会收到这次按键事件。
  2. 接着关闭最上层的模态框。
  3. 如果有多个模态框叠加,每再按一次 Escape 键,就会再关闭一层。

关闭行为由策略决定,不是偶然发生的。使用 dismissable="false" 渲染的对话框会忽略 Escape 键和背景遮罩点击。bsui/alert-dialog 对 Escape 键的响应与其他模态框相同,但会刻意忽略背景遮罩点击:这种模式的要点是必须明确作出选择,不能因意外操作而关闭。普通对话框会在点击背景遮罩时关闭,因为 dismissable 默认值为 true。

对话框中的表单

这个模式会同时运用上述所有规则:点击触发器打开模态框,模态框内包含带验证功能的表单,表单中又包含浮动下拉选择框。

HTML
<bs:bsui-dialog>
  <bs:bsui-dialog-trigger trigger_label="Invite teammate" trigger_variant="outline" />
  <bs:bsui-dialog-backdrop />
  <bs:bsui-dialog-popup>
    <bs:bsui-dialog-header>
      <bs:bsui-dialog-title content="Invite a teammate" />
      <bs:bsui-dialog-description content="They receive an email with a join link." />
    </bs:bsui-dialog-header>
    <bs:bsui-dialog-content>
      <bs:bsui-form block="team/invite" successMessage="Invitation sent.">
        <bs:bsui-field name="email">
          <bs:bsui-field-label text="Email" />
          <bs:bsui-input name="email" type="email" placeholder="colleague@example.com" required="true" />
          <bs:bsui-field-error />
        </bs:bsui-field>
        <bs:bsui-field name="role">
          <bs:bsui-field-label text="Role" />
          <bs:bsui-select name="role" defaultValue="editor" placeholder="Pick a role">
            <bs:bsui-select-trigger />
            <bs:bsui-select-popup>
              <bs:bsui-select-option value="viewer" label="Viewer" />
              <bs:bsui-select-option value="editor" label="Editor" />
              <bs:bsui-select-option value="admin" label="Admin" />
            </bs:bsui-select-popup>
          </bs:bsui-select>
        </bs:bsui-field>
        <bs:bsui-space size="2" />
        <bs:bsui-button label="Send invite" />
      </bs:bsui-form>
    </bs:bsui-dialog-content>
    <bs:bsui-dialog-footer>
      <bs:bsui-dialog-close label="Cancel" />
    </bs:bsui-dialog-footer>
  </bs:bsui-dialog-popup>
</bs:bsui-dialog>

上面的每个标签和属性都不可或缺:触发器会将操作转发给系统按钮,标题和描述接收 content,字段带有表单序列化所需的名称,而 required="true" 会在标签解析器中转换成真正的布尔值。

各个 store 在运行时的作用

bsui/dialog 会在服务器上将 {"open":false,"dismissable":true} 注入上下文。点击触发器后会执行 actions.open:弹出层和背景遮罩会通过 portal 挂载到 body,滚动会锁定并补偿滚动条宽度,弹出层会在 150ms 内显示,焦点会移至第一个可聚焦元素,按 Tab 键会在其中循环切换。页眉、内容区和页脚会按照模态框间距令牌自动调整间距。

bsui/select 会在表单中等待,其列表框为 hidden。点击触发器后会翻转 context.open,并使用视口固定坐标定位列表框。由于已选中 defaultValue="editor",弹出层会对齐位置,让 Editor 正好显示在触发器上方。方向键、Home、End 和按键搜索可移动当前选项;按 Enter 键或点击可选中选项;按 Tab 键或点击外部区域则会关闭弹出层,但不会选择选项。触发器上显示的文本会通过 data-wp-text="state.displayValue" 更新,隐藏的 <input name="role"> 则通过 data-wp-bind--value="state.selectedValue" 跟踪值,供表单之后序列化使用。由于最上层的模态框未经转换,这些弹出层在对话框中都能正确锚定。

bsui/form 会拦截提交操作。表单末尾的 bsui/button 会渲染为普通 button 元素,且不带 type 属性,因此默认情况下,它会根据 HTML 成为表单的提交控件;Cancel 按钮位于 form 元素外部的页脚中,无法提交任何内容。提交时,store 会序列化表单的 FormData,并通过 block 中指定的区块的数据 API 发送。在此处,这会针对 team/invite 区块的 数据库架构 创建一行记录。验证错误会按字段返回:每个 bsui/field 都会携带其 name,被标记为无效,将焦点环颜色改为危险色,并在其 bsui/field-error 警示中显示消息。提交成功后,表单正文会隐藏,successMessage 会显示;两者都通过 data-wp-bind--hidden 实现。

各层会依次关闭。 列表框打开时,按 Escape 键会关闭列表框,并将焦点返回下拉选择框触发器;再按一次 Escape 键会关闭对话框,并将焦点返回 Invite teammate。由于 dismissable 保持默认值,点击背景遮罩也会关闭对话框。关闭后会解除滚动锁定,并将弹出层从 portal 移回文档中的原位置。

将相同的标记粘贴到基于文件的页面中,会同步为原生区块;在编辑器中组装相同的组合,则会在画布中提供交互式预览。这是因为上述所有行为都由指令和 store 实现,而它们会在这两种环境中加载。

让这些衔接保持正常的机制

上述衔接并非约定,而是这个库在所有渲染场景中都能维持的不变量:每个标签都对应相同的排版样式;所有模态框弹出层都共用一种表面样式,并使后方页面变暗;浮动弹出层在页面滚动时仍锚定到触发器;按 Escape 键每次只会关闭一层,并且从内向外依次关闭。这些保证在前端和编辑器画布中都成立,无论使用默认令牌还是你的主题令牌。因此,在一种环境中正常工作的组合,在其他环境中也会有相同表现。

实时示例

本页中的组合展示了语法;/ui/examples 则是用来查找示例的短语手册。这里汇集了三个层次的实时渲染组合:展示两个或三个组件如何衔接的组合、由少量组件构成的常见产品模式,以及按真实产品中的交付方式组装的完整小型应用。每个组件页面(例如 /ui)还提供了各自的实用示例,从带标签的字段到弹出框中的日历都有。

交互性

介绍 UI 组件所基于的指令和 store,以及如何在自己的区块中使用它们。