tdesign-vue-next

TDesign Vue Next

S - スコープ

• 対象：tdesign-vue-next@^1 と Vue 3.3 以降
• 対象範囲：基本コンポーネント、レイアウトコンポーネント、ナビゲーションコンポーネント、入力コンポーネント、データ表示コンポーネント、フィードバックコンポーネント、テーマのカスタマイズ、ダークモード、Chat コンポーネント
• 対象外：ドキュメント化されていない内部 API、DOM 操作によるハック、TDesign の他の技術スタック（React／Miniprogram）

特に指定がない場合のデフォルト設定

• 言語：TypeScript + <script setup> 構文
• スタイル：テーマ設定には CSS 変数と ConfigProvider を使用し、コンポーネント内部のクラス名を直接上書きしないでください
• プロバイダー：統一した設定のため、アプリのルートで ConfigProvider を 1 つだけ使用してください
• アイコン：tdesign-icons-vue-next アイコンライブラリを使用してください
• インポート：コンポーネントを必要に応じてインポートしてください。import { Button } from 'tdesign-vue-next'

スコープのルール（必ず遵守）

1. TDesign の公式ドキュメントに記載されている API のみを使用してください
2. props、イベント、コンポーネント名を作り出さないでください
3. 型チェックを回避するために @ts-ignore を使用しないでください。型に関する問題は、まず公式の型定義を確認してください
4. バグの可能性がある場合や、ドキュメントと動作に食い違いがある場合は、ユーザーに明確に伝え、Issue の提出を案内してください
5. サンプルコードは、疑似コードや省略を示すプレースホルダーを含めず、そのまま実行できるものにしてください

複雑な機能のトリガー（該当する Reference を必ず開く）

トリガー条件	リファレンス
動的フォーム（FormItem の追加／削除）、フィールド間検証、非同期検証	references/form-advanced.md
サーバー側のソート／フィルタリング／ページネーション、仮想スクロール、編集可能なテーブル、ツリーテーブル	references/table-advanced.md
リモート検索、大規模データセット、ページネーション付き読み込み、カスタムレンダリング	references/select-advanced.md
ファイルリストの制御、中断後に再開できるアップロード、カスタムアップロードリクエスト	references/upload-advanced.md
ノードの非同期読み込み、checkStrictly、仮想スクロール	references/tree-advanced.md
非同期読み込み、動的オプション、カスタムパネル	references/cascader-advanced.md
Dialog／Drawer のネスト、命令型の呼び出し、クローズのインターセプト	references/dialog-drawer-advanced.md
テーマの高度なカスタマイズ、動的なテーマ切り替え、コンポーネント単位のスタイル上書き	references/theming-advanced.md
ダークモードの切り替え、システム設定との同期、ローカルのダークモード	references/dark-mode.md
AI チャットコンポーネント、ストリーミング応答、カスタムメッセージレンダリング	references/chat-advanced.md
TDesign Vue Next 1.x のバージョン間の違い、アップグレードガイド	references/tdesign-v1.md

Reference インデックス

トピック	説明	Reference
バージョンリファレンス	1.x バージョンの範囲、アップグレードに関する注意事項	references/tdesign-v1.md
フォームの高度な機能	動的フォーム、連動バリデーション、非同期バリデーション	references/form-advanced.md
テーブルの高度な機能	仮想スクロール、サーバーサイドデータ、編集可能なセル	references/table-advanced.md
セレクトの高度な機能	リモート検索、ページネーション、カスタムオプション	references/select-advanced.md
アップロードの高度な機能	制御されたアップロード、カスタムリクエスト、再開可能なアップロード	references/upload-advanced.md
ツリーの高度な機能	非同期読み込み、checkStrictly、仮想スクロール	references/tree-advanced.md
カスケーダーの高度な機能	非同期読み込み、動的パネル	references/cascader-advanced.md
ダイアログ／ドロワーの高度な機能	ネストされたレイヤー、命令型呼び出し	references/dialog-drawer-advanced.md
テーマのカスタマイズ	CSS 変数、Design Token、動的テーマ	references/theming-advanced.md
ダークモード	モード切り替え、システム設定、ローカルのダークモード	references/dark-mode.md
チャットコンポーネント	AI チャット、ストリーミング応答、メッセージのレンダリング	references/chat-advanced.md

---

P - プロセス

1) コンポーネント階層を特定する

User requirements
  ├── Basic display → Button / Link / Icon / Typography
  ├── Layout structure → Layout / Grid / Space / Divider
  ├── Navigation interaction → Menu / Tabs / Breadcrumb / Steps / Pagination
  ├── Data input → Form / Input / Select / DatePicker / Upload / ...
  ├── Data display → Table / List / Tree / Card / Descriptions / ...
  ├── Feedback → Message / Notification / Dialog / Drawer / Loading
  └── Advanced scenarios → Chat (AI conversation)

2) 提案を行う前にコンテキストを確認する

コンポーネントを提案する前に、次の点を確認してください。

• Vue のバージョン（3.3 以降を推奨）
• ConfigProvider が設定されているか
• ダークモードへの対応が必要か
• 特別な i18n 要件があるか
• データ量（仮想スクロールが必要かどうかに影響します）

3) まず ConfigProvider を設定する

<template>
  <ConfigProvider :global-config="globalConfig">
    <App />
  </ConfigProvider>
</template>

<script setup lang="ts">
import { ConfigProvider } from "tdesign-vue-next";

const globalConfig = {
  // Global configuration
};
</script>

4) コンポーネントの選択ルール

シナリオ	推奨コンポーネント	備考
シンプルなリスト表示	List	データ量が少なく、複雑な操作がない場合
複雑なデータテーブル	Table	並べ替え、フィルタリング、ページネーションに対応
大規模なデータテーブル	Table + virtual-scroll	仮想スクロールを有効にする
ツリーデータの選択	TreeSelect	ツリーの単一選択／複数選択
カスケード選択	Cascader	複数レベルの連動選択
シンプルなドロップダウン	Select	選択肢の数が中程度の場合
リモート検索セレクト	Select + filterable + remote	ローカルフィルタリングを無効にする
ファイルのアップロード	Upload	ドラッグ操作、複数ファイルに対応
フォーム入力	Form + FormItem	バリデーションと送信を一元管理
軽い通知	Message	操作結果のフィードバック、自動的に閉じる
重要な通知	Notification	ユーザーの確認が必要、またはアクションを含む場合
確認アクション	Dialog / Popconfirm	コンテキストに応じて選択する
サイドパネルの詳細	Drawer	ページの流れを中断しない場合
AI との会話	Chat	ストリーミングメッセージ、複数ターンの対話

5) フォームの判断フロー

Need to collect user input?
  ├── Yes → Use Form wrapper
  │     ├── Need dynamic add/remove fields? → See form-advanced.md
  │     ├── Need cross-field linking? → See form-advanced.md
  │     └── Simple form → Use FormItem + rules
  └── No → Use input component directly

6) テーブルの判断フロー

Need to display list data?
  ├── Data > 1000 rows? → Enable virtual scroll, see table-advanced.md
  ├── Need server-side pagination/sorting? → See table-advanced.md
  ├── Need editable cells? → See table-advanced.md
  └── Simple table → Use Table + columns + data

7) テーマのカスタマイズに関する判断フロー

Need to customize theme?
  ├── Only modify brand color → ConfigProvider theme prop
  ├── Modify multiple tokens → Override CSS variables
  ├── Deep customization → See theming-advanced.md
  └── Dark mode → See dark-mode.md

8) 複雑なシナリオはReferenceに案内する

複雑なトリガーの表からトリガー条件を特定した場合は、必ず次の対応を行ってください。

1. これが複雑なシナリオであることをユーザーに伝えます
2. 対応するReferenceドキュメントを開きます
3. Referenceで推奨されているパターンに基づいて提案します

9) アクセシビリティとパフォーマンスの確認

• フォームコントロールに適切なlabelが設定されていることを確認します
• 大量のデータを扱うシナリオでは、仮想スクロールまたはページネーションを有効にします
• template内で複雑な計算を行わず、computedを使用します
• リストのレンダリングで安定したkeyを設定します

---

O - 出力

必要に応じて出力に含める内容

1. コンポーネントの推奨：コンポーネント名と選定理由
2. 最小限の設定：必要なConfigProviderの設定
3. コード例：そのまま実行できる<script setup>コード
4. パフォーマンスのヒント：大量のデータや頻繁な更新が発生するシナリオに関する注意事項
5. Referenceのパス：複雑なシナリオに対応するReferenceドキュメントを案内します
6. 公式ドキュメントへのリンク：関連コンポーネントの公式ドキュメントURL

出力禁止事項

1. 検証されていないAPIやprops
2. 特定の内部実装に依存するハックコード
3. 不完全なコードスニペット（importや重要な設定の不足）
4. 他のTDesignテックスタック（React/Miniprogram）向けのコード
5. ユーザーのVueバージョンと互換性のない構文

回帰チェックリスト

• ConfigProvider：ルートコンポーネントが設定され、テーマトークンが有効になっていますか
• Form：rulesが定義され、バリデーションのトリガー（trigger）が正しく、modelが双方向バインディングされていますか
• Table：row-keyが安定した一意の値を提供し、columnsがcomputedでキャッシュされていますか
• Select：リモート検索でローカルフィルタリングが無効になっていますか（filterable + :filterがtrueを返す）
• Upload：制御モードのv-model:filesが正しく更新され、actionまたはrequestMethodが設定されていますか
• Tree/TreeSelect：keysの設定がデータ構造と一致し、非同期読み込みのload関数がPromiseを返していますか
• Dialog/Drawer：v-model:visibleが双方向バインディングされ、シナリオに応じてdestroyOnCloseが設定されていますか
• ダークモード：<html>またはルート要素にtheme-mode属性が追加されていますか
• アイコン：アイコンがtdesign-icons-vue-nextから正しくインポートされていますか
• TypeScript：コンポーネントpropsの型が正しく、イベントコールバックのパラメーター型が一致していますか

---

クイックリファレンス

インストール

npm install tdesign-vue-next
# Icon library
npm install tdesign-icons-vue-next

一括インポート

// main.ts
import { createApp } from "vue";
import TDesign from "tdesign-vue-next";
import "tdesign-vue-next/es/style/index.css";
import App from "./App.vue";

createApp(App).use(TDesign).mount("#app");

オンデマンドインポート（推奨）

// main.ts
import { createApp } from "vue";
import { Button, Input, Form, FormItem } from "tdesign-vue-next";
import "tdesign-vue-next/es/style/index.css";
import App from "./App.vue";

const app = createApp(App);
app.use(Button).use(Input).use(Form).use(FormItem);
app.mount("#app");

最小限の例

<template>
  <ConfigProvider>
    <Form :model="formData" :rules="rules" @submit="onSubmit">
      <FormItem label="Username" name="username">
        <Input v-model="formData.username" placeholder="Enter username" />
      </FormItem>
      <FormItem>
        <Button theme="primary" type="submit">Submit</Button>
      </FormItem>
    </Form>
  </ConfigProvider>
</template>

<script setup lang="ts">
import { reactive } from "vue";
import {
  ConfigProvider,
  Form,
  FormItem,
  Input,
  Button,
} from "tdesign-vue-next";
import type { FormRules, SubmitContext } from "tdesign-vue-next";

const formData = reactive({
  username: "",
});

const rules: FormRules<typeof formData> = {
  username: [{ required: true, message: "Username is required" }],
};

const onSubmit = ({ validateResult }: SubmitContext) => {
  if (validateResult === true) {
    console.log("Submit successful", formData);
  }
};
</script>

公式リソース

• 公式ドキュメント：https://tdesign.tencent.com/vue-next/overview
• GitHub：https://github.com/Tencent/tdesign-vue-next
• デザイン仕様：https://tdesign.tencent.com/design/values