x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/scrollbar.md

@@ -0,0 +1,218 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Scrollbar AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Scrollbar`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./scrollbar-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/scrollbar-v2`（包含 base.css、scrollbar-v2.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/scrollbar.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./scrollbar-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于包裹固定尺寸的内容区域，提供统一的自定义滚动条样式。
+
+
+### 何时使用
+
+- 页面局部区域需要独立滚动。
+- 下拉面板、抽屉、表格等复合组件需要统一滚动条视觉。
+- 需要通过方法控制内容区滚动位置。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Scrollbar } from 'x-next';
+
+</script>
+<template>
+<Scrollbar style="height: 160px">
+    <div style="height: 400px; box-sizing: border-box">
+      <p v-for="item in 12" :key="item">滚动内容 {{ item }}</p>
+    </div>
+  </Scrollbar>
+</template>
+```
+
+### 轨道类型
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Scrollbar } from 'x-next';
+
+</script>
+<template>
+<Scrollbar type="track" style="height: 160px">
+    <div style="height: 400px; box-sizing: border-box">
+      <p v-for="item in 12" :key="item">带轨道滚动内容 {{ item }}</p>
+    </div>
+  </Scrollbar>
+</template>
+```
+
+### 横向滚动
+
+默认横向滚动不会接管普通鼠标滚轮，可通过拖动滚动条、触控板横向手势或 Shift + 滚轮滚动。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Scrollbar } from 'x-next';
+
+</script>
+<template>
+<Scrollbar style="width: 420px">
+    <div style="display: inline-flex; gap: 12px; width: max-content; min-width: 940px; padding: 12px; box-sizing: border-box">
+      <span v-for="item in 10" :key="item">阶段 {{ item }}</span>
+    </div>
+  </Scrollbar>
+</template>
+```
+
+### 鼠标滚轮横向滚动
+
+设置 `horizontalWheel` 后，纯横向滚动区域会把普通鼠标滚轮转换为横向滚动；到达左右边界时会放行页面滚动。下面两个示例内容一致，可直接对比普通滚轮在未开启和开启后的差异。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Scrollbar } from 'x-next';
+
+</script>
+<template>
+<Scrollbar style="width: 420px">
+    <div style="display: inline-flex; gap: 12px; width: max-content; min-width: 940px; padding: 12px; box-sizing: border-box">
+      <span v-for="item in 10" :key="item">默认阶段 {{ item }}</span>
+    </div>
+  </Scrollbar>
+
+  <Scrollbar horizontal-wheel style="width: 420px">
+    <div style="display: inline-flex; gap: 12px; width: max-content; min-width: 940px; padding: 12px; box-sizing: border-box">
+      <span v-for="item in 10" :key="item">滚轮阶段 {{ item }}</span>
+    </div>
+  </Scrollbar>
+</template>
+```
+
+### 双向滚动
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Scrollbar } from 'x-next';
+
+</script>
+<template>
+<Scrollbar type="track" style="width: 420px; height: 180px">
+    <div style="display: grid; grid-template-columns: repeat(8, 96px); gap: 8px; width: max-content; padding: 12px; box-sizing: border-box">
+      <span v-for="item in 80" :key="item">单元 {{ item }}</span>
+    </div>
+  </Scrollbar>
+</template>
+```
+
+### 滚动事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Scrollbar } from 'x-next';
+import { ref } from 'vue';
+
+const eventLog = ref('等待滚动');
+
+const handleScroll = (event: Event) => {
+  const target = event.target as HTMLElement;
+  eventLog.value = `scrollTop: ${target.scrollTop}, scrollLeft: ${target.scrollLeft}`;
+};
+</script>
+<template>
+<Scrollbar style="height: 160px" @scroll="handleScroll">
+    <div style="height: 400px; box-sizing: border-box">
+      <p v-for="item in 12" :key="item">事件内容 {{ item }}</p>
+    </div>
+  </Scrollbar>
+  <p>{{ eventLog }}</p>
+</template>
+```
+
+### 命令式滚动
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Scrollbar } from 'x-next';
+import { ref } from 'vue';
+
+const scrollbarRef = ref();
+
+const scrollToTop = () => {
+  scrollbarRef.value?.scrollTo(0, 0);
+};
+
+const scrollToMiddle = () => {
+  scrollbarRef.value?.scrollTo({ top: 120, left: 180 });
+};
+
+const scrollToBottom = () => {
+  scrollbarRef.value?.scrollTop(260);
+};
+</script>
+<template>
+<Button @click="scrollToTop">回到左上</Button>
+  <Button @click="scrollToMiddle">滚动到中部</Button>
+  <Button @click="scrollToBottom">滚动到底部</Button>
+
+  <Scrollbar ref="scrollbarRef" type="track" style="width: 420px; height: 180px">
+    <div style="display: grid; grid-template-columns: repeat(8, 96px); gap: 8px; width: max-content; padding: 12px; box-sizing: border-box">
+      <span v-for="item in 80" :key="item">单元 {{ item }}</span>
+    </div>
+  </Scrollbar>
+</template>
+```
+
+### 禁用滚动方向
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Scrollbar } from 'x-next';
+
+</script>
+<template>
+<Scrollbar style="width: 420px" disable-horizontal>
+    <div style="display: inline-flex; gap: 12px; width: max-content; min-width: 940px; padding: 12px; box-sizing: border-box">
+      <span v-for="item in 10" :key="item">不会横向滚动 {{ item }}</span>
+    </div>
+  </Scrollbar>
+</template>
+```
+
+### 外层样式
+
+`class` 和 `style` 会透传到内部滚动容器，同时 `style` 中的宽高、最大宽高等布局尺寸会同步到 Scrollbar 外层节点，保证自定义滚动条轨道和真实滚动区域对齐。横向或双向滚动场景建议直接在 Scrollbar 上设置 `width` / `height`。`outerClass` 和 `outerStyle` 用于控制 Scrollbar 外层节点。`hide` 是复合组件内部兼容选项，只隐藏自定义滚动条，不会禁用内容滚动，业务代码不建议直接使用。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Scrollbar } from 'x-next';
+
+</script>
+<template>
+<Scrollbar outer-class="scrollbar-shell" style="height: 160px">
+    <div style="height: 400px; box-sizing: border-box">
+      <p v-for="item in 12" :key="item">外层样式内容 {{ item }}</p>
+    </div>
+  </Scrollbar>
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./scrollbar-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。