x-next 1.14.0 → 1.16.0

package/AI_USAGE.md

@@ -1,11 +1,11 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # x-next AI 使用手册
 
-适用版本：**x-next@1.14.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
+适用版本：**x-next@1.16.0**。Vue：`^3.5.0`；Node：`>=20.19.0`。
 
-来源指纹（AI 行为说明、docs 导入快照、映射、样式依赖、版本、公开类型和 API 参考）：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+来源指纹（AI 行为说明、docs 导入快照、映射、样式依赖、版本、公开类型和 API 参考）：`089f62cfcc5dbb14a7c66c139cdccc00de64d2ebdf90162e3dca9438c15ba4de`。
 
-覆盖 57 个组件族与 103 个公开组件/服务导出。优先通过 [本地按需索引](./AI_USAGE/index.md) 读取组件页和 API，不为查本包用法默认搜索网络。
+覆盖 58 个组件族与 105 个公开组件/服务导出。优先通过 [本地按需索引](./AI_USAGE/index.md) 读取组件页和 API，不为查本包用法默认搜索网络。
 
 读取入口：`node_modules/x-next/AI_USAGE.md`；可用 `require.resolve('x-next/AI_USAGE.md')` 定位。消费项目应在自己的指令中明确引用。
 
@@ -40,6 +40,7 @@
 | Pagination | `Pagination` | `<x-pagination>` | `v-model:current`, `v-model:page-size` | `x-next/style/pagination` | `button.css`, `empty.css`, `form-checkbox.css`, `form-input.css`, `form-input-number.css`, `form-select.css`, `scrollbar-v2.css`, `spin.css`, `trigger.css` | [组件文档](https://x-next.yjmf.com/components/pagination) |
 | Steps | `Steps` | `<x-steps>` | `v-model:current` | `x-next/style/steps` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/steps) |
 | Tabs | `Tabs` | `<x-tabs>` | `v-model:active-key` | `x-next/style/tabs` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/tabs) |
+| TreeSelect | `TreeSelect`, `TreeSelectDropdown` | `<x-tree-select>` | `v-model`, `v-model:input-value`, `v-model:popup-visible`, `v-model:expanded-keys` | `x-next/style/tree-select` | `empty.css`, `form-checkbox.css`, `form-select.css`, `scrollbar-v2.css`, `spin.css`, `trigger.css` | [组件文档](https://x-next.yjmf.com/components/tree-select) |
 | Empty | `Empty` | `<x-empty>` | 无 | `x-next/style/empty` | 无独立依赖 | [组件文档](https://x-next.yjmf.com/components/empty) |
 | Upload | `Upload` | `<x-upload>` | `v-model:file-list` | `x-next/style/upload` | `image.css`, `progress.css`, `trigger.css`, `tooltip.css` | [组件文档](https://x-next.yjmf.com/components/upload) |
 | BarChart | `BarChart` | `<x-bar-chart>` | 无 | `x-next/style/bar-chart` | `spin.css` | [组件文档](https://x-next.yjmf.com/components/bar-chart) |
@@ -782,6 +783,42 @@ function resized(size: number) { current.value = 1; feedback.value = `每页 ${s
 </template>
 ```
 
+## TreeSelect
+
+[组件文档与 live demo](https://x-next.yjmf.com/components/tree-select)。用于在层级数据中选择节点，`data` 是 `{ key, title, children }` 树。单选为标量、`multiple` 为数组、`treeCheckable` 勾选模式始终返回数组；`allowSearch` 默认多选 / 勾选开启、单选关闭，`checkedStrategy` 默认 `parent`。
+
+勾选模式默认父子联动：勾选叶子会向上影响父级半选 / 全选，禁用与 `disableCheckbox` 节点不参与联动。`checkedStrategy` 决定回填 key：`parent` 只回填最高层已选节点，`child` 只回填叶子，`all` 返回全部；`treeCheckStrictly` 关闭联动且策略不生效。`change(value, info)` 的 `info` 含 `node`、`checked` / `selected`；`expand(keys, info)` 报告展开变化，`node-click` 报告节点点击。`v-model:expanded-keys` 控制展开，`default-expand-all` 只初始化。
+
+多选 / 勾选模式下点击节点会清空搜索词，需要保留时用 `allowSearch: { retainInputValue: true }`。`labelInValue` 时值为 `{ value, label, raw }`；`data` 中不存在的选中值默认保留并按 key 回显，`fallbackOption` 传函数可自定义、传 `false` 丢弃。异步子节点用 `isLeaf: false` + `loadMore`，展开时先加载再展开。搜索默认按标题过滤并保留命中祖先，`filterTreeNode` 可自定义；远程搜索设置 `filterTreeNode=false` 并用 `@search` 替换 `data`。大数据量传 `virtualListProps` 开启虚拟滚动。实例方法 `focus()` / `blur()` / `expandAll()` / `checkAll()`。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import 'x-next/dist/style.css';
+const region = ref<string | number | undefined>('hz');
+const feedback = ref('已选：hz');
+const data = [
+  {
+    key: 'zj',
+    title: '浙江省',
+    children: [
+      { key: 'hz', title: '杭州' },
+      { key: 'nb', title: '宁波' },
+      { key: 'wz', title: '温州（暂停服务）', disabled: true },
+    ],
+  },
+];
+function changed(value: unknown) {
+  feedback.value = value ? `已选：${String(value)}` : '已清空';
+}
+</script>
+<template>
+  <TreeSelect v-model="region" :data="data" default-expand-all allow-clear placeholder="请选择城市" @change="changed" />
+  <p role="status">{{ feedback }}</p>
+</template>
+```
+
 ## Steps
 
 [组件文档与 live demo](https://x-next.yjmf.com/components/steps)。子组件的公开名称是 `Step`。使用 `v-model:current`，序号从 **1** 开始，`defaultCurrent=1`、`status='process'`、`type='default'`、`direction='horizontal'`；点击切换需开启 `changeable`，默认关闭。
@@ -8278,6 +8315,701 @@ const handleChangeActive = () => {
 </template>
 ```
 
+## TreeSelect 扩展场景
+
+### 用途与选型
+
+用于在层级数据中选择单个、多个或勾选一批节点，适合地区、组织架构、分类目录、指标维度等字段。
+
+
+### 何时使用
+
+候选项存在父子层级，并希望像 Select 一样在下拉里完成选择时使用 TreeSelect；地区、部门、目录、指标树都是典型场景。平铺枚举用 Select，独立的多列级联用 Cascader；需要直接浏览树结构时使用独立的 Tree 组件。
+
+
+### 基础用法
+
+单选点击叶子节点后关闭面板并回显标题；点击分支节点只展开 / 收起。`allowClear` 提供清空按钮；禁用节点不可点击，也不会在清空时被误删。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import type { TreeSelectNodeData, TreeSelectValue } from 'x-next';
+
+const value = ref<string | number | undefined>('hz');
+const feedback = ref('已选：hz');
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'zj',
+    title: '浙江省',
+    children: [
+      { key: 'hz', title: '杭州' },
+      { key: 'nb', title: '宁波' },
+      { key: 'wz', title: '温州（暂停服务）', disabled: true },
+    ],
+  },
+];
+function changed(value: TreeSelectValue | TreeSelectValue[] | undefined) {
+  feedback.value = value ? `已选：${String(value)}` : '已清空';
+}
+</script>
+<template>
+<TreeSelect
+    v-model="value"
+    :data="data"
+    default-expand-all
+    allow-clear
+    placeholder="请选择城市"
+    @change="changed"
+  />
+  <p>{{ feedback }}</p>
+</template>
+```
+
+### 多选
+
+`multiple` 开启多选，值始终是数组，面板保持展开直到点击外部或按 Escape。`maxTagCount` 只折叠展示，不限制数量；`tagNowrap` 让标签不换行。多选 / 勾选模式下点击节点会清空搜索词（与 Select 一致），需要保留搜索词时用 `allowSearch: { retainInputValue: true }`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import type { TreeSelectNodeData, TreeSelectValue } from 'x-next';
+
+const value = ref<(string | number)[]>(['hz', 'nb']);
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'zj',
+    title: '浙江省',
+    children: [
+      { key: 'hz', title: '杭州' },
+      { key: 'nb', title: '宁波' },
+      { key: 'wz', title: '温州（暂停服务）', disabled: true },
+    ],
+  },
+];
+function removed(value: TreeSelectValue | undefined) {
+  console.log('移除：', value);
+}
+</script>
+<template>
+<TreeSelect
+    v-model="value"
+    :data="data"
+    multiple
+    default-expand-all
+    allow-clear
+    :max-tag-count="2"
+    tag-nowrap
+    placeholder="可多选城市"
+    @remove="removed"
+  />
+</template>
+```
+
+### 勾选模式与父子联动
+
+`treeCheckable` 开启复选框。勾选叶子后父节点自动变为半选；半选节点不出现在值里。默认 `checkedStrategy="parent"`，勾选整个分支时只回填父节点 key。禁用和 `disableCheckbox` 节点不参与联动，但仍可被父节点联动勾选。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import type { TreeSelectNodeData, TreeSelectValue } from 'x-next';
+
+const value = ref<(string | number)[]>(['hz']);
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'zj',
+    title: '浙江省',
+    children: [
+      { key: 'hz', title: '杭州' },
+      { key: 'nb', title: '宁波' },
+    ],
+  },
+];
+function changed(value: TreeSelectValue | TreeSelectValue[] | undefined, info: Record<string, unknown>) {
+  console.log('当前值：', value, '节点：', info.node);
+}
+</script>
+<template>
+<TreeSelect
+    v-model="value"
+    :data="data"
+    tree-checkable
+    default-expand-all
+    placeholder="勾选城市"
+    @change="changed"
+  />
+</template>
+```
+
+### 勾选策略
+
+`checkedStrategy` 控制回填值的粒度：`parent`（默认）保留最高层已选节点，`child` 只保留叶子，`all` 返回全部勾选节点。切换策略只影响后续回填值，规范业务数据时用 `parent` 更省心。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect, RadioGroup, Radio } from 'x-next';
+import type { TreeSelectNodeData } from 'x-next';
+
+const value = ref<(string | number)[]>(['zj']);
+const strategy = ref<'parent' | 'child' | 'all'>('parent');
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'zj',
+    title: '浙江省',
+    children: [
+      { key: 'hz', title: '杭州' },
+      { key: 'nb', title: '宁波' },
+    ],
+  },
+];
+</script>
+<template>
+<RadioGroup v-model="strategy">
+    <Radio value="parent">parent</Radio>
+    <Radio value="child">child</Radio>
+    <Radio value="all">all</Radio>
+  </RadioGroup>
+  <TreeSelect
+    v-model="value"
+    :data="data"
+    tree-checkable
+    default-expand-all
+    :checked-strategy="strategy"
+  />
+  <p>当前值：{{ value }}</p>
+</template>
+```
+
+### 严格勾选模式
+
+`treeCheckStrictly` 取消父子联动，勾选状态完全由业务控制；值为 `['zj']` 时子节点不会被自动勾选。适合「父级只作为分组标题、勾选互相独立」的场景。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import type { TreeSelectNodeData } from 'x-next';
+
+const value = ref<(string | number)[]>(['zj']);
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'zj',
+    title: '浙江省',
+    children: [
+      { key: 'hz', title: '杭州' },
+      { key: 'nb', title: '宁波' },
+    ],
+  },
+];
+</script>
+<template>
+<TreeSelect v-model="value" :data="data" tree-checkable tree-check-strictly default-expand-all />
+</template>
+```
+
+### 搜索与自定义过滤
+
+`allowSearch` 开启搜索框。默认按标题忽略大小写匹配，命中节点的祖先会保留展示，命中的文字自动高亮。`filterTreeNode` 可换成按编码等业务字段匹配；`search` 事件在 `searchDelay`（默认 500ms）后触发，适合远程查询。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import type { TreeSelectNodeData } from 'x-next';
+
+const value = ref<string | number | undefined>('');
+const input = ref('');
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'zj',
+    title: '浙江省',
+    code: '330000',
+    children: [{ key: 'hz', title: '杭州', code: '330100' }],
+  },
+];
+const filterByCodeOrTitle = (input: string, node: TreeSelectNodeData) =>
+  String(node.code ?? '').includes(input) || String(node.title ?? '').includes(input);
+</script>
+<template>
+<TreeSelect
+    v-model="value"
+    v-model:input-value="input"
+    :data="data"
+    allow-search
+    :filter-tree-node="filterByCodeOrTitle"
+    placeholder="输入城市名或行政区划代码"
+    @search="query => console.log('搜索：', query)"
+  />
+</template>
+```
+
+### 异步加载子节点
+
+给节点的 `isLeaf: false`，并传入 `loadMore`，展开时先请求子级、成功后再展开；加载中的节点显示转圈图标。适合目录、组织架构等大数据量场景，配合 `search` 事件还能实现远程搜索。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import type { TreeSelectNodeData } from 'x-next';
+
+const value = ref<string | number | undefined>('');
+const data = ref<TreeSelectNodeData[]>([
+  { key: 'region-east', title: '华东大区', isLeaf: false },
+]);
+const loadRegion = (node: TreeSelectNodeData): Promise<void> =>
+  new Promise((resolve) => {
+    setTimeout(() => {
+      node.children = [
+        { key: `${node.key}-a`, title: `${node.title} · 一组` },
+        { key: `${node.key}-b`, title: `${node.title} · 二组` },
+      ];
+      resolve();
+    }, 600);
+  });
+</script>
+<template>
+<TreeSelect v-model="value" :data="data" :load-more="loadRegion" placeholder="展开大区加载子级" />
+</template>
+```
+
+### 展开控制
+
+`default-expand-all` 首次渲染展开全部节点；`v-model:expanded-keys` 受控展开状态；`default-expanded-keys` 只指定部分节点；`auto-expand-parent`（默认开启）会在指定节点参与展开时自动补全祖先。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import type { TreeSelectNodeData } from 'x-next';
+
+const value = ref<string | number | undefined>('');
+const expandedKeys = ref<(string | number)[]>(['zj']);
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'zj',
+    title: '浙江省',
+    children: [{ key: 'hz', title: '杭州' }],
+  },
+];
+</script>
+<template>
+<TreeSelect
+    v-model="value"
+    v-model:expanded-keys="expandedKeys"
+    :data="data"
+    @expand="keys => console.log('展开：', keys)"
+  />
+</template>
+```
+
+### 自定义字段名
+
+`fieldNames` 把 `key`、`title`、`children`、`disabled` 等字段映射到业务数据上，无需在进入组件前转换结构。`checkable`、`disableCheckbox`、`selectable`、`isLeaf`、`icon` 同样可映射。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+
+const value = ref<string | number | undefined>('dept-design');
+const data = [
+  {
+    id: 'dept',
+    name: '产品技术中心',
+    sub: [
+      { id: 'dept-design', name: '设计部' },
+      { id: 'dept-fe', name: '前端组' },
+    ],
+  },
+];
+</script>
+<template>
+<TreeSelect
+    v-model="value"
+    :data="data"
+    :field-names="{ key: 'id', title: 'name', children: 'sub' }"
+    default-expand-all
+    placeholder="选择部门"
+  />
+</template>
+```
+
+### 值与标题
+
+`labelInValue` 让值变成 `{ value, label, raw }` 对象，提交表单或保存草稿时无需再反查标题；数据中已不存在的选中值会保留并在标签里回显，`fallbackOption` 关闭后则直接丢弃。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import type { TreeSelectNodeData, TreeSelectValue } from 'x-next';
+
+const value = ref<{ value: string | number; label: string } | undefined>({ value: 'hz', label: '杭州' });
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'zj',
+    title: '浙江省',
+    children: [{ key: 'hz', title: '杭州' }],
+  },
+];
+function changed(value: TreeSelectValue | TreeSelectValue[] | undefined) {
+  console.log('当前值：', value);
+}
+</script>
+<template>
+<TreeSelect v-model="value" :data="data" label-in-value default-expand-all allow-clear @change="changed" />
+</template>
+```
+
+### 自定义节点
+
+`title` 插槽拿到节点状态（`checked` / `halfChecked` / `selected` / `expanded` / `level`），`node-icon` 与 `switcher-icon` 分别替换节点前缀图标和展开箭头；数据里的 `icon` 字段也可以直接给节点配置图标函数。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import type { TreeSelectNodeData } from 'x-next';
+
+const value = ref<string | number | undefined>('hz');
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'cloud',
+    title: '云平台',
+    children: [
+      { key: 'hz', title: '杭州集群', status: 'healthy' },
+      { key: 'nb', title: '宁波集群', status: 'warning' },
+    ],
+  },
+];
+</script>
+<template>
+<TreeSelect v-model="value" :data="data" default-expand-all>
+    <template #title="{ node, checked }">
+      <span>
+        {{ node.title }}
+        <i v-if="node.status">{{ node.status === 'healthy' ? '●' : '▲' }}</i>
+      </span>
+    </template>
+  </TreeSelect>
+</template>
+```
+
+### 连接线与整行节点
+
+`showLine` 显示层级连接线，最后一个子节点的线止于自身行中；`blockNode` 让节点占据整行、悬停与选中背景铺满，适合表格筛选器里的窄宽度选择框。两者可以组合。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect, Switch } from 'x-next';
+import type { TreeSelectNodeData } from 'x-next';
+
+const value = ref<string | number | undefined>('sz-tc');
+const block = ref(true);
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'zj',
+    title: '浙江省',
+    children: [
+      { key: 'hz', title: '杭州' },
+      { key: 'nb', title: '宁波' },
+    ],
+  },
+];
+</script>
+<template>
+<Switch v-model="block" checked-text="整行" unchecked-text="缩进" />
+  <TreeSelect
+    v-model="value"
+    :data="data"
+    show-line
+    :block-node="block"
+    default-expand-all
+    allow-clear
+    placeholder="带连接线的树"
+  />
+</template>
+```
+
+### 禁用、错误、加载与尺寸
+
+`disabled` 关闭交互，`error` 标记校验失败，`loading` 展示加载图标并在面板内显示加载态，`size` 支持 `mini` / `small` / `medium` / `large`。这些状态与 Select 保持一致，可直接放进 FormItem。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect, Button } from 'x-next';
+
+const value = ref<string | number | undefined>('a');
+const loading = ref(false);
+const data = [
+  { key: 'a', title: '可选节点 A' },
+  { key: 'b', title: '可选节点 B' },
+];
+</script>
+<template>
+<TreeSelect :data="data" size="mini" placeholder="mini" />
+  <TreeSelect :data="data" size="small" placeholder="small" />
+  <TreeSelect :data="data" size="medium" placeholder="medium" />
+  <TreeSelect :data="data" size="large" placeholder="large" />
+  <TreeSelect :data="data" disabled placeholder="禁用" />
+  <TreeSelect v-model="value" :data="data" error placeholder="错误" />
+  <TreeSelect :data="data" :loading="loading" placeholder="加载" />
+  <Button size="small" @click="loading = !loading">{{ loading ? '结束加载' : '模拟加载' }}</Button>
+</template>
+```
+
+### 缺失值回显
+
+当值对应的节点不在当前 `data`（数据权限、分页、远程未命中）时，默认保留该值并以原始 key 回显；`fallbackOption` 传函数可自定义回显内容，传 `false` 则丢弃不存在节点。下拉里也会把这类值显示为额外节点，方便用户主动清除。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+
+const value = ref<string | number | undefined>('archived-node');
+const data = [
+  { key: 'a', title: '可选节点 A' },
+  { key: 'b', title: '可选节点 B' },
+];
+const fallback = (value: string | number) => ({
+  key: value,
+  title: `归档节点（${String(value)}）`,
+});
+</script>
+<template>
+<TreeSelect v-model="value" :data="data" :fallback-option="fallback" allow-clear />
+</template>
+```
+
+### 虚拟列表
+
+数据量大时传入 `virtualListProps` 开启虚拟滚动，`height` 控制可视区高度；关闭 `scrollbar` 可退回原生滚动条。搜索命中的节点同样按扁平结果虚拟化，不会因为层级展开而失效。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import type { TreeSelectNodeData } from 'x-next';
+
+const value = ref<string | number | undefined>('');
+const data: TreeSelectNodeData[] = Array.from({ length: 240 }, (_, index) => ({
+  key: `node-${index + 1}`,
+  title: `数据节点 ${index + 1}`,
+  isLeaf: true,
+}));
+</script>
+<template>
+<TreeSelect
+    v-model="value"
+    :data="data"
+    :virtual-list-props="{ height: 220 }"
+    allow-search
+    allow-clear
+    placeholder="240 个扁平节点"
+  />
+</template>
+```
+
+### 下拉定制与批量操作
+
+`header` / `footer` 插槽承载批量操作，`show-header-on-empty` / `show-footer-on-empty` 决定空态时是否保留；`empty` 替换空态。配合实例方法 `checkAll()` 与 `expandAll()` 可以做出「全选 / 展开全部」的工具条。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect, Button } from 'x-next';
+import type { TreeSelectInstance, TreeSelectNodeData } from 'x-next';
+
+const value = ref<(string | number)[]>([]);
+const select = ref<TreeSelectInstance>();
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'east',
+    title: '华东区',
+    children: [
+      { key: 'east-hz', title: '杭州' },
+      { key: 'east-nb', title: '宁波' },
+    ],
+  },
+];
+</script>
+<template>
+<TreeSelect ref="select" v-model="value" :data="data" tree-checkable default-expand-all>
+    <template #header>
+      <Button size="mini" @click="select?.checkAll(true)">全选</Button>
+      <Button size="mini" @click="select?.checkAll(false)">清空</Button>
+      <Button size="mini" @click="select?.expandAll(true)">展开全部</Button>
+    </template>
+    <template #footer>已选 {{ value.length }} 项</template>
+  </TreeSelect>
+</template>
+```
+
+### 自定义触发器与实例方法
+
+默认触发器承载输入与标签；如需完全自定义，使用 `trigger` 插槽并绑定 `onKeydown`，同时补齐 `role="combobox"` 与 ARIA。实例方法提供 `focus()` / `blur()` / `expandAll()` / `checkAll()`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import type { TreeSelectNodeData } from 'x-next';
+
+const value = ref<string | number | undefined>('');
+const popup = ref(false);
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'east',
+    title: '华东区',
+    children: [{ key: 'east-hz', title: '杭州' }],
+  },
+];
+</script>
+<template>
+<TreeSelect v-model="value" v-model:popup-visible="popup" :data="data" default-expand-all>
+    <template #trigger="{ popupVisible, disabled, treeId, activeDescendant, onKeydown }">
+      <button
+        type="button" role="combobox" :disabled="disabled" aria-label="自定义地区选择"
+        aria-haspopup="tree" :aria-expanded="popupVisible" :aria-controls="treeId"
+        :aria-activedescendant="activeDescendant" @keydown="onKeydown"
+      >{{ value || '选择地区' }}</button>
+    </template>
+  </TreeSelect>
+</template>
+```
+
+### 在 Form 中校验
+
+放在 FormItem 中即可继承尺寸、禁用与校验状态；值变化会触发 `validateTrigger`。必填校验使用 FormItem 的规则，不要依赖原生表单控件。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { reactive, ref } from 'vue';
+import { Form, FormItem, TreeSelect, Button, Space } from 'x-next';
+import type { FieldRule, FormInstance, TreeSelectNodeData } from 'x-next';
+
+const state = reactive<{ region: string | number | undefined }>({ region: undefined });
+const rules: Record<string, FieldRule[]> = { region: [{ required: true, message: '请选择归属地区' }] };
+const form = ref<FormInstance>();
+const result = ref('');
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'zj',
+    title: '浙江省',
+    children: [{ key: 'hz', title: '杭州' }],
+  },
+];
+const validate = async () => {
+  const errors = await form.value!.validate();
+  result.value = errors ? '校验失败' : '校验通过';
+};
+</script>
+<template>
+<Form ref="form" :model="state" :rules="rules">
+    <FormItem field="region" label="归属地区" required>
+      <TreeSelect v-model="state.region" :data="data" default-expand-all allow-clear />
+    </FormItem>
+    <Button type="primary" @click="validate">校验</Button>
+    <p>{{ result }}</p>
+  </Form>
+</template>
+```
+
+### 键盘与无障碍
+
+面板打开后：`↑` / `↓` 在可见节点间移动，`→` 展开当前节点或进入第一个子节点，`←` 收起或回到父节点，`Enter` 选中节点，勾选模式下 `空格` 切换勾选，`Escape` 关闭面板，`Tab` 离开并关闭。Home / End 在搜索框为空时跳到首 / 末节点。触发器是 `role="combobox"` 并关联 `aria-controls` / `aria-activedescendant`，树容器是 `role="tree"`，节点带 `aria-level`、`aria-selected`、`aria-checked`（半选为 `mixed`）。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { TreeSelect } from 'x-next';
+import type { TreeSelectNodeData } from 'x-next';
+
+const value = ref<string | number | undefined>('');
+const popup = ref(false);
+const data: TreeSelectNodeData[] = [
+  {
+    key: 'zj',
+    title: '浙江省',
+    children: [{ key: 'hz', title: '杭州' }],
+  },
+];
+import type { HTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "键盘选择地区" } satisfies HTMLAttributes;
+</script>
+<template>
+<TreeSelect v-bind="nativeAttrs1"
+    v-model="value"
+    v-model:popup-visible="popup"
+    :data="data"
+    default-expand-all
+
+    placeholder="方向键选择，Enter 确认"
+  />
+</template>
+```
+
+### 节点数据
+
+| 字段 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| `key` | 节点键值，全局唯一；不传按路径生成 | `string \| number` | `-` |
+| `title` | 节点标题 | `string` | 取 `key` |
+| `children` | 子节点 | `TreeSelectNodeData[]` | `-` |
+| `disabled` | 是否禁用（不可选、不可勾选、不参与联动） | `boolean` | `false` |
+| `checkable` | 是否可勾选 | `boolean` | `true` |
+| `disableCheckbox` | 是否禁用复选框（仍可被父节点联动） | `boolean` | `false` |
+| `selectable` | 是否可选中 | `boolean` | `true` |
+| `isLeaf` | 是否叶子节点（配合 `loadMore`） | `boolean` | 无子节点即叶子 |
+| `icon` | 节点前缀图标 | `() => VNode` | `-` |
+
+
+### 无障碍
+
+- 触发器输入为 `role="combobox"`，带 `aria-haspopup="tree"`、`aria-expanded`、`aria-controls` 和 `aria-activedescendant`。
+- 树容器为 `role="tree"`，节点为 `role="treeitem"`，带 `aria-level`、`aria-posinset`、`aria-setsize`、`aria-selected`、`aria-expanded`、`aria-checked`（半选为 `mixed`）。
+- 键盘完整支持 `↑` / `↓` / `←` / `→` / `Home` / `End` / `Enter` / `空格` / `Escape` / `Tab`。
+- 标签关闭按钮与清空按钮均为真实按钮并提供无障碍名称；移除标签后焦点回到输入框。
+
+
+### 已知限制
+
+- 勾选模式下 `treeCheckStrictly` 为真时半选概念不生效，值完全由业务控制，请保持值与 `data` 同步。
+- `checkedStrategy` 在 `treeCheckStrictly` 下不生效（严格模式直接返回勾选集合）。
+- `loadMore` 依赖节点的 `isLeaf: false` 标记；数据里已有 `children` 的节点不会再触发加载。
+- 搜索为前端过滤；远程搜索请设置 `filterTreeNode=false`，用 `@search` 请求数据并替换 `data`。
+- 节点 `key` 必须唯一；重复键会退化为路径键并在控制台告警。
+- 与 Arco 的差异：`checkedStrategy` 默认 `parent`（Arco 默认 `all`），并在其基础上提供 `child`；值可为 `labelInValue` 对象且附带 `raw` 原始节点，属于 x-next 的扩展。
+
+
 ## Empty 扩展场景
 
 ### 用途与选型
@@ -9580,6 +10312,33 @@ const series = ref([
 </template>
 ```
 
+### CSS 变量与系列颜色
+
+`series[].color` 和 `labels.color` 支持 CSS 自定义属性引用（含 fallback），以及具名颜色、hex、rgb/rgba、hsl/hsla。传入值原样用于折线、面积、数据点、图例和提示色块，变量在图表所在节点解析；变量值变化无需替换系列数据。未传颜色时使用内置主题色板。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+const area = ref(true);
+
+import { ref } from 'vue';
+import { Button, LineChart } from 'x-next';
+import type { LineChartSeries } from 'x-next';
+
+const alternateColor = ref(false);
+const series: LineChartSeries[] = [
+  { name: '访问量（PV）', data: [20, 45, 30], color: 'var(--demo-line-color, var(--x-color-primary-6))' },
+];
+</script>
+<template>
+<div :style="{ '--demo-line-color': alternateColor ? 'var(--x-color-success-6)' : 'var(--x-color-primary-6)' }">
+    <Button @click="alternateColor = !alternateColor">切换系列颜色</Button>
+    <LineChart :categories="['10-07', '10-08', '10-09']" :series="series"
+      :labels="{ color: 'var(--x-color-text-primary)' }" area legend ariaLabel="CSS 变量颜色示例" />
+  </div>
+</template>
+```
+
 ### 面积图与堆叠面积
 
 `area` 打开填充；配合 `stack` 变为堆叠面积。堆叠面积适合看「总量 + 构成」——每层填充在下界与上界之间。
@@ -10293,6 +11052,35 @@ const visible = rightVisible;
 </template>
 ```
 
+### 长内容滚动
+
+默认布局由内部 Scrollbar 滚动正文，标题和底部操作区保持可见。四个方向、有无 footer 均适用；`bodyStyle` 的 padding 包含在正文高度内。`fill` 插槽替换整套布局时，滚动与标题布局由插槽内容负责。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Button, Drawer, Space } from 'x-next';
+
+const visible = ref(false);
+const placement = ref<'left' | 'right' | 'top' | 'bottom'>('right');
+const showFooter = ref(false);
+const placements = ['left', 'right', 'top', 'bottom'] as const;
+</script>
+<template>
+<label><input v-model="showFooter" type="checkbox" /> 显示底部操作区</label>
+  <Space>
+    <Button v-for="side in placements" :key="side" @click="placement = side; visible = true">
+      {{ side }} 长内容
+    </Button>
+  </Space>
+  <Drawer v-model="visible" title="长内容滚动" :placement="placement"
+    :width="560" :height="360" :show-footer="showFooter" :body-style="{ padding: '20px' }">
+    <p v-for="index in 40" :key="index">发布记录 {{ index }}：正文滚动后，标题和底部操作区仍可操作。</p>
+  </Drawer>
+</template>
+```
+
 ### 受控与事件
 
 ```vue
@@ -15137,6 +15925,49 @@ const data: TableData[] = [
 </template>
 ```
 
+### 页面页头与表格内部层级
+
+Table 根节点建立独立层叠上下文，固定列、吸顶表头和滚动轨道的层级限制在表格内部。下面的页面页头使用 `z-index: 10`；纵向滚动后应始终覆盖表格，横向滚动仍保留左右固定列。可切换吸顶表头和自定义滚动条检查组合行为。
+
+公开 CSS 变量 `--x-table-fixed-z-index`（默认 10）和 `--x-table-header-z-index`（默认 100）用于调整表格内部层级。可在 Table 的 `style` 或主题容器上设置；整个表格与页面浮层的顺序由业务容器的 `z-index` 决定。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ref } from 'vue';
+import { Table } from 'x-next';
+import type { TableColumnData } from 'x-next';
+
+const stickyHeader = ref(true);
+const scrollbar = ref(true);
+const columns: TableColumnData[] = [
+  { title: '名称', dataIndex: 'name', width: 180, fixed: 'left' },
+  { title: '说明', dataIndex: 'description', width: 640 },
+  { title: '状态', dataIndex: 'status', width: 140, fixed: 'right' },
+];
+const data = Array.from({ length: 25 }, (_, index) => ({
+  key: String(index), name: `记录 ${index + 1}`, description: '横向滚动检查左右固定列', status: '已发布',
+}));
+</script>
+<template>
+<label><input v-model="stickyHeader" type="checkbox" /> 吸顶表头</label>
+  <label><input v-model="scrollbar" type="checkbox" /> 自定义滚动条</label>
+  <div class="table-layer-demo">
+    <div class="table-layer-demo__header">页面页头：应始终覆盖滚动中的表格</div>
+    <Table :columns="columns" :data="data" :scroll="{ x: 960 }"
+      :sticky-header="stickyHeader ? 55 : false" :scrollbar="scrollbar" :pagination="false" />
+  </div>
+</template>
+<style scoped>
+.table-layer-demo { width: 100%; max-width: 720px; height: 300px; overflow: auto; }
+.table-layer-demo__header {
+  position: sticky; top: 0; z-index: 10; height: 55px;
+  display: flex; align-items: center; padding: 0 16px;
+  background: var(--x-color-bg-surface); color: var(--x-color-text-primary);
+}
+</style>
+```
+
 ### 固定操作列与状态控制
 
 同时展示手柄、展开、选择和左右固定列。调整列宽会保留当前排序与筛选；只清空某一列时，其他列筛选继续生效。选中行在条纹和悬浮下仍保持选中反馈。
@@ -26499,7 +27330,7 @@ interface LineChartSeries {
     name?: string;
     /** 该系列按 categories 顺序排列的值 */
     data: Array<number | null | undefined>;
-    /** 该系列的颜色，默认取内置分类色板（按系列下标循环） */
+    /** 该系列的颜色，支持 CSS 变量及 fallback；默认取内置分类色板（按系列下标循环） */
     color?: CSSColor;
 }
 
@@ -26521,7 +27352,7 @@ interface LineChartLabelsOptions {
     yFormatter?: (value: number) => string;
     /** 轴标签字号，默认 12 */
     fontSize?: number;
-    /** 轴标签颜色，默认取组件文字 token */
+    /** 轴标签颜色，支持 CSS 变量及 fallback；默认取组件文字 token */
     color?: CSSColor;
 }
 
@@ -33788,6 +34619,496 @@ type Filters = Record<string, string[]>;
 ```
 
 
+## TreeSelect API
+
+公开声明：`dist/components/tree-select/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 绑定值，勾选 / 多选为数组 | undefined &#124; string &#124; number &#124; TreeSelectLabelValue &#124; TreeSelectValue[] | 否 | undefined |
+| defaultValue | 默认值（非受控） | undefined &#124; string &#124; number &#124; TreeSelectLabelValue &#124; TreeSelectValue[] | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| multiple | 是否多选 | undefined &#124; false &#124; true | 否 | false |
+| treeCheckable | 是否开启勾选模式，值始终为数组 | undefined &#124; false &#124; true | 否 | false |
+| treeCheckStrictly | 勾选模式是否取消父子联动 | undefined &#124; false &#124; true | 否 | false |
+| checkedStrategy | 勾选回填策略 | undefined &#124; "all" &#124; "parent" &#124; "child" | 否 | "parent" |
+| data | 树数据 | undefined &#124; TreeSelectNodeData[] | 否 | [] |
+| fieldNames | 自定义节点字段名 | undefined &#124; { [x: string]: string &#124; undefined; key?: string &#124; undefined; title?: string &#124; undefined; children?: string &#124; undefined; disabled?: string &#124; undefined; checkable?: string &#124; undefined; disableCheckbox?: string &#124; undefined; selectable?: string &#124; undefined; isLeaf?: string &#124; undefined; icon?: string &#124; undefined; } | 否 | 未声明 |
+| labelInValue | 值是否包含标题 | undefined &#124; false &#124; true | 否 | false |
+| selectable | 节点可选规则，支持 'leaf' 或方法 | undefined &#124; false &#124; true &#124; "leaf" &#124; (node: TreeSelectNodeData, info: { isLeaf: boolean; level: number; }) => boolean | 否 | true |
+| allowSearch | 是否允许搜索 | undefined &#124; false &#124; true &#124; { retainInputValue?: boolean; } | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+| allowClear | 是否允许清空 | undefined &#124; false &#124; true | 否 | false |
+| filterTreeNode | 过滤节点方法，false 关闭过滤 | undefined &#124; false &#124; true &#124; (inputValue: string, node: TreeSelectNodeData) => boolean | 否 | true |
+| searchDelay | search 事件触发延迟 | undefined &#124; number | 否 | 500 |
+| inputValue | 搜索输入值（v-model） | undefined &#124; string | 否 | 未声明 |
+| defaultInputValue | 默认搜索输入值 | undefined &#124; string | 否 | "" |
+| size | 尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| placeholder | 占位提示 | undefined &#124; string | 否 | 未声明 |
+| loading | 是否加载中 | undefined &#124; false &#124; true | 否 | false |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| error | 是否错误状态 | undefined &#124; false &#124; true | 否 | false |
+| bordered | 是否显示边框 | undefined &#124; false &#124; true | 否 | true |
+| maxTagCount | 最多展示标签数，0 不限制 | undefined &#124; number | 否 | 0 |
+| tagNowrap | 标签是否不换行 | undefined &#124; false &#124; true | 否 | false |
+| popupVisible | 面板显示状态（v-model） | undefined &#124; false &#124; true | 否 | undefined |
+| defaultPopupVisible | 面板默认显示状态 | undefined &#124; false &#124; true | 否 | false |
+| unmountOnClose | 关闭时销毁面板 | undefined &#124; false &#124; true | 否 | false |
+| popupContainer | 弹出层挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+| triggerProps | 触发器配置 | undefined &#124; TriggerProps | 否 | 未声明 |
+| defaultExpandAll | 默认展开全部节点 | undefined &#124; false &#124; true | 否 | false |
+| expandedKeys | 展开节点（v-model） | undefined &#124; TreeSelectKey[] | 否 | undefined |
+| defaultExpandedKeys | 默认展开节点 | undefined &#124; TreeSelectKey[] | 否 | [] |
+| autoExpandParent | 是否自动展开父节点 | undefined &#124; false &#124; true | 否 | true |
+| showLine | 是否显示连接线 | undefined &#124; false &#124; true | 否 | false |
+| blockNode | 节点占据整行 | undefined &#124; false &#124; true | 否 | false |
+| virtualListProps | 虚拟列表配置，传入即开启 | undefined &#124; VirtualListProps | 否 | 未声明 |
+| scrollbar | 是否开启滚动条或滚动条配置 | undefined &#124; false &#124; true &#124; ScrollbarProps | 否 | true |
+| maxHeight | 下拉列表最大高度 | undefined &#124; string &#124; number | 否 | 未声明 |
+| loadMore | 异步加载子节点 | undefined &#124; (node: TreeSelectNodeData) => Promise<void> | 否 | 未声明 |
+| fallbackOption | 自定义缺失值显示，false 丢弃 | undefined &#124; false &#124; true &#124; (value: TreeSelectKey) => TreeSelectNodeData | 否 | true |
+| formatLabel | 格式化显示内容 | undefined &#124; (data: TreeSelectNodeData) => string | 否 | 未声明 |
+| showHeaderOnEmpty | 空态是否显示页头 | undefined &#124; false &#124; true | 否 | false |
+| showFooterOnEmpty | 空态是否显示页脚 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: TreeSelectValue &#124; TreeSelectValue[] &#124; undefined) => any |
+| update:inputValue | 搜索输入更新时触发 | undefined &#124; (inputValue: string) => any |
+| update:popupVisible | 面板显隐更新时触发 | undefined &#124; (visible: boolean) => any |
+| update:expandedKeys | 展开节点更新时触发 | undefined &#124; (keys: TreeSelectKey[]) => any |
+| change | 值变化时触发 | undefined &#124; (value: TreeSelectValue &#124; TreeSelectValue[] &#124; undefined, info: Record<string, unknown>) => any |
+| inputValueChange | 搜索输入变化时触发 | undefined &#124; (inputValue: string) => any |
+| search | 用户搜索时触发（searchDelay 后） | undefined &#124; (inputValue: string) => any |
+| popupVisibleChange | 面板显隐变化时触发 | undefined &#124; (visible: boolean) => any |
+| clear | 点击清空按钮时触发 | undefined &#124; (ev: Event) => any |
+| remove | 关闭多选标签时触发 | undefined &#124; (removed: TreeSelectValue &#124; undefined) => any |
+| expand | 展开状态变化时触发 | undefined &#124; (keys: TreeSelectKey[], info: Record<string, unknown>) => any |
+| dropdownScroll | 下拉滚动时触发 | undefined &#124; (ev: Event) => any |
+| nodeClick | 点击（勾选）节点时触发 | undefined &#124; (value: TreeSelectValue, info: Record<string, unknown>) => any |
+| focus | 默认触发器聚焦 | undefined &#124; (ev: FocusEvent) => any |
+| blur | 默认触发器失焦 | undefined &#124; (ev: FocusEvent) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| title | 自定义节点标题；参数 { node, value, title, level, checked, halfChecked, selected, expanded, disabled, isLeaf } | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| node-icon | 节点前缀图标；参数 { node } | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| switcher-icon | 展开 / 收起图标；参数 { node, expanded, loading } | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| label | 选择框显示内容；参数 { data }，data 为 { value, label, raw } | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| header | 下拉页头 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| footer | 下拉页脚 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| empty | 空状态内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| prefix | 选择框前缀元素 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| arrow-icon | 箭头图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| loading-icon | 加载中图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| search-icon | 搜索图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| trigger | 自定义触发元素；参数 { popupVisible, disabled, treeId, activeDescendant, onKeydown } | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | 公开声明未细化（用法和实现已显式暴露） |
+| blur | 公开声明未细化（用法和实现已显式暴露） |
+| expandAll | 公开声明未细化（用法和实现已显式暴露） |
+| checkAll | 公开声明未细化（用法和实现已显式暴露） |
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type TreeSelectKey = string | number;
+
+interface TreeSelectNodeData {
+    /**
+     * @zh 节点键值，全局唯一；不传时按节点路径自动生成
+     * @en Node key, unique in the whole tree; generated from the node path when omitted
+     */
+    key?: TreeSelectKey;
+    /**
+     * @zh 节点标题
+     * @en Node title
+     */
+    title?: string;
+    /**
+     * @zh 子节点
+     * @en Child nodes
+     */
+    children?: TreeSelectNodeData[];
+    /**
+     * @zh 是否禁用，禁用节点不可选中、不可勾选、不参与父子联动
+     * @en Whether disabled. Disabled nodes cannot be selected or checked and are excluded from cascade
+     */
+    disabled?: boolean;
+    /**
+     * @zh 是否可勾选，仅 `treeCheckable` 时生效
+     * @en Whether checkable, only works with `treeCheckable`
+     */
+    checkable?: boolean;
+    /**
+     * @zh 是否禁用复选框，仍可被父节点联动勾选
+     * @en Whether the checkbox is disabled. The node can still be toggled by its parent
+     */
+    disableCheckbox?: boolean;
+    /**
+     * @zh 是否可选中
+     * @en Whether selectable
+     */
+    selectable?: boolean;
+    /**
+     * @zh 是否为叶子节点，配合 `loadMore` 判断是否需要异步加载子节点
+     * @en Whether it is a leaf, used with `loadMore` for lazy loading
+     */
+    isLeaf?: boolean;
+    /**
+     * @zh 节点前缀图标
+     * @en Node prefix icon
+     */
+    icon?: RenderFunction;
+    [other: string]: any;
+}
+
+type TreeSelectFieldNames = FieldString<TreeSelectNodeData>;
+
+interface TreeSelectLabelValue {
+    /**
+     * @zh 选中的键值
+     * @en Selected key
+     */
+    value: TreeSelectKey;
+    /**
+     * @zh 选中的标题
+     * @en Selected title
+     */
+    label: string;
+    /**
+     * @zh 节点原始数据
+     * @en Raw node data
+     */
+    raw?: TreeSelectNodeData;
+}
+
+type TreeSelectValue = TreeSelectKey | TreeSelectLabelValue;
+
+type TreeSelectFilterNode = (inputValue: string, node: TreeSelectNodeData) => boolean;
+
+type TreeSelectSelectable = boolean | 'leaf' | ((node: TreeSelectNodeData, info: {
+    isLeaf: boolean;
+    level: number;
+}) => boolean);
+
+interface TreeSelectInstance {
+    /** 聚焦默认触发器 */
+    focus: () => void;
+    /** 失焦默认触发器 */
+    blur: () => void;
+    /** 展开 / 收起全部可展开节点，默认展开 */
+    expandAll: (expanded?: boolean) => void;
+    /** 全选 / 清空勾选，仅勾选模式生效，默认全选 */
+    checkAll: (checked?: boolean) => void;
+}
+
+interface TreeSelectProps {
+    modelValue?: TreeSelectValue | TreeSelectValue[];
+    defaultValue?: TreeSelectValue | TreeSelectValue[];
+    multiple?: boolean;
+    treeCheckable?: boolean;
+    treeCheckStrictly?: boolean;
+    checkedStrategy?: 'all' | 'parent' | 'child';
+    data?: TreeSelectNodeData[];
+    fieldNames?: TreeSelectFieldNames;
+    labelInValue?: boolean;
+    selectable?: TreeSelectSelectable;
+    allowSearch?: boolean | {
+        retainInputValue?: boolean;
+    };
+    allowClear?: boolean;
+    filterTreeNode?: boolean | TreeSelectFilterNode;
+    searchDelay?: number;
+    inputValue?: string;
+    defaultInputValue?: string;
+    size?: Size;
+    placeholder?: string;
+    loading?: boolean;
+    disabled?: boolean;
+    error?: boolean;
+    bordered?: boolean;
+    maxTagCount?: number;
+    tagNowrap?: boolean;
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    unmountOnClose?: boolean;
+    popupContainer?: string | HTMLElement;
+    triggerProps?: TriggerProps;
+    defaultExpandAll?: boolean;
+    expandedKeys?: TreeSelectKey[];
+    defaultExpandedKeys?: TreeSelectKey[];
+    autoExpandParent?: boolean;
+    showLine?: boolean;
+    blockNode?: boolean;
+    virtualListProps?: VirtualListProps;
+    scrollbar?: boolean | ScrollbarProps;
+    maxHeight?: number | string;
+    loadMore?: (node: TreeSelectNodeData) => Promise<void>;
+    fallbackOption?: boolean | ((value: TreeSelectKey) => TreeSelectNodeData);
+    formatLabel?: (data: TreeSelectNodeData) => string;
+    showHeaderOnEmpty?: boolean;
+    showFooterOnEmpty?: boolean;
+}
+
+interface TreeSelectNodeInfo {
+    key: string;
+    value: TreeSelectKey;
+    title: string;
+    raw: TreeSelectNodeData;
+    level: number;
+    index: number;
+    parentKey?: string;
+    pathKeys: string[];
+    childrenKeys: string[];
+    siblingIndex: number;
+    siblingCount: number;
+    isLeaf: boolean;
+    disabled: boolean;
+    checkable: boolean;
+    disableCheckbox: boolean;
+    selectable: boolean;
+    loading: boolean;
+}
+
+interface TreeSelectNodeSlotProps {
+    node: TreeSelectNodeData;
+    value: TreeSelectKey;
+    title: string;
+    level: number;
+    checked: boolean;
+    halfChecked: boolean;
+    selected: boolean;
+    expanded: boolean;
+    disabled: boolean;
+    isLeaf: boolean;
+}
+```
+
+
+## TreeSelectDropdown API
+
+公开声明：`dist/components/tree-select/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| id | 见场景用法与类型 | undefined &#124; string | 否 | 未声明 |
+| loading | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| empty | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| virtualList | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| showLine | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| scrollbar | 见场景用法与类型 | undefined &#124; false &#124; true &#124; ScrollbarProps | 否 | true |
+| maxHeight | 见场景用法与类型 | undefined &#124; string &#124; number | 否 | 未声明 |
+| onScroll | 见场景用法与类型 | undefined &#124; ((ev: Event) => void) & ((...args: any[]) => any) &#124; ((ev: Event) => void)[] & ((...args: any[]) => any) | 否 | 未声明 |
+| showHeaderOnEmpty | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+| showFooterOnEmpty | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| scroll | 见场景用法与类型 | undefined &#124; ((ev: Event) => void) & ((...args: any[]) => any) &#124; ((ev: Event) => void)[] & ((...args: any[]) => any) |
+| keydown | 见场景用法与类型 | undefined &#124; (...args: any[]) => any |
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type TreeSelectKey = string | number;
+
+interface TreeSelectNodeData {
+    /**
+     * @zh 节点键值，全局唯一；不传时按节点路径自动生成
+     * @en Node key, unique in the whole tree; generated from the node path when omitted
+     */
+    key?: TreeSelectKey;
+    /**
+     * @zh 节点标题
+     * @en Node title
+     */
+    title?: string;
+    /**
+     * @zh 子节点
+     * @en Child nodes
+     */
+    children?: TreeSelectNodeData[];
+    /**
+     * @zh 是否禁用，禁用节点不可选中、不可勾选、不参与父子联动
+     * @en Whether disabled. Disabled nodes cannot be selected or checked and are excluded from cascade
+     */
+    disabled?: boolean;
+    /**
+     * @zh 是否可勾选，仅 `treeCheckable` 时生效
+     * @en Whether checkable, only works with `treeCheckable`
+     */
+    checkable?: boolean;
+    /**
+     * @zh 是否禁用复选框，仍可被父节点联动勾选
+     * @en Whether the checkbox is disabled. The node can still be toggled by its parent
+     */
+    disableCheckbox?: boolean;
+    /**
+     * @zh 是否可选中
+     * @en Whether selectable
+     */
+    selectable?: boolean;
+    /**
+     * @zh 是否为叶子节点，配合 `loadMore` 判断是否需要异步加载子节点
+     * @en Whether it is a leaf, used with `loadMore` for lazy loading
+     */
+    isLeaf?: boolean;
+    /**
+     * @zh 节点前缀图标
+     * @en Node prefix icon
+     */
+    icon?: RenderFunction;
+    [other: string]: any;
+}
+
+type TreeSelectFieldNames = FieldString<TreeSelectNodeData>;
+
+interface TreeSelectLabelValue {
+    /**
+     * @zh 选中的键值
+     * @en Selected key
+     */
+    value: TreeSelectKey;
+    /**
+     * @zh 选中的标题
+     * @en Selected title
+     */
+    label: string;
+    /**
+     * @zh 节点原始数据
+     * @en Raw node data
+     */
+    raw?: TreeSelectNodeData;
+}
+
+type TreeSelectValue = TreeSelectKey | TreeSelectLabelValue;
+
+type TreeSelectFilterNode = (inputValue: string, node: TreeSelectNodeData) => boolean;
+
+type TreeSelectSelectable = boolean | 'leaf' | ((node: TreeSelectNodeData, info: {
+    isLeaf: boolean;
+    level: number;
+}) => boolean);
+
+interface TreeSelectInstance {
+    /** 聚焦默认触发器 */
+    focus: () => void;
+    /** 失焦默认触发器 */
+    blur: () => void;
+    /** 展开 / 收起全部可展开节点，默认展开 */
+    expandAll: (expanded?: boolean) => void;
+    /** 全选 / 清空勾选，仅勾选模式生效，默认全选 */
+    checkAll: (checked?: boolean) => void;
+}
+
+interface TreeSelectProps {
+    modelValue?: TreeSelectValue | TreeSelectValue[];
+    defaultValue?: TreeSelectValue | TreeSelectValue[];
+    multiple?: boolean;
+    treeCheckable?: boolean;
+    treeCheckStrictly?: boolean;
+    checkedStrategy?: 'all' | 'parent' | 'child';
+    data?: TreeSelectNodeData[];
+    fieldNames?: TreeSelectFieldNames;
+    labelInValue?: boolean;
+    selectable?: TreeSelectSelectable;
+    allowSearch?: boolean | {
+        retainInputValue?: boolean;
+    };
+    allowClear?: boolean;
+    filterTreeNode?: boolean | TreeSelectFilterNode;
+    searchDelay?: number;
+    inputValue?: string;
+    defaultInputValue?: string;
+    size?: Size;
+    placeholder?: string;
+    loading?: boolean;
+    disabled?: boolean;
+    error?: boolean;
+    bordered?: boolean;
+    maxTagCount?: number;
+    tagNowrap?: boolean;
+    popupVisible?: boolean;
+    defaultPopupVisible?: boolean;
+    unmountOnClose?: boolean;
+    popupContainer?: string | HTMLElement;
+    triggerProps?: TriggerProps;
+    defaultExpandAll?: boolean;
+    expandedKeys?: TreeSelectKey[];
+    defaultExpandedKeys?: TreeSelectKey[];
+    autoExpandParent?: boolean;
+    showLine?: boolean;
+    blockNode?: boolean;
+    virtualListProps?: VirtualListProps;
+    scrollbar?: boolean | ScrollbarProps;
+    maxHeight?: number | string;
+    loadMore?: (node: TreeSelectNodeData) => Promise<void>;
+    fallbackOption?: boolean | ((value: TreeSelectKey) => TreeSelectNodeData);
+    formatLabel?: (data: TreeSelectNodeData) => string;
+    showHeaderOnEmpty?: boolean;
+    showFooterOnEmpty?: boolean;
+}
+
+interface TreeSelectNodeInfo {
+    key: string;
+    value: TreeSelectKey;
+    title: string;
+    raw: TreeSelectNodeData;
+    level: number;
+    index: number;
+    parentKey?: string;
+    pathKeys: string[];
+    childrenKeys: string[];
+    siblingIndex: number;
+    siblingCount: number;
+    isLeaf: boolean;
+    disabled: boolean;
+    checkable: boolean;
+    disableCheckbox: boolean;
+    selectable: boolean;
+    loading: boolean;
+}
+
+interface TreeSelectNodeSlotProps {
+    node: TreeSelectNodeData;
+    value: TreeSelectKey;
+    title: string;
+    level: number;
+    checked: boolean;
+    halfChecked: boolean;
+    selected: boolean;
+    expanded: boolean;
+    disabled: boolean;
+    isLeaf: boolean;
+}
+```
+
+
 ## TrendChart API
 
 公开声明：`dist/components/trend-chart/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。