Select 选择器
Forms
自动交互
Introduction
一个自定义下拉选择控件，允许用户从预定义列表中选择一个或多个选项。该组件作为浏览器原生 <select> 元素的完全无障碍、可样式化且响应式的替代方案。
Select 组件已作为 select 区块完全集成到 Page Builder 中，使内容作者和开发人员能够直接在 CMS 中轻松配置可视选项、占位符、尺寸、多选和颜色主题。
Usage
以下示例展示了内容编辑人员如何绑定和构建交互式下拉选择。
1. 标准单项选择
一个标准的单项下拉列表，允许用户选择其偏好的框架。它具有自定义标签和占位符文本。
{
"type": "select",
"label": "Framework",
"placeholder": "Select a framework",
"interactive": true,
"items": [
{ "label": "React", "value": "react" },
{ "label": "Solid", "value": "solid" },
{ "label": "Svelte", "value": "svelte", "disabled": true },
{ "label": "Vue", "value": "vue" },
{ "label": "Hono", "value": "hono" }
]
}
React
Solid
Svelte
Vue
Hono
2. 带自定义样式（surface 变体）的多项选择
演示如何启用多个活动选择，触发器标签以逗号分隔显示。同时展示了独特的视觉 surface 变体。
{
"type": "select",
"label": "CSS Frameworks",
"placeholder": "Choose frameworks",
"multiple": true,
"variant": "surface",
"size": "lg",
"defaultValue": ["panda"],
"interactive": true,
"items": [
{ "label": "Tailwind CSS", "value": "tailwind" },
{ "label": "Panda CSS", "value": "panda" },
{ "label": "Vanilla Extract", "value": "vanilla" }
]
}
Tailwind CSS
Panda CSS
Vanilla Extract
3. 禁用态下拉选择器
展示一个临时不可用或只读的 select 元素。该视觉状态禁用所有交互，阻止下拉列表被打开或聚焦。
{
"type": "select",
"label": "Language Settings",
"placeholder": "Select Language",
"disabled": true,
"interactive": true,
"items": [
{ "label": "English", "value": "en" },
{ "label": "Deutsch", "value": "de" }
]
}
English
Deutsch
Props
| 属性 | CMS 字段类型 | 默认值 | 描述 / 支持的选项 |
|---|---|---|---|
标签文本 (label) | string | - | 渲染在下拉触发器上方的描述性文本。 |
占位符 (placeholder) | string | - | 未选择任何选项时，触发器按钮内显示的幽灵文本。 |
选项列表 (items) | list | - | 选项列表，每项包含 label、value 以及可选的 disabled 状态。 |
多选 (multiple) | boolean | false | 启用后，用户可选择多个选项；选择期间下拉保持打开。 |
默认值 (defaultValue) | list | - | 初始选中的选项值数组，在加载时预勾选。 |
可取消选择 (deselectable) | boolean | false | 允许通过再次单击当前选项来清除单项选择。 |
表单名称 (name) | string | - | 用于在表单提交期间捆绑原生值的标准 HTML name 属性。 |
禁用 (disabled) | boolean | false | 禁用用户交互，并对下拉应用变暗的覆盖层。 |
无效状态 (invalid) | boolean | false | 触发错误边框并显示无效的视觉状态。 |
视觉变体 (variant) | select | "outline" | 触发器的边框与填充主题。 • 选项： "outline"、"surface"。 |
尺寸比例 (size) | select | "md" | 控制整体间距、内边距和字体大小。 • 选项： "xs"、"sm"、"md"、"lg"、"xl"。 |
强制交互 (interactive) | boolean | true | 将下拉触发器和菜单浮层作为交互式客户端孤岛注水。 |
Developer Notes & Accessibility
- 注水孤岛： 由于 Select 需要客户端 JavaScript 来切换菜单、筛选选项并绑定自定义按键监听器，默认作为交互式 Preact 孤岛注水（
"interactive": true）。 - WAI-ARIA 合规性： 该组件充当高保真语义自定义组合框。焦点安全地保留在触发按钮上（
role="combobox"），选项通过标准aria-activedescendant、aria-expanded和aria-controls绑定动态管理。键盘方向键、Home/End和Escape开箱即用，运行流畅。 - 表单集成： 它输出一个视觉隐藏的原生
<select>元素，填充与选择匹配的隐藏<option>元素。标准的 HTTP POST 表单提交原生可用，无需任何辅助 JS 状态序列化。