# @ax-design/scrollbar 中文文档

规范地址：https://npmcn.com/package/%40ax-design/scrollbar/

版本：0\.4\.3
npm 元数据更新时间：2026-10-26T18:19:41.411Z
中文译文更新时间：2026-11-09T22:19:37.905Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.5 MB，197 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：5 个
- 首次发布：2026-10-26T01:53:31.077Z
- 最新版本发布：2026-10-26T18:19:40.442Z
- 近 30 天下载量：1707（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

将容器或页面的滚动条替换为 CSS 的网络组件,用于Axiom 设计系统.

## 安装

```sh
npm install @ax-design/scrollbar
```

也可以使用：`pnpm add @ax-design/scrollbar`、`yarn add @ax-design/scrollbar`、`bun add @ax-design/scrollbar`

## README

# ![Ax Scrollbar](https://raw.githubusercontent.com/ax-design/scrollbar/master/docs/logo.png)

替换容器或页面滚动条的网络组件,用于Axiom设计系统.

[![npm version](https://img.shields.io/npm/v/@ax-design/scrollbar.svg)](https://www.npmjs.com/package/@ax-design/scrollbar) ![MIT Licence](https://img.shields.io/badge/license-MIT-green.svg)

`<ax-scroll-view>` 是一个滚动容器 `<ax-scrollbar>` 绘制页面的滚动条。 滚动保持原生(轮子、触摸、按键、在页面中查找、, `scrollIntoView`); 栏是显示位置并驱动取景器的上覆. 默认外观是 Windows 8 (Modern UI) 滚动条,其每个部分(thumb,按钮,音轨,标记,悬浮卡)的样式都是用 `::part()` 或取而代之的是装备箱.

## 安装

```bash
# with npm
npm install @ax-design/scrollbar

# with bun
bun add @ax-design/scrollbar
```

并导入:

```javascript
// CommonJS
require('@ax-design/scrollbar').register();

// ES modules
import { register } from '@ax-design/scrollbar';
register();
```

`register()` 定义 `<ax-scroll-view>`, (中文(简体) ), `<ax-scrollbar>`,部分要素`<ax-scrollbar-thumb>` (他们) `scrollbar-fill` 财务报告和审定财务报表 `scrollbar-glyph` 层 `elevation` 层和,通过 `@ax-design/surface`, (中文(简体) ), `<ax-surface>`不止一次打电话是安全的.

如果你不使用捆绑器,装入 `build/main.js` (它暴露了 `AxScrollbar`)或导入 `build/index.mjs`。 。 。 .

## 使用量

### 滚动视图

内容围成 `<ax-scroll-view>` 并赋予它一个高度:

```html
<ax-scroll-view style="height: 420px">
  <article>
    <h2>Introduction</h2>
    <p>...</p>
  </article>
</ax-scroll-view>
```

-   元素需要一个高度:它的取景口是绝对定位的,所以它不会从内容中大小化自己.
-   将贴在内容上,而不是在元素上:取景口覆盖元素的贴花框.
-   元素有元素的滚动 API(`scrollTop`, (中文(简体) ), `scrollLeft`, (中文(简体) ), `scrollHeight`, (中文(简体) ), `scrollWidth`, (中文(简体) ), `scrollTo()`, (中文(简体) ), `scrollBy()`, (中文(简体) ), `scroll()`),在取景所上演. `scroll` 财务报告和审定财务报表 `scrollend` 也发出在元素上,不发泡. `viewport` 是真正滚动的元素.
-   栏被画在内容上,绝不收缩卷轴. 该组件将显示在主机上的条的厚度写为 `--ax-scrollbar-vertical-size` 财务报告和审定财务报表 `--ax-scrollbar-horizontal-size` (单位:千美元)`0px` 用于未显示的栏,所以内容可以远离它们:

```css
ax-scroll-view > .body {
  padding-right: var(--ax-scrollbar-vertical-size);
}
```

### 页面滚动条

点一 `<ax-scrollbar>` 页面中的任意位置 :

```html
<body>
  <ax-scrollbar></ax-scrollbar>
  ...
</body>
```

-   一页有一. 一秒钟 `<ax-scrollbar>` 登录警告并保持惰性.
-   它隐藏了页面的原生卷轴栏并自画自画. 页面仍然以本土方式滚动.
-   它是一个固定的覆盖在窗口上,不需要任何指针事件。 内容 `z-index` 实值 `--ax-scrollbar-z-index` (默认) `2147483000`),所以有模式的一页可以放入它们下面.
-   `suspended` 淡出栏杆,让他们忽略输入,为页面上的灯盒. 把它取出,他们又出现.

## 概念

### 默认外观

没有工具包,这些部件画出Windows 8 (Modern UI),带有Windows 8.1 XAML ScrollBar, ScrollViewer和TolleTip模板的编号:一个17px条在250ms和出167ms中会逐渐淡出,一个平方拇指,33px按钮有切夫龙,一个苍白的音轨,平平平的勾克,一个没有阴影的平方卡,以及一个只用拇指的平板指示来触摸. 这些数字是主机符的初始值和默认主题的规则. 它们是一个17px栏的数字:拇指和被悬浮的标记填充了栏,而按钮,箭头和标记是那些被缩放的数字 `--ax-scrollbar-thickness` / 17px,所以一个更厚或更薄的条是同一种图画,大或小.

### 结构是部分

每一块铁条都是阴暗的 有风格的 `::part()`。名称沿用 WebKit 滚动条伪元素.

```css
ax-scroll-view::part(scrollbar-vertical) {
  background: #f0f0f0;
}

ax-scroll-view::part(thumb) {
  --ax-radius: 2px;
  --ax-corner-shape: bevel;
  --ax-scrollbar-part-color: rgba(0, 0, 0, 0.35);
}
ax-scroll-view::part(thumb-hover) {
  --ax-scrollbar-part-color: rgba(0, 0, 0, 0.6);
}
ax-scroll-view::part(thumb-pressed) {
  --ax-scrollbar-part-color: rgba(0, 0, 0, 0.75);
}
```

**级联规则.** 页面规则 `::part(x)` 胜过该部分的影子 CSS 无论它的具体性如何 它取代它设定的每个财产的默认值 `x`: 默认主题的状态规则 该属性停止应用 。 重述在规则之后应该不同的状态,按照休息的顺序,流出,在拇指上,徘徊,按住. 什么规则没有设置 保持默认的。 其中 `::part()` 规则后一取胜.

规则集是外观输入(以下), Surface 的形状属性(`--ax-radius`, (中文(简体) ), `--ax-corner-shape`, (中文(简体) ), `--ax-border-width` 和他们, `--elevation-depth` 财务报告和审定财务报表 `--elevation-color`,对于一张卡片真实的CSS(`color`, (中文(简体) ), `font`, (中文(简体) ), `padding`, (中文(简体) ), `max-width`) (中文(简体) ). 组件重排每个部分的形状属性,所以条上的规则不会渗入到它们;在部分设置.

组件为几何写出内线样式(拇指的长度和位置,轨迹片段的剪接,标记位置, `display` 隐藏部件、角大小、卡片位置)和私人 `--ax-scrollbar-shown-*` 用于绘制一个部分的值的属性。 不要设置这些。 零件、栏和牌 `pointer-events: none` 与 `!important`。 。 。 .

### 几何输入

栏杆不取指针事件. 组件在卷轴上观察指向器,并找到条、其零件及其热区(`--ax-scrollbar-hotzone`)由几何来表示,所以在隐藏栏下的内容保持了它的徘徊并点击.

-   拖起拇指来. 按下音轨向指针行驶( 持有时重复) , 或与 `track-click="jump"` 向指针上滚动. 按钮步入 `--ax-scrollbar-line` 并重复,同时持有.
-   卷起栏杆(按钮,轨迹,标记)滑行和快步相加;一转轮,触取,键或脚本卷轴会停止滑行. 拖累是永远不会平滑的.
-   所绘制的拇指、跟踪片和标记跟随滚动位置的短滞后(`--ax-scrollbar-thumb-smoothing`) (中文(简体) ).
-   条条出现在指针移动或滚动上,然后在 `--ax-scrollbar-idle-delay`。 。 。 .

### 标记

标记是赛道上对内容中某个位置的勾选,例如标题或搜索命中. 让他们与 `marker-selector`数字 :

```html
<ax-scroll-view marker-selector="h2" style="height: 420px">...</ax-scroll-view>
```

每场比赛都变成标记:它的ID是元素的 `id` (或 `ax-marker-N`),其标签为文本. 匹配值在内容添加或删除节点时再次被读取; 在另一种更改调用之后 `refreshMarkers()`。 。 。 . `marker-axis="horizontal"` 把它们放在水平栏上.

或者设置 `markers` 财产,在选择者持有列表时胜过选择者(即使是空列表); `null` 给选择器回控。 它需要元素,a `NodeList`,标记对象,或混合。 带有标记对象 `element` 需要没有 `id` 或者说 `label`:它们来自元素,如同一个赤裸的元素.

```javascript
view.markers = [
  { id: 'intro', label: 'Introduction', position: 0 },
  { id: 'setup', label: 'Setup', element: document.getElementById('setup') },
  { id: 'row-3', label: 'Result 3', axis: 'horizontal', position: 1200, data: { hits: 4 } },
  document.getElementById('summary'),
];
```

标记比 `--ax-scrollbar-marker-spacing` 共享一个标记, 其牌列出全部。 按下一个标记滚动到视图的中间(`marker-align="start"`:它的起始边缘到视图的起始). 打电话 `preventDefault()` 打开 `markeractivate` 跳跃自己.

### 那张牌

一张牌在标记上打开,并显示其标记的标签,每行一张,缩到最长的一张(A`--ax-scrollbar-fit-width` 打开 `part="card-content"`,具有压倒性 `::part(card-content)`) (中文(简体) ). 它是一个表面 画与 `scrollbar-fill` 财务报告和审定财务报表 `elevation` 层,放置在存在 Popover API 的上层,否则 `position: fixed`样式 `::part(card)`数字 :

```css
ax-scroll-view::part(card) {
  --ax-scrollbar-part-color: #fff;
  --ax-scrollbar-part-border-color: #ccc;
  --ax-border-width: 1px;
  --elevation-depth: 8;
  color: #222;
  font: 12px/1.4 system-ui;
  padding: 6px 10px;
}
```

其他内容,扩展 `AxScrollbarCard` 在工具包中并覆盖 `render(markers, content)`。 。 。 .

### 隐藏部件

`hide` 是一个简单的空格分隔列表,其中列出从未显示的部分: `thumb`, (中文(简体) ), `button`, (中文(简体) ), `track` (与它的碎片), `track-piece`, (中文(简体) ), `corner`, (中文(简体) ), `marker`, (中文(简体) ), `card`,隐藏部分不占用房间,不输入:隐藏标记不测量,隐藏卡不打开. 未知名称被忽略 .

第一部分是布局第一次需要它,然后保留下来。 从未显示的部分从未制作过: 永不滚动的轴使其栏上的任何部分( 或没有其他轴, 或角) , 一种在 `hide` 没有标记的卷轴视图没有标记, 标记从未被徘徊的人没有牌。 一个首次显示的酒吧(内容增长, `hide` )将其部分在那个框中作成并画入下一个框中,而一个会消失的部分会留下(没有显示). 工具箱的课用同样的方式: `createElement` 当该部分被首次需要时, 运行该类, 所以一个工具箱的部分只存在于一个栏中 .

```html
<ax-scroll-view hide="button">...</ax-scroll-view>
<ax-scroll-view hide="button track corner">...</ax-scroll-view>
```

默认是一个空列表,所以默认的外观会用鼠标显示其按钮并跟踪;一个工具包会给出自己的默认(`hide` 资料夹。 属性,即使是空的,也压倒了它. 触摸所隐藏的不是问题 `hide`,参见 [触摸](https://npmcn.com/package/%40ax-design/scrollbar/#readme-touch)。 。 。 .

### 按配置排列的图层

这些零件是表面的,和 `{part}-layers` 按油漆顺序(如 `layers` ”。 没有属性的一类保持其默认值 : `scrollbar-fill` 对于每一部分, `scrollbar-fill scrollbar-glyph` 对于一个按钮, `scrollbar-fill elevation` 为一张卡。 命名层取代列表, 因此名称 `scrollbar-fill` 以保持充电。 未注册的名称在注册前会被忽略.

```html
<ax-scroll-view track-layers="scrollbar-fill acrylic" thumb-layers="scrollbar-fill reveal">...</ax-scroll-view>
```

### 夹子

工具箱通过依赖性注射将部件替换为自己的类别。 每一种都有 **合同类** 无画 (`AxScrollbarThumb` 以及a类 **默认类** 与 Windows 8 的外观相扩展(`AxScrollbarDefaultThumb` (见A/CN.9/WG.III/WP.III/WP.1号文件)。 套件类扩展了其中之一,并用它自己的影子根来取出它的外观(`static styles`),所以默认外观上的任何内容都不必被关闭. 栏杆保留着他们决定的:在栏杆上坐到哪个部分,还有多长时间.

```javascript
import { AxScrollbarThumb, defineScrollbarKit } from '@ax-design/scrollbar';

class SlabThumb extends AxScrollbarThumb {
  static styles = `
    :host { background: #888; margin: 0 3px; }
    :host([pressed]) { background: rgb(0, 120, 215); }
  `;
}

defineScrollbarKit('slab', { thumb: SlabThumb, hide: '' });
```

```html
<ax-scroll-view kit="slab" style="height: 420px">...</ax-scroll-view>
```

`defineScrollbarKit(name, kit)` 任何课程 `thumb`, (中文(简体) ), `button`, (中文(简体) ), `track`, (中文(简体) ), `trackPiece`, (中文(简体) ), `corner`, (中文(简体) ), `marker`, (中文(简体) ), `card`,以及 `hide`。不延长此类合同等级的类别将丢入 `TypeError`; 定义名称两次抛出。 套件离开是默认的课。 每个类别的定义是: `<ax-scrollbar-NAME-KIND>` 除非它已经是一个自定义元素。 包可在元素后定义,当元素重建时 `kit` 重建栏杆。 一个作者的 `::part()` 规则仍然赢得一个工具箱自己的CSS.

什么样的部分类可以使用:

-   `static styles`: 部分阴影根中的 CSS,读取状态为 `:host([hover])`, (中文(简体) ), `:host([pressed])`, (中文(简体) ), `:host([axis="vertical"])`, (中文(简体) ), `:host([direction="start"])`, (中文(简体) ), `:host([disabled])`, (中文(简体) ), `:host([rtl])`。 。 。 .
-   `partState`: 只读 `axis`, (中文(简体) ), `direction`, (中文(简体) ), `hover`, (中文(简体) ), `pressed`, (中文(简体) ), `disabled`, (中文(简体) ), `indicator`, (中文(简体) ), `engaged`, (中文(简体) ), `rtl`标记 `onThumb` 财务报告和审定财务报表 `current`。 。 。 . `stateChanged(prev, next)` 每次更改后运行.
-   `defaultLayers_()` 财务报告和审定财务报表 `layerNames_()` 为分层.
-   `look(state, values)` 财务报告和审定财务报表 `static extraSchema` 以动画来看待国家的投入.
-   `render(markers, content)` 牌上写着.

### Windows XP 工具包

`@ax-design/scrollbar/kits/luna` 是 Windows XP (Luna) 滚动条作为工具箱:用抓取线、刻有音轨、 XP 信息提示、 不淡出来。 它需要注册的元素,定义的工具包和一个颜色方案.

```ts
import { register } from '@ax-design/scrollbar';
import { adoptLunaSchemes, defineLunaKit } from '@ax-design/scrollbar/kits/luna';

register();
defineLunaKit(); // defines the kit "luna"
adoptLunaSchemes(); // adds the scheme classes to the document
```

```html
<div class="luna-blue">
  <ax-scroll-view kit="luna" snap style="height: 420px">...</ax-scroll-view>
</div>
```

使用 `snap` 用套件:它把拇指的边缘放在整个设备像素上,然后套件还把拇指的四条抓取线画成整个设备像素,这样它们就可以在任何缩放和任何显示尺度(包括110%、125%和150%)上保持四条不同的线.

计划是班级 `luna-blue`, (中文(简体) ), `luna-olive`, (中文(简体) ), `luna-silver`, (中文(简体) ), `luna-purple`, (中文(简体) ), `luna-orange`, (中文(简体) ), `luna-pink` 财务报告和审定财务报表 `luna-gold`,设置在滚动视图上或任何祖先上(习惯属性继承到部分中)。 他们是弦 `lunaSchemes`,哪个 `adoptLunaSchemes(root = document)` 将字符串写入文档或阴影根; 将文件链接起来, 将字符串写入并链接起来 。 Blue,Olive Green和Silver是Windows XP的计划.

一个方案是一类自定义属性,所以一个自定义方案是一类设置这些属性,别无他法. 色调为: `--luna-accent`, (中文(简体) ), `-accent-light`, (中文(简体) ), `-accent-deep` (thumb,按钮), `--luna-glyph` (麦兜,握住), `--luna-face` (轨道、角)和 `--luna-disabled`数字对比,0比1: `--luna-highlight`, (中文(简体) ), `--luna-shade`, (中文(简体) ), `--luna-gloss`, (中文(简体) ), `--luna-depth`, (中文(简体) ), `--luna-hot`, (中文(简体) ), `--luna-press`, (中文(简体) ), `--luna-etch` (和 `--luna-relief`,只有演示的 XP 窗口读取). `--luna-light` (单位:千美元)`top-left` 或者说 `top`)说出光从何处来,并 `--luna-diagonal` 财务报告和审定财务报表 `--luna-glint` (0或 1) 切换箭头按钮的两个细节. 每一个颜色的零件都是用 白色和黑色的音色 由这些数字铺上, 所以一个新的方案需要它的音调 和它相似的方案的数字 `lunaSchemes` 并改变它们。 工作表的头条列出了每个属性及其所达到的角色.

一个彩色的轮回 一个方案. `--luna-accent-light` 是拇指和扣子在休息时的颜色 `--luna-accent`, (中文(简体) ), `--luna-accent-deep` 财务报告和审定财务报表 `--luna-glyph` 也许 `auto`当他们不是被骗的时候, 零件从 `--luna-accent-light` 在 OKLCH 中,当方案值发生变化时: 颜色的色调被保留,口音(环,热脸)和深色调(热时的色调和边缘,暗指的指向线,暗指的指向)会更暗而更有色调,而箭头和被指的指向则是颜色在淡色上发出色调而暗相上发出白调的暗色调. 关系与发货计划相适应(蓝色、紫色、橙色和粉色为月亮样式、银色和金色为金属样式),并用下列文字记下: `src/kits/luna/tones.ts`. 设定基调的计划保持自身价值.

```css
.luna-moss {
  --luna-light: top-left; --luna-diagonal: 1; --luna-glint: 0;
  --luna-face: #e4e6d4; --luna-disabled: #f0f0e6;
  --luna-highlight: 1; --luna-shade: 0.72; --luna-gloss: 0.182; --luna-depth: 0.196; --luna-hot: 0.624; --luna-press: 0.675; --luna-etch: 0; --luna-relief: 1;
  --luna-accent-light: #d3e6bf; /* the rest follows from this one */
}
```

计划设定时是金属的 `--luna-light: top` 取出"银"之数:一出暗刻相环相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相通相 最重要的数字是 `--luna-gloss` 财务报告和审定财务报表 `--luna-depth` 和 `--luna-etch` (指环. 颜色又变了 `--luna-accent-light`。 。 。 .

```css
.luna-steel {
  --luna-light: top; --luna-diagonal: 0; --luna-glint: 0;
  --luna-face: #e0dfe3; --luna-text: #0e1010; --luna-disabled: #f0f0e6;
  --luna-highlight: 0.731; --luna-shade: 0.913; --luna-gloss: 1; --luna-depth: 1; --luna-hot: 1; --luna-press: 0; --luna-etch: 1; --luna-relief: 0.686;
  --luna-accent-light: #d5dde8;
}
```

该工具包也是编写工具包的范例。 其每一部分都延长了此类合同类别(`AxScrollbarThumb`, (中文(简体) ), `AxScrollbarButton`,并带来同类规则作为自己的影子CSS(`static styles`,写在 `:host` 联 合 国 `::before` 财务报告和审定财务报表 `::after`);没有从外部抽取任何东西,默认外观也不必被关闭. 行为是唯一的代码: 升起的部分反映 `--luna-light` 作为属性 `light`,因为选择器可以在属性上切换几何,而不是在属性值上切换,并得出所剩的音量 `auto`;拇指也用设备像素来握住. 演示中滚动视图周围的XP窗口是Page CSS,而不是工具包的一部分.

### 触摸

`touch` 选择什么栏 触摸:

-   `indicator` (默认,Windows 8行为):栏只显示拇指,作为不取入的平板指标. 按钮,音轨和转角在显示时被放出并同时淡出后被鼠标带回,页面会像往常一样在指下滚动.
-   `bar`:在触摸栏杆时,看起来像鼠标一样工作. 在酒吧上下出一指或在其热地段下出一指属于酒吧,然后在5px之后决定:沿着它所拖的酒吧陡峭地走(相对于它所在的地方),在它中间没有其他事情发生. 快速的自带滑翔到被窃听的地方 或者激活它的下方的标记.

在两种模式中,被徘徊的标记及其卡片用于 `--ax-scrollbar-touch-idle-delay` 后指举起后.

### 无障碍

-   原生卷轴和焦点停留。 取景口是一个真正的滚动容器. 需要集中注意力(`tabindex="0"`) 只有在内部没有任何内容时,所以仅文本区域仍可被按键滚动,而有链接、按钮或字段的区域不会添加自己的 Tab stop:焦点会进入内容,然后从中箭头和页面密钥滚动. 在决定焦点变化的内容或属性时再次检查它 。 将重点集中在该要素的同时将重点放在取景点上(`delegatesFocus`) (中文(简体) ). 该元素本身没有作用或标签;对于任何元素,添加它们: `<ax-scroll-view role="region" aria-label="...">`。 。 。 .
-   条和牌是 `aria-hidden="true"`,没有角色,也不在标签顺序中。 标记用于指针:为相同的目的地提供链接或按钮. 无障碍树只显示内容.
-   强迫颜色( E)`forced-colors: active`: 上覆被隐藏而出土卷轴回. 印刷也一样.
-   减少动议`prefers-reduced-motion: reduce`:没有滑翔,没有拇指出错,部分改变一次看. 默认的卡片会减少移动, 并在之后自行关闭 `--ax-scrollbar-touch-idle-delay`。 。 。 .

### 浏览器支持

浏览器为 `::part()`: Chrome 73+,Firefox 72+,Safari 13.1+,以及 `ResizeObserver`, (中文(简体) ), `MutationObserver` 和指针事件。 波波佛API, `delegatesFocus` 财务报告和审定财务报表 `@property` 增强:没有第一个卡是固定元素;没有 `delegatesFocus` Tab 仍然到达了视图端口,但是点击元素时却不能将其聚焦.

## 参考文献

### 主机属性

打开 `<ax-scroll-view>` 财务报告和审定财务报表 `<ax-scrollbar>`的更改;改为: `kit` 重建栏杆.

| 属性 | 值/ 默认值 | 含义 |
| --- | --- | --- |
| `vertical`, (中文(简体) ), `horizontal` | `auto` (违约), `always`, (中文(简体) ), `hidden` | `auto`: 当有要滚动的东西时显示. `always`永远显示, `disabled` 当无所事事的时候. `hidden`:从未显示. |
| `hide` | 部件列表 | 部件从未显示。 见 [隐藏部件](https://npmcn.com/package/%40ax-design/scrollbar/#readme-hiding-parts)。 。 。 . |
| `touch` | `indicator` (违约), `bar` | 酒吧里有什么关系? 见 [触摸](https://npmcn.com/package/%40ax-design/scrollbar/#readme-touch)。 。 。 . |
| `track-click` | `page` (违约), `jump` | 音轨页面上的按键,或向指针滚动. |
| `snap` | 布尔 | 整个设备像素上的缩略图边缘和标记,用于复制桌面控制的主题. 当大拇指被固定的时候 `--ax-scrollbar-thumb-nudge`在CSS px中,拇指内部抽出的东西增加了它沿着栏子的位置,以整个设备像素着陆,就像月球套件的抓取线一样. |
| `kit` | 工具包名称 | 用那个工具包建零件. |
| `marker-selector` | CSS 选择器 | 制作匹配元素的标记 . |
| `marker-axis` | `vertical` (违约), `horizontal` | 由元素制成的标记轴. |
| `marker-align` | `center` (违约), `start` | 在那里,一个标记滚动 并坐在轨道上. |
| `suspended` | 布尔 | 淡出栏杆而忽略输入. |
| `indicator` | `auto` (违约), `near`, (中文(简体) ), `pinned` | `auto`栏杆显示在滚动器上的每一步. `near`: 仅在栏或卷轴上指针(总是如此) `<ax-scrollbar>`) (中文(简体) ). `pinned`栏杆总是显示. |
| `thumb-layers`, (中文(简体) ), `button-layers`, (中文(简体) ), `track-layers`, (中文(简体) ), `track-piece-layers`, (中文(简体) ), `corner-layers`, (中文(简体) ), `marker-layers`, (中文(简体) ), `card-layers` | 层名 | 见 [按配置排列的图层](https://npmcn.com/package/%40ax-design/scrollbar/#readme-layers-by-configuration)。 。 。 . |

由组件编写,供您选择( )`ax-scroll-view[indicator-state="touch"]::part(thumb)`,与 `~=` 名单:

| 属性 | 数值 |
| --- | --- |
| `indicator-state` | `none`, (中文(简体) ), `mouse`, (中文(简体) ), `touch` |
| `last-indicator` | `mouse`, (中文(简体) ), `touch`: 显示指标,或最后一个显示时,栏会淡出。 每个指标的样式 `indicator-state`,所以在淡出时保持外观. |
| `vertical-state`, (中文(简体) ), `horizontal-state` | 列表 `visible`, (中文(简体) ), `disabled`, (中文(简体) ), `hover`, (中文(简体) ), `near`, (中文(简体) ), `engaged`, (中文(简体) ), `pressed` |

### 主机符号

自定义属性设置在元素或任何祖先上(它们继承). 每个布局都会读出符号 `refresh()`;一个变化,从样式属性,规则或动画,适用于下个帧而无需调用. 时间常数是时间常数,除非注明:一次之后,运动已覆盖大约63%的距离; `0s` 即时.

| 脚本 | 默认 | 含义 |
| --- | --- | --- |
| `--ax-scrollbar-thickness` | `17px` | 酒吧的浓厚. 默认外观从中大小: 拇指和悬浮的标记填入栏中, 其余的缩放 `thickness / 17px`。 。 。 . |
| `--ax-scrollbar-padding` | `0px` | 酒吧边缘与其按钮和音轨之间的空间. |
| `--ax-scrollbar-thumb-min-length` | `48px` | 最短的拇指( T)`17px` ,而触摸指标显示). |
| `--ax-scrollbar-button-length` | `33/17` 厚度(`33px`(中文(简体) ) | 轴上按钮长度; `auto` 是一个正方形。 未注册: 未设置, 是比例 . |
| `--ax-scrollbar-hotzone` | `0px` | 从酒吧外缘向外的热带深度;百分比为厚度. 让酒吧 `near` 状态. |
| `--ax-scrollbar-line` | `40px` | 按下按钮的滚动 。 音轨页面为视图减一行. |
| `--ax-scrollbar-idle-delay` | `3s` | 鼠标指示器持续多久. |
| `--ax-scrollbar-touch-idle-delay` | `500ms` | 触摸指示器多久, 它盘旋标记和卡片停留. |
| `--ax-scrollbar-z-index` | `2147483000` | 堆叠 `<ax-scrollbar>` (未登记,与 `var()`) (中文(简体) ). |

很少更改 :

| 脚本 | 默认 | 含义 |
| --- | --- | --- |
| `--ax-scrollbar-scroll-smoothing` | `50ms` | 卷轴的胶片开始. |
| `--ax-scrollbar-thumb-smoothing` | `100ms` | 卷轴后方有被抽取的拇指、脚印和标记. |
| `--ax-scrollbar-repeat-delay`, (中文(简体) ), `--ax-scrollbar-repeat-interval` | `250ms`, (中文(简体) ), `50ms` | 等一等 等一等 等一等. |
| `--ax-scrollbar-expand-delay`, (中文(简体) ), `--ax-scrollbar-contract-delay` | `0s`, (中文(简体) ), `0s` | 需要多长时间才能拍拍 `engaged`在他们离开前闲置. |
| `--ax-scrollbar-state-smoothing` | `0s` | 颜色和大小在徘徊、按住和接触时会改变. |
| `--ax-scrollbar-fade-smoothing` | `75ms` | 栏杆显示或隐藏时的片段淡出. |
| `--ax-scrollbar-fade-in-duration`, (中文(简体) ), `--ax-scrollbar-fade-out-duration` | `250ms`, (中文(简体) ), `167ms` | 线性淡出(一张牌随它而淡出). `0s` 让它去滑行. |
| `--ax-scrollbar-slide-smoothing` | `160ms` | 部分从外缘滑入. |
| `--ax-scrollbar-slide-distance` | `0px` | 隐藏的部分坐落在外缘多远;从内容侧向负滑行. |
| `--ax-scrollbar-marker-spacing` | `6px` | 离这个更近的标记 只有一个标记. |
| `--ax-scrollbar-marker-reach` | `12px` | 距离标记中心有多远 指针仍然击中它. |
| `--ax-scrollbar-card-gap` | `12px` | 一张卡和酒吧之间的距离. |
| `--ax-scrollbar-card-delay` | `400ms` | 在第一个卡打开前等待标记. |
| `--ax-scrollbar-card-slide-duration` | `367ms` | 一张开口卡的幻灯片. |
| `--ax-scrollbar-card-slide-distance` | `12px` | 一张牌滑多远; `0px` 没有. |

由主机上的组件编写, 只读 : `--ax-scrollbar-vertical-size` 财务报告和审定财务报表 `--ax-scrollbar-horizontal-size`。 。 。 .

### 部件

| 编 | 元素 | 页:1 |
| --- | --- | --- |
| `scrollbar`, (中文(简体) ), `scrollbar-vertical`, (中文(简体) ), `scrollbar-horizontal` | `div` | 一巴;其厚度为宽或高. |
| `button`, (中文(简体) ), `button-start`, (中文(简体) ), `button-end` | `<ax-scrollbar-button>` | 一个带有切夫龙的步键. |
| `track` | `<ax-scrollbar-track>` | 整个赛道. |
| `track-piece`, (中文(简体) ), `track-piece-start`, (中文(简体) ), `track-piece-end` | `<ax-scrollbar-track-piece>` | 大拇指两侧的赛道. |
| `thumb` | `<ax-scrollbar-thumb>` | 你拖着的那部分. |
| `corner` | `<ax-scrollbar-corner>` | 两相会之处. |
| `marker` | `<ax-scrollbar-marker>` | 赛道上的标记. |
| `card`, (中文(简体) ), `card-content` | `<ax-scrollbar-card>`, (中文(简体) ), `div` | 标记的悬浮卡. |
| `viewport`, (中文(简体) ), `content` | `div` | `<ax-scroll-view>` 只有这个. |

一个部件携带 `part="<kind> <kind>-<axis> <kind>-<state>..."` (角无轴. `::part(thumb)` 匹配两个轴; `::part(thumb-vertical)` ; 列表与所有名称匹配 : `::part(marker-on-thumb marker-hover)`。 。 。 .

国家标志,每种标志都一样,也是部分元素的属性(`hover`, (中文(简体) ), `pressed`, (中文(简体) ), `engaged`, (中文(简体) ), `disabled`, (中文(简体) ), `rtl`, (中文(简体) ), `on-thumb`, (中文(简体) ), `current`附加时 `axis` 财务报告和审定财务报表 `direction`:

| 脚本 | 什么时候 |
| --- | --- |
| `<kind>-hover` | 指针在部分上方(按下标记计数). |
| `<kind>-pressed` | 拇指被拖动,按住按钮或页面重复,按住标记. |
| `<kind>-engaged` | 拇指或标记被徘徊,拇指被拖走,或者指针被放入热区,被延后. |
| `<kind>-disabled` | 轴无所取相. |
| `marker-current` | 卷轴到达的最后一个标记 . |
| `marker-on-thumb` | 标于指下. |
| `card-enter`, (中文(简体) ), `card-open`, (中文(简体) ), `card-exit` | 卡片生命周期:开始,显示,关闭(保持到其退出过渡结束). |
| `card-forward`, (中文(简体) ), `card-backward` | 牌会移动到卷轴的末端或开头. |
| `card-first`, (中文(简体) ), `card-swap` | 开卡时没有打开,或者替换开卡. |

### 部分投入

设定( A)`::part()`),注册并打出,没有继承. 部分的动画师将所绘制的值移动到当前状态的输入上.

| 财产 | 类型 | 默认 | 含义 |
| --- | --- | --- | --- |
| `--ax-scrollbar-part-color` | `<color>` | 透明 | 满色相. |
| `--ax-scrollbar-part-border-color` | `<color>` | 透明 | 边框颜色 . |
| `--ax-scrollbar-part-glyph-color` | `<color>` | 透明 | 按钮箭头的颜色 . |
| `--ax-scrollbar-part-size` | `<length>` | `0px` | 跨栏大小:拇指厚度,标记宽度. |
| `--ax-scrollbar-part-thickness` | `<length>` 或者说 `auto` | `auto` | 栏杆上的标记大小; `auto` 是一个点. |
| `--ax-scrollbar-part-opacity` | `<number>` | `1` | 显示栏时不透明 . |
| `--ax-scrollbar-part-glyph-scale` | `<number>` | `1` | 按钮箭头的缩放 . |
| `--ax-scrollbar-part-lines` | `<number>` | `2` | 纸牌标签的行. |
| `--ax-scrollbar-part-align` | `<number>` | `0.5` | 拇指横过栏子的地方: `0` 内缘, `1` 外缘. 未出动画. |
| `--ax-scrollbar-part-fill-clip` | `border-box` 或者说 `padding-box` | `border-box` | 填充是否止于边界内缘. |

按钮的箭头已设定 `::part(button)` 与 `--ax-scrollbar-glyph-width`, (中文(简体) ), `-height`, (中文(简体) ), `-thickness`, (中文(简体) ), `-offset`, (中文(简体) ), `-shape` (单位:千美元)`chevron` 或者说 `triangle`和 `-corner-radius`。 。 。 .

### 活动

在元素上;它们会泡出并跨越阴影界限. `detail` 实值 `{ marker, markers }`:标记和所有标记共享. `scroll` 财务报告和审定财务报表 `scrollend` 重新发送于 `<ax-scroll-view>`。 。 。 .

| 活动 | 何时 |
| --- | --- |
| `markerenter` | 指针移动到标记上. |
| `markerleave` | 指针留下它上的最后一块标记(直入另一起火灾) `markerenter` 页:1. |
| `markeractivate` | 标记上的媒体发布,移动量低于4px. 可取消. |

### JS API( API)

| 成员 | 打开 | 含义 |
| --- | --- | --- |
| `markers` | 两者 | 列表集,作为标记,或 `null` 选择者负责。 设置可移动的标记和元素,或 `null`。 。 。 . |
| `refresh()` | 两者 | 布局在下一个框架上传递;在从脚本中更改符后调用. |
| `refreshMarkers()` | 两者 | 收集并再次测量下帧的标记. |
| `viewport`, (中文(简体) ), `scrollTop`, (中文(简体) ), `scrollLeft`, (中文(简体) ), `scrollHeight`, (中文(简体) ), `scrollWidth`, (中文(简体) ), `scrollTo()`, (中文(简体) ), `scrollBy()`, (中文(简体) ), `scroll()` | `<ax-scroll-view>` | 取景口的卷轴API. |

标记对象有 `id`, (中文(简体) ), `label`, (中文(简体) ), `axis` (单位:千美元)`vertical` (默认), `position` (滚动坐标为px,被忽略) `element`, (中文(简体) ), `element` (它的起始边缘是位置,在每个布局上测量)和 `data` (为具相相相相相相相.

### 包和出口

| 导出 | 含义 |
| --- | --- |
| `register()` | 定义元素、层和默认部分. |
| `AxScrollView`, (中文(简体) ), `AxScrollbar` | 这两个元素. |
| `defineScrollbarKit(name, kit)`, (中文(简体) ), `hasScrollbarKit(name)`类型 `ScrollbarKit` | 定义和查看包. |
| `AxScrollbarPart` | 所有部件的基础; 延伸 `AxSurface`。 。 。 . |
| `AxScrollbarThumb`, (中文(简体) ), `AxScrollbarButton`, (中文(简体) ), `AxScrollbarTrack`, (中文(简体) ), `AxScrollbarTrackPiece`, (中文(简体) ), `AxScrollbarCorner`, (中文(简体) ), `AxScrollbarMarker`, (中文(简体) ), `AxScrollbarCard` | 合同类:无画. |
| `AxScrollbarDefaultThumb`, (中文(简体) ), `AxScrollbarDefaultButton`, (中文(简体) ), `AxScrollbarDefaultTrack`, (中文(简体) ), `AxScrollbarDefaultTrackPiece`, (中文(简体) ), `AxScrollbarDefaultCorner`, (中文(简体) ), `AxScrollbarDefaultMarker`, (中文(简体) ), `AxScrollbarDefaultCard` | 默认类:Windows 8外观. |
| `isPartClass(cls, kind)` | 班级是否是这种班级的一部分. |
| `@ax-design/scrollbar/kits/luna`数字 : `defineLunaKit()`, (中文(简体) ), `lunaSchemes`, (中文(简体) ), `adoptLunaSchemes(root?)` | Windows XP工具包及其色彩方案. 见 [Windows XP 工具包](https://npmcn.com/package/%40ax-design/scrollbar/#readme-windows-xp-kit)。 。 。 . |
| 类型 `PartClass`, (中文(简体) ), `PartKind`, (中文(简体) ), `PartState`, (中文(简体) ), `Look`, (中文(简体) ), `ScrollMarker`, (中文(简体) ), `Axis`, (中文(简体) ), `Placement` | `PartKind` 实值 `'thumb' | 'button' | 'track' | 'track-piece' | 'corner' | 'marker' | 'card'`。 。 。 . |

## 更改日志

见 [变动情况](https://npmcn.com/package/%40ax-design/scrollbar/CHANGELOG.md)。 。 。 .

## 发展

```bash
bun install
bun run build         # es/, build/index.mjs, build/main.js
bun run check         # type check
bun test              # unit tests
bun run test:browser  # browser tests
bun run demo          # demo page: Windows 8, Minimal, Windows 11, Windows XP kit, Cyber Punk
```

## 常见问题

### @ax-design/scrollbar 是什么？

将容器或页面的滚动条替换为 CSS 的网络组件,用于Axiom 设计系统\.

### 如何安装 @ax-design/scrollbar？

在项目目录运行 npm install @ax-design/scrollbar，或使用 pnpm add / yarn add / bun add。

### @ax-design/scrollbar 支持 TypeScript 吗？

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

### @ax-design/scrollbar 支持 ESM 还是 CommonJS？

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

### @ax-design/scrollbar 可以商用吗？

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

### @ax-design/scrollbar 的下载量有多少？

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

### @ax-design/scrollbar 还在维护吗？

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