textual-builder

Textual Builder

概要

このスキルは、モダンな Web にインスパイアされた API でターミナルおよびブラウザベースのアプリケーションを作成するための Python フレームワークである Textual を使用して、洗練されたテキストユーザーインターフェース（TUI）を構築するのに役立ちます。リファレンスドキュメント、カードゲームのテンプレート、および Textual 開発のベストプラクティスが含まれています。

クイックスタート

基本的な Textual アプリ

from textual.app import App, ComposeResult
from textual.widgets import Header, Footer, Label

class MyApp(App):
    def compose(self) -> ComposeResult:
        yield Header()
        yield Label("Hello, Textual!")
        yield Footer()

if __name__ == "__main__":
    app = MyApp()
    app.run()

カードゲームテンプレート

カードゲームのプロトタイピングには、テンプレートをコピーしてください:

cp -r assets/card-game-template/* ./my-game/
cd my-game
python app.py

テンプレートには以下が含まれます:

• 表向き/裏向きの状態を持つインタラクティブな Card ウィジェット
• プレイヤーのカード用の Hand コンテナ
• ターン管理を備えたプレイエリア
• カードの選択とプレイのためのキーバインディング
• カスタマイズ可能なスタイリング

カスタマイズガイドについては assets/card-game-template/README.md を参照してください。

リファレンスドキュメントを読むべきタイミング

このスキルには包括的なリファレンスファイルが含まれています。タスクに応じて読み込んでください:

references/basics.md

読むタイミング: アプリ構造のセットアップ、リアクティブ属性の使用、マウントの処理、ウィジェットのクエリ、またはメッセージ/イベントを扱う場合。

内容:

• アプリ構造と compose メソッド
• リアクティブ属性とウォッチャー
• マウントと動的なウィジェットの作成
• ウィジェットのクエリ
• メッセージ、イベント、カスタムメッセージ

references/widgets.md

読むタイミング: ボタン、入力欄、ラベル、データテーブルなどの UI 要素を追加する場合、またはカスタムウィジェットを作成する場合。

内容:

• 表示ウィジェット（Label、Static、Placeholder）
• 入力ウィジェット（Button、Input、TextArea、Switch）
• 表形式データ用の DataTable
• レイアウトコンテナ（Container、Grid、Horizontal、Vertical）
• カスタムウィジェットの作成
• Header/Footer

references/layout.md

読むタイミング: レイアウトを設計する場合、ウィジェットを配置する場合、グリッドシステムを使用する場合、またはレスポンシブなサイジングを扱う場合。

内容:

• レイアウトの種類（vertical、horizontal、grid）
• グリッド設定（セルのスパン、行/列のサイジング）
• 配置とコンテンツのポジショニング
• ウィジェットを画面端にドッキング
• サイジング（fixed、relative、fractional、auto）
• スペーシング（margin、padding）
• スクロール

references/styling.md

読むタイミング: CSS スタイルを適用する場合、テーマ設定、ボーダーの追加、またはウィジェットの外観をカスタマイズする場合。

内容:

• CSS ファイルとセレクター
• 色（名前付き、16 進数、RGB、テーマ変数）
• ボーダーとボーダースタイル
• テキストスタイルと配置
• 不透明度とティント
• スタイル付きテキスト用の Rich マークアップ
• 疑似クラス（:hover、:focus など）

references/interactivity.md

読むタイミング: キーボードショートカットを実装する場合、マウスイベントを処理する場合、ユーザー操作に応答する場合、またはインタラクティブな動作を作成する場合。

内容:

• キーバインディングとアクション
• 動的なバインディングの更新
• マウスイベント（click、hover、enter、leave）
• キーボードイベント
• フォーカス管理
• ウィジェット固有のメッセージ
• カスタムメッセージ
• 通知とタイマー

一般的なワークフロー

新しい TUI アプリの作成

1. 基本的なアプリ構造から始める（クイックスタートを参照）
2. レイアウトを設計する（references/layout.md を読む）
3. ウィジェットを追加する（references/widgets.md を読む）
4. CSS でスタイリングする（references/styling.md を読む）
5. インタラクティブ性を追加する（references/interactivity.md を読む）

カードゲームのプロトタイピング

1. カードゲームテンプレートをコピーする
2. ゲームのカードプロパティに合わせて Card ウィジェットをカスタマイズする
3. アクションメソッド内のゲームロジックを変更する
4. メッセージハンドラーにゲーム固有のルールを追加する
5. app.tcss でカードとレイアウトをスタイリングする

インタラクティブな機能の追加

1. BINDINGS でキーバインディングを定義する
2. アクションメソッド（action_*）を実装する
3. ウィジェットメッセージ（on_button_pressed など）を処理する
4. 状態管理にリアクティブ属性を使用する
5. ウォッチャーで UI を更新する

ベストプラクティス

• 段階的な開発: シンプルに始めて、段階的に複雑さを追加する
• リアクティブな状態: UI に影響する状態には reactive() を使用する
• CSS の分離: スタイルはインラインではなく .tcss ファイルに記述する
• ウィジェットの再利用: 繰り返し使うコンポーネントにはカスタムウィジェットを作成する
• メッセージのバブリング: メッセージの伝播を制御するには event.stop() を使用する
• 型ヒント: IDE のサポートを向上させるために適切な型ヒントを使用する
• ID とクラス: クエリとスタイリングには意味のある ID/クラスを使用する

インストール

pip install textual
# or
uv pip install textual

現在のバージョン: v0.86.0+ (2025 年 11 月時点、最新は v6.6.0)

リソース

references/

オンデマンドで読み込まれる包括的なドキュメント:

• basics.md - コアコンセプトとアプリ構造
• widgets.md - ウィジェットのカタログと使用方法
• layout.md - レイアウトシステムと配置
• styling.md - CSS とテーマ設定
• interactivity.md - イベント、バインディング、アクション

assets/

• card-game-template/ - インタラクティブなカード、手札、ターン管理を備えたカードゲーム用の完全なスターターテンプレート

公式ドキュメント

このスキルで扱われていないトピックについては、以下を参照してください:

• https://textual.textualize.io/ (公式ドキュメント)
• https://github.com/Textualize/textual (GitHub リポジトリ)