---
id: "tree"
title: "树形选择"
category: "选择组件"
document_type: "component-specification"
spec_status: "local-current-draft"
element_ui: "2.15.6"
vue: "2.6.14"
page: "../index.html#spec-tree"
source_data: "../component-data.json"
official_components: ["tree"]
template_components: ["el-input", "el-tree"]
scenario_count: 6
verification: "scenario-checklist-not-full-test-pass"
---

# 树形选择

专题 `tree` · 选择组件 · Element UI 2.15.6

## 适用范围与组件映射

公共色板及字体基线适用于整个运营后台。本库整理基础组件、组件状态和可复用的组合模式；本轮补齐表单整体验证、页面布局和导航组合；具体业务字段与跨页流程仍在业务场景中说明。专题验收清单包含接入要求，不表示当前示例已实现或已验证全部场景。

官方条目映射：`tree`。

本页模板直接使用的 Element UI 标签：`el-input`、`el-tree`。

## 通用基线

- 组件库：Element UI **2.15.6**；运行样例 Vue **2.6.14**。
- 系统中文字体：macOS 优先苹方，Windows 通常微软雅黑；工程顺序固定为 `"PingFang SC", "Microsoft YaHei", sans-serif`。不要求安装或加载网络字体，兼容回退不是另一套可选样式。
- 后续仅采用经验证且固定版本的兼容 Element UI 2.x；Element Plus 属于独立迁移路线。
- 正文、数据值、输入及已选值：`14px / 400 / 21px`，`#303133`。
- 表头及组件分组标题：`14px / 600 / 21px`；弹窗标题：`16px / 600 / 24px`，均使用 `#303133`。
- 辅助说明：`12px / 400 / 18px`，`#595959`；错误、链接、状态、禁用与占位按各自语义处理。
- 适用组件的默认尺寸为 `small / 32px`；不得将这一高度机械应用于表格、文本域、浮层等全部组件。
- 规范正文与场景说明使用 `14px / 400 / 24px`、`#303133`，不降成灰蓝小字。
- 筛选文本输入占位统一“请输入”；未选择下拉统一“请选择”；默认全部的下拉显示“全部”。字段标签保留业务含义；日期保留开始/结束语义。
- 次级文字操作（查看更多、编辑、详情、数据中心、更多）：`12px / 400 / 18px`，`#3377BB`；保留点击热区。
- 本规范库的深色目录、蓝色展示区属于文档排版，不是业务组件颜色或业务导航规范。

## 本页用法与分类

默认用法：选择多个层级节点时，默认沿用当前带过滤框的复选树，父子勾选联动；搜索只过滤可见节点，不清空已勾选项。

| 区分什么 | 本页内容 | 选用或触发条件 |
| --- | --- | --- |
| 用途：层级多选 | 树呈现层级结构；复选框用于收集多个节点。 | 当前专题默认用于层级多选，不作为侧边导航。仅展示结构或定位单个节点时，应按对应用途另定交互，不沿用复选结果语义。 |
| 功能：父子勾选关系 | 父子联动和各节点独立勾选是选择规则。 | 当前使用父子联动；只有父子必须独立选择时再配置严格勾选，并单独检查禁用传递及返回结果。 |
| 自动状态：展开、定位和勾选 | 展开控制可见层级；定位指出当前节点；勾选才改变选择集合。 | 半选由部分子节点勾选自动产生；当前节点高亮只有启用时才显示，不能把展开或鼠标经过算作勾选。 |
| 扩展功能：编辑与异步数据 | 懒加载、节点增删和拖拽需要额外数据与操作规则。 | 当前只含静态树的过滤和勾选。业务确有需求后才接入这些能力，拖拽还需键盘替代与位置限制。 |

使用边界：不把未选、已选、半选、禁用当作四套树样式。不把编辑、拖拽或远端加载默认包含在本页演示内。

## 组件规则

- **TREE-R01**：用于层级数据选择，不作为本次侧边导航；当前默认使用带过滤的父子联动复选树。展开、当前节点定位和勾选是独立行为，严格勾选仅在需要父子独立选择时另行配置。
- **TREE-R02**：提供未选 / 已选 / 半选 / 禁用 / 过滤无结果；搜索不清空原选择，node-key 稳定唯一。
- **TREE-R03**：按需使用懒加载、拖拽、节点编辑；拖拽需限定允许位置并提供键盘替代。此例覆盖过滤和父子勾选，不接入编辑及异步。
- **TREE-R04**：【公共用色】颜色仅从公共色值 引用：主色系 3 个基础色值、辅助功能色 3 个、中性色 10 个，共 16 个基础色值。角色可以多个，实际色值复用；不为每个组件、悬停 或不同字段再新增近似颜色。透明效果仅限遮罩 35% 与阴影 12%，从 外壳深色 派生。
- **TREE-R05**：【统一字体】统一系统中文字体：macOS 优先苹方（PingFang SC），Windows 通常使用微软雅黑（Microsoft YaHei）；工程顺序固定为 "PingFang SC", "Microsoft YaHei", sans-serif。使用设备已有字体，不要求安装或加载网络字体；最后一项仅作兼容回退，不是供页面作者任选的另一套样式。正文 14px/400/21px；表头与分组标题 14px/600/21px，弹窗标题 16px/600/24px；次级文字操作和辅助说明 12px/400/18px。正文与标题同用 #303133；不通过额外加粗或透明度改变正文轻重。
- **TREE-R06**：【叠加优先级】状态叠加规则：禁用阻断交互；输入类控件错误边框覆盖蓝色聚焦边框；输入框不叠加外圈或阴影，其他无边框操作保留键盘焦点提示；选中底覆盖悬停底；只读不等于禁用；加载不等于成功；业务启用/停用的文字结果不等于控件是否可点击。
- **TREE-R07**：【节点与展开】节点正文深灰、展开箭头辅助深灰；展开只改变箭头方向和子节点，不自动表示选中。
- **TREE-R08**：【悬停与当前节点】悬停或键盘定位浅灰背景；启用当前节点高亮时使用选中浅蓝底和操作蓝文字。
- **TREE-R09**：【勾选与半选】只有启用复选时使用主题蓝方框、白色对勾；父节点部分选中显示白色横线，不混同当前节点。
- **TREE-R10**：【禁用节点】禁用节点使用禁用灰并阻止对应操作，保留已选形状；禁用父节点不擅自禁用全部子节点。
- **TREE-R11**：【懒加载与空结果】真实异步节点请求显示主题蓝加载图标；失败为错误红短提示和操作蓝重试，空树用空值灰，不绘制红色触发框。
- **TREE-R12**：【组件边界】独立树没有输入触发框；当前节点、复选勾选和展开分别定义。仅树选择框组合才另用输入校验边框。
- **TREE-R13**：树上方过滤框沿用输入框专题的内容列宽度；树节点展开层级不改变输入宽度，长节点名称按树容器提供完整值读取。

## 场景与验收清单

以下为需核对的场景组；`[ ]` 不代表已经测试通过。

- [ ] **TREE-S01**：当前样例：过滤、节点展开、父子勾选与半选、禁用叶子、空结果；过滤不丢失已选节点。
- [ ] **TREE-S02**：勾选与展开分别验收；只有启用当前节点高亮时再检查定位状态。搜索框只承担过滤，不为树容器制造输入错误框。
- [ ] **TREE-S03**：接入验收：严格勾选、懒加载、失败、节点增删、拖拽位置、自定义节点与键盘移动替代。
- [ ] **TREE-S04**：接入验收：稳定节点标识（node-key）、大树性能、刷新后的展开与勾选保持。
- [ ] **TREE-S05**：共用视觉验收：仅核对本组件实际适用的颜色与组合状态；无此能力标为不适用，不给静态内容添加输入错误、半选或按下状态。
- [ ] **TREE-S06**：共用文字验收：正文14px/400、次级操作12px/400、标题600；检查实际子元素与弹出层。输入焦点只改自身边框，按钮和链接保留键盘焦点轮廓。

### 专题验收重点

父子半选、过滤保持已选、禁用节点、空结果。

## 当前示例模板

以下来自本专题的结构化示例，使用 Vue 2 模板语法。`v-model`、事件方法、数据列表等依赖 [components.js](../components.js)；完整样式文件及加载顺序见 [通用基线](FOUNDATIONS.md)。自定义组合标签的内部实现由下方依赖文件提供，不能仅复制标签作为完整组件。

```html
<label for="spec-tree-filter" class="audit-field-label">节点关键词</label>
<el-input id="spec-tree-filter" v-model="treeFilter" placeholder="请输入节点关键词" clearable label="节点关键词">
</el-input>
<el-tree aria-label="可勾选的分类树" ref="demoTree" :data="treeData" show-checkbox node-key="id" default-expand-all :filter-node-method="filterNode" :default-checked-keys="[11]">
</el-tree>
```

## 交付与使用边界

- 规范条款、示例代码与待验收场景分开理解；有示例不等于已覆盖所有样式、交互状态和使用场景。
- 业务接口、权限、时区、金额精度、数据规模等依赖应从实际项目读取，不使用演示值代替生产约定。
- 发生样式或文案变更时，同步专题数据、页面与 Markdown，避免规范和样例分离。

## 来源与关联

- 来源线索：本次补充。
- [打开本专题页面](../index.html#spec-tree)
- [通用基线](FOUNDATIONS.md)
- [规范总索引](README.md)
- [结构化规范数据](../component-data.json)（记录 id：`tree`）
- [原始历史样板](../original-20260621.html)
- [历史规范条目](../spec-notes.json)

## 本组件颜色状态表

| 状态 / 条件 | 统一规则 |
| --- | --- |
| 节点与展开 | 节点正文深灰、展开箭头辅助深灰；展开只改变箭头方向和子节点，不自动表示选中。 |
| 悬停与当前节点 | 悬停或键盘定位浅灰背景；启用当前节点高亮时使用选中浅蓝底和操作蓝文字。 |
| 勾选与半选 | 只有启用复选时使用主题蓝方框、白色对勾；父节点部分选中显示白色横线，不混同当前节点。 |
| 禁用节点 | 禁用节点使用禁用灰并阻止对应操作，保留已选形状；禁用父节点不擅自禁用全部子节点。 |
| 懒加载与空结果 | 真实异步节点请求显示主题蓝加载图标；失败为错误红短提示和操作蓝重试，空树用空值灰，不绘制红色触发框。 |

独立树没有输入触发框；当前节点、复选勾选和展开分别定义。仅树选择框组合才另用输入校验边框。

[公共颜色与字体 token](../color-tokens.json) · [公共组件样式](../color-contract.css) · [系统字体合同（最后加载）](../font-contract.css)

## 业务落地场景

- [人群标签 · 左侧标签目录 · 分类选择](../../showcase/index.html#segments) · [场景文档](../../showcase/docs/segments.md)
- [推广报表 · 日报 · 报表内代理层级及展开](../../showcase/index.html#reports) · [场景文档](../../showcase/docs/reports.md)
- [推广报表 · 代理层级树 · 展开与节点选择](../../showcase/index.html#agents) · [场景文档](../../showcase/docs/agents.md)

[竞品组件拆解](../../reference-review/竞品组件反推规范.html) · [业务场景分类](../../业务场景分类清单.md)