@ data- slot/ 切换组
一组具有共享状态的切换按钮,支持单个或多个选择.
安装
bun add @data-slot/toggle-group
使用量
基本标记
<!-- Single selection (default) -->
<div data-slot="toggle-group" data-default-value="center">
<button data-slot="toggle-group-item" data-value="left">Left</button>
<button data-slot="toggle-group-item" data-value="center">Center</button>
<button data-slot="toggle-group-item" data-value="right">Right</button>
</div>
<!-- Multiple selection -->
<div data-slot="toggle-group" data-multiple data-default-value="bold italic">
<button data-slot="toggle-group-item" data-value="bold">B</button>
<button data-slot="toggle-group-item" data-value="italic">I</button>
<button data-slot="toggle-group-item" data-value="underline">U</button>
</div>
Java 脚本
import { create, createToggleGroup } from "@data-slot/toggle-group";
// Auto-discover and bind all toggle-group elements
const controllers = create();
// Or target a specific element
const group = createToggleGroup(element, {
defaultValue: "center",
multiple: false,
orientation: "horizontal",
loop: true,
onValueChange: (value) => console.log(value),
});
// Programmatic control
group.setValue("left");
group.toggle("bold");
console.log(group.value); // ["left"]
// Cleanup
group.destroy();
API 密码
初始化
create(scope?)
寻找和约束未初始化 [data-slot="toggle-group"] 后裔 scope (违约) document) (中文(简体) ). 回返 ToggleGroupController[] 新绑起的根。 初始化范围元素本身,使用 createToggleGroup。 。 。 .
import { create } from "@data-slot/toggle-group";
const controllers = create();
createToggleGroup(root, options?)
创建一个 ToggleGroupController 用于一个根元素。 JavaScript 选项优先于相应的数据属性. 再次调用此选项为绑定根返回其已存在的控制器; 在重新绑定新选项前将其销毁 .
import { createToggleGroup } from "@data-slot/toggle-group";
const controller = createToggleGroup(element, {});
槽数
运行时间槽
toggle-group- 管理单项或多项选择和键盘导航的根元素.toggle-group-item- 在组内切换按钮,由独特的data-value; 获得aria-pressed财务报告和审定财务报表data-state作为其选择的变化.
数据属性
根元素
| 属性 | 说明 |
|---|---|
data-slot="toggle-group" | 要求。 识别根元素. |
data-default-value | 初始选定值 。 多个值的空格分隔. |
data-multiple | 启用多个选择模式 . |
data-orientation | "horizontal" 或者说 "vertical" 键盘导航. |
data-loop | 结尾的键盘焦点( 默认) true; 使用情况 "false" 停止在结尾. |
data-disabled | 禁用整个组 . |
项目要点
| 属性 | 说明 |
|---|---|
data-slot="toggle-group-item" | 要求。 确定一个项目. |
data-value | 要求。 与本项目相关的值 . |
data-disabled | 禁用此特定项目 . |
状态属性(按构成部分设置)
| 属性 | 数值 | 说明 |
|---|---|---|
aria-pressed | "true" | "false" | 是否按下项目 . |
data-state | "on" | "off" | 造型的视觉状态. |
data-value (在根头上) | 空格分隔值 | 当前所选. |
选项
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
defaultValue | string | string[] | [] | 初始选定值 。 对于多值,使用数组或空格分隔的字符串. |
multiple | boolean | false | 允许多个选择 . |
orientation | "horizontal" | "vertical" | "horizontal" | 键盘导航方向 . |
loop | boolean | true | 将键盘焦点置于尾端 . |
disabled | boolean | false | 禁用整个组 . |
onValueChange | (value: string[]) => void | - 说吧 | 选择更改时召回 . |
主计长
| 方法/财产 | 说明 |
|---|---|
setValue(value: string | string[]) | 替换选择。 字符串是空格分隔的;未知值被忽略,单模式保留了第一个匹配值. |
toggle(value: string) | 切换一个值;单模式清除上一个选择. |
value | 当前选择( 只读) string[],包括单模式). |
destroy() | 删除听众并释放根绑定 . |
控制器在小组停用时使用方法。 用户互动和 toggle-group:set 禁用时被屏蔽.
活动
境外事件
// Listen for changes
root.addEventListener("toggle-group:change", (e) => {
console.log(e.detail.value); // string[]
});
入境事件
| 活动 | 细节 | 说明 |
|---|---|---|
toggle-group:set | { value: string | string[] } | 程序设定选择 |
// Set selection from outside
root.dispatchEvent(new CustomEvent("toggle-group:set", {
detail: { value: "bold" }
}));
// Set multiple values
root.dispatchEvent(new CustomEvent("toggle-group:set", {
detail: { value: ["bold", "italic"] }
}));
说明: 组禁用时被屏蔽 .
折旧形状
下列形状被去化并会在v1.0中去除:
// Deprecated: bare string
root.dispatchEvent(new CustomEvent("toggle-group:set", {
detail: "bold"
}));
// Deprecated: bare array
root.dispatchEvent(new CustomEvent("toggle-group:set", {
detail: ["bold", "italic"]
}));
使用 { value: ... } 换句话说.
样式
/* Style pressed items */
[data-slot="toggle-group-item"][data-state="on"] {
background: #333;
color: white;
}
/* Style disabled items */
[data-slot="toggle-group-item"][aria-disabled="true"] {
opacity: 0.5;
cursor: not-allowed;
}
键盘导航
| 密钥 | 行动 |
|---|---|
ArrowRight 编号 : ArrowDown | 移动到下一个项目( 基于方向) |
ArrowLeft 编号 : ArrowUp | 移动到上一个项目( 根据方向) |
Home | 移动到第一个项目 |
End | 移动到上一个项目 |
Enter 编号 : Space | 切换当前项目 |
无障碍
- 根已经
role="group" - 项目有:
aria-pressed属性 - 已禁用的项目有:
aria-disabled="true"和本土disabled - 支持运行键盘导航的标签索引
- 添加
aria-label或者说aria-labelledby转到上下文的根