--- id: "cascader" title: "级联选择与面板" category: "选择组件" document_type: "component-specification" spec_status: "local-current-draft" element_ui: "2.15.6" vue: "2.6.14" page: "../index.html#spec-cascader" source_data: "../component-data.json" official_components: ["cascader", "cascader-panel"] template_components: ["el-cascader", "el-cascader-panel"] scenario_count: 7 verification: "scenario-checklist-not-full-test-pass" --- # 级联选择与面板 专题 `cascader` · 选择组件 · Element UI 2.15.6 ## 适用范围与组件映射 公共色板及字体基线适用于整个运营后台。本库整理基础组件、组件状态和可复用的组合模式；本轮补齐表单整体验证、页面布局和导航组合；具体业务字段与跨页流程仍在业务场景中说明。专题验收清单包含接入要求，不表示当前示例已实现或已验证全部场景。 官方条目映射：`cascader`、`cascader-panel`。 本页模板直接使用的 Element UI 标签：`el-cascader`、`el-cascader-panel`。 ## 通用基线 - 组件库：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`；保留点击热区。 - 本规范库的深色目录、蓝色展示区属于文档排版，不是业务组件颜色或业务导航规范。 ## 本页用法与分类 默认用法：表单中的层级字段默认使用当前触发框：单选末级、展示完整路径，可搜索和清除；独立面板用于需要一直看见层级的区域。 | 区分什么 | 本页内容 | 选用或触发条件 | | --- | --- | --- | | 呈现：触发框或常驻面板 | 两种容器决定层级列表在哪里显示。 | 普通表单使用触发框展开；需要持续浏览层级时用当前独立面板。更换容器不自动改变单选或多选规则。 | | 功能：选择数量与父子关系 | 单选/多选决定可取多少项；父子关联决定父节点如何参与选择。 | 当前样例单选末级。只有明确需要多个结果或允许选父级时，才另行配置并验收，不把这些库能力默认全部打开。 | | 数据：路径显示与返回值 | 显示完整路径或末级名称影响可读性；返回值配置决定返回路径数组还是末级值。 | 本页保留完整路径。接入时分别确定显示内容和提交格式；只显示末级时仍需能查到完整路径。 | | 自动状态：展开、选中与反馈 | 展开路径用于浏览，选中才确定值；禁用与加载来自节点和请求。 | 点击展开不等于选中；禁用按实际父子关系处理。懒加载、失败和重试仅在接入异步数据时出现，本页为静态两级数据。 | 使用边界：不把触发框、面板、多选和半选称为几种同级外观。不把返回值配置当作路径显示样式。 ## 组件规则 - **CASCADER-R01**：用于真实层级选项，默认采用触发框内的单选末级选择；需要层级常驻时使用独立面板。单选/多选属于选择数量，父子关联属于选择规则，分别按业务需要配置，不能用平级筛选伪造上下级。 - **CASCADER-R02**：触发框宽度统一参考输入框专题；完整路径不得把内容列撑宽，超出时保留完整值读取入口。独立多级面板按面板容器和视口边界处理，不把触发框宽度直接当成所有层级列宽。 - **CASCADER-R03**：路径可全展示或仅末级展示，但必须有完整路径承接；覆盖禁用节点、空子级、懒加载失败与重试。 - **CASCADER-R04**：组件示例为静态两级级联；懒加载与异步错误需由宿主接入，不能宣称本样例已验证远端。 - **CASCADER-R05**：【公共用色】颜色仅从公共色值 引用：主色系 3 个基础色值、辅助功能色 3 个、中性色 10 个，共 16 个基础色值。角色可以多个，实际色值复用；不为每个组件、悬停 或不同字段再新增近似颜色。透明效果仅限遮罩 35% 与阴影 12%，从 外壳深色 派生。 - **CASCADER-R06**：【统一字体】统一系统中文字体：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；不通过额外加粗或透明度改变正文轻重。 - **CASCADER-R07**：【叠加优先级】状态叠加规则：禁用阻断交互；输入类控件错误边框覆盖蓝色聚焦边框；输入框不叠加外圈或阴影，其他无边框操作保留键盘焦点提示；选中底覆盖悬停底；只读不等于禁用；加载不等于成功；业务启用/停用的文字结果不等于控件是否可点击。 - **CASCADER-R08**：输入及选择触发框统一单层矩形：默认 白色 底、正文深灰 14px/400 字、禁用灰 占位、边框灰 边框；聚焦仅原边框 主题蓝，错误 错误红。鼠标点击与键盘进入均不新增外框或阴影。范围日期仅外层容器变边框，内部两个输入不重复画框。 - **CASCADER-R09**：仅接入真实字段校验时，触发框和就近错误短提示同步使用错误红；若配置错误图标，图标也同步。普通聚焦不报错，禁用不触发新校验；候选查询无匹配不等于字段错误，当前本地示例不伪造远端失败。 - **CASCADER-R10**：输入族统一直角 0px：普通输入、密码、文本域、自动补全、单选/多选触发框、级联、日期/时间与范围、数字输入及前后缀组合输入；默认/聚焦/错误/只读/禁用均不改变圆角。组合输入外侧和拼接处均不保留小圆角，弹出面板的圆角由面板规范独立定义。 - **CASCADER-R11**：【触发框与路径】白底、正文深灰、边框灰；聚焦仅原边框主题蓝；路径分隔使用辅助深灰，不增加外圈。 - **CASCADER-R12**：【展开与选中】当前展开路径使用操作蓝文字与选中浅蓝定位；普通悬停浅灰背景；最终选择保留明确选中标记。 - **CASCADER-R13**：【多选模式】只有多选模式才使用主题蓝复选标记；父级部分选中用白色横线，单选模式不显示半选。 - **CASCADER-R14**：【禁用】不可选节点文字禁用灰并阻止选择；默认父子关联模式下父节点禁用会传递至后代。父子非关联模式（checkStrictly）按节点自身disabled值处理，切换模式须单独验收。 - **CASCADER-R15**：【懒加载与错误】请求子级时主题蓝加载图标；失败在对应层错误红提示及操作蓝重试；真实字段校验错误仅同步触发框与短提示。 - **CASCADER-R16**：【组件边界】级联单选没有复选半选；只有明确启用多选及父子勾选关系时才呈现勾选和半选。路径展开不是最终选中。 ## 场景与验收清单 以下为需核对的场景组；`[ ]` 不代表已经测试通过。 - [ ] **CASCADER-S01**：当前样例：静态两级叶子选择、清除、路径搜索、禁用叶子以及独立面板。 - [ ] **CASCADER-S02**：接入验收：先确定选择数量与父子关联规则，再按需验证多选标签折叠、父子非关联选择（checkStrictly）；返回路径数组或末级值（emitPath）属于数据格式，不是显示样式。 - [ ] **CASCADER-S03**：接入验收：点击/悬停展开、完整路径承接、懒加载子级、叶子判断、空子级、失败重试与长路径。 - [ ] **CASCADER-S04**：父节点禁用是否传递至后代必须按实际 checkStrictly 配置检查，不把单选或严格模式误写成复选半选。 - [ ] **CASCADER-S05**：共用视觉验收：仅核对本组件实际适用的颜色与组合状态；无此能力标为不适用，不给静态内容添加输入错误、半选或按下状态。 - [ ] **CASCADER-S06**：共用文字验收：正文14px/400、次级操作12px/400、标题600；检查实际子元素与弹出层。输入焦点只改自身边框，按钮和链接保留键盘焦点轮廓。 - [ ] **CASCADER-S07**：宽度联动验收：按输入框专题核对整项与边框口径、同组对齐、长内容、窄容器换行及状态不跳宽。 ### 专题验收重点 选择叶子、清除、搜索路径、禁用分支；懒加载失败另行接入验收。 ## 当前示例模板 以下来自本专题的结构化示例，使用 Vue 2 模板语法。`v-model`、事件方法、数据列表等依赖 [components.js](../components.js)；完整样式文件及加载顺序见 [通用基线](FOUNDATIONS.md)。自定义组合标签的内部实现由下方依赖文件提供，不能仅复制标签作为完整组件。 ```html

级联选择

独立层级面板

``` ## 交付与使用边界 - 规范条款、示例代码与待验收场景分开理解；有示例不等于已覆盖所有样式、交互状态和使用场景。 - 业务接口、权限、时区、金额精度、数据规模等依赖应从实际项目读取，不使用演示值代替生产约定。 - 发生样式或文案变更时，同步专题数据、页面与 Markdown，避免规范和样例分离。 ## 来源与关联 - 来源线索：本次补充。 - [打开本专题页面](../index.html#spec-cascader) - [通用基线](FOUNDATIONS.md) - [规范总索引](README.md) - [结构化规范数据](../component-data.json)（记录 id：`cascader`） - [原始历史样板](../original-20260621.html) - [历史规范条目](../spec-notes.json) ## 本组件颜色状态表 | 状态 / 条件 | 统一规则 | | --- | --- | | 触发框与路径 | 白底、正文深灰、边框灰；聚焦仅原边框主题蓝；路径分隔使用辅助深灰，不增加外圈。 | | 展开与选中 | 当前展开路径使用操作蓝文字与选中浅蓝定位；普通悬停浅灰背景；最终选择保留明确选中标记。 | | 多选模式 | 只有多选模式才使用主题蓝复选标记；父级部分选中用白色横线，单选模式不显示半选。 | | 禁用 | 不可选节点文字禁用灰并阻止选择；默认父子关联模式下父节点禁用会传递至后代。父子非关联模式（checkStrictly）按节点自身disabled值处理，切换模式须单独验收。 | | 懒加载与错误 | 请求子级时主题蓝加载图标；失败在对应层错误红提示及操作蓝重试；真实字段校验错误仅同步触发框与短提示。 | 级联单选没有复选半选；只有明确启用多选及父子勾选关系时才呈现勾选和半选。路径展开不是最终选中。 [公共颜色与字体 token](../color-tokens.json) · [公共组件样式](../color-contract.css) · [系统字体合同（最后加载）](../font-contract.css) ## 业务落地场景 **当前业务：暂未采用。** 现有代理树与普通下拉没有逐级选择路径；保留级联选择作为储备组件。 本页保留组件示例和接入规则。已核实的参考截图尚未提供合适业务落点，不链接无关首页，不为覆盖组件而新增业务字段。 **适用条件**：表单中的层级字段默认使用当前触发框：单选末级、展示完整路径，可搜索和清除；独立面板用于需要一直看见层级的区域。 **采用边界**：不把触发框、面板、多选和半选称为几种同级外观。不把返回值配置当作路径显示样式。 [竞品组件拆解](../../reference-review/竞品组件反推规范.html) · [业务场景分类](../../业务场景分类清单.md)