字节跳动抖音前端与 UED 团队维护的 Semi Design 又推新版。v2.99.0 虽以修复为主，但涉及的 Cascader filterTreeNode 问题在日常业务中高频出现——级联选择器开启节点筛选后行为异常，直接影响表单交互体验。借此版本更新，我们梳理一下 Semi Design 的核心定位，并用一个可跑的项目示例把 Cascader 筛联筛选的正确用法落地。
级联筛选的坑与修复
Cascader（级联选择器）在中后台场景里承担地区选择、分类筛选等职责。filterTreeNode 属性允许用户输入关键词动态过滤节点，这在选项层级深、数据量大时几乎是必开的功能。
v2.99.0 之前，开启 filterTreeNode 后存在边界情况：当搜索结果跨多级时，选中路径回填或面板展开逻辑可能出现偏差，导致用户选了却看不到正确回显，或者面板折叠状态与预期不符。这类 bug 在数据层级超过三级时更容易触发。
修复后，筛选命中节点的路径回填和面板联动恢复一致。如果你此前因为这个问题绕开 filterTreeNode、改用自定义搜索方案，现在可以回归原生属性。
Semi Design 的定位：中后台优先
Semi Design 不是通用 UI 库的"又一个替代品"，它的设计语言和组件 API 明确面向中后台：
- 设计语言内置：间距、色板、圆角、阴影体系已预设，不需要从零搭设计规范。
- 主题系统灵活：通过 Design Token 覆盖，从品牌色到组件细节都能一键切换，不需要 fork 源码改样式。
- React 组件覆盖面广：表单、表格、导航、图表容器、上传等 60+ 组件，API 偏实用而非炫技。
对于需要快速交付内部工具、运营后台、数据看板的团队，Semi 的"开箱即用"不是营销话术——它确实省掉了设计规范对齐和基础组件造轮子的阶段。
实战：Cascader 筛选 + 主题定制
下面用一个最小可跑的 React 项目演示两件事：Cascader 开启 filterTreeNode 的正确写法，以及 Semi Design Token 主题覆盖。
项目初始化
npm create vite@latest semi-demo -- --template react
cd semi-demo
npm install @douyinfe/semi-ui @douyinfe/semi-icons
npm run dev
Cascader 级联筛选示例
把 src/App.jsx 替换为以下内容：
import { Cascader, Form, Button } from '@douyinfe/semi-ui';
import { IconSearch } from '@douyinfe/semi-icons';
// 模拟三级分类数据
const options = [
{
value: 'electronics',
label: '电子产品',
children: [
{
value: 'phone',
label: '手机',
children: [
{ value: 'iphone', label: 'iPhone' },
{ value: 'pixel', label: 'Pixel' },
{ value: 'xiaomi', label: '小米' },
],
},
{
value: 'laptop',
label: '笔记本',
children: [
{ value: 'macbook', label: 'MacBook' },
{ value: 'thinkpad', label: 'ThinkPad' },
],
},
],
},
{
value: 'clothing',
label: '服装',
children: [
{
value: 'men',
label: '男装',
children: [
{ value: 'shirt', label: '衬衫' },
{ value: 'jacket', label: '夹克' },
],
},
{
value: 'women',
label: '女装',
children: [
{ value: 'dress', label: '连衣裙' },
{ value: 'coat', label: '大衣' },
],
},
],
},
];
function App() {
return (
<div style={{ padding: 40, maxWidth: 600 }}>
<h3>商品分类选择（支持搜索筛选）</h3>
<Form layout="horizontal">
<Form.Select field="category" label="分类">
<Cascader
style={{ width: 360 }}
options={options}
filterTreeNode
placeholder="输入关键词筛选，如「小米」「夹克」"
showSearch
showNextLevel={false}
onChange={(value) => console.log('选中路径:', value)}
/>
</Form.Select>
<Button theme="solid" type="primary" htmlType="submit">
提交
</Button>
</Form>
</div>
);
}
export default App;
关键点说明：
filterTreeNode开启后，用户在输入框键入关键词，Semi 会跨所有层级匹配 label，命中节点的完整路径自动展示。v2.99.0 修复了此前路径回填不一致的问题。showNextLevel={false}让搜索结果只显示命中节点本身而非逐级展开，适合选项多、层级深的场景。onChange回调返回的是完整路径数组，如['electronics', 'phone', 'xiaomi']，直接对接后端分类 ID 链。
主题覆盖：一行改品牌色
Semi 的 CSS Variable 体系让主题切换不需要编译步骤。在 src/index.css 或全局样式文件顶部加入：
:root {
/* 主品牌色：从默认蓝改为抖音红 */
--semi-color-primary: #fe2c55;
--semi-color-primary-hover: #e8244d;
--semi-color-primary-active: #d01a42;
/* 圆角：从 4px 改为更圆润的 8px */
--semi-border-radius-small: 8px;
--semi-border-radius-medium: 12px;
}
刷新页面后，所有 Button、Cascader、Form 的主色调和圆角同步变化，无需改组件代码。这套 Token 覆盖机制在多品牌/多租户后台里尤其实用——不同客户切换主题只需替换 CSS 变量文件。
升级与采用建议
已有项目升级：v2.99.0 是修复版本，无破坏性 API 变动。直接升级即可：
npm install @douyinfe/semi-ui@2.99.0
如果你用了 Cascader + filterTreeNode，升级后验证搜索选中回填是否恢复正常，重点测三级以上数据。
新项目评估：考虑以下几点——
| 维度 | Semi Design 适合 | 不适合 |
|---|---|---|
| 场景 | 中后台表单/表格/导航密集型 | 营销 H5、强视觉定制 C 端 |
| 技术栈 | React 18+ | Vue / Angular |
| 设计资源 | 无独立设计团队，需要现成规范 | 有完整品牌设计系统，需深度定制 |
| 主题需求 | 多租户/多品牌切换 | 单一品牌、样式改动极少 |
Semi Design 的组件覆盖度和主题灵活性在中后台赛道里属于前列。v2.99.0 的 Cascader 修复看似小改动，但对依赖级联筛选的表单流程来说是稳定性补丁。如果你在选型阶段，建议用上面的示例项目跑一遍核心交互组件（Table、Form、Cascader、Navigation），感受 API 设计的一致性和主题切换的流畅度，再决定是否深入采用。