詳細ガイド
Angular Aria

ツリー

概要

ツリーは、アイテムを展開して子を表示したり、折りたたんで非表示にしたりできる階層データを表示します。ユーザーは矢印キーで移動し、ノードを展開・折りたたみ、ナビゲーションやデータ選択のシナリオのためにアイテムを選択できます。

使用法

ツリーは、ユーザーがネストされた構造をナビゲートする必要がある階層データを表示するのに適しています。

ツリーを使用する場合:

  • ファイルシステムのナビゲーションを構築する
  • フォルダーとドキュメントの階層を表示する
  • ネストされたメニュー構造を作成する
  • 組織図を表示する
  • 階層データを閲覧する
  • ネストされたセクションを持つサイトナビゲーションを実装する

ツリーを避ける場合:

  • フラットなリストを表示する場合（代わりにListboxを使用）
  • データテーブルを表示する場合（代わりにGridを使用）
  • シンプルなドロップダウンを作成する場合（代わりにSelectを使用）
  • パンくずナビゲーションを構築する場合（パンくずパターンを使用）

機能

  • 階層ナビゲーション - 展開・折りたたみ機能付きのネストされたツリー構造
  • 選択モード - 明示的またはフォーカス追従動作による単一選択または複数選択
  • フォーカス追従選択 - フォーカス変更時に任意で自動選択
  • キーボードナビゲーション - 矢印キー、Home、End、先行入力による検索
  • 展開/折りたたみ - 右/左矢印キーまたはEnterキーで親ノードを切り替え
  • 無効化されたアイテム - フォーカス管理付きで特定のノードを無効化
  • フォーカスモード - Roving tabindexまたはactivedescendantフォーカス戦略
  • RTLサポート - 右から左へ記述する言語のナビゲーション

例

アイテムを選択するのではなく、クリックすることでアクションをトリガーするナビゲーションにはツリーを使用します。

[nav]="true"を設定してナビゲーションモードを有効にします。これにより、選択の代わりにaria-currentを使用して現在のページを示します。

単一選択

ユーザーがツリーから1つのアイテムを選択するシナリオでは、単一選択を有効にします。

単一選択の場合は、[multi]="false"（デフォルト）のままにします。ユーザーはSpaceキーを押してフォーカスされているアイテムを選択します。

複数選択

ユーザーがツリーから複数のアイテムを選択できるようにします。

ツリーに[multi]="true"を設定します。ユーザーはSpaceキーで個別にアイテムを選択するか、Shift+矢印キーで範囲を選択します。

フォーカスに追従する選択

選択がフォーカスに追従する場合、フォーカスされたアイテムは自動的に選択されます。これにより、ナビゲーションシナリオでのインタラクションが簡素化されます。

ツリーに[selectionMode]="'follow'"を設定します。ユーザーが矢印キーでナビゲートすると、選択が自動的に更新されます。

無効化されたツリーアイテム

特定のツリーノードを無効にして、インタラクションを防ぎます。無効化されたアイテムがフォーカスを受け取れるかどうかを制御します。

ツリーで[softDisabled]="true"の場合、無効化されたアイテムはフォーカスを受け取ることができますが、アクティブ化または選択できません。[softDisabled]="false"の場合、無効化されたアイテムはキーボードナビゲーション中にスキップされます。

Testing

Angular Aria provides component harnesses for testing tree components. Here is an example of how to use the harnesses in a component test:

import {ComponentFixture, TestBed} from '@angular/core/testing';
import {HarnessLoader} from '@angular/cdk/testing';
import {TestbedHarnessEnvironment} from '@angular/cdk/testing/testbed';
import {TreeHarness} from '@angular/aria/tree/testing';
import {MyTreeComponent} from './my-tree'; // Your component

describe('MyTreeComponent', () => {
  let fixture: ComponentFixture<MyTreeComponent>;
  let loader: HarnessLoader;

  beforeEach(async () => {
    TestBed.configureTestingModule({
      imports: [MyTreeComponent],
    });

    fixture = TestBed.createComponent(MyTreeComponent);
    await fixture.whenStable();
    loader = TestbedHarnessEnvironment.loader(fixture);
  });

  it('should navigate and expand tree items', async () => {
    const tree = await loader.getHarness(TreeHarness);

    // Get top-level structure representation
    expect(await tree.getTreeStructure()).toEqual({
      children: [{text: 'public'}, {text: 'src'}, {text: 'package.json'}],
    });

    // Get all items (currently visible)
    const items = await tree.getItems();
    expect(items.length).toBe(3);

    // Expand the first item ('public')
    expect(await items[0].isExpanded()).toBe(false);
    await items[0].click();
    expect(await items[0].isExpanded()).toBe(true);

    // Verifying tree structure updates after expansion
    expect(await tree.getTreeStructure()).toEqual({
      children: [
        {
          text: 'public',
          children: [{text: 'index.html'}, {text: 'styles.css'}],
        },
        {text: 'src'},
        {text: 'package.json'},
      ],
    });
  });
});

API

Tree

階層的なナビゲーションと選択を管理するコンテナディレクティブです。

Inputs

プロパティ 型 デフォルト 説明
disabled boolean false ツリー全体を無効にします
softDisabled boolean true trueの場合、無効化されたアイテムはフォーカス可能ですが、インタラクティブではありません
multi boolean false 複数アイテムの選択が可能かどうか
selectionMode 'explicit' | 'follow' 'explicit' 選択に明示的なアクションが必要か、フォーカスに追従するかどうか
nav boolean false ツリーがナビゲーションモードであるかどうか（aria-currentを使用）
wrap boolean true キーボードナビゲーションが最後のアイテムから最初のアイテムにラップするかどうか
focusMode 'roving' | 'activedescendant' 'roving' ツリーで使用されるフォーカス戦略
values any[] [] 選択されたアイテムの値（双方向バインディングをサポート）

メソッド

メソッド パラメータ 説明
expandAll none すべてのツリーノードを展開します
collapseAll none すべてのツリーノードを折りたたみます
selectAll none すべてのアイテムを選択します（複数選択モードのみ）
clearSelection none すべての選択をクリアします

TreeItem

子ノードを含むことができるツリー内の個々のノードです。

Inputs

プロパティ 型 デフォルト 説明
parent Tree | TreeItemGroup — 必須。 親のTreeルートまたはTreeItemGroup。
value any — 必須。 このツリーアイテムの一意な値
disabled boolean false このアイテムを無効にします
expanded boolean false ノードが展開されているかどうか（双方向バインディングをサポート）

シグナル

プロパティ 型 説明
selected Signal<boolean> アイテムが選択されているかどうか
active Signal<boolean> アイテムが現在フォーカスを持っているかどうか
hasChildren Signal<boolean> アイテムが子ノードを持っているかどうか

メソッド

メソッド パラメータ 説明
expand none このノードを展開します
collapse none このノードを折りたたみます
toggle none 展開状態を切り替えます

TreeItemGroup

The structural directive applied to an ng-template that holds the children nodes of an expandable tree item.

Inputs

Property Type Default Description
ownedBy TreeItem — Required. The reference of the parent ngTreeItem.

Usage 

<ul ngTree #tree="ngTree">
  <li ngTreeItem [parent]="tree" value="parent" #parentItem="ngTreeItem">
    Parent Item
    <ul role="group">
      <ng-template ngTreeItemGroup [ownedBy]="parentItem" #group="ngTreeItemGroup">
        <li ngTreeItem [parent]="group" value="child1">Child 1</li>
        <li ngTreeItem [parent]="group" value="child2">Child 2</li>
      </ng-template>
    </ul>
  </li>
</ul>