Core · 稳定

滚动容器

显式滚动区：给「可滚动」一个看得见的边界。

inset 变体：内嵌阴影 + 背景色 + 圆角边框，强烈暗示可滚动。

这里是一段超长内容，必须超出 140px 高度才能看到滚动条效果。

第二条：overscroll-behavior: contain 已开启，不会把滚动传到外层。

第三条：触屏使用惯性滚动（-webkit-overflow-scrolling: touch）。

第四条：prefers-reduced-motion: reduce 时自动关闭平滑滚动。

第五条：滚动条宽度随变体调整（sm 6px / 默认 8px / lg 12px）。

第六条：可通过 tabindex="0" 让本容器可被键盘聚焦。

条 1

条 2

条 3

条 4

条 5

条 6

条 7

横向 A

横向 B

横向 C

横向 D

横向 E

html

<div class="demo-row" style="align-items:flex-start">  <div class="icen-scroll-area icen-scroll-area--inset" data-icen-scrollbars="auto" tabindex="0" style="width:240px;height:140px;font-size:var(--icen-density-font-size-sm);color:var(--icen-token-text-muted)">    <p>inset 变体：内嵌阴影 + 背景色 + 圆角边框，<strong>强烈暗示可滚动</strong>。</p>    <p>这里是一段超长内容，必须超出 140px 高度才能看到滚动条效果。</p>    <p>第二条：overscroll-behavior: contain 已开启，不会把滚动传到外层。</p>    <p>第三条：触屏使用惯性滚动（-webkit-overflow-scrolling: touch）。</p>    <p>第四条：prefers-reduced-motion: reduce 时自动关闭平滑滚动。</p>    <p>第五条：滚动条宽度随变体调整（sm 6px / 默认 8px / lg 12px）。</p>    <p>第六条：可通过 tabindex="0" 让本容器可被键盘聚焦。</p>  </div>  <div class="icen-scroll-area icen-scroll-area--y icen-scroll-area--sm" data-icen-scrollbars="scroll" data-icen-scrollbar-delay="600" tabindex="0" aria-label="仅滚动时显示，闲置 600 毫秒后隐藏" style="width:160px;height:140px;padding:8px;background:var(--icen-token-bg-soft);border-radius:var(--icen-radius-md);font-size:var(--icen-density-font-size-sm)">    <div style="height:280px;display:flex;flex-direction:column;gap:6px">      <div class="demo-box">条 1</div>      <div class="demo-box">条 2</div>      <div class="demo-box">条 3</div>      <div class="demo-box">条 4</div>      <div class="demo-box">条 5</div>      <div class="demo-box">条 6</div>      <div class="demo-box">条 7</div>    </div>  </div>  <div class="icen-scroll-area icen-scroll-area--x icen-scroll-area--lg" data-icen-scrollbars="visible" tabindex="0" aria-label="始终显示的横向滚动条" style="max-width:240px;padding-bottom:8px">    <div style="display:flex;gap:8px;width:520px">      <div class="demo-box" style="flex-shrink:0">横向 A</div>      <div class="demo-box" style="flex-shrink:0">横向 B</div>      <div class="demo-box" style="flex-shrink:0">横向 C</div>      <div class="demo-box" style="flex-shrink:0">横向 D</div>      <div class="demo-box" style="flex-shrink:0">横向 E</div>    </div>  </div></div>

特性

方向：icen-scroll-area--x / --y / --both 限定滚动方向

全局 base.css 提供统一无箭头滚动条；调用 initScrollArea() 后启用闲置隐藏，未来插入的弹出面板也会接管。仅 CSS 时保持可见。

data-icen-scrollbars="auto|scroll|visible|hidden" 可在任意组件子树覆盖。默认 scroll 在滚动或聚焦时显示；auto 额外在悬停时显示；visible 始终显示；hidden 隐藏指示器但保留滚动。

data-icen-scrollbar-delay="900" 设置闲置毫秒；data-icen-scrollbar-gutter="auto|stable|both-edges" 独立控制留槽。--fade 是内容边缘遮罩，与滑块隐藏无关。

接口

初始化: initScrollArea()（kit 一行入口可直接命名导入）
导出: initScrollArea
类型: dist/behaviors/scroll-area.d.mts（随 npm 包发布，含全部 JSDoc 约束）

安装

bun add @icen.ai/ui

pnpm add @icen.ai/ui

npm install @icen.ai/ui

yarn add @icen.ai/ui

一行引入该组件（CSS 与 behavior 自动带上，无需关心内部 CSS 文件名）：

import { initScrollArea } from '@icen.ai/ui/kit/scroll-area';initScrollArea();

也可以用脚手架直接打印引入行：

bash

bunx --bun @icen.ai/ui add scroll-area

Astro 项目注意：kit 入口里的 CSS import 在页面 <script> 里会被 Astro 的 client bundle 摇掉——请改在布局 frontmatter 里引 CSS（import '@icen.ai/ui/components/scroll-area.css';），JS 行为仍可走 kit。Vite SPA / webpack 项目无此问题。

用法

import '@icen.ai/ui/ui.css';import { initScrollArea } from '@icen.ai/ui/behaviors/scroll-area';const dispose = initScrollArea(); // 页面一次；卸载时 dispose()<div class="icen-scroll-area icen-scroll-area--inset" tabindex="0"  data-icen-scrollbars="scroll" data-icen-scrollbar-delay="1200"  data-icen-scrollbar-gutter="stable" style="height:200px">  超长内容…</div><!-- 变体：--sm/--lg（滚动条宽度）/--x/--y/--both（轴向）/--inset（带边界）/--fade（渐隐遮罩）-->