開始使用 Flutter 的 GenUI SDK

本指南說明如何開始使用 Flutter 的 GenUI SDK 及其系列套件。 SDK 的主要元件 (Widget) 說明請參閱主要元件頁面。

請依照下列說明將 genui 加入您的 Flutter 應用程式。 程式碼範例示範如何在透過執行 flutter create 建立的全新應用程式上進行操作， 但您也可以依照相同步驟操作現有的 Flutter 應用程式。

genui 套件可連接至多種代理提供者。 可用的提供者包括：

Firebase AI Logic

適用於所有與 LLM 互動皆在 Flutter 用戶端進行、無需伺服器的正式版應用程式。 Firebase 也讓您能更安全地發布 AI 功能，因為 Firebase 會負責管理您的 Gemini API 金鑰。

GenUI A2UI

適用於代理在伺服器上執行的用戶端/伺服器架構。

自行建置

您也可以自行建置轉接器，以連接您偏好的 LLM 提供者。 期待我們與社群很快帶來更多選項。

若您要為 iOS 或 macOS 建置 Flutter 專案， 請在 {ios,macos}/Runner/*.entitlements 檔案中加入下列金鑰， 以啟用對外網路請求：

<dict>
...
<key>com.apple.security.network.client</key>
<true/>
</dict>

接下來，請依照下列說明將您的應用程式連接至所選的代理提供者。

1. 建立 SurfaceController，並提供您要讓代理使用的元件 (Widget) 目錄 (catalog)。 建立 A2uiTransportAdapter 以解析訊息並與其連接。

2. 建立 PromptBuilder，並提供系統指令及工具（您希望代理能夠呼叫的函式）。 您應始終包含 SurfaceController 提供的工具，但也可以自行加入其他工具。 將此內容加入您的 LLM 系統提示。

3. 使用 SurfaceController 和 A2uiTransportAdapter 的執行個體建立 Conversation。 您的應用程式主要透過此物件完成各項操作。

   範例：

   dart

   class _MyHomePageState extends State<MyHomePage> {
     late final SurfaceController _surfaceController;
     late final A2uiTransportAdapter _transportAdapter;
     late final Conversation _conversation;
   ​
     @override
     void initState() {
       super.initState();
   ​
       // Create a SurfaceController with a widget catalog.
       // The BasicCatalogItems contain basic widgets for text, markdown, and images.
       _surfaceController = SurfaceController(catalogs: [BasicCatalogItems.asCatalog()]);
   ​
       // The Conversation wires transport -> controller internally.
       _transportAdapter = A2uiTransportAdapter(onSend: (message) async {
         // Implement sending to LLM and pipe chunks back.
       });
   ​
       final catalog = BasicCatalogItems.asCatalog();
       final promptBuilder = PromptBuilder.chat(
         catalog: catalog,
         systemPromptFragments: [
           '''
           You are an expert in creating funny riddles. Every time I give you a word,
           you should generate UI that displays one new riddle related to that word.
           Each riddle should have both a question and an answer.
           '''
         ],
       );
   ​
       // ... initialize your LLM Client of choice using promptBuilder.systemPromptJoined()
   ​
       // Create the Conversation to orchestrate everything.
       _conversation = Conversation(
         controller: _surfaceController,
         transport: _transportAdapter,
       );
   ​
       // Listen for surface lifecycle events:
       _conversation.events.listen((event) {
         if (event is ConversationSurfaceAdded) {
           _onSurfaceAdded(event);
         } else if (event is ConversationSurfaceRemoved) {
           _onSurfaceDeleted(event);
         }
       });
     }
   ​
     @override
     void dispose() {
       _textController.dispose();
       _conversation.dispose();
       _transportAdapter.dispose();
   ​
       super.dispose();
     }
   }
   

   content_copy

使用 Conversation 類別中的 sendRequest 方法傳送請求至代理， 或直接串流至您的 LLM 用戶端， 並使用 _transportAdapter.addChunk 將結果串流傳至轉接器。

若要接收並顯示生成的 UI：

1. 監聽 Conversation 中的 events 串流，以追蹤 UI 表面 (surface) 的新增與移除。 這些事件會為每個表面包含一個 surface ID。

2. 使用上一步驟接收到的 surface ID，為每個活躍表面建置 Surface 元件 (Widget)。

   範例：

   dart

   class _MyHomePageState extends State<MyHomePage> {
     // ...
   ​
     final _textController = TextEditingController();
     final _surfaceIds = <String>[];
   ​
     // Send a request containing the user's [text] to the agent.
     void _sendMessage(String text) async {
       if (text.trim().isEmpty) return;
       // await _conversation.sendRequest(ChatMessage.user(TextPart(text)));
     }
   ​
     // Invoked by the events stream listener when a new
     // UI surface is generated. Here, the ID is stored so the
     // build method can create a Surface to display it.
     void _onSurfaceAdded(ConversationSurfaceAdded update) {
       setState(() {
         _surfaceIds.add(update.surfaceId);
       });
     }
   ​
     // Invoked by the events stream listener when a UI surface is removed.
     void _onSurfaceDeleted(ConversationSurfaceRemoved update) {
       setState(() {
         _surfaceIds.remove(update.surfaceId);
       });
     }
   ​
     @override
     Widget build(BuildContext context) {
       return Scaffold(
         appBar: AppBar(
           backgroundColor: Theme.of(context).colorScheme.inversePrimary,
           title: Text(widget.title),
         ),
         body: Column(
           children: [
             Expanded(
               child: ListView.builder(
                 itemCount: _surfaceIds.length,
                 itemBuilder: (context, index) {
                   // For each surface, create a Surface to display it.
                   final id = _surfaceIds[index];
                   return Surface(surfaceContext: _surfaceController.contextFor(id));
                 },
               ),
             ),
             SafeArea(
               child: Padding(
                 padding: const EdgeInsets.symmetric(horizontal: 16.0),
                 child: Row(
                   children: [
                     Expanded(
                       child: TextField(
                         controller: _textController,
                         decoration: const InputDecoration(
                           hintText: 'Enter a message',
                         ),
                       ),
                     ),
                     const SizedBox(width: 16),
                     ElevatedButton(
                       onPressed: () {
                         // Send the user's text to the agent.
                         _sendMessage(_textController.text);
                         _textController.clear();
                       },
                       child: const Text('Send'),
                     ),
                   ],
                 ),
               ),
             ),
           ],
         ),
       );
     }
   }
   

   content_copy

為了方便起見，您可以使用提供的核心元件 (Widget) 目錄。 不過，大多數正式版應用程式都會想要定義自訂元件目錄。

若要加入自訂元件，請依照下列說明操作。

1. 相依於 json_schema_builder 套件

   使用 dart pub add 將 json_schema_builder 新增為 pubspec.yaml 檔案中的相依套件：

   $ dart pub add json_schema_builder
   

   content_copy

2. 建立新元件的 schema

   每個目錄項目都需要一個 schema 來定義填入所需的資料。 使用 json_schema_builder 套件，為新元件定義 schema。

   dart

   import 'package:json_schema_builder/json_schema_builder.dart';
   import 'package:flutter/material.dart';
   import 'package:genui/genui.dart';
   ​
   final _schema = S.object(
     properties: {
       'question': S.string(description: 'The question part of a riddle.'),
       'answer': S.string(description: 'The answer part of a riddle.'),
     },
     required: ['question', 'answer'],
   );
   

   content_copy

3. 建立 CatalogItem

   每個 CatalogItem 代表代理被允許生成的一種元件 (Widget) 類型。 為此，它結合了名稱、schema，以及產生組成生成 UI 之元件的建置函式。

   dart

   final riddleCard = CatalogItem(
     name: 'RiddleCard',
     dataSchema: _schema,
     widgetBuilder:
         ({
           required data,
           required id,
           required buildChild,
           required dispatchEvent,
           required context,
           required dataContext,
         }) {
           final json = data as Map<String, Object?>;
           final question = json['question'] as String;
           final answer = json['answer'] as String;
   ​
           return Container(
             constraints: const BoxConstraints(maxWidth: 400),
             decoration: BoxDecoration(border: Border.all()),
             padding: const EdgeInsets.all(16),
             child: Column(
               crossAxisAlignment: CrossAxisAlignment.start,
               children: [
                 Text(question, style: Theme.of(context).textTheme.headlineMedium),
                 const SizedBox(height: 8.0),
                 Text(answer, style: Theme.of(context).textTheme.headlineSmall),
               ],
             ),
           );
         },
   );
   

   content_copy

4. 將 CatalogItem 加入目錄

   在實例化 SurfaceController 時，加入您的目錄項目。

   dart

   _surfaceController = SurfaceController(
     catalogs: [BasicCatalogItems.asCatalog().copyWith([riddleCard])],
   );
   

   content_copy

5. 更新系統指令以使用新元件

   為了確保代理知道要使用您的新元件， 請在系統指令中告知使用方式與時機。 執行時請提供 CatalogItem 中的名稱。

   dart

   final promptBuilder = PromptBuilder.chat(
     catalog: catalog,
     systemPromptFragments: [
       '''
       You are an expert in creating funny riddles. Every time I give you a word,
       generate a RiddleCard that displays one new riddle related to that word.
       Each riddle should have both a question and an answer.
       '''
     ],
   );
   ​
   // Pass promptBuilder.systemPromptJoined() to your LLM Config
   

   content_copy

genui 的核心概念是 DataModel，這是一個集中式、 可觀測的存放區，用於儲存所有動態 UI 狀態 (state)。 每個元件的狀態不由自身管理，而是儲存在 DataModel 中。

元件 (Widget) 會與此模型中的資料進行_繫結_。 當模型中的資料變更時，只有相依於該特定資料的元件才會重新建置 (rebuild)。 這是透過傳遞給每個元件建置函式的 DataContext 物件來實現的。

若要將元件的屬性繫結至資料模型， 請在 AI 傳送的資料中指定一個特殊的 JSON 物件。 此物件可包含標準 JSON 基本型別（用於靜態值）， 或含有 path 屬性的物件（用於繫結至資料模型中的值）。

舉例來說，若要在 Text 元件中顯示使用者名稱，AI 會生成：

{
  "component": "Text",
  "text": "Welcome to GenUI",
  "variant": "h1"
}

{
  "component": "Image",
  "url": "https://example.com/image.png",
  "variant": "mediumFeature"
}

輸入元件（例如 TextField）會直接更新 DataModel。 當使用者在繫結至 /user/name 的文字欄位中輸入內容時， DataModel 會更新，任何繫結至相同路徑的其他元件 都會自動重新建置以顯示新值。

這種反應式資料流簡化了狀態管理 (state management)，並在 使用者、UI 與 AI 之間建立了強大的高頻寬互動迴圈。

請參閱 genui 儲存庫中包含的範例。 旅遊應用程式示範如何定義代理可用於生成特定領域 UI 的自訂元件目錄。

若有任何不清楚或遺漏之處，請建立 issue。

genui 套件提供 LLM 一組可用於生成 UI 的工具。 若要讓 LLM 使用這些工具， 透過 PromptBuilder 提供的系統指令必須 明確告知它這樣做。

這就是為什麼先前的範例包含 代理的系統指令，其中有「每當我給您一個單字時，您應生成顯示...的 UI」這一行：

final promptBuilder = PromptBuilder.chat(
  catalog: catalog,
  instructions: '''
    You are an expert in creating funny riddles.
    Every time I give you a word, you should generate UI that
    displays one new riddle related to that word.
    Each riddle should have both a question and an answer.
    ''',
);

若要觀察應用程式與代理之間的通訊， 請在 main 方法中啟用記錄。

import 'package:logging/logging.dart';
import 'package:genui/genui.dart';
​
final logger = configureGenUiLogging(level: Level.ALL);
​
void main() async {
  logger.onRecord.listen((record) {
    debugPrint('${record.loggerName}: ${record.message}');
  });
​
  // Additional initialization of bindings and Firebase.
}

Firebase 對 Apple 平台有最低版本需求， 可能高於 Flutter 的預設值。 請檢查您的 Podfile（iOS 用）和 CMakeLists.txt（macOS 用）， 確保目標版本符合或超過 Firebase 的需求。