# @data-slot/slider 中文文档

规范地址：https://npmcn.com/package/%40data-slot/slider/

版本：1\.1\.3
npm 元数据更新时间：2026-11-05T12:26:32.506Z
中文译文更新时间：2026-11-11T13:45:41.619Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40data-slot/slider
原文对照：https://npmcn.com/package/%40data-slot/slider/?lang=original
项目主页：https://github.com/bejamas/data-slot#readme
源码仓库：https://github.com/bejamas/data-slot

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：35.4 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-01-31T18:07:33.642Z
- 最新版本发布：2026-11-05T12:26:32.132Z
- 近 30 天下载量：4280（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：151（近 12 个月 151 个）

## 中文简介

香草JavaScript的无头滑动组件. 支持具有完全键盘导航和ARIA合规的单值和射程滑动.

## 安装

```sh
npm install @data-slot/slider
```

也可以使用：`pnpm add @data-slot/slider`、`yarn add @data-slot/slider`、`bun add @data-slot/slider`

## README

# @ data- slot/ sliver 数据位/ 滑动器

香草JavaScript的无头滑动组件. 支持具有完全键盘导航和ARIA合规的单值和射程滑动.

## 安装

```bash
bun add @data-slot/slider
# or
npm install @data-slot/slider
```

## 使用量

### HTML 结构

```html
<!-- Single value slider -->
<div data-slot="slider" data-default-value="50">
  <div data-slot="slider-track">
    <div data-slot="slider-range"></div>
  </div>
  <div data-slot="slider-thumb"></div>
</div>

<!-- Optional control wrapper -->
<div data-slot="slider" data-default-value="50">
  <div data-slot="slider-control">
    <div data-slot="slider-track">
      <div data-slot="slider-range"></div>
    </div>
    <div data-slot="slider-thumb"></div>
  </div>
</div>

<!-- Range slider (two thumbs) -->
<div data-slot="slider" data-default-value="25,75">
  <div data-slot="slider-track">
    <div data-slot="slider-range"></div>
  </div>
  <div data-slot="slider-thumb"></div>
  <div data-slot="slider-thumb"></div>
</div>
```

### Java 脚本

```javascript
import { create, createSlider } from "@data-slot/slider";

// Auto-discover and bind all [data-slot="slider"] elements
const controllers = create();

// Or target a specific element
const slider = createSlider(element, {
  defaultValue: 50,
  min: 0,
  max: 100,
  step: 1,
  thumbAlignment: "edge",
  onValueChange: (value) => console.log("Changed:", value),
  onValueCommit: (value) => console.log("Committed:", value),
});

// Programmatic control
slider.setValue(75);
console.log(slider.value); // 75

// Cleanup
slider.destroy();
```

## API 密码

### 初始化

#### `create(scope?)`

寻找和约束未初始化 `[data-slot="slider"]` 后裔 `scope` (违约) `document`) (中文(简体) ). 回返 `SliderController[]` 新绑起的根。 初始化范围元素本身,使用 `createSlider`。 。 。 .

```typescript
import { create } from "@data-slot/slider";

const controllers = create();
```

#### `createSlider(root, options?)`

创建一个 `SliderController` 用于一个根元素。 JavaScript 选项优先于相应的数据属性. 再次调用此选项为绑定根返回其已存在的控制器; 在重新绑定新选项前将其销毁 .

```typescript
import { createSlider } from "@data-slot/slider";

const controller = createSlider(element, {});
```

### 槽数

#### 运行时间槽

-   `slider` - 管理值、界限、方向和残疾状态的根元素.
-   `slider-control` - 轨迹和拇指周围的可选交互包. 省略后,会使用音轨的母音,一般为根.
-   `slider-track` - 用于测量指针位置和显示射程和拇指的必用道.
-   `slider-range` - 音轨的可选填充部分;其位置和大小遵循选定的值或范围.
-   `slider-thumb` - 需要有滑动语义和键盘支持的可拖动控制。 单个值或两个值用于范围;两个拇指启用范围模式.

### 数据属性

| 属性 | 说明 | 默认 |
| --- | --- | --- |
| `data-default-value` | 初始价值(`50` 或者说 `25,75` 范围) | `min` (单), `[min, min]` (范围) |
| `data-min` | 最低价值 | `0` |
| `data-max` | 最大值 | `100` |
| `data-step` | 职级递增 | `1` |
| `data-large-step` | 页面上下页的大步骤 | `step * 10` |
| `data-orientation` | `horizontal` 或者说 `vertical` | `horizontal` |
| `data-thumb-alignment` | `center`, (中文(简体) ), `edge`,或 `edge-client-only` | `center` |
| `data-disabled` | 禁用滑动器 | \- 说吧 |

### 选项

JavaScript 选项优先于根数据属性.

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `defaultValue` | `number | [number, number]` | `min` (单), `[min, min]` (范围) | 初始值; 被夹到边框并断开到 `step`。两个拇指启用范围模式. |
| `min` | `number` | `0` | 最低价值 |
| `max` | `number` | `100` | 最大值 |
| `step` | `number` | `1` | 分级递增;非正值回落到 `1` |
| `largeStep` | `number` | `step * 10` | 页面上调/页下和Shift+箭头的增量 |
| `orientation` | `"horizontal" | "vertical"` | `"horizontal"` | 滑动取向 |
| `thumbAlignment` | `"center" | "edge" | "edge-client-only"` | `"center"` | 缩略图放置在轨迹边缘 |
| `disabled` | `boolean` | `false` | 禁用用户交互和输入设定的事件 |
| `onValueChange` | `(value: number | [number, number]) => void` | `undefined` | 要求修改价值,包括方案更新;对初始化和不变值保持沉默 |
| `onValueCommit` | `(value: number | [number, number]) => void` | `undefined` | 调用指针释放/取消, 键盘值变化后模糊, 或更改 `slider:set` 更新 |

### 主计长

| 方法/财产 | 说明 |
| --- | --- |
| `setValue(value: number | [number, number])` | 更新值, 包括禁用时的值 。 当值发生变化时, 释放会改变, 但不会释放承诺 . |
| `value` | 当前值( 只读) `number | [number, number]`(中文(简体) ) |
| `min` | 解析最小值( 只读) `number`(中文(简体) ) |
| `max` | 解析最大值( 只读) `number`(中文(简体) ) |
| `disabled` | 是否禁用交互( 只读) `boolean`(中文(简体) ) |
| `destroy()` | 删除听众并释放根绑定 |

### 活动

#### 境外事件

听这些关于根元素的事件.

| 活动 | 细节 | 说明 |
| --- | --- | --- |
| `slider:change` | `{ value: number | [number, number] }` | 值变化时起火 |
| `slider:commit` | `{ value: number | [number, number] }` | 在指针放出/取消时起火, 键盘值变化后模糊, 或者更改 `slider:set` 更新 |

#### 入境事件

将这些事件传到根元件上.

| 活动 | 细节 | 说明 |
| --- | --- | --- |
| `slider:set` | `{ value: number | [number, number] }` | 按方案设定值 |

```javascript
// Listen for changes
root.addEventListener("slider:change", (e) => {
  console.log("Value:", e.detail.value);
});

// Set value from outside
root.dispatchEvent(new CustomEvent("slider:set", {
  detail: { value: 50 }
}));

// Set range value
root.dispatchEvent(new CustomEvent("slider:set", {
  detail: { value: [25, 75] }
}));
```

**说明:** 禁用滑动器时被屏蔽 .

#### 折旧形状

下列形状被去化并会在v1.0中去除:

```javascript
// Deprecated: bare number
root.dispatchEvent(new CustomEvent("slider:set", {
  detail: 50
}));

// Deprecated: bare array
root.dispatchEvent(new CustomEvent("slider:set", {
  detail: [25, 75]
}));
```

使用 `{ value: ... }` 换句话说.

### 样式

该组件为 CSS 勾通设置了数据属性和内置样式:

```css
/* Root state */
[data-slot="slider"][data-orientation="horizontal"] { ... }
[data-slot="slider"][data-orientation="vertical"] { ... }
[data-slot="slider"][data-disabled] { ... }
[data-slot="slider"][data-dragging] { ... }

/* Parts mirror shared state for shadcn/Base-style selectors */
[data-slot="slider-track"][data-orientation="horizontal"] { ... }
[data-slot="slider-track"][data-orientation="vertical"] { ... }
[data-slot="slider-range"][data-orientation="horizontal"] { ... }
[data-slot="slider-range"][data-orientation="vertical"] { ... }
[data-slot="slider-track"][data-disabled] { ... }
[data-slot="slider-range"][data-disabled] { ... }
[data-slot="slider-thumb"][data-orientation="horizontal"] { ... }
[data-slot="slider-thumb"][data-orientation="vertical"] { ... }
[data-slot="slider-thumb"][data-disabled] { ... }

/* Thumb positioning (set automatically) */
[data-slot="slider-thumb"] {
  position: absolute;
  /* --position: X%; inset-inline-start/top or bottom/left are applied inline */
  /* translate is applied inline to center the thumb on the resolved visual position */
}

/* Range thumbs expose their index */
[data-slot="slider-thumb"][data-index="0"] { ... }
[data-slot="slider-thumb"][data-index="1"] { ... }

/* Range positioning (set automatically) */
[data-slot="slider-range"] {
  /* horizontal: relative + inset-inline-start/width */
  /* vertical: absolute + bottom/height */
}

/* Thumb dragging state */
[data-slot="slider-thumb"][data-dragging] { ... }
```

`slider-track`, (中文(简体) ), `slider-range`,以及 `slider-thumb` 也获得基底式内线布局 样式来自控制器。 跑步时间拥有赛道 `position: relative`,则 范围的起始/大小定位,拇指的绝对位置/翻译,所以 作者只需要提供视觉风格, 除非他们有意想要覆盖 那个布局行为.

何时 `thumbAlignment` 实值 `"edge"` 或者说 `"edge-client-only"`,运行时间衡量 将拇指放入可见的轨道。 在这些模式中, `--position` 区域启动/ 大小 vars 代表已渲染的布局位置 超过原始价值百分比.

#### 缩略图对齐

默认情况下,滑动拇指会以活性值为中心. 也就是说拇指可以 当值为 `min` 或者说 `max`。 。 。 .

使用 `thumbAlignment` 或者说 `data-thumb-alignment` 改变这种行为:

-   `"center"` - 默认。 拇指以数值为中心,可能会溢出轨迹边缘.
-   `"edge"` - 将拇指套入,使其边缘与轨迹边缘一致 `min` 财务报告和审定财务报表 `max`。 。 。 .
-   `"edge-client-only"` - 接受基本UI API均等。 在这个香草包里 它的表现和 `"edge"`。 。 。 .

```html
<div data-slot="slider" data-default-value="25" data-thumb-alignment="edge">
  <div data-slot="slider-track">
    <div data-slot="slider-range"></div>
  </div>
  <div data-slot="slider-thumb"></div>
</div>
```

```javascript
createSlider(element, {
  defaultValue: 25,
  thumbAlignment: "edge",
});
```

### 键盘导航

| 密钥 | 行动 |
| --- | --- |
| `ArrowRight` 编号 : `ArrowLeft` | 水平滑动器的增/减 |
| `ArrowUp` 编号 : `ArrowDown` | 垂直滑动器的增减 |
| `PageUp` | 增加次数 |
| `PageDown` | 大量减少 |
| `Home` | 设定到分钟 |
| `End` | 设置为最大 |
| `Shift+Arrow` | 以大步移动 |

### 无障碍

每个拇指元素都收到:

-   `role="slider"`
-   `tabindex="0"`
-   `aria-valuemin` 编号 : `aria-valuemax` 编号 : `aria-valuenow`
-   `aria-orientation`
-   `aria-disabled` (残疾时)
-   `aria-label` (从) `data-label` 或为范围自动生成)

`slider-track`, (中文(简体) ), `slider-range`,以及 `slider-thumb` 也镜像根的 `data-orientation` 财务报告和审定财务报表 `data-disabled` 装模作样. `slider-control` 可选; 当省去时,根会起到交互控制表面的作用.

## 许可证

麻省理工学院

## 常见问题

### @data-slot/slider 是什么？

香草JavaScript的无头滑动组件\. 支持具有完全键盘导航和ARIA合规的单值和射程滑动\.

### 如何安装 @data-slot/slider？

在项目目录运行 npm install @data-slot/slider，或使用 pnpm add / yarn add / bun add。

### @data-slot/slider 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @data-slot/slider 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @data-slot/slider 可以商用吗？

@data-slot/slider 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @data-slot/slider 的下载量有多少？

根据 npm 官方下载统计，@data-slot/slider 在 2026/10/12 – 2026/11/10 这 30 天内被下载 4,280 次，日均约 143 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @data-slot/slider 还在维护吗？

最新版本 1\.1\.3 发布于 2026/11/05（6 天前）；至今共发布 151 个版本，其中过去 12 个月发布了 151 个；首次发布于 2026/02/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。