gpui

GPUI のベストプラクティス

Zed エディターを支える UI フレームワーク、GPUI を使ってデスクトップアプリケーションを構築するための包括的なガイドです。影響度に基づいて優先順位付けされた、8 つのカテゴリにわたる 40 以上のルールを収録しています。

適用する場面

次の作業を行う際に、これらのガイドラインを参照してください。

• 新しい GPUI ビューやコンポーネントを作成するとき
• Entity を使った状態管理を実装するとき
• イベントやキーボードショートカットを処理するとき
• 非同期タスクやバックグラウンド処理を扱うとき
• フォーム、リスト、ダイアログを構築するとき
• Tailwind のような API でコンポーネントのスタイルを設定するとき
• GPUI アプリケーションをテストするとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	コアコンセプト	重大	core-
2	レンダリング	重大	render-
3	状態管理	高	state-
4	イベント処理	高	event-
5	非同期処理と並行処理	中〜高	async-
6	スタイリング	中	style-
7	コンポーネント	中	comp-
8	アンチパターン	重大	anti-

クイックリファレンス

1. コアコンセプト（重大）

• core-ownership-model - GPUI の単一所有権モデルを理解する
• core-entity-operations - read/update/observe/subscribe を正しく使う
• core-weak-entity - WeakEntity を使って循環参照を解消する
• core-context-types - App、Context、AsyncApp を使う場面を把握する

2. レンダリング（重大）

• render-render-vs-renderonce - 状態を持つ場合は Render、コンポーネントには RenderOnce を選ぶ
• render-element-composition - div() とメソッドチェーンで要素ツリーを構築する
• render-conditional - 条件付きスタイリングには .when() と .when_some() を使う
• render-shared-string - 文字列のコピーを避けるために SharedString を使う
• render-builder-pattern - ビルダーパターンでコンポーネントを設計する

3. 状態管理（高）

• state-notify - 状態を変更した後は、必ず cx.notify() を呼び出す
• state-observe - Entity の変更に応じて処理するには cx.observe() を使う
• state-subscribe - 型付きイベントには cx.subscribe() を使う
• state-global - アプリ全体で共有する状態には Global トレイトを使う
• state-keyed-state - 永続的な状態には window.use_keyed_state() を使う

4. イベント処理（高）

• event-actions - キーボードショートカット用のアクションを定義して登録する
• event-listener - ビューに紐づくイベントハンドラーには cx.listener() を使う
• event-focus - FocusHandle と key_context でフォーカスを管理する
• event-propagation - イベントのバブリングと stop_propagation を理解する

5. 非同期処理と並行処理（中〜高）

• async-task-lifecycle - キャンセルを防ぐため、タスクを保持するかデタッチする
• async-debounce - タイマーとタスクの置き換えでデバウンスを実装する
• async-background-spawn - CPU 負荷の高い処理には background_spawn を使う
• async-weak-entity - await をまたぐ安全なアクセスには WeakEntity を使う
• async-error-handling - .log_err() と .detach_and_log_err() を使う

6. スタイリング（中）

• style-flexbox - レイアウトには h_flex() と v_flex() を使う
• style-theme-colors - 色には必ず cx.theme() を使う
• style-spacing - レスポンシブな間隔には DynamicSpacing を使う
• style-elevation - レイヤー化されたサーフェスにはエレベーションシステムを使う

7. コンポーネント（中）

• comp-stateless - #[derive(IntoElement)] を使った RenderOnce を優先する
• comp-traits - Disableable、Selectable、Sizable トレイトを実装する
• comp-focus-ring - アクセシビリティのためにフォーカスリングを追加する
• comp-dialog - ダイアログの管理には WindowExt を使う
• comp-variant - コンポーネントのスタイルにはバリアント列挙型を使う

8. アンチパターン（重大）

• anti-silent-error - let _ = でエラーを黙って破棄しない
• anti-drop-task - Task を保持もデタッチもせずに破棄しない
• anti-drop-subscription - サブスクリプションは必ずデタッチするか保持する
• anti-circular-reference - Entity の循環を避け、WeakEntity を使う
• anti-missing-notify - 状態変更後の cx.notify() を忘れない
• anti-unwrap - unwrap() を避け、? または明示的なエラー処理を使う

アーキテクチャの概要

┌─────────────────────────────────────────────────────────┐
│                    Application (App)                     │
│              (Single owner of all Entities)              │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
    ┌───────────┐       ┌───────────┐       ┌──────────┐
    │ Entity<A> │       │ Entity<B> │       │ Global<C>│
    └───────────┘       └───────────┘       └──────────┘
        │                   │                   │
        │ read/update       │ read/update       │ via App
        │ via Context<A>    │ via Context<B>    │
        │
    ┌─────────────────────────────────────────────────┐
    │           UI Rendering (Render trait)           │
    │      Each frame: fn render(&mut self, ...)      │
    │      Returns: impl IntoElement (Element tree)   │
    └─────────────────────────────────────────────────┘
        │
        ├─ observe() → changes trigger render
        ├─ subscribe() → events trigger reactions
        ├─ notify() → signal changes
        └─ emit() → send typed events

使用方法

詳しい説明やコード例については、各ルールファイルをお読みください。

rules/core-ownership-model.md
rules/render-render-vs-renderonce.md
rules/anti-silent-error.md

各ルールファイルには、以下が含まれています。

• 重要な理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加の背景情報と参考資料