Tree

展示和操作层级数据。中文惯用名：树。

稳定本期新增已接入

元信息

字段	值
规范 ID	`component.tree`
名称	Tree
二级分类	数据展示（`data-display`）
用途	展示和操作层级数据
描述	中文惯用名：树。

预览

静态结构：Tree 为自实现树（非第三方原语），根节点 role="tree"，节点 role="treeitem"。每行 flex：含子节点时渲染 switcher 按钮（chevron-right 图标，展开时 rotate-90 旋转，transition-transform 过渡），无子节点渲染同宽占位；checkable 时在图标后渲染 Checkbox；标题文本 truncate。按深度缩进（paddingLeft = depth × 16 + 4 px）；选中行 bg-accent 加粗；禁用节点（整树 disabled 或节点级 disabled）半透明且不可点。勾选为独立勾选（不联动父子），父节点在子孙存在勾选时显示半选（indeterminate）。展开 / 选中 / 勾选均支持受控（传 expandedKeys / selectedKeys / checkedKeys）与非受控（default*Keys 初始化内部状态）。

DSL 结构

DslNode

{
  "type": "Tree",
  "props": {
    "treeData": [
      {
        "key": "org",
        "title": "组织架构",
        "children": [
          {
            "key": "dev",
            "title": "研发部",
            "children": [
              {
                "key": "frontend",
                "title": "前端组"
              },
              {
                "key": "backend",
                "title": "后端组"
              }
            ]
          },
          {
            "key": "design",
            "title": "设计部"
          }
        ]
      }
    ],
    "defaultExpandedKeys": [
      "org",
      "dev"
    ],
    "checkable": true
  }
}

何时用

何时使用

展示和操作层级数据：组织架构、目录、分类、地区等多级结构。
需要逐层展开 / 收起浏览父子关系，或按节点单选定位。
需要对层级节点做独立勾选（如权限点、资源多选），父节点以半选反映子孙勾选。

何时不用

仅折叠 / 展开平级分组内容、不表达层级数据：使用 Accordion。
平级视图或模式切换：使用 Segmented 或 Tabs，Tree 不承载内容面板切换。
行列对齐的批量数据操作：使用 Table（树表联动场景 Tree 仅作层级侧栏）。
线性步骤或流程进度：使用 Steps / Timeline。

变体

变体	视觉形态	适用场景
默认（可选择）	chevron 展开 + 缩进层级，选中行高亮	目录、分类浏览与单选定位
checkable 可勾选	节点前复选框，支持半选	权限配置、资源多选等层级勾选
受控模式	expandedKeys / selectedKeys / checkedKeys 外部驱动	与外部状态联动（如树表联动、搜索结果定位展开）
非受控模式	defaultExpandedKeys / defaultSelectedKeys / defaultCheckedKeys 初始化	独立展示，交互状态由组件自管
禁用态	整树或节点级半透明、不可交互	只读查看或无权限节点的展示

API 属性

属性	类型	默认值	说明
`treeData`	`TreeNodeData[]`	[]	树数据（可含表达式解析后的数组）；节点结构 { key, title, children?, disabled? }
`expandedKeys`	`string[]`	—	受控展开 keys；传入即受控，需配合 onExpand 更新
`defaultExpandedKeys`	`string[]`	—	非受控初始展开 keys
`selectedKeys`	`string[]`	—	受控选中 keys；传入即受控，需配合 onSelect 更新
`defaultSelectedKeys`	`string[]`	—	非受控初始选中 keys
`checkable`	`boolean`	false	节点前显示勾选框；勾选为独立勾选，父节点按子孙勾选状态显示半选
`checkedKeys`	`string[]`	—	受控勾选 keys；传入即受控，需配合 onCheck 更新
`defaultCheckedKeys`	`string[]`	—	非受控初始勾选 keys
`disabled`	`boolean`	false	整树禁用；节点级禁用用 treeData 节点的 disabled
`onSelect`	`(keys: string[]) => void`	—	选中事件，传出选中 keys 数组（单选语义，数组含当前选中节点 key）
`onExpand`	`(keys: string[]) => void`	—	展开事件，传出最新展开 keys 数组
`onCheck`	`(keys: string[]) => void`	—	勾选事件，传出最新勾选 keys 数组
`className`	`string`	—	通用：根节点 class（与内置样式合并）
`style`	`CSSProperties`	—	通用：根节点内联样式

使用规范

节点 key 必须全局唯一且稳定，作为展开 / 选中 / 勾选三类状态的唯一标识。
受控与非受控二选一：传 expandedKeys / selectedKeys / checkedKeys 即受控，必须在对应事件中回写；只用 default*Keys 时组件自管状态。
选中为单选语义（点击标题选中当前节点）；需要多选时开启 checkable 而非依赖 selected。
勾选为独立勾选：勾选父节点不会自动勾选子孙，父节点仅以半选提示子孙存在勾选，业务侧按 checkedKeys 自行解释。
节点级禁用（节点 disabled）用于无权限或不可选分支；整树只读用 disabled 整体禁用。
层级缩进固定 16px / 级，标题超长 truncate，重要完整名称通过详情区或 Tooltip 补充。

正例

✓ 组织选择：checkable + defaultExpandedKeys 展开前两级，onCheck 收集勾选 keys 提交权限配置。
✓ 树表联动：selectedKeys 受控，onSelect 回写并刷新右侧 Table 数据。
✓ 目录浏览：非受控模式，用户自行展开收起，点击标题定位资源。

反例

✕ 用 Tree 折叠平级的内容分组（无父子数据语义，应使用 Accordion）。
✕ 传入受控 keys 却不处理对应事件回写，导致状态卡住无法交互。
✕ 预期勾选父节点自动级联勾选子孙（实现为独立勾选，需业务侧自行处理级联）。

Design Token 映射

不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。