# 画面設計書 29-Actions（アクション一覧）

## 概要

本ドキュメントは、Windows Terminal のアクション一覧画面（Actions）の設計を記述する。キーバインドとアクション（コマンド）の一覧表示・新規作成・編集画面への遷移を行う画面である。

### 本画面の処理概要

**業務上の目的・背景**：Windows Terminal のキーボードショートカットとアクション（コマンド）をGUIで管理するための画面である。ユーザーが登録済みのキーバインドとアクションの対応を一覧で確認し、新しいアクションを追加したり、既存のアクションを編集したりできる。settings.json を直接編集せずにキーバインドをカスタマイズできるため、初心者にも優しいインターフェースを提供する。

**画面へのアクセス方法**：MainPage（設定ナビゲーション）の左側ナビゲーションから「アクション」項目をクリックすることでアクセスする。初回アクセス時にはInfoBadgeが表示され、訪問済みになるとバッジが消える。

**主要な操作・処理内容**：
1. アクション（コマンド）の一覧表示（ListView。コマンド名とキーバインドを表示）
2. 新規アクションの追加（Add New ボタン）
3. アクションのクリックによる編集画面（EditAction）への遷移
4. ドキュメントリンクへのアクセス（HyperlinkButton）

**画面遷移**：
- 遷移元：MainPage（設定ナビゲーション）
- 遷移先：EditAction（アクション編集）- アクションクリック時

**権限による表示制御**：特に権限による制御はない。DisplayBadge プロパティにより未訪問時にInfoBadgeが表示される（ActionsNavItem上）。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 82 | 設定の読み込み・保存 | 主機能 | キーバインドとアクションの一覧表示・管理 |
| 84 | 設定UI | 主機能 | アクション一覧のUI表示 |

## 画面種別

一覧

## URL/ルーティング

UWP/WinUI アプリケーションのためURL/ルーティングは適用されない。MainPage の contentFrame 内に Frame.Navigate で表示される。ナビゲーションパラメータとして ActionsViewModel が渡される。

## 入出力項目

| 項目名 | 入出力 | データ型 | 説明 |
|--------|--------|----------|------|
| CommandList | 入力（表示） | IObservableVector<CommandViewModel> | アクション一覧 |
| CurrentCommand | 入出力 | CommandViewModel | 現在選択中のコマンド |

## 表示項目

| 表示領域 | 項目名 | コントロール種別 | 説明 |
|----------|--------|-----------------|------|
| ヘッダー | Actions_Disclaimer | HyperlinkButton | ドキュメントリンク（https://go.microsoft.com/fwlink/?linkid=2341386） |
| ヘッダー | AddNewButton | Button | 新規アクション追加ボタン（アイコン E710 + テキスト） |
| 一覧 | CommandsListView | ListView（ItemClick有効） | アクション一覧 |
| 一覧アイテム | DisplayName | TextBlock（KeyBindingNameTextBlockStyle、WrapWholeWords） | コマンド表示名 |
| 一覧アイテム | FirstKeyChordText | Border + TextBlock（KeyChordBorderStyle + KeyChordTextBlockStyle） | キーバインド表示（KeyChord テキスト、空の場合は非表示） |

## イベント仕様

### 1-OnNavigatedTo

MainPage からナビゲートされた時に発火する。ナビゲーションパラメータから ActionsViewModel を取得し、CurrentPage を Base に設定する。MarkAsVisited メソッドにより InfoBadge の表示が解除される。レイアウト更新後に AddNewButton にプログラム的フォーカスを設定する（LayoutUpdated 使用、1回のみ）。テレメトリログとして "NavigatedToPage" イベント（PageId="actions"）を記録する。

### 2-AddNewCommand

新規アクション追加ボタンのクリック時に発火する（x:Bind で ViewModel.AddNewCommand にバインド）。新しいコマンドを作成し、編集画面への遷移が開始される。

### 3-CmdListItemClicked

一覧アイテムがクリックされた時に発火する（x:Bind で ViewModel.CmdListItemClicked にバインド）。選択されたコマンドの編集画面（EditAction）への遷移が開始される。

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| AddNewCommand | メモリ上のモデル | INSERT | 新しいアクションをメモリ上のモデルに追加 |

### テーブル別更新項目詳細

本画面自体は直接ファイルに書き込まない。MainPage の SaveButton 経由で settings.json に永続化される。

## メッセージ仕様

特になし。

## 例外処理

特になし。

## 備考

- Dark / Light / HighContrast テーマ対応。各テーマで TextBox と KeyChord のスタイル（色、背景、ボーダー）が切り替わる。
- CommandTemplate 内の KeyChord テキストは、FirstKeyChordText が空文字列でない場合のみ表示される（StringNotEmptyToVisibility コンバーター使用）。
- ListView の ItemTemplate は CommandTemplate として定義され、ListViewItem の AutomationProperties.Name に DisplayNameAndKeyChordAutomationPropName が設定されている。
- Actions ページ訪問時に MarkAsVisited が呼ばれ、MainPage の ActionsNavItem 上の InfoBadge が非表示になる。

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ActionsViewModel.idl | `src/cascadia/TerminalSettingsEditor/ActionsViewModel.idl` | ActionsViewModel（CommandList, CurrentPage, DisplayBadge, AddNewCommand, CmdListItemClicked）と CommandViewModel（Name, DisplayName, FirstKeyChordText, KeyChordList）を確認する |

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Actions.cpp | `src/cascadia/TerminalSettingsEditor/Actions.cpp` | コンストラクタ（行14-18）でAddNewButtonのAutomationProperties設定。OnNavigatedTo（行20-41）でCurrentPage=Base設定、MarkAsVisited、LayoutUpdated フォーカス設定、テレメトリ記録 |

**主要処理フロー**:
1. **行14-18**: コンストラクタで InitializeComponent + AutomationProperties 設定
2. **行20-23**: OnNavigatedTo で ViewModel 取得、CurrentPage = Base
3. **行25-26**: MarkAsVisited で InfoBadge 解除
4. **行27-32**: LayoutUpdated で AddNewButton にフォーカス

#### Step 3: XAML レイアウトを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Actions.xaml | `src/cascadia/TerminalSettingsEditor/Actions.xaml` | テーマ辞書（Dark/Light/HighContrast）によるスタイル切替、CommandTemplate のデータバインディング、ListView の構造を理解する |

### プログラム呼び出し階層図

```
MainPage._Navigate("Actions_Nav")
    |
    +-- contentFrame.Navigate(typeof(Actions), ActionsViewModel)
            |
            +-- Actions::OnNavigatedTo
            |       +-- ActionsViewModel 取得
            |       +-- CurrentPage = Base
            |       +-- MarkAsVisited (InfoBadge解除)
            |       +-- LayoutUpdated (AddNewButton フォーカス)
            |       +-- TraceLogging
            |
            +-- AddNewCommand (x:Bind -> ViewModel)
            |       +-- 新規コマンド作成 -> EditAction 遷移
            |
            +-- CmdListItemClicked (x:Bind -> ViewModel)
                    +-- 選択コマンドの EditAction 遷移
```

### データフロー図

```
[入力]                        [処理]                         [出力]

ActionsViewModel ----------> Actions Page             -----> ListView (アクション一覧)
  +-- CommandList              |                               |
  +-- DisplayBadge             +-- ListView DataBinding        +-- コマンド名テキスト
                               |                               +-- KeyChord テキスト
                               +-- ItemClick ---------> EditAction 遷移
                               +-- AddNewCommand -----> 新規作成 -> EditAction 遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Actions.xaml | `src/cascadia/TerminalSettingsEditor/Actions.xaml` | テンプレート | UI レイアウト定義（テーマ対応スタイル含む） |
| Actions.cpp | `src/cascadia/TerminalSettingsEditor/Actions.cpp` | ソース | ページ実装 |
| ActionsViewModel.idl | `src/cascadia/TerminalSettingsEditor/ActionsViewModel.idl` | IDL | ViewModel インターフェース定義 |
| ActionsViewModel.h | `src/cascadia/TerminalSettingsEditor/ActionsViewModel.h` | ソース | ViewModel クラス定義 |
| ActionsViewModel.cpp | `src/cascadia/TerminalSettingsEditor/ActionsViewModel.cpp` | ソース | ViewModel 実装 |
| CommonResources.xaml | `src/cascadia/TerminalSettingsEditor/CommonResources.xaml` | リソース | 共通スタイル定義 |
