Xây dựng ứng dụng có giao diện người dùng tạo sinh (GenUI)

1. Giới thiệu

Trong lớp học lập trình này, bạn sẽ xây dựng một ứng dụng danh sách việc cần làm bằng Flutter, Firebase AI Logic và gói genui mới. Bạn sẽ bắt đầu bằng một ứng dụng trò chuyện dựa trên văn bản, nâng cấp ứng dụng đó bằng GenUI để cung cấp cho tác nhân khả năng tạo giao diện người dùng riêng, và cuối cùng là xây dựng thành phần giao diện người dùng tương tác tuỳ chỉnh của riêng bạn mà bạn và tác nhân có thể thao tác trực tiếp.

Một ứng dụng danh sách việc cần làm đang chạy trong Chrome

Bạn sẽ thực hiện

  • Xây dựng giao diện trò chuyện cơ bản bằng Flutter và Firebase AI Logic
  • Tích hợp gói genui để tạo các nền tảng dựa trên AI tạo sinh
  • Thêm một thanh tiến trình để cho biết thời điểm ứng dụng đang chờ phản hồi từ trợ lý ảo
  • Tạo một nền tảng có tên và hiển thị nền tảng đó ở một vị trí riêng trong giao diện người dùng.
  • Xây dựng một thành phần danh mục GenUI tuỳ chỉnh giúp bạn kiểm soát cách trình bày nhiệm vụ

Bạn cần có

  • Một trình duyệt web, chẳng hạn như Chrome
  • Flutter SDK được cài đặt cục bộ
  • Đã cài đặt và định cấu hình Firebase CLI

Lớp học lập trình này dành cho các nhà phát triển Flutter có trình độ trung cấp.

2. Trước khi bắt đầu

Thiết lập dự án Flutter

  1. Nếu bạn chưa cài đặt, hãy cài đặt Flutter SDK trên máy.
  2. Mở cửa sổ dòng lệnh rồi chạy flutter create để tạo một dự án mới:
    flutter create intro_to_genui
    cd intro_to_genui
    
  3. Thêm các phần phụ thuộc cần thiết vào dự án Flutter:
    flutter pub add firebase_core firebase_ai genui json_schema_builder
    
    Phần dependencies cuối cùng của bạn sẽ có dạng như sau (số phiên bản có thể hơi khác):
    dependencies:
      flutter:
        sdk: flutter
    
      cupertino_icons: ^1.0.9
      firebase_core: ^4.15.0
      firebase_ai: ^4.0.0
      genui: ^0.10.3
      json_schema_builder: ^0.1.7
    
  4. Chạy flutter pub get để tải tất cả các gói xuống.Nếu được nhắc rằng có các phiên bản gói mới hơn, bạn có thể chạy flutter pub outdated để kiểm tra các phiên bản và flutter pub upgrade để cập nhật các phần phụ thuộc.

Thiết lập dự án Firebase

  1. Nếu bạn chưa thực hiện, hãy cài đặt Giao diện dòng lệnh (CLI) của Firebase.
  2. Đăng nhập vào Firebase bằng Tài khoản Google của bạn:
    firebase login
    
  3. Cài đặt FlutterFire CLI:
    dart pub global activate flutterfire_cli
    
  4. Trong thư mục dự án Flutter, hãy chạy lệnh sau để định cấu hình dự án Flutter của bạn nhằm sử dụng Firebase:
    flutterfire configure
    
    Lệnh này sẽ thực hiện những việc sau:
    1. Hỏi bạn xem bạn muốn sử dụng dự án Firebase hiện có hay tạo một dự án Firebase mới. Chọn Tạo dự án Firebase mới.
    2. Hỏi bạn muốn nhắm đến nền tảng nào (iOS, Android, Web) cho ứng dụng Flutter. Hiện tại, hãy chọn Web.

Lệnh flutterfire configure tự động tạo một dự án Firebase và một Ứng dụng web Firebase mới trong dự án Firebase đó. Sau đó, lệnh này sẽ tạo một tệp cấu hình Firebase (firebase_options.dart) và tự động thêm tệp đó vào thư mục lib/ của dự án Flutter.

Xin lưu ý rằng ứng dụng cho lớp học lập trình này chỉ hoạt động với Flutter SDK và Chrome được cài đặt trên máy của bạn (tức là ứng dụng này sẽ được tạo dưới dạng một ứng dụng web). Tuy nhiên, vì ứng dụng này được xây dựng bằng Flutter nên cũng sẽ hoạt động trên các nền tảng khác! Vì vậy, khi kết thúc lớp học lập trình, hãy thử chạy lại flutterfire configure để thêm tính năng hỗ trợ cho iOS, Android hoặc một nền tảng khác, sau đó tạo lại ứng dụng trên nền tảng đó.

Để biết thêm thông tin, hãy xem hướng dẫn cách thêm Firebase vào một ứng dụng Flutter.

Thiết lập Firebase AI Logic

  1. Đăng nhập vào bảng điều khiển của Firebase. Sử dụng chính Tài khoản Google mà bạn đã dùng để đăng nhập vào Firebase CLI.
  2. Chọn dự án Firebase mà bạn vừa tạo bằng FlutterFire CLI.
  3. Trên trình đơn điều hướng bên trái, hãy chọn Dịch vụ AI > Logic AI.
  4. Nhấp vào Bắt đầu để bắt đầu quy trình có hướng dẫn.
  5. Chọn bắt đầu bằng Gemini Developer API rồi làm theo lời nhắc trên màn hình để thiết lập Firebase AI Logic.

Bạn đã có các trình bổ trợ FlutterFire cần thiết để sử dụng Firebase AI Logic trong phần "Thiết lập dự án Flutter". Bạn đã sẵn sàng chuyển sang bước tiếp theo để lập trình ứng dụng!

3. Tạo giao diện trò chuyện cơ bản

Trước khi giới thiệu Giao diện người dùng tạo sinh, ứng dụng của bạn cần có một nền tảng: một ứng dụng trò chuyện cơ bản dựa trên văn bản do Firebase AI Logic cung cấp. Để bắt đầu nhanh, bạn sẽ sao chép và dán toàn bộ chế độ thiết lập cho giao diện trò chuyện.

Một phiên bản dựa trên văn bản của ứng dụng

Tạo tiện ích bong bóng tin nhắn

Để hiển thị tin nhắn văn bản của người dùng và nhân viên hỗ trợ, ứng dụng của bạn cần có một tiện ích. Tạo một tệp mới có tên là lib/message_bubble.dart rồi thêm lớp sau:

import 'package:flutter/material.dart';

class MessageBubble extends StatelessWidget {
  final String text;
  final bool isUser;

  const MessageBubble({super.key, required this.text, required this.isUser});

  @override
  Widget build(BuildContext context) {
    final theme = Theme.of(context);
    final colorScheme = theme.colorScheme;

    final bubbleColor = isUser
        ? colorScheme.primary
        : colorScheme.surfaceContainerHighest;

    final textColor = isUser
        ? colorScheme.onPrimary
        : colorScheme.onSurfaceVariant;

    return Padding(
      padding: const EdgeInsets.symmetric(vertical: 6.0, horizontal: 8.0),
      child: Column(
        crossAxisAlignment: isUser
            ? CrossAxisAlignment.end
            : CrossAxisAlignment.start,
        children: [
          Row(
            mainAxisAlignment: isUser
                ? MainAxisAlignment.end
                : MainAxisAlignment.start,
            children: [
              Flexible(
                child: Container(
                  padding: const EdgeInsets.symmetric(
                    horizontal: 16.0,
                    vertical: 12.0,
                  ),
                  decoration: BoxDecoration(
                    color: bubbleColor,
                    borderRadius: BorderRadius.only(
                      topLeft: const Radius.circular(20),
                      topRight: const Radius.circular(20),
                      bottomLeft: Radius.circular(isUser ? 20 : 0),
                      bottomRight: Radius.circular(isUser ? 0 : 20),
                    ),
                    boxShadow: [
                      BoxShadow(
                        color: Colors.black.withAlpha(20),
                        blurRadius: 4,
                        offset: const Offset(0, 2),
                      ),
                    ],
                    gradient: isUser
                        ? LinearGradient(
                            colors: [
                              colorScheme.primary,
                              colorScheme.primary.withAlpha(200),
                            ],
                            begin: Alignment.topLeft,
                            end: Alignment.bottomRight,
                          )
                        : null,
                  ),
                  child: Text(
                    text,
                    style: theme.textTheme.bodyLarge?.copyWith(
                      color: textColor,
                      height: 1.3,
                    ),
                  ),
                ),
              ),
            ],
          ),
          const SizedBox(height: 2),
        ],
      ),
    );
  }
}

MessageBubble là một StatelessWidget hiển thị một tin nhắn trò chuyện. Sau này, bạn sẽ dùng lớp này trong lớp học lập trình để hiện tin nhắn của cả bạn và trợ lý, nhưng chủ yếu đây chỉ là một tiện ích Text bắt mắt.

Triển khai giao diện người dùng Chat trong main.dart

Thay thế toàn bộ nội dung của lib/main.dart bằng cách triển khai chatbot văn bản hoàn chỉnh này:

import 'package:flutter/material.dart';
import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_ai/firebase_ai.dart';
import 'package:intro_to_genui/message_bubble.dart';
import 'firebase_options.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Just Today',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.blue),
      ),
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

sealed class ConversationItem {}

class TextItem extends ConversationItem {
  final String text;
  final bool isUser;
  TextItem({required this.text, this.isUser = false});
}

class _MyHomePageState extends State<MyHomePage> {
  final List<ConversationItem> _items = [];
  final _textController = TextEditingController();
  final _scrollController = ScrollController();
  late final ChatSession _chatSession;

  @override
  void initState() {
    super.initState();
    final model = FirebaseAI.googleAI().generativeModel(
      model: 'gemini-3.5-flash',
    );
    _chatSession = model.startChat();
    _chatSession.sendMessage(Content.text(systemInstruction));
  }

  void _scrollToBottom() {
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (_scrollController.hasClients) {
        _scrollController.animateTo(
          _scrollController.position.maxScrollExtent,
          duration: const Duration(milliseconds: 300),
          curve: Curves.easeOut,
        );
      }
    });
  }

  @override
  void dispose() {
    _textController.dispose();
    _scrollController.dispose();
    super.dispose();
  }

  Future<void> _addMessage() async {
    final text = _textController.text;

    if (text.trim().isEmpty) {
      return;
    }
    _textController.clear();

    setState(() {
      _items.add(TextItem(text: text, isUser: true));
    });

    _scrollToBottom();

    final response = await _chatSession.sendMessage(Content.text(text));

    if (response.text?.isNotEmpty ?? false) {
      setState(() {
        _items.add(TextItem(text: response.text!, isUser: false));
      });
      _scrollToBottom();
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
        title: const Text('Just Today'),
      ),
      body: Column(
        children: [
          Expanded(
            child: ListView(
              controller: _scrollController,
              padding: const EdgeInsets.all(16),
              children: [
                for (final item in _items)
                  switch (item) {
                    TextItem() => MessageBubble(
                          text: item.text,
                          isUser: item.isUser,
                        ),
                  },
              ],
            ),
          ),
          SafeArea(
            child: Padding(
              padding: const EdgeInsets.symmetric(horizontal: 16.0),
              child: Row(
                children: [
                  Expanded(
                    child: TextField(
                      controller: _textController,
                      onSubmitted: (_) => _addMessage(),
                      decoration: const InputDecoration(
                        hintText: 'Enter a message',
                      ),
                    ),
                  ),
                  const SizedBox(width: 8),
                  ElevatedButton(
                    onPressed: _addMessage,
                    child: const Text('Send'),
                  ),
                ],
              ),
            ),
          ),
        ],
      ),
    );
  }
}

const systemInstruction = '''
  ## PERSONA
  You are an expert task planner.

  ## GOAL
  Work with me to produce a list of tasks that I should do today, and then track
  the completion status of each one.

  ## RULES
  Talk with me only about tasks that I should do today.
  Do not engage in conversation about any other topic.
  Do not offer suggestions unless I ask for them.
  Do not offer encouragement unless I ask for it.
  Do not offer advice unless I ask for it.
  Do not offer opinions unless I ask for them.

  ## PROCESS
  ### Planning
  *   Ask me for information about tasks that I should do today.
  *   Synthesize a list of tasks from that information.
  *   Ask clarifying questions if you need to.
  *   When you have a list of tasks that you think I should do today, present it
    to me for review.
  *   Respond to my suggestions for changes, if I have any, until I accept the
    list.

  ### Tracking
  *   Once the list is accepted, ask me to let you know when individual tasks are
    complete.
  *   If I tell you a task is complete, mark it as complete.
  *   Once all tasks are complete, send a message acknowledging that, and then
    end the conversation.
''';

Tệp main.dart mà bạn vừa sao chép và dán sẽ thiết lập một ChatSession cơ bản bằng Firebase AI Logic và câu lệnh trong systemInstruction. Thành phần này quản lý các lượt trò chuyện bằng cách duy trì danh sách các phần tử TextItem và hiển thị chúng cùng với các truy vấn của người dùng bằng cách sử dụng tiện ích MessageBubble mà bạn đã tạo trước đó.

Dưới đây là một số điều cần kiểm tra trước khi tiếp tục:

  • Phương thức initState là nơi thiết lập kết nối với Firebase AI Logic.
  • Ứng dụng này cung cấp một TextField và một nút để gửi tin nhắn cho nhân viên hỗ trợ.
  • Phương thức _addMessage là nơi tin nhắn của người dùng được gửi đến tác nhân.
  • Danh sách _items là nơi lưu trữ nhật ký trò chuyện.
  • Thông báo sẽ xuất hiện trong ListView bằng tiện ích MessageBubble.

Kiểm thử ứng dụng

Sau khi hoàn tất, bạn có thể chạy và kiểm thử ứng dụng.

flutter run -d chrome

Hãy thử trò chuyện với trợ lý về một số việc bạn muốn làm hôm nay. Mặc dù giao diện người dùng chỉ dựa trên văn bản có thể hoàn thành công việc, nhưng GenUI có thể giúp trải nghiệm trở nên dễ dàng và nhanh chóng hơn.

Sau khi hoàn tất kiểm thử, hãy dừng ứng dụng đang chạy bằng cách nhấn q (hoặc Ctrl+C) trong thiết bị đầu cuối trước khi tiếp tục bước tiếp theo.

4. Tích hợp gói GenUI

Giờ là lúc nâng cấp từ văn bản thuần túy lên Giao diện người dùng tạo sinh. Bạn sẽ thay thế vòng lặp nhắn tin Firebase cơ bản bằng các đối tượng GenUI Conversation, Catalog và SurfaceController. Điều này cho phép mô hình AI tạo thực thể cho các tiện ích Flutter thực tế trong luồng trò chuyện.

Một phiên bản của ứng dụng có tích hợp GenUI

Gói genui cung cấp 5 lớp mà bạn sẽ sử dụng trong suốt lớp học lập trình này:

  • SurfaceController liên kết giao diện người dùng do mô hình tạo với màn hình.
  • A2uiTransportAdapter kết nối các yêu cầu GenUI nội bộ với mọi mô hình ngôn ngữ bên ngoài.
  • Conversation gói bộ điều khiển và bộ chuyển đổi truyền tải bằng một API hợp nhất cho ứng dụng Flutter của bạn.
  • Catalog mô tả các tiện ích và thuộc tính có sẵn cho mô hình ngôn ngữ.
  • Surface là một tiện ích hiển thị giao diện người dùng do mô hình tạo.

Chuẩn bị sẵn sàng hiển thị Surface được tạo

Trong lib/main.dart, mã hiện có bao gồm một lớp TextItem đại diện cho một tin nhắn văn bản trong cuộc trò chuyện. Ngay sau lớp TextItem, hãy thêm một lớp SurfaceItem để biểu thị một Surface do tác nhân tạo:

class TextItem extends ConversationItem {
  // ... existing code ...
}

// New!
class SurfaceItem extends ConversationItem {
  final String surfaceId;
  SurfaceItem({required this.surfaceId});
}

Khởi động các thành phần GenUI

Ở đầu lib/main.dart, hãy nhập thư viện genui:

import 'package:genui/genui.dart' hide TextPart;
import 'package:genui/genui.dart' as genui;

Cả gói genui và gói firebase_ai đều có lớp TextPart. Bằng cách nhập genui theo cách này, bạn đang đặt không gian tên cho phiên bản TextPart của nó là genui.TextPart, tránh xung đột tên.

Khai báo các bộ điều khiển chức năng cốt lõi trong _MyHomePageState sau _chatSession:

class _MyHomePageState extends State<MyHomePage> {
  // ... existing members
  late final ChatSession _chatSession;

  // Add GenUI controllers
  late final SurfaceController _controller;
  late final A2uiTransportAdapter _transport;
  late final Conversation _conversation;
  late final Catalog catalog;

Tiếp theo, hãy cập nhật initState để chuẩn bị bộ điều khiển của thư viện GenUI.

Xoá dòng này khỏi initState:

_chatSession.sendMessage(Content.text(systemInstruction));

Sau đó, hãy thêm mã sau:

@override
void initState() {
  // ... existing code ...

  // Initialize the GenUI Catalog.
  // The genui package provides a default set of primitive widgets (like text
  // and basic buttons) out of the box using this class.
  catalog = BasicCatalogItems.asCatalog();

  // Create a SurfaceController to manage the state of generated surfaces.
  _controller = SurfaceController(catalogs: [catalog]);

  // Create a transport adapter that will process messages to and from the
  // agent, looking for A2UI messages.
  _transport = A2uiTransportAdapter(onSend: _sendAndReceive);

  // Link the transport and SurfaceController together in a Conversation,
  // which provides your app a unified API for interacting with the agent.
  _conversation = Conversation(
    controller: _controller,
    transport: _transport,
  );
}

Mã này tạo một lớp Conversation quản lý bộ điều khiển và bộ chuyển đổi. Cuộc trò chuyện đó cung cấp cho ứng dụng của bạn một luồng sự kiện mà ứng dụng có thể dùng để theo dõi những gì trợ lý đang tạo, cũng như một phương thức để gửi tin nhắn cho trợ lý.

Tiếp theo, hãy tạo một trình nghe cho các sự kiện trò chuyện. Những sự kiện này bao gồm các sự kiện liên quan đến bề mặt cũng như các sự kiện về tin nhắn văn bản và lỗi:

@override
void initState() {
  // ... existing code ...

  // Listen to GenUI stream events to update the UI
  _conversation.events.listen((event) {
    setState(() {
      switch (event) {
        case ConversationSurfaceAdded added:
          _items.add(SurfaceItem(surfaceId: added.surfaceId));
          _scrollToBottom();
        case ConversationSurfaceRemoved removed:
          _items.removeWhere(
            (item) =>
                item is SurfaceItem && item.surfaceId == removed.surfaceId,
          );
        case ConversationContentReceived content:
          _items.add(TextItem(text: content.text, isUser: false));
          _scrollToBottom();
        case ConversationError error:
          debugPrint('GenUI Error: ${error.error}');
        default:
      }
    });
  });
}

Cuối cùng, hãy tạo câu lệnh hệ thống và gửi câu lệnh đó đến tác nhân:

  @override
  void initState() {
    // ... existing code ...

    // Create the system prompt for the agent, which will include this app's
    // system instruction as well as the schema for the catalog.
    final promptBuilder = PromptBuilder.chat(
      catalog: catalog,
      systemPromptFragments: [systemInstruction],
    );

    // Send the prompt into the Conversation, which will subsequently route it
    // to Firebase using the transport mechanism.
    _conversation.sendRequest(
      ChatMessage.system(promptBuilder.systemPromptJoined()),
    );
  }

Đồng thời, hãy cập nhật phương thức dispose() trong _MyHomePageState để các trình điều khiển GenUI mới thêm được dọn dẹp đúng cách khi tiện ích bị loại bỏ:

  @override
  void dispose() {
    _conversation.dispose();
    _transport.dispose();
    _controller.dispose();
    _textController.dispose();
    _scrollController.dispose();
    super.dispose();
  }

Bề mặt hiển thị

Tiếp theo, hãy cập nhật phương thức build của ListView để hiển thị các SurfaceItem trong danh sách _items:

Expanded(
  child: ListView(
    controller: _scrollController,
    padding: const EdgeInsets.all(16),
    children: [
      for (final item in _items)
        switch (item) {
          TextItem() => MessageBubble(
            text: item.text,
            isUser: item.isUser,
          ),
          // New!
          SurfaceItem() => Surface(
            surfaceContext: _controller.contextFor(
              item.surfaceId,
            ),
          ),
        },
    ],
  ),
),

Hàm khởi tạo cho tiện ích Surface lấy một surfaceContext cho biết bề mặt mà tiện ích này chịu trách nhiệm hiển thị. SurfaceController được tạo trước đó (_controller) cung cấp định nghĩa và trạng thái cho từng nền tảng, đồng thời đảm bảo nền tảng đó được tạo lại khi có bản cập nhật.

Kết nối GenUI với Firebase AI Logic

Gói genui sử dụng phương pháp "Mang mô hình của riêng bạn", nghĩa là bạn kiểm soát LLM nào hỗ trợ trải nghiệm của bạn. Trong trường hợp này, bạn đang sử dụng Firebase AI Logic, nhưng gói này được xây dựng để hoạt động với nhiều tác nhân và nhà cung cấp.

Sự tự do đó đi kèm với một chút trách nhiệm: bạn cần lấy các thông báo do gói genui tạo và gửi đến tác nhân bạn chọn, đồng thời bạn cần lấy phản hồi của tác nhân và gửi lại vào genui.

Để làm việc đó, bạn sẽ xác định phương thức _sendAndReceive được tham chiếu trong mã cho bước trước. Trong lib/main.dart, hãy thêm _sendAndReceive vào bên trong lớp _MyHomePageState (ví dụ: ngay sau dòng late final Catalog catalog;):

class _MyHomePageState extends State<MyHomePage> {
  // ... existing code ...
  late final Catalog catalog;

  // New!
  Future<void> _sendAndReceive(ChatMessage msg) async {
    final buffer = StringBuffer();

    // Reconstruct the message part fragments
    for (final part in msg.parts) {
      if (part.isUiInteractionPart) {
        buffer.write(part.asUiInteractionPart!.interaction);
      } else if (part is genui.TextPart) {
        buffer.write(part.text);
      }
    }

    if (buffer.isEmpty) {
      return;
    }

    final text = buffer.toString();

    // Send the string to Firebase AI Logic.
    final response = await _chatSession.sendMessage(Content.text(text));

    if (response.text?.isNotEmpty ?? false) {
      // Feed the response back into GenUI's transportation layer
      _transport.addChunk(response.text!);
    }
  }

Phương thức này sẽ được gói genui gọi bất cứ khi nào cần gửi một thông báo đến tác nhân. Lệnh gọi đến addChunk ở cuối phương thức sẽ đưa phản hồi của tác nhân trở lại gói genui, cho phép gói này xử lý phản hồi và tạo giao diện người dùng.

Cuối cùng, hãy thay thế hoàn toàn phương thức _addMessage hiện có bằng phiên bản mới này để phương thức này định tuyến các thông báo vào Conversation thay vì Firebase:

  Future<void> _addMessage() async {
    final text = _textController.text;

    if (text.trim().isEmpty) {
      return;
    }

    _textController.clear();

    setState(() {
      _items.add(TextItem(text: text, isUser: true));
    });

    _scrollToBottom();

    // Send the user's input through GenUI instead of directly to Firebase.
    await _conversation.sendRequest(ChatMessage.user(text));
  }

Vậy là xong! Hãy thử chạy lại ứng dụng. Ngoài tin nhắn văn bản, bạn sẽ thấy tác nhân tạo ra các thành phần giao diện người dùng như nút, tiện ích văn bản và nhiều thành phần khác.

Bạn thậm chí có thể thử yêu cầu tác nhân hiển thị giao diện người dùng theo một cách cụ thể. Ví dụ: hãy thử một câu lệnh như "Cho tôi xem các việc cần làm của tôi theo cột, có nút đánh dấu từng việc là đã hoàn tất".

5. Thêm trạng thái chờ

Quá trình tạo LLM không đồng bộ. Trong khi chờ phản hồi, giao diện trò chuyện cần tắt các nút nhập và hiển thị chỉ báo tiến trình để người dùng biết GenUI đang tạo nội dung. Rất may là gói genui cung cấp một Listenable mà bạn có thể dùng để theo dõi trạng thái của cuộc trò chuyện. Giá trị ConversationState đó bao gồm thuộc tính isWaiting để xác định xem mô hình có đang tạo nội dung hay không.

Gói các chế độ điều khiển đầu vào bằng một ValueListenableBuilder

Trong phương thức build của _MyHomePageState trong lib/main.dart, hãy tìm tiện ích SafeArea ở cuối Column và bao bọc thành phần con Row (chứa TextField và ElevatedButton) bằng một ValueListenableBuilder lắng nghe _conversation.state. Bằng cách kiểm tra state.isWaiting, bạn có thể tắt tính năng nhập trong khi mô hình đang tạo nội dung:

SafeArea(
  child: Padding(
    padding: const EdgeInsets.symmetric(horizontal: 16.0),
    // Wrap the Row in a ValueListenableBuilder:
    child: ValueListenableBuilder<ConversationState>(
      valueListenable: _conversation.state,
      builder: (context, state, child) {
        return Row(
          children: [
            Expanded(
              child: TextField(
                controller: _textController,
                // Also disable the Enter key submission when waiting!
                onSubmitted: state.isWaiting ? null : (_) => _addMessage(),
                decoration: const InputDecoration(
                  hintText: 'Enter a message',
                ),
              ),
            ),
            const SizedBox(width: 8),
            ElevatedButton(
              // Disable the send button when the model is generating
              onPressed: state.isWaiting ? null : _addMessage,
              child: const Text('Send'),
            ),
          ],
        );
      },
    ),
  ),
),

Thêm thanh tiến trình

Trong phương thức build của _MyHomePageState, hãy bao bọc tiện ích Column chính bên trong một Stack và thêm một ValueListenableBuilder kết xuất LinearProgressIndicator làm thành phần con thứ hai của Stack đó. Khi bạn hoàn tất, body của Scaffold sẽ có dạng như sau:

body: Stack( // New!
  children: [
    Column(
      children: [
        // ... existing Expanded and SafeArea widgets ...
      ],
    ),
    // Listen to the state again, this time to render a progress indicator
    ValueListenableBuilder<ConversationState>(
      valueListenable: _conversation.state,
      builder: (context, state, child) {
        if (state.isWaiting) {
          return const LinearProgressIndicator();
        }
        return const SizedBox.shrink();
      },
    ),
  ],
),

6. Lưu giữ một giao diện người dùng tạo sinh (GenUI)

Cho đến nay, danh sách việc cần làm đã được hiển thị trong luồng trò chuyện có thể cuộn, với mỗi tin nhắn hoặc thành phần mới được thêm vào danh sách khi đến. Trong bước tiếp theo, bạn sẽ tìm hiểu cách đặt tên cho một nền tảng và hiển thị nền tảng đó ở một vị trí cụ thể trong giao diện người dùng.

Trước tiên, ở đầu lib/main.dart, trước void main(), hãy khai báo một hằng số để dùng làm mã nhận dạng bề mặt:

const taskDisplaySurfaceId = 'task_display';

Thứ hai, trong initState(), hãy cập nhật câu lệnh switch trong trình nghe Conversation để đảm bảo mọi nền tảng có mã nhận dạng đó đều không được thêm vào _items. Để làm được việc này, hãy cập nhật nhánh case ConversationSurfaceAdded added: bên trong _conversation.events.listen bằng cách gói các dòng _items.add(...) và _scrollToBottom() trong một câu lệnh if:

_conversation.events.listen((event) {
  setState(() {
    switch (event) {
      case ConversationSurfaceAdded added:
        // Wrap these two lines in an if check:
        if (added.surfaceId != taskDisplaySurfaceId) {
          _items.add(SurfaceItem(surfaceId: added.surfaceId));
          _scrollToBottom();
        }
      case ConversationSurfaceRemoved removed:
        // ... existing code ...

Tiếp theo, hãy mở cấu trúc bố cục của cây tiện ích trong _MyHomePageState.build để tạo một khoảng trống cho bề mặt được ghim ngay trước nhật ký trò chuyện. Chèn AnimatedSize và const Divider() làm hai thành phần con đầu tiên của Column chính, ngay trước mã Expanded(child: ListView(...)):

body: Stack(
  children: [
    Column(
      children: [
        // Insert these two new widgets at the top of the Column:
        AnimatedSize(
          duration: const Duration(milliseconds: 300),
          child: Container(
            padding: const EdgeInsets.all(16),
            alignment: Alignment.topLeft,
            child: Surface(
              surfaceContext: _controller.contextFor(
                taskDisplaySurfaceId,
              ),
            ),
          ),
        ),
        const Divider(),
        Expanded(
          child: ListView(
            // ... existing code ...

Cho đến nay, nhân viên hỗ trợ của bạn có toàn quyền tạo và sử dụng các nền tảng khi thấy phù hợp. Để đưa ra hướng dẫn cụ thể hơn, bạn cần xem lại câu lệnh hệ thống. Thêm phần ## USER INTERFACE sau vào cuối câu lệnh được lưu trữ trong hằng số systemInstruction:

const systemInstruction = '''
  // ... existing prompt content ...

  ## USER INTERFACE
  *   To display the list of tasks create one and only one instance of the
    TaskDisplay catalog item. Use "$taskDisplaySurfaceId" as its surface ID.
  *   Update $taskDisplaySurfaceId as necessary when the list changes.
  *   $taskDisplaySurfaceId must include a button for each task that I can use
    to mark it complete. When I use that button to mark a task complete, it
    should send you a message indicating what I've done.
  *   Avoid repeating the same information in a single message.
  *   When responding with text, rather than A2UI messages, be brief.
''';

Bạn cần đưa ra hướng dẫn rõ ràng cho tác nhân về thời điểm và cách sử dụng các nền tảng giao diện người dùng. Bằng cách yêu cầu tác nhân sử dụng một mục cụ thể trong danh mục và mã nhận dạng nền tảng (và sử dụng lại một phiên bản duy nhất), bạn có thể giúp đảm bảo rằng tác nhân sẽ tạo giao diện mà bạn muốn thấy.

Bạn cần làm thêm một số việc, nhưng bạn có thể thử chạy lại ứng dụng để xem tác nhân tạo bề mặt hiển thị tác vụ ở đầu giao diện người dùng.

7. Tạo tiện ích danh mục tuỳ chỉnh

Tại thời điểm này, mục TaskDisplay trong danh mục không tồn tại. Trong một vài bước tiếp theo, bạn sẽ khắc phục vấn đề đó bằng cách tạo một giản đồ dữ liệu, một lớp để phân tích cú pháp giản đồ đó, một tiện ích và mục danh mục kết hợp mọi thứ lại với nhau.

Trước tiên, hãy tạo một tệp mới có tên là task_display.dart trong thư mục lib/ của dự án và thêm các nội dung nhập sau:

import 'package:flutter/material.dart';
import 'package:genui/genui.dart';
import 'package:json_schema_builder/json_schema_builder.dart';

Tạo lược đồ dữ liệu

Tiếp theo, hãy xác định giản đồ dữ liệu mà tác nhân sẽ cung cấp khi muốn tạo một màn hình tác vụ. Quá trình này sử dụng một số hàm khởi tạo phức tạp trong gói json_schema_builder, nhưng về cơ bản, bạn chỉ đang xác định một giản đồ JSON dùng trong các thông báo đến và đi từ tác nhân.

Bắt đầu bằng một S.object cơ bản tham chiếu đến tên thành phần:

final taskDisplaySchema = S.object(
  properties: {
    'component': S.string(enumValues: ['TaskDisplay']),
  },
);

Tiếp theo, hãy thêm title, tasks, name, isCompleted và completeAction vào các thuộc tính của lược đồ.

final taskDisplaySchema = S.object(
  properties: {
    'component': S.string(enumValues: ['TaskDisplay']),
    'title': S.string(description: 'The title of the task list'),
    'tasks': S.list(
      description: 'A list of tasks to be completed today',
      items: S.object(
        properties: {
          'name': S.string(description: 'The name of the task to be completed'),
          'isCompleted': S.boolean(
            description: 'Whether the task is completed',
          ),
          'completeAction': A2uiSchemas.action(
            description:
                'The action performed when the user has completed the task.',
          ),
        },
      ),
    ),
  },
);

Hãy xem thuộc tính completeAction. Thành phần này được tạo bằng A2uiSchemas.action, hàm khởi tạo cho một thuộc tính giản đồ đại diện cho một Hành động A2UI. Bằng cách thêm một hành động vào giản đồ, về cơ bản, ứng dụng sẽ cho tác nhân biết: "Này, khi bạn giao cho tôi một nhiệm vụ, hãy cung cấp cả tên và siêu dữ liệu cho một hành động mà tôi có thể dùng để cho bạn biết nhiệm vụ đó đã hoàn tất". Sau đó, ứng dụng sẽ gọi hành động đó khi người dùng nhấn vào một hộp đánh dấu.

Tiếp theo, hãy thêm các trường required vào giản đồ. Những thuộc tính này hướng dẫn tác nhân điền sẵn một số thuộc tính nhất định mỗi lần. Trong trường hợp này, bạn phải cung cấp mọi thuộc tính!

final taskDisplaySchema = S.object(
  properties: {
    'component': S.string(enumValues: ['TaskDisplay']),
    'title': S.string(description: 'The title of the task list'),
    'tasks': S.list(
      description: 'A list of tasks to be completed today',
      items: S.object(
        properties: {
          'name': S.string(description: 'The name of the task to be completed'),
          'isCompleted': S.boolean(
            description: 'Whether the task is completed',
          ),
          'completeAction': A2uiSchemas.action(
            description:
                'The action performed when the user has completed the task.',
          ),
        },
        // New!
        required: ['name', 'isCompleted', 'completeAction'],
      ),
    ),
  },
  // New!
  required: ['title', 'tasks'],
);

Tạo lớp phân tích cú pháp dữ liệu

Khi tạo các phiên bản của thành phần này, tác nhân sẽ gửi dữ liệu khớp với giản đồ. Thêm 2 lớp để phân tích cú pháp JSON đến thành các đối tượng Dart có kiểu mạnh. Lưu ý cách _TaskDisplayData xử lý cấu trúc gốc, đồng thời uỷ quyền phân tích cú pháp mảng bên trong cho _TaskData.

class _TaskData {
  final String name;
  final bool isCompleted;
  final String actionName;
  final JsonMap? actionContext;

  _TaskData({
    required this.name,
    required this.isCompleted,
    required this.actionName,
    this.actionContext,
  });

  factory _TaskData.fromJson(Map<String, Object?> json) {
    try {
      final action = json['completeAction']! as JsonMap;
      final event = action['event']! as JsonMap;

      return _TaskData(
        name: json['name'] as String,
        isCompleted: json['isCompleted'] as bool,
        actionName: event['name'] as String,
        actionContext: event['context'] as JsonMap?,
      );
    } catch (e) {
      throw Exception('Invalid JSON for _TaskData: $e');
    }
  }
}

class _TaskDisplayData {
  final String title;
  final List<_TaskData> tasks;

  _TaskDisplayData({required this.title, required this.tasks});

  factory _TaskDisplayData.fromJson(Map<String, Object?> json) {
    try {
      return _TaskDisplayData(
        title: (json['title'] as String?) ?? 'Tasks',
        tasks: (json['tasks'] as List<Object?>)
            .map((e) => _TaskData.fromJson(e as Map<String, Object?>))
            .toList(),
      );
    } catch (e) {
      throw Exception('Invalid JSON for _TaskDisplayData: $e');
    }
  }
}

Nếu bạn từng xây dựng bằng Flutter, thì các lớp này có thể tương tự như các lớp bạn đã tạo. Chúng chấp nhận một JsonMap và trả về một đối tượng được nhập mạnh mẽ chứa dữ liệu được phân tích cú pháp từ JSON.

Hãy xem các trường actionName và actionContext trong _TaskData. Các sự kiện này được trích xuất từ thuộc tính completeAction của JSON và chứa tên của hành động cũng như bối cảnh dữ liệu của hành động đó (tham chiếu đến vị trí của hành động trong mô hình dữ liệu của GenUI). Các giá trị này sẽ được dùng sau để tạo UserActionEvent.

Mô hình dữ liệu là một kho lưu trữ tập trung, có thể ghi nhận được cho tất cả trạng thái giao diện người dùng động, do thư viện genui duy trì. Khi tạo một thành phần giao diện người dùng từ danh mục, tác nhân cũng tạo một đối tượng dữ liệu khớp với giản đồ của thành phần đó. Đối tượng dữ liệu này được lưu trữ trong mô hình dữ liệu trong ứng dụng khách, nhờ đó, bạn có thể dùng đối tượng này để tạo tiện ích và tham chiếu trong các thông báo sau này cho tác nhân (như completeAction mà bạn sắp kết nối với một tiện ích).

Thêm tiện ích

Bây giờ, hãy tạo một tiện ích để hiển thị danh sách. Hàm này sẽ chấp nhận một thực thể của lớp _TaskDisplayData và một lệnh gọi lại để gọi khi một tác vụ hoàn tất.

class _TaskDisplay extends StatelessWidget {
  final _TaskDisplayData data;
  final void Function(_TaskData) onCompleteTask;

  const _TaskDisplay({required this.data, required this.onCompleteTask});

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      mainAxisSize: MainAxisSize.min,
      children: [
        Padding(
          padding: const EdgeInsets.all(16.0),
          child: Text(
            data.title,
            style: Theme.of(context).textTheme.titleLarge,
          ),
        ),
        ...data.tasks.map(
          (task) => CheckboxListTile(
            title: Text(
              task.name,
              style: TextStyle(
                decoration: task.isCompleted
                    ? TextDecoration.lineThrough
                    : TextDecoration.none,
              ),
            ),
            value: task.isCompleted,
            onChanged: task.isCompleted
                ? null
                : (val) {
                    if (val == true) {
                      onCompleteTask(task);
                    }
                  },
          ),
        ),
      ],
    );
  }
}

Tạo CatalogItem

Sau khi tạo giản đồ, trình phân tích cú pháp và tiện ích, giờ đây, bạn có thể tạo một CatalogItem để liên kết tất cả các thành phần này với nhau.

Ở cuối task_display.dart, hãy tạo taskDisplay làm biến cấp cao nhất, dùng _TaskDisplayData để phân tích cú pháp JSON đến và tạo một phiên bản của tiện ích _TaskDisplay.

final taskDisplay = CatalogItem(
  name: 'TaskDisplay',
  dataSchema: taskDisplaySchema,
  widgetBuilder: (itemContext) {
    final json = itemContext.data as Map<String, Object?>;
    final data = _TaskDisplayData.fromJson(json);

    return _TaskDisplay(
      data: data,
      onCompleteTask: (task) async {
        // We will implement this next!
      },
    );
  },
);

Triển khai onCompleteTask

Để tiện ích hoạt động, tiện ích cần giao tiếp lại với nhân viên hỗ trợ khi một nhiệm vụ hoàn tất. Thay thế phần giữ chỗ onCompleteTask trống bằng mã sau để tạo và gửi sự kiện bằng completeAction từ dữ liệu nhiệm vụ.

onCompleteTask: (task) async {
  // A data context is a reference to a location in the data model. This line
  // turns that reference into a concrete data object that the agent can use.
  // It's kind of like taking a pointer and replacing it with the value it
  // points to.
  final JsonMap resolvedContext = await resolveContext(
    itemContext.dataContext,
    task.actionContext,
  );

  // Dispatch an event back to the agent, letting it know a task was completed.
  // This will be sent to the agent in an A2UI message that includes the name
  // of the action, the surface ID, and the resolved data context.
  itemContext.dispatchEvent(
    UserActionEvent(
      name: task.actionName,
      sourceComponentId: itemContext.id,
      context: resolvedContext,
    ),
  );
}

Đăng ký mục trong danh mục

Cuối cùng, hãy mở main.dart, nhập tệp mới và đăng ký tệp đó cùng với các mục khác trong danh mục.

Thêm nội dung nhập này vào đầu lib/main.dart:

import 'task_display.dart';

Thay thế catalog = BasicCatalogItems.asCatalog(); trong hàm initState() bằng:

// The Catalog is immutable, so use copyWith to create a new version
// that includes our custom catalog item along with the basics.
catalog = BasicCatalogItems.asCatalog().copyWith(newItems: [taskDisplay]);

Bạn đã hoàn tất! Khởi động lại ứng dụng để xem các thay đổi.

8. Thử nghiệm nhiều cách tương tác với trợ lý

Một ứng dụng danh sách việc cần làm chạy trong Chrome

Giờ đây, khi đã thêm tiện ích mới vào Danh mục và tạo không gian cho tiện ích đó trong giao diện người dùng của ứng dụng, bạn có thể bắt đầu làm việc với tác nhân. Một trong những lợi ích chính của GenUI là cung cấp hai cách để tương tác với dữ liệu: thông qua giao diện người dùng của ứng dụng như nút và hộp đánh dấu, và thông qua một tác nhân hiểu ngôn ngữ tự nhiên và có thể suy luận về dữ liệu. Hãy thử nghiệm cả hai!

  • Sử dụng trường văn bản để mô tả 3 hoặc 4 việc cần làm và xem các việc đó xuất hiện trong danh sách.
  • Sử dụng hộp đánh dấu để chuyển đổi trạng thái của một việc cần làm thành hoàn thành hoặc chưa hoàn thành.
  • Tạo danh sách gồm 5 đến 6 việc cần làm, sau đó yêu cầu tác nhân xoá những việc cần làm mà bạn phải lái xe đến một nơi nào đó.
  • Yêu cầu Gemini tạo một danh sách các việc cần làm lặp lại dưới dạng các mục riêng lẻ ("Tôi cần mua thiệp chúc mừng cho Mẹ, Bố và Bà. Tạo các việc cần làm riêng cho những việc đó").
  • Yêu cầu trợ lý đánh dấu tất cả việc cần làm là đã hoàn thành hoặc chưa hoàn thành, hoặc đánh dấu hoàn thành hai hoặc ba việc cần làm đầu tiên.

9. Xin chúc mừng

Xin chúc mừng! Bạn đã tạo một ứng dụng theo dõi công việc dựa trên AI bằng Giao diện người dùng tạo sinh và Flutter.

Kiến thức bạn học được

  • Tương tác với các mô hình nền tảng của Google bằng Flutter Firebase SDK
  • Kết xuất các nền tảng tương tác do Gemini tạo bằng GenUI
  • Ghim các nền tảng trong bố cục bằng cách sử dụng mã hiển thị tĩnh được xác định trước
  • Thiết kế các giản đồ và danh mục tiện ích tuỳ chỉnh cho các vòng lặp tương tác mạnh mẽ

Tài liệu tham khảo