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

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

安装

# with npm
npm install @ax-design/scrollbar

# with bun
bun add @ax-design/scrollbar

并导入:

// 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> 并赋予它一个高度:

<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 用于未显示的栏,所以内容可以远离它们:

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

页面滚动条

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

<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 滚动条伪元素.

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数字 :

<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:它们来自元素,如同一个赤裸的元素.

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)数字 :

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 当该部分被首次需要时, 运行该类, 所以一个工具箱的部分只存在于一个栏中 .

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

默认是一个空列表,所以默认的外观会用鼠标显示其按钮并跟踪;一个工具包会给出自己的默认(hide 资料夹。 属性,即使是空的,也压倒了它. 触摸所隐藏的不是问题 hide,参见 触摸。 。 。 .

按配置排列的图层

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

<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),所以默认外观上的任何内容都不必被关闭. 栏杆保留着他们决定的:在栏杆上坐到哪个部分,还有多长时间.

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: '' });

<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 信息提示、 不淡出来。 它需要注册的元素,定义的工具包和一个颜色方案.

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

<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. 设定基调的计划保持自身价值.

.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。 。 。 .

.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 重建栏杆.

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

主机符号

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

很少更改 :

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

部件

一个部件携带 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:

部分投入

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

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

活动

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

JS API( API)

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

包和出口

更改日志

见 变动情况。 。 。 .

发展

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