dioxus-knowledge-patch

Dioxus のナレッジパッチ

注意

Dioxus 0.8.0-alpha.1 はプレリリース向けのガイダンスであり、安定版のリリース前に変更される可能性があります。

Dioxus アプリケーションの作成、移行、デバッグ、テスト、パッケージ化を行う際に、このスキルを使用してください。API を選択する前にプロジェクトを調査してください。安定版とプレリリース版では動作が異なります。

リファレンスインデックス

リファレンス	トピック
components-reactivity.md	コンポーネント、プロパティ、シグナル、ストア、フック、タスク、リソース、サスペンス、エラー、イベント
assets-styling-ui.md	アセット、RSX、属性、CSS、Tailwind、ドキュメント要素、評価、アクセシブルな UI
fullstack-routing.md	サーバー関数、Axum、SSR、ハイドレーション、フォーム、ストリーミング、WebSocket、ファイル、ルーティング
cli-platforms-bundling.md	CLI、プロジェクト設定、Web／デスクトップ／モバイル、ログ記録、デバッグ、デプロイ、インストーラー
renderers-testing-internals.md	ネイティブおよびカスタムレンダラー、LiveView、直接 SSR、テスト、ホットパッチ、WASM 分割、ネイティブプラグイン
migration-edge-cases.md	破壊的な API 変更、非推奨、依存関係の境界、動作上のエッジケース、プレビューに関する注意事項
ecosystem-sdk-components.md	スタイル付きコンポーネント、プリミティブ、仮想リスト、属性、SDK サービス、永続化、タイマー

最初に確認すること

• API を変更する前に、Cargo.toml、Cargo.lock、Dioxus.toml、有効な Cargo 機能、インストール済みの dx バージョンを確認してください。
• アプリケーションが Web、デスクトップ、モバイル、フルスタック、LiveView、SSR 専用、カスタムレンダラーのどれに該当するかを確認してください。同じソースが複数のターゲット向けにコンパイルされる場合があります。
• クライアント専用およびサーバー専用の依存関係は、それぞれの Cargo 機能の内側に配置してください。サーバー関数の本体に記述しても、近くにあるネイティブコードやシークレットがクライアントビルドから隠されるわけではありません。
• 統合された dioxus クレートと、現在のプレリュードを優先してください。低レベルのランタイム、スケジューラー、レンダラーの API では、明示的なインポートが必要な場合があります。
• ネイティブまたはモバイルのツールチェーンの問題を診断する前に、dx doctor を実行してください。
• プレビュー API はオプトインとして扱い、安定版プロジェクトに適用する前に、依存関係と CLI の正確なバージョンを確認してください。

破壊的な変更と非推奨

コンポーネントはスコープを受け取らなくなりました

コンポーネントはプロパティを直接受け取り、Element は静的な結果ベースとなり、spawn や consume_context などのランタイムヘルパーに Scope 引数は不要です。

fn Counter() -> Element {
    let mut count = use_signal(|| 0);
    rsx! {
        button { onclick: move |_| count += 1, "{count}" }
    }
}

何もレンダリングしない場合は rsx! {} を使用してください。通常のエラーは ? を使って祖先の ErrorBoundary に伝播できます。削除された VNode::None パターンは使用しないでください。

読みやすいプロパティとストアのレンズを優先する

リアクティブな読み取り専用プロパティには ReadSignal<T> を使用してください。RSX はシグナル、メモ、ストアのレンズ、または通常の値を、これに変換できます。生成されたレンズ型には意図的に名前が付けられていないため、汎用のストアヘルパーでは Readable または Writable の境界を受け入れてください。

#[component]
fn Title(title: ReadSignal<String>) -> Element {
    rsx! { h1 { "{title}" } }
}

ReadOnlySignal は非推奨です。子要素がシグナルの読み取りガードを借用するのではなく、アイテムごとのリアクティブなレンズを必要とするコレクションには Store を使用してください。

起動方法と機能はプラットフォームによって選択されます

dioxus::launch または LaunchBuilder を使用してください。レンダラー機能はメインの dioxus クレートにあり、フルスタックのクライアントビルドとサーバービルドでは、それぞれ web と server を有効にする必要があります。

[features]
web = ["dioxus/web"]
desktop = ["dioxus/desktop"]
server = ["dioxus/server"]

古い dioxus-lib クレートはなくなりました。フレームワークのライブラリ層のみが必要な場合は、lib 機能を指定して dioxus を使用してください。

イベントのキャンセルは同期的に行います

.await の前に event.prevent_default() を呼び出してください。Web フォームは既定で送信されるため、アプリケーション側で送信を処理する場合は onsubmit をキャンセルしてください。LiveView は Rust のハンドラーをサーバー上で実行するため、ブラウザーの既定動作を間に合うようにキャンセルできません。その場合は、同期的なブラウザー側 JavaScript を使用してください。

アセットパスとオプションの変更

asset! のパスは現在のクレートルートを基準とした絶対パスで、/ で始まります。 AssetOptions とそのバリアントコンストラクターを使用してください。古い mg! や ImageAssetOptions::new() の形式は使用しないでください。

let image = asset!(
    "/assets/image.png",
    AssetOptions::image().with_format(ImageFormat::Avif),
);

フルスタック型は Dioxus 向けです

特にネイティブクライアントでは、永続的な API に明示的なルートマクロを使用してください。 Dioxus の ServerFnError は、同じ名前の汎用 server_fn 型ではありません。また、公開依存関係の境界は Dioxus が想定するバージョンに合わせてください。

依存関係の修正後、安定版に固定されたプロジェクトが 0.7.5 に関連する変更で失敗する場合は、ソースコードを変更する前に cargo update を実行してください。

リアクティビティと非同期処理

読み取りによってサブスクリプションが作成されます

レンダリング中にシグナルを読み取ると、そのコンポーネントがサブスクライブします。イベントハンドラー内だけで読み取っても、サブスクライブされません。メモ、エフェクト、フューチャー、リソース、ローダーは、それぞれの実行セマンティクスに従って読み取りを追跡します。意図的にサブスクライブせずに読み取るには peek() を使用してください。

1 つのランタイムステップ内でのシグナルへの書き込みはバッチ処理されます。.await によってステップが終了し、保留中の UI が描画されます。書き込みの直後に依存するメモを読み取ると、同期的に再計算されます。

適切なタスクプリミティブを選ぶ

• use_action は最新の Result を保存し、再度呼び出されると古い処理をキャンセルします。
• spawn は現在のコンポーネント用に !Send フューチャーを所有し、アンマウント時にキャンセルします。
• spawn_forever はアプリのルートにアプリの存続期間中の処理をアタッチします。より短命なシグナルを保持してはいけません。
• CPU バウンドの処理は、ネイティブスレッドまたは Web Worker に移してください。

リソース、ローダー、サスペンス

use_resource は、追跡対象の依存関係が変更されると再起動します。結果のエラーをクローン可能にする必要がある場合は、CapturedError または dioxus::Ok を使用してください。use_loader は読み込み状態とエラー状態をサスペンスおよびエラーバウンダリー経由で処理します。ウォーターフォールを避けるには、最初の ? より前に独立したローダーを開始してください。

フルスタックのサスペンスデータには、結果をハイドレーション用にシリアライズできるよう、サーバーフューチャーを使用する必要があります。リアクティブな読み取りは外側のクロージャーに置いてください。

フルスタックのクイックリファレンス

Axum サーバーを構成する

#[cfg(feature = "server")]
dioxus::serve(|| async move {
    use dioxus::server::axum::routing::get;

    Ok(dioxus::server::router(app)
        .route("/health", get(|| async { "ok" })))
});

組み立てたルーターに追加された通常の Axum ルートは、SSR フォールバックより優先されます。認証済みセッションなどのリクエスト拡張にはサーバー専用のエクストラクターを使用し、クライアントのペイロードに含まれないようにしてください。

HTTP のセマンティクスを維持する

• 認識されないサーバーエラーは HTTP 500 になります。OrHttpError、またはステータス変換トレイトを実装する型付きエラーを使用してください。
• SSR エラーを処理する ErrorBoundary は、FullstackContext を通じて HTTP ステータスを再設定する必要があります。
• 最初のストリーミングチャンクがコミットされると、ヘッダーとステータスは固定されます。
• ネイティブクライアントは、サーバー関数、ファイル、ストリーム、WebSocket をサポートしますが、SSR、ハイドレーションデータ、SSG、FullstackContext はサポートしません。

ハイドレーションの決定性を保つ

クライアントはハイドレーション中にコンポーネントツリーを再実行します。同期的な非決定性処理は use_server_cached に、非同期の非決定性処理はサーバーフューチャーまたはローダーに、ブラウザーのみの読み取りは use_effect に配置してください。サーバーキャッシュ対象のクロージャーに副作用を入れないでください。

ルーティングのクイックリファレンス

Routable を導出し、Router::<Route> {} をマウントして、型付きバリアントで遷移します。 マッチングでは、静的パス、動的フィールド、キャッチオールの順に優先され、同順位の場合は列挙型の順序で決まります。型付き値が存在しないか、不正な場合、クエリセグメントとハッシュセグメントがあってもルートは拒否されません。

#[derive(Clone, PartialEq, Routable)]
enum Route {
    #[route("/")]
    Home,
    #[route("/post/:id")]
    Post { id: u64 },
}

レイアウトでは Outlet::<Route> {} を通じて子をレンダリングします。特にブラウザー、ハッシュ、LiveView、メモリールーティングでは、URL の動作が重要な場合に履歴プロバイダーを明示的に設定してください。

アセット、スタイリング、RSX

• Asset の値が Rust の最適化後も残っている場合にのみ、アセットがバンドルされます。最終アプリからエクスポートされたライブラリアセットを保持するか、意図的に間接参照する静的変数に #[used] を指定してください。
• アセットディレクトリ配下の子パスは、ソース名ではなく、ハッシュ付きでフォーマットされた Asset から作成してください。
• 属性のスプレッドはソース順に適用され、後の値が優先されます。None は動的属性を削除します。
• 未知の属性とすべての Web コンポーネント属性は引用符で囲んでください。ダッシュを含むタグは、型指定のない Web コンポーネントを作成します。
• 複数ノードの RSX では、最初のノードに key を指定してください。
• Tailwind 4 では、入力ファイルに Tailwind をインポートし、@source で Rust ソースをスキャンして、DX が生成したスタイルシートを含めてください。

CLI とプラットフォームのワークフロー

dx doctor
dx serve --web
dx build --raw-json-diagnostics
dx bundle --json-output

CLI は、Web、デスクトップ、iOS、Android、フルスタック、および通常の Rust パッケージをサポートしています。ネイティブバンドルはホスト環境に依存します。モバイルビルドでは、プラットフォーム SDK と署名設定も必要です。完全な診断情報には --log-to-file を使用し、別のツールで DX のビルド引数を再現する必要がある場合は dx print を使用してください。

フルスタックの Web デプロイでは、生成された public ディレクトリとサーバー実行ファイルの両方を配置してください。本番コンテナは IP=0.0.0.0 でバインドしてください。dioxus::launch は IP と PORT を読み取ります。