SidebarItem 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

在 Sidebar 中呈现导航入口，支持激活状态、图标、层级与状态提示，帮助识别当前位置。

使用选择

用于 Sidebar 导航入口，提供稳定身份、图标、文本和目标地址。激活状态不等于自动完成业务路由。

• 提供稳定 id 与 label；href 表示导航地址，onSelect 处理选择通知。

• disabled 禁止导航；actions 配置条目附加操作，parts 配置内置徽标和操作按钮。

• 内置updated圆点的名称随LocaleProvider更新；label、tags及actions仍属调用方内容。折叠态的装饰与可访问树结构保持原有契约。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { SidebarItem } from '@snowui-design-system/components';	let opened = $state('');</script> <div style="width: min(100%, 12rem);"><SidebarItem id="components" label="Components" icon="squares-four" iconCollection="phosphor" onSelect={() => opened = 'Components'} /></div>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

API 参考

主操作与标签／updated 之间的有效间距至少为 4 CSS px，缩小根字号或 gap scale 时仍保留；较大首选间距保持不变。长文字先缩略，Link 与 Button 都遵守可用宽度；末尾操作独立预留空间，不覆盖状态标签。leading 槽不小于内置图标既有的 12px 下限，默认 20px 与层级连接线对齐保持不变。

提供 href 时导航内容使用链接，否则使用按钮。附属 actions 与主导航操作独立；tags 显示在 label 与 updated 提示之间。折叠后保留图标，内置 Tooltip 提供完整标签。组件负责折叠过渡、标签布局与操作位置，页面只需提供数据和业务回调。

depth={1} 表示二级 Item。组件在既有 20px leading 槽内通过伪元素绘制等长双臂的 L 形点线：由密集的 1px Black/40% 点组成，弯曲圆角为 4px；默认视觉线长为 9px × 9px。竖线中心与同列一级 Item 的 Icon 中心对齐，横线中心与二级 Item 文字中心对齐。该图形只表达层级关系，没有独立交互或无障碍语义，不进入图标资源解析，也不随 IconProvider 切换。二级 Item 不同时显示普通 icon；调用方在 Sidebar 折叠时仍应隐藏二级 Item。