n-scroll-list 横向滚动列表
内容横向排列超出容器宽度时滑动浏览的容器：隐藏原生滚动条保持界面干净，可选底部自绘滑动指示器（轨道 + 滑块，随滚动实时位移），滚动到最左/最右端触发事件。典型场景：分类入口、商品横滑区、标签流、排行榜横排卡片。
内容放默认插槽自行排布（横向一行，多行内容请自行包一层纵向容器），组件不管理内容项与数据。scroll 控制是否允许滚动，indicator 独立控制指示器显示。内容不足以滚动时指示器自动隐藏。尺寸传 -1 或字符串 "-1" 时使用主题令牌，默认 48 / 16 / 4px；数字和数字字符串为 px，也可直接配置 px / rpx 长度，宽度还支持百分比。
平台兼容性
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 | QQ小程序 |
|---|---|---|---|---|---|---|
| √ | √ | √ | × | × | × | × |
如何调用
html
<n-scroll-list>
<view style="flex-direction:row">
<!-- 内容项，横向排列 -->
</view>
</n-scroll-list>API
属性
| 参数 | 说明 | 类型 | 默认值 | 可选值 |
|---|---|---|---|---|
| scroll | 是否允许横向滚动，关闭时保留当前位置 | Boolean | true | - |
| indicator | 是否显示底部滑动指示器；内容不足时自动隐藏 | Boolean | true | - |
| indicatorWidth | 轨道总宽；-1 跟随主题令牌，默认 48px | String / Number | -1 | -1、有限正数、正数 px/rpx/% 长度 |
| indicatorBarWidth | 滑块宽；-1 跟随主题令牌，默认 16px；超出轨道自动限宽 | String / Number | -1 | -1、有限正数、正数 px/rpx/% 长度 |
| indicatorHeight | 轨道高，滑块同高；-1 跟随主题令牌，默认 4px | String / Number | -1 | -1、有限正数、正数 px/rpx 长度 |
| indicatorColor | 轨道色，空则跟随主题弱填充（随深浅主题切换） | String | "" | CSS 色值 |
| indicatorActiveColor | 滑块色，空则跟随主题品牌色 | String | "" | CSS 色值 |
| indicatorCap | 轨道与滑块两端形态 | String | "round" | round / square |
| indicatorStyle | 指示器容器行内样式，最后应用，可覆盖与内容的间距 | String | "" | - |
| customClass | 根节点类，须在组件样式表内定义 | String | "" | - |
| customStyle | 根节点行内样式，最后应用，可设置背景和外边距等 | String | "" | - |
事件
| 事件名 | 说明 |
|---|---|
| left | 滚动到最左端时触发；进入边界沿触发，停在边界拖动不重复触发 |
| right | 滚动到最右端时触发；触发规则同 left |
| error | 指示器配置非法时触发，参数 NScrollListError：{prop: string, message: string}；仅停显指示器，滚动不受影响，修正后自动恢复 |
插槽
| 插槽名 | 说明 |
|---|---|
| default | 滚动内容；组件内容行为横向 flex，内容项间距用 margin 表达，多行内容请自行包一层纵向容器 |
方法
| 方法名 | 说明 |
|---|---|
| measure | 手动重新测量容器、内容、轨道与滑块；自动尺寸检测尚未完成时可主动请求 |
样式令牌
| CSS 变量 | 默认值 | 作用 |
|---|---|---|
| --n-scroll-list-track-w | 48px | 指示器轨道总宽 |
| --n-scroll-list-thumb-w | 16px | 指示器滑块宽 |
| --n-scroll-list-track-h | 4px | 指示器轨道高 |
| --n-scroll-list-gap | 12px | 指示器与内容的间距 |
实现说明
| 能力 | 常见做法 | 本组件做法与取舍 |
|---|---|---|
| 滚动容器 | scroll-view 加 scroll-x | 使用官方 direction：scroll 为 true 时 horizontal，为 false 时 none；不依赖触摸拦截 |
| 原生滚动条 | 各端 CSS 伪元素逐端隐藏 | 使用 scroll-view 的 show-scrollbar 属性，各端声明式关闭，无样式补丁 |
| 指示器跟手 | wxs / bindingx 响应层 | scroll-view 的 scroll 事件驱动响应式滚动位置，滑块以 transform 位移，不用脚本注入 |
| 尺寸与单位 | 数字 / 字符串指定尺寸，计算滑块行程 | 数字统一为 px；px/rpx/% 长度由原生样式解析，轨道和滑块测量值决定行程；-1 保留 CSS 变量与 SCSS 默认值，修正令牌后无需手动换算 |
| 滑块宽度 | 固定宽度，超宽配置可能溢出 | 固定宽度可配，以轨道实际宽度限宽；行程为轨道宽减滑块宽，滚动比例经 [0,1] 截断 |
| 到边事件 | 依赖平台 scrolltoupper/scrolltolower（端差异大：H5 端横向边界事件不派发） | scroll 事件坐标统一判定（到边阈值 1px），组件侧沿触发：初始停在最左端不触发，回到中间区后才重新进入判定，边界反复拖动不重复派发；各端行为一致 |
| 内容不足 | 指示器仍在原位 | 可滚动宽度不足 1px 视为不可滚，指示器整体隐藏，避免一条停在端点的死滑块 |
| 尺寸重测 | 暴露 init 手动重测 | 容器、内容及指示器尺寸自动重测；App / Web 使用元素尺寸观察，小程序使用组件库共享的 200ms 布局检测，隐藏页面及卸载停止观察；另暴露 measure |
| 参数错误 | 默认值替代非法配置 | 尺寸非法或形态非法触发 error 并停显指示器，滚动本体不受影响；修正后自动恢复 |
尺寸默认值只在样式令牌定义，脚本不再复制尺寸常量。主题尺寸、百分比与 rpx 变化后，布局测量完成即更新滑块行程；小程序自动检测存在最多一个检测周期的延迟，measure 也通过下一次布局测量异步生效。百分比轨道宽相对指示器容器，百分比滑块宽相对轨道。关闭滚动仍保留指示器，隐藏指示器仍允许滚动。
指示器默认色不设专属色：轨道读主题弱填充、滑块读主题品牌色，随深浅主题切换。indicatorStyle 与 customStyle 最后应用，可覆盖默认样式；指示器与内容默认间距 12px，可用 indicatorStyle 的 margin-top 覆盖。组件不管理内容项、分页与滚动定位。