树形控件

树形控件以可展开层级呈现嵌套数据，支持用户逐级定位、选择和操作节点。

src3 项

components3 项

button.css4 KB

tree.css3 KB

legacy.css已锁定

tests1 项

tree.spec.ts

index.ts2 KB

package.json1 KB

安装Terminal

npm install @a3s-lab/ui@0.4.0

<div class="tree" role="tree" aria-label="项目文件">
  <div
    role="treeitem"
    aria-label="src"
    aria-expanded="true"
    aria-selected="false"
    data-value="src"
  >
    <div data-tree-row>
      <svg aria-hidden="true"><!-- 文件夹图标 --></svg>
      <span data-tree-label>src</span>
    </div>
    <div role="group">
      <div
        role="treeitem"
        aria-label="tree.js"
        aria-selected="true"
        data-value="src/tree.js"
      >
        <div data-tree-row>
          <svg aria-hidden="true"><!-- 文件图标 --></svg>
          <span data-tree-label>tree.js</span>
        </div>
      </div>
    </div>
  </div>
</div>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

用法

树形控件适合文件浏览器、资源层级和嵌套配置。它与折叠面板不同：焦点会在可见节点之间移动，选择状态明确，并向辅助技术表达父子层级。

引入 CSS

导入 Tailwind 和一个完整的 A3S UI 样式包。

@import "tailwindcss";
@import "@a3s-lab/ui/a3s.css";

也可以只导入基础 CSS、树形控件 CSS 和一个样式包。

@import "tailwindcss";
@import "@a3s-lab/ui/base.css";
@import "@a3s-lab/ui/components/tree.css";
@import "@a3s-lab/ui/styles/a3s.css";

引入 JavaScript

加载完整运行时，或先加载运行时，再加载树形控件脚本。

<script src="/assets/js/runtime.min.js" defer></script>
<script src="/assets/js/tree.min.js" defer></script>

添加树形结构 HTML

<div class="tree" role="tree" aria-label="项目文件">
  <div
    role="treeitem"
    aria-label="src"
    aria-expanded="true"
    aria-selected="false"
    data-value="src"
  >
    <div data-tree-row>
      <svg aria-hidden="true"><!-- 文件夹图标 --></svg>
      <span data-tree-label>src</span>
    </div>
    <div role="group">
      <div
        role="treeitem"
        aria-label="tree.js"
        aria-selected="true"
        data-value="src/tree.js"
      >
        <div data-tree-row>
          <svg aria-hidden="true"><!-- 文件图标 --></svg>
          <span data-tree-label>tree.js</span>
        </div>
      </div>
    </div>
  </div>
</div>

参数

标记	用途
`.tree[role="tree"]`	复合控件根节点。通过 `aria-label` 或 `aria-labelledby` 提供可访问名称。
`[role="treeitem"]`	一个可选择节点。使用 `aria-selected`，并按需添加 `aria-expanded` 和 `aria-disabled`。
`[data-tree-row]`	树节点内的可视行。点击可展开节点时，会同时选择并切换该分支。
`[role="group"]`	可展开节点直接拥有的子节点组。
`[data-tree-label]`	主要可见标签，也是字符快速定位的备用文本。
`[data-tree-meta]`	可选的尾部信息，例如文件大小或子项数量。
`data-value`	事件返回的稳定值；省略时依次使用节点 `id` 或标签。

控制器负责维护 tabindex，使子节点组的可见性与 aria-expanded 同步，并确保 Tab 顺序中只有一个可用的可见节点。

JavaScript API

const tree = document.querySelector("#project-tree");
const item = tree.querySelector('[data-value="src/components"]');

tree.expand(item, true);
tree.select(item, true);
tree.refresh();

方法	行为
`tree.select(item, focus = false)`	设置唯一选中节点，并可选择将焦点移到该节点。
`tree.expand(item, expanded = true)`	展开或折叠直接拥有子节点组的节点。
`tree.toggle(item)`	切换节点的展开状态。
`tree.refresh()`	重新读取动态添加、删除或禁用的节点。

选择变化会触发可冒泡的 change 事件，详情为 { item, value }；展开变化会触发 a3s:tree-toggle，详情为 { item, value, expanded }。

状态与变体

禁用节点

在树节点上设置 aria-disabled="true"。禁用节点仍然可见，但指针、方向键导航和字符快速定位都会跳过它。

RTL

المصدرعنصران

المكونات

الفهرس

<div
    id="tree-demo-rtl"
    class="tree"
    role="tree"
    aria-label="ملفات المشروع"
    dir="rtl"
  >
    <div
      role="treeitem"
      aria-label="المصدر"
      aria-expanded="true"
      aria-selected="false"
      data-value="src"
    >
      <div data-tree-row>
        <svg
          class="lucide lucide-folder"
          xmlns="http://www.w3.org/2000/svg"
          width="24"
          height="24"
          viewBox="0 0 24 24"
          fill="none"
          stroke="currentColor"
          stroke-width="2"
          stroke-linecap="round"
          stroke-linejoin="round"
        >
          <path d="M2 6a2 2 0 0 1 2-2h5l2 2h9a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2Z" />
        </svg>
        <span data-tree-label>المصدر</span>
        <span data-tree-meta>عنصران</span>
      </div>
      <div role="group">
        <div
          role="treeitem"
          aria-label="المكونات"
          aria-selected="true"
          data-value="components"
        >
          <div data-tree-row>
            <svg
              class="lucide lucide-folder"
              xmlns="http://www.w3.org/2000/svg"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
            >
              <path d="M2 6a2 2 0 0 1 2-2h5l2 2h9a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2Z" />
            </svg>
            <span data-tree-label>المكونات</span>
          </div>
        </div>
        <div
          role="treeitem"
          aria-label="الفهرس"
          aria-selected="false"
          data-value="index"
        >
          <div data-tree-row>
            <svg
              class="lucide lucide-file"
              xmlns="http://www.w3.org/2000/svg"
              width="24"
              height="24"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="2"
              stroke-linecap="round"
              stroke-linejoin="round"
            >
              <path d="M14.5 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7.5L14.5 2z" />
              <polyline points="14 2 14 8 20 8" />
            </svg>
            <span data-tree-label>الفهرس</span>
          </div>
        </div>
      </div>
    </div>
  </div>

层级缩进、引导线与箭头都会跟随文档方向。在 RTL 中，ArrowLeft 用于展开或进入分支，ArrowRight 用于折叠或返回父节点。

可访问性

树节点应当是根节点或某个直接子节点组的直接子元素。
为每个节点提供简洁的可访问名称。显式使用 aria-label，可以避免子节点组或尾部信息被误读为当前分支名称。
不要在树节点行中嵌套按钮、链接或表单控件；焦点和选择应由树节点本身承担。
层级选择使用树形控件；相互独立的内容展开使用折叠面板；页面导航使用侧边栏。

按键	操作
`ArrowDown` / `ArrowUp`	移到下一个或上一个可用的可见节点。
`Home` / `End`	移到第一个或最后一个可用的可见节点。
`ArrowRight` / `ArrowLeft`	展开、进入、折叠或返回父节点；RTL 中方向相反。
`Enter` / `Space`	选择当前焦点节点。
可打印字符	移到下一个以输入文字开头的可见节点。

#树形控件

#用法

引入 CSS

引入 JavaScript

添加树形结构 HTML

#参数

#JavaScript API

#状态与变体

#禁用节点

#RTL

#可访问性

树形控件

用法

参数

JavaScript API

状态与变体

禁用节点

RTL

可访问性