树 tree

数据展示组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

collection 是层级元信息的唯一事实源，标记只管长相；缩进由子层容器自己顶着

项目文件

▸src

▸components

✓main.ts

▸docs

✓README.md

<script setup lang="ts">
import {
  XhTreeBranch,
  XhTreeBranchContent,
  XhTreeBranchControl,
  XhTreeBranchText,
  XhTreeBranchTrigger,
  XhTreeItem,
  XhTreeItemIndicator,
  XhTreeItemText,
  XhTreeLabel,
  XhTreeRoot,
  XhTreeTree,
} from "@xihan-ui/vue";

const collection = [
  {
    value: "src",
    label: "src",
    children: [
      {
        value: "components",
        label: "components",
        children: [
          { value: "button", label: "Button.vue" },
          { value: "dialog", label: "Dialog.vue" },
        ],
      },
      { value: "main", label: "main.ts" },
    ],
  },
  {
    value: "docs",
    label: "docs",
    children: [
      { value: "guide", label: "guide.md" },
      { value: "api", label: "api.md" },
    ],
  },
  { value: "readme", label: "README.md" },
];
</script>

<template>
  <XhTreeRoot
    :collection="collection"
    :default-expanded-value="['src']"
    style="inline-size: 100%; max-inline-size: 320px"
  >
    <XhTreeLabel>项目文件</XhTreeLabel>
    <XhTreeTree>
      <XhTreeBranch value="src">
        <XhTreeBranchControl>
          <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
          <XhTreeBranchText>src</XhTreeBranchText>
        </XhTreeBranchControl>
        <XhTreeBranchContent>
          <XhTreeBranch value="components">
            <XhTreeBranchControl>
              <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
              <XhTreeBranchText>components</XhTreeBranchText>
            </XhTreeBranchControl>
            <XhTreeBranchContent>
              <XhTreeItem value="button">
                <XhTreeItemIndicator>✓</XhTreeItemIndicator>
                <XhTreeItemText>Button.vue</XhTreeItemText>
              </XhTreeItem>
              <XhTreeItem value="dialog">
                <XhTreeItemIndicator>✓</XhTreeItemIndicator>
                <XhTreeItemText>Dialog.vue</XhTreeItemText>
              </XhTreeItem>
            </XhTreeBranchContent>
          </XhTreeBranch>
          <XhTreeItem value="main">
            <XhTreeItemIndicator>✓</XhTreeItemIndicator>
            <XhTreeItemText>main.ts</XhTreeItemText>
          </XhTreeItem>
        </XhTreeBranchContent>
      </XhTreeBranch>

      <XhTreeBranch value="docs">
        <XhTreeBranchControl>
          <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
          <XhTreeBranchText>docs</XhTreeBranchText>
        </XhTreeBranchControl>
        <XhTreeBranchContent>
          <XhTreeItem value="guide">
            <XhTreeItemIndicator>✓</XhTreeItemIndicator>
            <XhTreeItemText>guide.md</XhTreeItemText>
          </XhTreeItem>
          <XhTreeItem value="api">
            <XhTreeItemIndicator>✓</XhTreeItemIndicator>
            <XhTreeItemText>api.md</XhTreeItemText>
          </XhTreeItem>
        </XhTreeBranchContent>
      </XhTreeBranch>

      <XhTreeItem value="readme">
        <XhTreeItemIndicator>✓</XhTreeItemIndicator>
        <XhTreeItemText>README.md</XhTreeItemText>
      </XhTreeItem>
    </XhTreeTree>
  </XhTreeRoot>
</template>

多选

selectionMode 默认 single，改成 multiple 后点击与确认键都变成切换，选中集合形状不变仍是数组

投放城市

▸华东

✓上海

✓杭州

✓南京

▸华北

✓北京

✓天津

选中：hz

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTreeBranch,
  XhTreeBranchContent,
  XhTreeBranchControl,
  XhTreeBranchText,
  XhTreeBranchTrigger,
  XhTreeItem,
  XhTreeItemIndicator,
  XhTreeItemText,
  XhTreeLabel,
  XhTreeRoot,
  XhTreeTree,
} from "@xihan-ui/vue";

const collection = [
  {
    value: "cn",
    label: "华东",
    children: [
      { value: "sh", label: "上海" },
      { value: "hz", label: "杭州" },
      { value: "nj", label: "南京" },
    ],
  },
  {
    value: "north",
    label: "华北",
    children: [
      { value: "bj", label: "北京" },
      { value: "tj", label: "天津" },
    ],
  },
];

const selected = ref<string[]>(["hz"]);
</script>

<template>
  <div style="width: 100%; max-width: 320px; display: grid; gap: 12px">
    <XhTreeRoot
      v-model:selected-value="selected"
      :collection="collection"
      :default-expanded-value="['cn', 'north']"
      selection-mode="multiple"
    >
      <XhTreeLabel>投放城市</XhTreeLabel>
      <XhTreeTree>
        <XhTreeBranch value="cn">
          <XhTreeBranchControl>
            <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
            <XhTreeBranchText>华东</XhTreeBranchText>
          </XhTreeBranchControl>
          <XhTreeBranchContent>
            <XhTreeItem value="sh">
              <XhTreeItemIndicator>✓</XhTreeItemIndicator>
              <XhTreeItemText>上海</XhTreeItemText>
            </XhTreeItem>
            <XhTreeItem value="hz">
              <XhTreeItemIndicator>✓</XhTreeItemIndicator>
              <XhTreeItemText>杭州</XhTreeItemText>
            </XhTreeItem>
            <XhTreeItem value="nj">
              <XhTreeItemIndicator>✓</XhTreeItemIndicator>
              <XhTreeItemText>南京</XhTreeItemText>
            </XhTreeItem>
          </XhTreeBranchContent>
        </XhTreeBranch>

        <XhTreeBranch value="north">
          <XhTreeBranchControl>
            <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
            <XhTreeBranchText>华北</XhTreeBranchText>
          </XhTreeBranchControl>
          <XhTreeBranchContent>
            <XhTreeItem value="bj">
              <XhTreeItemIndicator>✓</XhTreeItemIndicator>
              <XhTreeItemText>北京</XhTreeItemText>
            </XhTreeItem>
            <XhTreeItem value="tj">
              <XhTreeItemIndicator>✓</XhTreeItemIndicator>
              <XhTreeItemText>天津</XhTreeItemText>
            </XhTreeItem>
          </XhTreeBranchContent>
        </XhTreeBranch>
      </XhTreeTree>
    </XhTreeRoot>
    <span>选中：{{ selected.length ? selected.join("、") : "（无）" }}</span>
  </div>
</template>

受控

传了 expandedValue / selectedValue 就由宿主说了算，组件只发事件不落内部值，宿主写回它才动

文档目录

▸接口

✓鉴权

✓用户

▸指南

展开：api · 选中：（无）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhTreeBranch,
  XhTreeBranchContent,
  XhTreeBranchControl,
  XhTreeBranchText,
  XhTreeBranchTrigger,
  XhTreeItem,
  XhTreeItemIndicator,
  XhTreeItemText,
  XhTreeLabel,
  XhTreeRoot,
  XhTreeTree,
} from "@xihan-ui/vue";

const collection = [
  {
    value: "api",
    label: "接口",
    children: [
      { value: "auth", label: "鉴权" },
      { value: "user", label: "用户" },
    ],
  },
  {
    value: "guide",
    label: "指南",
    children: [{ value: "start", label: "快速开始" }],
  },
];

const expanded = ref<string[]>(["api"]);
const selected = ref<string[]>([]);

function onExpandedChange(details: { value: string[] }) {
  expanded.value = details.value;
}

function onSelectionChange(details: { value: string[] }) {
  selected.value = details.value;
}
</script>

<template>
  <div style="width: 100%; max-width: 320px; display: grid; gap: 12px">
    <div style="display: flex; gap: 8px">
      <XhButton size="sm" @click="expanded = ['api', 'guide']">全部展开</XhButton>
      <XhButton size="sm" @click="expanded = []">全部收起</XhButton>
    </div>

    <XhTreeRoot
      :collection="collection"
      :expanded-value="expanded"
      :selected-value="selected"
      @expanded-change="onExpandedChange"
      @selection-change="onSelectionChange"
    >
      <XhTreeLabel>文档目录</XhTreeLabel>
      <XhTreeTree>
        <XhTreeBranch value="api">
          <XhTreeBranchControl>
            <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
            <XhTreeBranchText>接口</XhTreeBranchText>
          </XhTreeBranchControl>
          <XhTreeBranchContent>
            <XhTreeItem value="auth">
              <XhTreeItemIndicator>✓</XhTreeItemIndicator>
              <XhTreeItemText>鉴权</XhTreeItemText>
            </XhTreeItem>
            <XhTreeItem value="user">
              <XhTreeItemIndicator>✓</XhTreeItemIndicator>
              <XhTreeItemText>用户</XhTreeItemText>
            </XhTreeItem>
          </XhTreeBranchContent>
        </XhTreeBranch>

        <XhTreeBranch value="guide">
          <XhTreeBranchControl>
            <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
            <XhTreeBranchText>指南</XhTreeBranchText>
          </XhTreeBranchControl>
          <XhTreeBranchContent>
            <XhTreeItem value="start">
              <XhTreeItemIndicator>✓</XhTreeItemIndicator>
              <XhTreeItemText>快速开始</XhTreeItemText>
            </XhTreeItem>
          </XhTreeBranchContent>
        </XhTreeBranch>
      </XhTreeTree>
    </XhTreeRoot>

    <span>
      展开：{{ expanded.length ? expanded.join("、") : "（无）" }} · 选中：{{
        selected.length ? selected.join("、") : "（无）"
      }}
    </span>
  </div>
</template>

点行不展开与禁用节点

expandOnClick 关掉后只有箭头与左右方向键能改展开态；禁用节点仍可聚焦，只是确认键不认它

构建产物

▸build

✓vite.config.ts

✓pnpm-lock.yaml（禁用）

▸dist

✓README.md

<script setup lang="ts">
import {
  XhTreeBranch,
  XhTreeBranchContent,
  XhTreeBranchControl,
  XhTreeBranchText,
  XhTreeBranchTrigger,
  XhTreeItem,
  XhTreeItemIndicator,
  XhTreeItemText,
  XhTreeLabel,
  XhTreeRoot,
  XhTreeTree,
} from "@xihan-ui/vue";

const collection = [
  {
    value: "build",
    label: "build",
    children: [
      { value: "vite", label: "vite.config.ts" },
      { value: "lock", label: "pnpm-lock.yaml", disabled: true },
    ],
  },
  // 空数组也算分支：展得开，只是里头没有行
  { value: "dist", label: "dist", children: [] },
  { value: "readme", label: "README.md" },
];
</script>

<template>
  <XhTreeRoot
    :collection="collection"
    :default-expanded-value="['build']"
    :expand-on-click="false"
    style="inline-size: 100%; max-inline-size: 320px"
  >
    <XhTreeLabel>构建产物</XhTreeLabel>
    <XhTreeTree>
      <XhTreeBranch value="build">
        <XhTreeBranchControl>
          <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
          <XhTreeBranchText>build</XhTreeBranchText>
        </XhTreeBranchControl>
        <XhTreeBranchContent>
          <XhTreeItem value="vite">
            <XhTreeItemIndicator>✓</XhTreeItemIndicator>
            <XhTreeItemText>vite.config.ts</XhTreeItemText>
          </XhTreeItem>
          <XhTreeItem value="lock">
            <XhTreeItemIndicator>✓</XhTreeItemIndicator>
            <XhTreeItemText>pnpm-lock.yaml（禁用）</XhTreeItemText>
          </XhTreeItem>
        </XhTreeBranchContent>
      </XhTreeBranch>

      <XhTreeBranch value="dist">
        <XhTreeBranchControl>
          <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
          <XhTreeBranchText>dist</XhTreeBranchText>
        </XhTreeBranchControl>
        <XhTreeBranchContent />
      </XhTreeBranch>

      <XhTreeItem value="readme">
        <XhTreeItemIndicator>✓</XhTreeItemIndicator>
        <XhTreeItemText>README.md</XhTreeItemText>
      </XhTreeItem>
    </XhTreeTree>
  </XhTreeRoot>
</template>

关键词过滤

collection 换一份树就换一棵：标记跟着数据用 v-for 渲，过滤剩下的分支顺手全展开

投放城市

▸华东

✓上海

✓杭州

✓南京

▸华北

▸华南

<script setup lang="ts">
import { computed, ref, watch } from "vue";
import {
  XhTreeBranch,
  XhTreeBranchContent,
  XhTreeBranchControl,
  XhTreeBranchText,
  XhTreeBranchTrigger,
  XhTreeItem,
  XhTreeItemIndicator,
  XhTreeItemText,
  XhTreeLabel,
  XhTreeRoot,
  XhTreeTree,
} from "@xihan-ui/vue";

interface City {
  value: string;
  label: string;
}

interface Region {
  value: string;
  label: string;
  children: City[];
}

const source: Region[] = [
  {
    value: "east",
    label: "华东",
    children: [
      { value: "sh", label: "上海" },
      { value: "hz", label: "杭州" },
      { value: "nj", label: "南京" },
    ],
  },
  {
    value: "north",
    label: "华北",
    children: [
      { value: "bj", label: "北京" },
      { value: "tj", label: "天津" },
    ],
  },
  {
    value: "south",
    label: "华南",
    children: [
      { value: "gz", label: "广州" },
      { value: "sz", label: "深圳" },
    ],
  },
];

const keyword = ref("");

// 分支名命中就整枝留下，否则只留命中的子节点；一个子节点都不剩的分支整枝去掉
const collection = computed<Region[]>(() => {
  const key = keyword.value.trim();
  if (!key) return source;
  return source
    .map((region) => ({
      ...region,
      children: region.label.includes(key)
        ? region.children
        : region.children.filter((city) => city.label.includes(key)),
    }))
    .filter((region) => region.children.length > 0);
});

const expanded = ref<string[]>(["east"]);

watch(keyword, () => {
  expanded.value = collection.value.map((region) => region.value);
});
</script>

<template>
  <div style="width: 100%; max-width: 320px; display: grid; gap: 12px">
    <input v-model="keyword" type="search" aria-label="城市关键词" placeholder="输入城市名" />

    <XhTreeRoot v-model:expanded-value="expanded" :collection="collection">
      <XhTreeLabel>投放城市</XhTreeLabel>
      <XhTreeTree>
        <XhTreeBranch v-for="region in collection" :key="region.value" :value="region.value">
          <XhTreeBranchControl>
            <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
            <XhTreeBranchText>{{ region.label }}</XhTreeBranchText>
          </XhTreeBranchControl>
          <XhTreeBranchContent>
            <XhTreeItem v-for="city in region.children" :key="city.value" :value="city.value">
              <XhTreeItemIndicator>✓</XhTreeItemIndicator>
              <XhTreeItemText>{{ city.label }}</XhTreeItemText>
            </XhTreeItem>
          </XhTreeBranchContent>
        </XhTreeBranch>
      </XhTreeTree>
    </XhTreeRoot>

    <span v-if="!collection.length">没有匹配「{{ keyword }}」的城市</span>
  </div>
</template>

异步加载子节点

展开那一刻才去要数据：先摆一行禁用的占位，取回来就地换掉，收起再展开不重复请求

组织架构

▸研发中心

▸运维中心

▸业务中心

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTreeBranch,
  XhTreeBranchContent,
  XhTreeBranchControl,
  XhTreeBranchText,
  XhTreeBranchTrigger,
  XhTreeItem,
  XhTreeItemIndicator,
  XhTreeItemText,
  XhTreeLabel,
  XhTreeRoot,
  XhTreeTree,
} from "@xihan-ui/vue";

interface Node {
  value: string;
  label: string;
  disabled?: boolean;
  children?: Node[];
}

// 占位行也是一个真节点：它得在 collection 里，方向键才走得到它
function pending(owner: string): Node[] {
  return [{ value: `${owner}-pending`, label: "加载中…", disabled: true }];
}

const collection = ref<Node[]>([
  { value: "rd", label: "研发中心", children: pending("rd") },
  { value: "ops", label: "运维中心", children: pending("ops") },
  { value: "biz", label: "业务中心", children: pending("biz") },
]);

const staff: Record<string, string[]> = {
  rd: ["赵一", "钱二"],
  ops: ["孙三"],
  biz: ["李四", "周五", "吴六"],
};

const expanded = ref<string[]>([]);
const loaded = new Set<string>();

function fetchChildren(value: string): void {
  if (loaded.has(value)) return;
  loaded.add(value);
  window.setTimeout(() => {
    const branch = collection.value.find((node) => node.value === value);
    if (!branch) return;
    branch.children = staff[value].map((name, index) => ({
      value: `${value}-${index}`,
      label: name,
    }));
  }, 800);
}

function onExpandedChange(details: { value: string[] }): void {
  expanded.value = details.value;
  for (const value of details.value) fetchChildren(value);
}
</script>

<template>
  <XhTreeRoot
    :collection="collection"
    :expanded-value="expanded"
    style="inline-size: 100%; max-inline-size: 320px"
    @expanded-change="onExpandedChange"
  >
    <XhTreeLabel>组织架构</XhTreeLabel>
    <XhTreeTree>
      <XhTreeBranch v-for="node in collection" :key="node.value" :value="node.value">
        <XhTreeBranchControl>
          <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
          <XhTreeBranchText>{{ node.label }}</XhTreeBranchText>
        </XhTreeBranchControl>
        <XhTreeBranchContent>
          <XhTreeItem v-for="child in node.children" :key="child.value" :value="child.value">
            <XhTreeItemIndicator>✓</XhTreeItemIndicator>
            <XhTreeItemText>{{ child.label }}</XhTreeItemText>
          </XhTreeItem>
        </XhTreeBranchContent>
      </XhTreeBranch>
    </XhTreeTree>
  </XhTreeRoot>
</template>

前缀与行尾

行里放什么由标记说了算：文字前塞图标、文字后塞操作，方向指示也可以挪到行尾去

工作区

📁src›

📄index.ts

📄app.vue

📁docs›

（还没动过）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTreeBranch,
  XhTreeBranchContent,
  XhTreeBranchControl,
  XhTreeBranchIndicator,
  XhTreeBranchText,
  XhTreeItem,
  XhTreeItemText,
  XhTreeLabel,
  XhTreeRoot,
  XhTreeTree,
} from "@xihan-ui/vue";

const collection = [
  {
    value: "src",
    label: "src",
    children: [
      { value: "index", label: "index.ts" },
      { value: "app", label: "app.vue" },
    ],
  },
  {
    value: "docs",
    label: "docs",
    children: [{ value: "guide", label: "guide.md" }],
  },
];

const log = ref("（还没动过）");

function rename(label: string): void {
  log.value = `重命名 ${label}`;
}
</script>

<template>
  <div style="width: 100%; max-width: 320px; display: grid; gap: 12px">
    <XhTreeRoot :collection="collection" :default-expanded-value="['src']">
      <XhTreeLabel>工作区</XhTreeLabel>
      <XhTreeTree>
        <XhTreeBranch v-for="dir in collection" :key="dir.value" :value="dir.value">
          <XhTreeBranchControl>
            <span aria-hidden="true">📁</span>
            <XhTreeBranchText>{{ dir.label }}</XhTreeBranchText>
            <!-- 指示器不带点击语义，展开态转 90° 全靠皮肤读 data-state -->
            <XhTreeBranchIndicator>›</XhTreeBranchIndicator>
          </XhTreeBranchControl>
          <XhTreeBranchContent>
            <XhTreeItem v-for="file in dir.children" :key="file.value" :value="file.value">
              <span aria-hidden="true">📄</span>
              <XhTreeItemText>{{ file.label }}</XhTreeItemText>
              <!-- 掐断冒泡，否则点按钮连带把这一行也选上 -->
              <button type="button" @click.stop="rename(file.label)">重命名</button>
            </XhTreeItem>
          </XhTreeBranchContent>
        </XhTreeBranch>
      </XhTreeTree>
    </XhTreeRoot>
    <span>{{ log }}</span>
  </div>
</template>

只让叶子进选中集合

选中受控就由宿主定夺：分支的值直接不写回，点目录只剩展开收起这一个效果

要提交的文件

▸src

✓index.ts

✓app.vue

▸docs

已选：（无）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTreeBranch,
  XhTreeBranchContent,
  XhTreeBranchControl,
  XhTreeBranchText,
  XhTreeBranchTrigger,
  XhTreeItem,
  XhTreeItemIndicator,
  XhTreeItemText,
  XhTreeLabel,
  XhTreeRoot,
  XhTreeTree,
} from "@xihan-ui/vue";

const collection = [
  {
    value: "src",
    label: "src",
    children: [
      { value: "index", label: "index.ts" },
      { value: "app", label: "app.vue" },
    ],
  },
  {
    value: "docs",
    label: "docs",
    children: [
      { value: "guide", label: "guide.md" },
      { value: "api", label: "api.md" },
    ],
  },
];

const leaves = new Set(collection.flatMap((dir) => dir.children.map((file) => file.value)));

const selected = ref<string[]>([]);

function onSelectionChange(details: { value: string[] }): void {
  selected.value = details.value.filter((value) => leaves.has(value));
}
</script>

<template>
  <div style="width: 100%; max-width: 320px; display: grid; gap: 12px">
    <XhTreeRoot
      :collection="collection"
      :selected-value="selected"
      :default-expanded-value="['src']"
      selection-mode="multiple"
      @selection-change="onSelectionChange"
    >
      <XhTreeLabel>要提交的文件</XhTreeLabel>
      <XhTreeTree>
        <XhTreeBranch v-for="dir in collection" :key="dir.value" :value="dir.value">
          <XhTreeBranchControl>
            <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
            <XhTreeBranchText>{{ dir.label }}</XhTreeBranchText>
          </XhTreeBranchControl>
          <XhTreeBranchContent>
            <XhTreeItem v-for="file in dir.children" :key="file.value" :value="file.value">
              <XhTreeItemIndicator>✓</XhTreeItemIndicator>
              <XhTreeItemText>{{ file.label }}</XhTreeItemText>
            </XhTreeItem>
          </XhTreeBranchContent>
        </XhTreeBranch>
      </XhTreeTree>
    </XhTreeRoot>
    <span>已选：{{ selected.length ? selected.join("、") : "（无）" }}</span>
  </div>
</template>

级联勾选

selection-mode="multiple" 加 cascade 内建父子传导：点分支整枝勾上、子全勾父勾、部分勾中半选；勾选框是行里的一段标记，态从插槽作用域取

投放城市

▸–华东

上海

✓杭州

南京

▸华北

北京

天津

选中值（默认只收叶）：hz

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTreeBranch,
  XhTreeBranchContent,
  XhTreeBranchControl,
  XhTreeBranchText,
  XhTreeBranchTrigger,
  XhTreeItem,
  XhTreeItemText,
  XhTreeLabel,
  XhTreeRoot,
  XhTreeTree,
} from "@xihan-ui/vue";

const collection = [
  {
    value: "east",
    label: "华东",
    children: [
      { value: "sh", label: "上海" },
      { value: "hz", label: "杭州" },
      { value: "nj", label: "南京" },
    ],
  },
  {
    value: "north",
    label: "华北",
    children: [
      { value: "bj", label: "北京" },
      { value: "tj", label: "天津" },
    ],
  },
];

const selected = ref<string[]>(["hz"]);

const boxStyle = {
  display: "inline-flex",
  flex: "none",
  alignItems: "center",
  justifyContent: "center",
  inlineSize: "1rem",
  blockSize: "1rem",
  border: "1px solid var(--xh-border-strong)",
  borderRadius: "3px",
  fontSize: "0.75rem",
  lineHeight: "1",
};
</script>

<template>
  <div style="display: grid; gap: 8px; justify-items: start">
    <XhTreeRoot
      v-slot="{ isSelected, isIndeterminate }"
      v-model:selected-value="selected"
      :collection="collection"
      :default-expanded-value="['east', 'north']"
      selection-mode="multiple"
      cascade
    >
      <XhTreeLabel>投放城市</XhTreeLabel>
      <XhTreeTree>
        <XhTreeBranch v-for="region in collection" :key="region.value" :value="region.value">
          <XhTreeBranchControl>
            <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
            <span aria-hidden="true" :style="boxStyle">
              {{ isSelected(region.value) ? "✓" : isIndeterminate(region.value) ? "–" : "" }}
            </span>
            <XhTreeBranchText>{{ region.label }}</XhTreeBranchText>
          </XhTreeBranchControl>
          <XhTreeBranchContent>
            <XhTreeItem v-for="city in region.children" :key="city.value" :value="city.value">
              <span aria-hidden="true" :style="boxStyle">
                {{ isSelected(city.value) ? "✓" : "" }}
              </span>
              <XhTreeItemText>{{ city.label }}</XhTreeItemText>
            </XhTreeItem>
          </XhTreeBranchContent>
        </XhTreeBranch>
      </XhTreeTree>
    </XhTreeRoot>
    <p>选中值（默认只收叶）：{{ selected.length ? selected.join("、") : "（无）" }}</p>
  </div>
</template>

拖放换父

树从不拥有数据：把 draggable 与拖放监听补在节点上，落点判定与数组搬运都在宿主这边，改完 collection 树自己重推层级

邮箱目录

▸收件箱2

📄报价单.pdf

📄周报.md

▸归档1

📄去年总结.docx

▸回收站0

把文件拖到别的目录上放开

<script setup lang="ts">
import { ref } from "vue";
import {
  XhTreeBranch,
  XhTreeBranchContent,
  XhTreeBranchControl,
  XhTreeBranchText,
  XhTreeBranchTrigger,
  XhTreeItem,
  XhTreeItemText,
  XhTreeLabel,
  XhTreeRoot,
  XhTreeTree,
} from "@xihan-ui/vue";

interface Doc {
  value: string;
  label: string;
}

interface Folder {
  value: string;
  label: string;
  children: Doc[];
}

const collection = ref<Folder[]>([
  {
    value: "inbox",
    label: "收件箱",
    children: [
      { value: "f1", label: "报价单.pdf" },
      { value: "f2", label: "周报.md" },
    ],
  },
  {
    value: "archive",
    label: "归档",
    children: [{ value: "f3", label: "去年总结.docx" }],
  },
  { value: "trash", label: "回收站", children: [] },
]);

const dragging = ref<string | null>(null);
const over = ref<string | null>(null);
const log = ref("把文件拖到别的目录上放开");

function onDragStart(event: DragEvent, value: string): void {
  dragging.value = value;
  // 不写载荷有些浏览器不认这次拖拽
  event.dataTransfer?.setData("text/plain", value);
}

function onDragEnd(): void {
  dragging.value = null;
  over.value = null;
}

function onDrop(folder: string): void {
  const value = dragging.value;
  onDragEnd();
  if (value == null) return;
  const from = collection.value.find((f) => f.children.some((c) => c.value === value));
  const to = collection.value.find((f) => f.value === folder);
  // 同一个目录里放开不算搬家
  if (!from || !to || from === to) return;
  const index = from.children.findIndex((c) => c.value === value);
  const [moved] = from.children.splice(index, 1);
  to.children.push(moved);
  log.value = `${moved.label} 移到了 ${to.label}`;
}

const dropStyle = {
  outline: "2px dashed var(--xh-border-strong)",
  outlineOffset: "-2px",
};
</script>

<template>
  <div style="width: 100%; max-width: 320px; display: grid; gap: 12px">
    <XhTreeRoot
      :collection="collection"
      :default-expanded-value="['inbox', 'archive', 'trash']"
    >
      <XhTreeLabel>邮箱目录</XhTreeLabel>
      <XhTreeTree>
        <XhTreeBranch v-for="folder in collection" :key="folder.value" :value="folder.value">
          <!-- 落点是目录那一行：拖过去时描一圈虚线，放开就搬 -->
          <XhTreeBranchControl
            :style="over === folder.value ? dropStyle : undefined"
            @dragover.prevent="over = folder.value"
            @dragleave="over = null"
            @drop.prevent="onDrop(folder.value)"
          >
            <XhTreeBranchTrigger>▸</XhTreeBranchTrigger>
            <XhTreeBranchText>{{ folder.label }}</XhTreeBranchText>
            <span style="margin-inline-start: auto">{{ folder.children.length }}</span>
          </XhTreeBranchControl>
          <XhTreeBranchContent>
            <XhTreeItem
              v-for="file in folder.children"
              :key="file.value"
              :value="file.value"
              draggable="true"
              :style="dragging === file.value ? { opacity: 0.5 } : undefined"
              @dragstart="onDragStart($event, file.value)"
              @dragend="onDragEnd"
            >
              <span aria-hidden="true">📄</span>
              <XhTreeItemText>{{ file.label }}</XhTreeItemText>
            </XhTreeItem>
          </XhTreeBranchContent>
        </XhTreeBranch>
      </XhTreeTree>
    </XhTreeRoot>
    <span>{{ log }}</span>
  </div>
</template>

产物

层	值
自定义元素	<xh-tree>
Vue 组件	XhTreeBranch XhTreeBranchContent XhTreeBranchControl XhTreeBranchIndicator XhTreeBranchText XhTreeBranchTrigger XhTreeItem XhTreeItemIndicator XhTreeItemText XhTreeLabel XhTreeRoot XhTreeTree
组合式函数	useTree
状态机	treeMachine
皮肤	@xihan-ui/styles/tree.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="tree"：root · label · tree · item · item-indicator · item-text · branch · branch-control · branch-trigger · branch-indicator · branch-text · branch-content

Props

属性	类型	必填	说明
collection	TreeNode[]		树数据，层级元信息的唯一事实源。缺省为空树。
expandedValue	string[]		展开集合。给定即受控：cell 直读 prop，写只发 onExpandedChange 不落内部值。
defaultExpandedValue	string[]
selectedValue	string[]		选中集合。给定即受控，语义同上。
defaultSelectedValue	string[]
selectionMode	TreeSelectionMode		默认 single。
cascade	boolean		multiple 下父子级联勾选：点分支整枝传导、子全勾父勾、部分勾中半选， 禁用子树整棵冻结。默认 false（朴素切换）；single 下无效。
checkedStrategy	CascadeStrategy		级联下对外值的收敛策略，默认 child（只收叶）；parent = 最高整枝，all = 全部勾中节点。
expandOnClick	boolean		点分支行是否顺带展开/收起，默认 true。关掉后只有 branch-trigger 与左右方向键能改展开态。
disabled	boolean		整棵树禁用：所有节点转 aria-disabled，键盘与点击都不再改展开/选中。
loop	boolean		上下键走到首尾是否回绕，默认 false。
typeahead	boolean		连打检索，默认开。关掉后可打印字符一律放行给页面。
dir	Direction		文字方向，默认 ltr；只对调左右方向键的「展开/收起」语义。
onExpandedChange	(details: TreeExpandedChangeDetails) => void
onSelectionChange	(details: TreeSelectionChangeDetails) => void

状态机

状态：idle

事件：EXPANDED.SET · BRANCH.EXPAND · BRANCH.COLLAPSE · BRANCH.TOGGLE · SELECTED.SET · NODE.SELECT · NODE.FOCUS · TREE.BLUR

connect API

useTree 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
collection	readonly TreeNode[]	作者给的原始树数据。
visibleNodes	readonly TreeVisibleNode[]	当前可见行序列（收起分支的子树不在其中）。 方向键、Home/End 与连打检索都在它上面走，不是在原始树上走。
expandedValue	string[]
selectedValue	string[]
focusedValue	string | null	焦点锚点；焦点不在树内、或它已被收起而不可见时为 null。
selectionMode	TreeSelectionMode
disabled	boolean
isExpanded	(value: string) => boolean
isSelected	(value: string) => boolean
isIndeterminate	(value: string) => boolean	级联模式下该分支是否半选（有效叶后代有勾有不勾）；非级联恒 false。
setExpandedValue	(next: string[]) => void
setSelectedValue	(next: string[]) => void
expand	(value: string) => void
collapse	(value: string) => void
select	(value: string) => void	单选替换、复选切换，与点击同一语义。
getRootProps	() => T['element']
getLabelProps	() => T['element']
getTreeProps	() => T['element']
getItemProps	(props: TreeNodeProps) => T['element']
getItemTextProps	(props: TreeNodeProps) => T['element']
getItemIndicatorProps	(props: TreeNodeProps) => T['element']
getBranchProps	(props: TreeNodeProps) => T['element']
getBranchControlProps	(props: TreeNodeProps) => T['element']
getBranchTriggerProps	(props: TreeNodeProps) => T['element']
getBranchIndicatorProps	(props: TreeNodeProps) => T['element']
getBranchTextProps	(props: TreeNodeProps) => T['element']
getBranchContentProps	(props: TreeNodeProps) => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
Tab / Shift+Tab	focus outside the tree	整棵树只占一个 Tab 位：焦点进入锚点节点，无锚点时先落容器再由它转投
ArrowDown	focus in tree	焦点移到下一个可见行（禁用行跳过；loop 默认关，末行不回绕）
ArrowUp	focus in tree	焦点移到上一个可见行（禁用行跳过；loop 默认关，首行不回绕）
Home	focus in tree	焦点移到首个可见行
End	focus in tree	焦点移到末个可见行（展开着的子树也算行）
ArrowRight	focus on branch（dir=rtl 时改由 ArrowLeft 承担）	收起的分支就地展开；已展开则把焦点移到首个子节点；叶子上什么都不做且不吞键
ArrowLeft	focus in tree（dir=rtl 时改由 ArrowRight 承担）	展开的分支就地收起；收起的分支与叶子则把焦点移到父节点；根层的行什么都不做
Enter / Space	focus on node, 节点未禁用	选中焦点节点（单选替换、复选切换）；焦点在分支上且 expandOnClick 未关时顺带切换展开态
*	focus in tree	展开与焦点行同一父级的全部分支（已展开与禁用的不动）；同级没有可展开的分支时不吞这个键
单个可打印字符	focus in tree, typeahead 未关	连打检索在可见行上按 label 首字母搬焦点，不改选中值，也不展开任何分支