n-segmented 分段器
少量等分选项的单选切换：一段灰底胶囊上滑块滑动选中的 iOS 分段控件形态，另有描边填充与底线两种外观。完全受控：点击不改变内部状态，只派发目标下标，页面回写 model-value 驱动滑块滑动——与请求联动的场景（切换失败要弹回）天然安全。
- 受控用法：
:model-value+@change回写；update:modelValue与change、click同参同发，手动双向绑定监听其一即可- 选项是等分布局，项数建议 2–5；长文字自动省略，超长建议精简文案或改用 n-tabs
- 单项禁用用对象项的禁用字段（
disabled-key可改字段名），整体禁用传disabled；选项数据或几何配置非法时派发error且不渲染残缺列表，修正后自动恢复
平台兼容性
| App | H5 | 微信小程序 | 支付宝小程序 | 百度小程序 | 头条小程序 | QQ小程序 |
|---|---|---|---|---|---|---|
| √ | √ | √ | × | × | × | × |
API
属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| items | string[] | UTSJSONObject[] | [] | 等分选项；字符串数组或对象数组，一次只用一种；坏项整体判错并派发 error，不渲染残缺列表 |
| model-value | number | 0 | 当前选中下标；-1 或越界为无选中（指示器隐藏），非整数或小于 -1 判错；点击后由父级回写 |
| name-key | string | "name" | 对象项的文字字段名；空串回落 name |
| disabled-key | string | "disabled" | 对象项的禁用字段名；空串回落 disabled，字段缺省表示可用 |
| type | "card" | "button" | "text" | "card" | 外观：card 灰底内缩滑块、button 描边框选中填充、text 底线 |
| shape | "square" | "circle" | "square" | 形状：square 圆角矩形、circle 胶囊；radius 显式设置时优先 |
| radius | number | -1 | 圆角 px；-1 按 shape 取主题令牌，0 为直角 |
| height | number | 0 | 选项行高度 px，下限 40 保证触控（button 型总高另含上下描边各 1px）；0 取主题令牌 |
| font-size | number | 0 | 文字字号 px；0 取主题令牌 |
| bold | boolean | true | 选中文字加粗 |
| color | string | "" | 未选中文字色；空串按外观取主题令牌 |
| active-color | string | "" | 选中文字色；空串按外观取主题令牌 |
| bg-color | string | "" | 容器背景色；空串按外观取主题令牌，button 型默认透明 |
| bar-color | string | "" | 指示色：滑块、填充、底线与描边共用一色；空串按外观取主题令牌 |
| disabled | boolean | false | 整体禁用：保色相降透明并拦截全部选择 |
| icon-only | boolean | false | 仅图标内容；经 item 插槽提供图标，每项宽度等于选项行高度呈方形 |
| immediate | boolean | true | 跳过挂载时的滑块入场动画；不影响后续选中切换 |
| duration | number | 200 | 滑块移动时长 ms；0 即时落位 |
| item-style | string | "" | 每项内容容器行内样式；不应破坏等分 flex |
| active-style | string | "" | 选中项容器的附加行内样式；与 item-style 合并应用 |
| text-style | string | "" | 内置文字行内样式；插槽文字由使用者自行指定 |
| bar-style | string | "" | 指示器行内样式；不应覆盖定位用的 transform/width |
| custom-class | string | "" | 根节点附加类名；类须定义在组件样式表内 |
| custom-style | string | "" | 根节点行内样式；可设置外距或 --n-segmented-* 令牌 |
事件
| 事件 | 参数 | 说明 |
|---|---|---|
| update:modelValue | index: number | 请求选中某项时回传下标，由父级回写；整体禁用、项禁用与重复点击已选中项不触发 |
| change | detail: | 同 update:modelValue 时机触发，item 为原始选项（对象项保留全部业务字段） |
| click | detail: | 同 change，保留"实际选中新项"语义 |
| error | detail: | 数据或配置非法时触发；index=-1 表示组件级配置，其他值为错误项下标；修正后自动恢复 |
插槽
| 插槽名 | 参数 | 说明 |
|---|---|---|
| item | 整体接管每项内容（放图标、换排版）；不传时渲染内置文字 |
主题令牌
| 令牌 | 默认值 | 说明 |
|---|---|---|
| --n-segmented-height | 40px | 选项行高度（触控下限 40px） |
| --n-segmented-height-button | 42px | button 型总高（含上下描边各 1px，选项行 = 总高 − 2） |
| --n-segmented-font-size | 14px | 文字字号 |
| --n-segmented-radius | 8px | 方角档圆角 |
| --n-segmented-circle-radius | 999px | 胶囊档圆角 |
| --n-segmented-inset | 2px | card 型滑块与容器边缘的内缩 |
| --n-segmented-bar-radius | 6px | card 型滑块圆角（= 容器圆角 − 内缩） |
| --n-segmented-bar-circle-radius | 999px | 胶囊档滑块圆角（radius 显式设置时同减内缩） |
| --n-segmented-padding-x | 4px | 项内水平留白 |
| --n-segmented-line-height | 2px | text 型底线粗细 |
| --n-segmented-disabled-opacity | 0.5 | 禁用透明度 |
在 uni.scss 写同名 !default 变量（$n-segmented-height: 44px;）可编译期覆盖；运行时换肤经根节点 custom-style 传入 CSS 变量。
实现说明
- 选项声明取数组模式：各参考实现中数组（字符串或对象 + 字段映射）是文档主流用法，子组件逐项声明会引入跨组件收集复杂度而收益有限，不收录；对象项保留全部业务字段，事件原样带回原始引用。
- 坏项显式报错不滤项：选项数据（非字符串/对象项、文字缺失或空白、禁用字段非布尔）与几何配置（负高度、非法时长、圆角小于 -1、选中下标非整数或小于 -1）整体判错并派发 error，不渲染残缺列表、不自动改选；修正配置后自动恢复。
- 三外观统一共享滑动指示器：滑块 / 填充块 / 底线都是同一个常驻绝对定位节点，JS 帧循环（16ms 时间戳调度）驱动 transform 位移与三次缓出插值，新目标从当前呈现位置续接；挂载首动可用
immediate跳过、duration为 0 即时落位；页面隐藏或应用切后台停帧落位，恢复后从当前位置继续；无选中时指示器原位隐藏（透明），恢复选中直接落位。 - 禁用视觉 = 保色相 + 降透明：整体与单项禁用都只降透明度（落在禁用项上的指示器同样降透明），不换灰底灰字，深浅主题下始终可读；被禁用的当前项保持选中显示，不擅自变更业务选择。
- 触控与圆角几何：选项行高度下限 40px，button 型总高另含上下描边各 1px（独立令牌，显式 height 同步注入两档）；radius 显式设置时容器与滑块的方角 / 胶囊档同时取该值（滑块自动减去内缩），shape 令牌默认不受影响。
- 结构位整根重建：外观、图标布局或项数翻转时组件整根重建一次装配到位（App 端动态插拔不重绘的规避惯例）；形状与选中切换只动类与指示器位移，不重建。
- Web 端可及性：radio 语义（aria-label / aria-checked / aria-disabled）、Tab 聚焦 + Enter / 空格选择、焦点可见轮廓、跟随系统减少动态效果设置。