1. مقدمة
في هذا الدرس التطبيقي حول الترميز، ستنشئ تطبيق قائمة مهام باستخدام Flutter وFirebase AI Logic وحزمة genui الجديدة. ستبدأ بتطبيق محادثة مستند إلى النصوص، ثم ستطوّره باستخدام GenUI لمنح الوكيل القدرة على إنشاء واجهة المستخدم الخاصة به، وأخيرًا ستنشئ مكوّن واجهة مستخدم تفاعليًا مخصّصًا يمكنك أنت والوكيل التعديل عليه مباشرةً.

الإجراءات التي ستنفذّها
- إنشاء واجهة محادثة أساسية باستخدام Flutter وFirebase AI Logic
- دمج حزمة
genuiلإنشاء مساحات عرض مستندة إلى الذكاء الاصطناعي التوليدي - إضافة شريط تقدّم للإشارة إلى أنّ التطبيق ينتظر ردًا من الوكيل
- إنشاء مساحة مُسمّاة وعرضها في مكان مخصّص في واجهة المستخدم
- إنشاء مكوّن مخصّص لكتالوج GenUI يتيح لك التحكّم في طريقة عرض المهام
المتطلبات
- متصفّح ويب، مثل Chrome
- حزمة تطوير البرامج (SDK) من Flutter المثبَّتة على الجهاز
- تثبيت Firebase CLI وإعداده
هذا الدرس التطبيقي حول الترميز مخصّص للمطوّرين الذين لديهم خبرة متوسطة في Flutter.
2. قبل البدء
إعداد مشروع Flutter
- إذا لم يسبق لك ذلك، ثبِّت حزمة تطوير البرامج (SDK) من Flutter على جهازك.
- افتح الوحدة الطرفية وشغِّل
flutter createلإنشاء مشروع جديد:flutter create intro_to_genui cd intro_to_genui - أضِف التبعيات اللازمة إلى مشروع Flutter:
يجب أن يبدو قسمflutter pub add firebase_core firebase_ai genui json_schema_builderdependenciesالنهائي على النحو التالي (قد تختلف أرقام الإصدارات قليلاً):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 - نفِّذ الأمر
flutter pub getلتنزيل جميع الحِزم.إذا طُلب منك توفُّر إصدارات أحدث من الحِزم، يمكنك تنفيذ الأمرflutter pub outdatedللتحقّق من الإصدارات والأمرflutter pub upgradeلتحديث التبعيات.
إعداد مشروع Firebase
- ثبِّت Firebase CLI، إذا لم يسبق لك ذلك.
- سجِّل الدخول إلى Firebase باستخدام حساب Google الخاص بك:
firebase login - ثبِّت FlutterFire CLI:
dart pub global activate flutterfire_cli - من دليل مشروع Flutter، نفِّذ الأمر التالي لإعداد مشروع Flutter لاستخدام Firebase:
سينفّذ هذا الأمر ما يلي:flutterfire configure- سؤالك عمّا إذا كنت تريد استخدام مشروع حالي على Firebase أو إنشاء مشروع جديد على Firebase اختَر إنشاء مشروع Firebase جديد.
- سيُطلب منك اختيار النظام الأساسي (iOS أو Android أو الويب) الذي تريد استهدافه لتطبيق Flutter. في الوقت الحالي، اختَر الويب.
ينشئ الأمر flutterfire configure تلقائيًا مشروع Firebase وتطبيق ويب جديدًا في Firebase ضمن مشروع Firebase هذا. بعد ذلك، ينشئ الأمر ملف إعداد Firebase (firebase_options.dart) ويضيفه تلقائيًا إلى دليل lib/ في مشروع Flutter.
يُرجى العِلم أنّ التطبيق الخاص بهذا الدرس التطبيقي حول الترميز يعمل فقط مع حزمة تطوير البرامج (SDK) من Flutter وChrome المثبَّتَين على جهازك (أي أنّه يتم إنشاؤه كتطبيق ويب). بما أنّ هذا التطبيق تم إنشاؤه باستخدام Flutter، سيعمل على منصات أخرى أيضًا. لذا، في نهاية الدرس التطبيقي حول الترميز، جرِّب إعادة تشغيل flutterfire configure لإضافة إمكانية استخدام التطبيق على iOS أو Android أو أي نظام أساسي آخر، ثم إعادة إنشاء التطبيق على هذا النظام الأساسي.
لمزيد من المعلومات، يُرجى الاطّلاع على تعليمات إضافة Firebase إلى تطبيق Flutter.
إعداد Firebase AI Logic
- سجِّل الدخول إلى وحدة تحكُّم Firebase. استخدِم حساب Google نفسه الذي استخدمته لتسجيل الدخول إلى Firebase CLI.
- اختَر مشروع Firebase الذي أنشأته للتو باستخدام FlutterFire CLI.
- من قائمة التنقّل اليمنى، اختَر خدمات الذكاء الاصطناعي > منطق الذكاء الاصطناعي.
- انقر على البدء لبدء سير العمل الموجَّه.
- اختَر البدء باستخدام Gemini Developer API، واتّبِع التعليمات الظاهرة على الشاشة لإعداد Firebase AI Logic.
لديك حاليًا مكوّنات FlutterFire الإضافية المطلوبة لاستخدام Firebase AI Logic من قسم "إعداد مشروع Flutter". أنت على استعداد لبدء ترميز تطبيقك في الخطوة التالية.
3- إنشاء واجهة محادثة أساسية
قبل تقديم واجهة المستخدم التوليدية، يحتاج تطبيقك إلى أساس: تطبيق محادثة نصي أساسي مستنِد إلى Firebase AI Logic. للبدء بسرعة، عليك نسخ الإعدادات الكاملة لواجهة المحادثة ولصقها.

إنشاء تطبيق الفقاعة المصغّر للرسائل
لعرض الرسائل النصية من المستخدم والموظف، يحتاج تطبيقك إلى أداة. أنشئ ملفًا جديدًا باسم lib/message_bubble.dart وأضِف الفئة التالية:
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 هو StatelessWidget يعرض رسالة محادثة واحدة. سيتم استخدامها لاحقًا في هذا الدرس التطبيقي حول الترميز لعرض الرسائل منك ومن الوكيل، ولكنّها في الغالب مجرد تطبيق مصغّر Text رائع.
تنفيذ واجهة مستخدم Chat في main.dart
استبدِل محتوى lib/main.dart بالكامل بتنفيذ روبوت الدردشة النصي الكامل هذا:
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.
''';
يُعدّ ملف main.dart الذي نسخته ولصقته للتوّ ChatSession أساسيًا باستخدام Firebase AI Logic والطلب في systemInstruction. وتدير هذه الفئة جولات المحادثة من خلال الاحتفاظ بقائمة من عناصر TextItem وعرضها إلى جانب طلبات المستخدمين باستخدام تطبيق MessageBubble المصغّر الذي أنشأته سابقًا.
في ما يلي بعض الأمور التي يجب التحقّق منها قبل المتابعة:
- يتم إعداد الاتصال بـ Firebase AI Logic من خلال طريقة
initState. - يوفّر التطبيق
TextFieldوزرًا لإرسال الرسائل إلى الوكيل. - الطريقة
_addMessageهي المكان الذي يتم فيه إرسال رسالة المستخدم إلى الوكيل. - قائمة
_itemsهي المكان الذي يتم فيه تخزين سجلّ المحادثات. - يتم عرض الرسائل في
ListViewباستخدام تطبيقMessageBubbleالمصغّر.
اختبار التطبيق
بعد الانتهاء من ذلك، يمكنك الآن تشغيل التطبيق واختباره.
flutter run -d chrome
يمكنك تجربة التحدّث مع الوكيل بشأن بعض المهام التي تريد إنجازها اليوم. صحيح أنّ واجهة المستخدم المستندة إلى النصوص فقط يمكنها إنجاز المهمة، ولكنّ واجهة GenUI يمكنها جعل التجربة أسهل وأسرع.
بعد إكمال الاختبار، أوقِف التطبيق قيد التشغيل بالضغط على q (أو Ctrl+C) في الوحدة الطرفية قبل المتابعة إلى الخطوة التالية.
4. دمج حزمة GenUI
حان الوقت الآن للترقية من النص العادي إلى واجهة المستخدم التوليدية. ستستبدل حلقة المراسلة الأساسية في Firebase بعناصر GenUI Conversation وCatalog وSurfaceController. يسمح ذلك لنموذج الذكاء الاصطناعي بإنشاء عناصر واجهة مستخدم Flutter فعلية ضمن بث المحادثة.

توفّر حزمة genui خمس فئات ستستخدمها في هذا الدرس التطبيقي حول الترميز:
SurfaceControllerيربط واجهة المستخدم التي أنشأها النموذج بالشاشة.A2uiTransportAdapterيربط طلبات GenUI الداخلية بأي نموذج لغوي خارجي.- تتضمّن حزمة
Conversationوحدة التحكّم ومحوّل النقل مع واجهة برمجة تطبيقات واحدة وموحّدة لتطبيق Flutter. -
Catalogيصف الأدوات والخصائص المتاحة للنموذج اللغوي. -
Surfaceهو أداة تعرض واجهة مستخدم من إنشاء النموذج.
استعدّ لعرض Surface تم إنشاؤه
في lib/main.dart، يتضمّن الرمز الحالي فئة TextItem تمثّل رسالة نصية واحدة ضمن المحادثة. بعد الفئة TextItem مباشرةً، أضِف الفئة SurfaceItem لتمثيل Surface الذي أنشأه الوكيل:
class TextItem extends ConversationItem {
// ... existing code ...
}
// New!
class SurfaceItem extends ConversationItem {
final String surfaceId;
SurfaceItem({required this.surfaceId});
}
بدء استخدام الوحدات الأساسية في GenUI
في أعلى lib/main.dart، استورِد مكتبة genui:
import 'package:genui/genui.dart' hide TextPart;
import 'package:genui/genui.dart' as genui;
تتضمّن كل من حزمة genui وحزمة firebase_ai فئة TextPart. من خلال استيراد genui بهذه الطريقة، يمكنك تحديد مساحة اسم لإصدار TextPart باسم genui.TextPart، ما يمنع حدوث تعارض في الأسماء.
يجب الإعلان عن وحدات التحكّم الوظيفية الأساسية في _MyHomePageState بعد _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;
بعد ذلك، عدِّل initState لإعداد وحدات التحكّم في مكتبة GenUI.
أزِل هذا السطر من initState:
_chatSession.sendMessage(Content.text(systemInstruction));
بعد ذلك، أضِف الرمز التالي:
@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,
);
}
تنشئ هذه التعليمات البرمجية واجهة Conversation تدير وحدة التحكّم والمحوّل. توفّر هذه المحادثة لتطبيقك سلسلة من الأحداث التي يمكنه استخدامها لمواكبة ما ينشئه الوكيل، بالإضافة إلى طريقة لإرسال الرسائل إلى الوكيل.
بعد ذلك، أنشئ مستمعًا لأحداث المحادثة. وتشمل هذه الأحداث تلك المتعلّقة بالمنصات، بالإضافة إلى الأحداث المتعلّقة بالرسائل النصية والأخطاء:
@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:
}
});
});
}
أخيرًا، أنشئ طلب النظام وأرسِله إلى الوكيل:
@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()),
);
}
عدِّل أيضًا طريقة dispose() في _MyHomePageState حتى يتم تنظيف عناصر التحكّم GenUI التي تمت إضافتها حديثًا بشكلٍ صحيح عند التخلص من التطبيق المصغّر:
@override
void dispose() {
_conversation.dispose();
_transport.dispose();
_controller.dispose();
_textController.dispose();
_scrollController.dispose();
super.dispose();
}
مساحات العرض
بعد ذلك، عدِّل طريقة build في ListView لعرض SurfaceItem في قائمة _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,
),
),
},
],
),
),
يأخذ الدالة الإنشائية للأداة Surface وسيطة surfaceContext تحدّد السطح الذي تكون الأداة مسؤولة عن عرضه. يوفر SurfaceController الذي تم إنشاؤه سابقًا، _controller، التعريف والحالة لكل سطح، ويتأكّد من إعادة إنشائه عند توفّر تحديث.
ربط GenUI بـ Firebase AI Logic
تستخدم حزمة genui نهج "استخدام النموذج الخاص بك"، ما يعني أنّك تتحكّم في نموذج اللغة الكبير الذي يشغّل تجربتك. في هذه الحالة، أنت تستخدم Firebase AI Logic، ولكن تم تصميم الحزمة للعمل مع مجموعة متنوعة من البرامج الوكيلة ومقدّمي الخدمات.
تتطلّب هذه الحرية بعض المسؤولية الإضافية، إذ عليك أخذ الرسائل التي تنشئها حزمة genui وإرسالها إلى الوكيل الذي اخترته، كما عليك أخذ ردود الوكيل وإرسالها مرة أخرى إلى genui.
لإجراء ذلك، عليك تحديد طريقة _sendAndReceive المشار إليها في الرمز البرمجي للخطوة السابقة. في lib/main.dart، أضِف _sendAndReceive داخل الفئة _MyHomePageState (على سبيل المثال، بعد السطر 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!);
}
}
سيتم استدعاء هذه الطريقة من خلال حزمة genui عندما تحتاج إلى إرسال رسالة إلى الوكيل. يؤدي استدعاء addChunk في نهاية الطريقة إلى إرسال ردّ الوكيل إلى حزمة genui، ما يتيح له معالجة الردّ وإنشاء واجهة مستخدم.
أخيرًا، استبدِل طريقة _addMessage الحالية بالكامل بهذا الإصدار الجديد، وذلك لتوجيه الرسائل إلى Conversation بدلاً من 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));
}
هذا كل شيء! حاوِل تشغيل التطبيق مرة أخرى. بالإضافة إلى الرسائل النصية، سيظهر لك الوكيل وهو ينشئ مساحات في واجهة المستخدم، مثل الأزرار وأدوات النص والمزيد.
يمكنك أيضًا أن تطلب من الوكيل عرض واجهة المستخدم بطريقة معيّنة. على سبيل المثال، جرِّب رسالة مثل "أريد عرض مهامي في عمود مع زر لوضع علامة الاكتمال على كل مهمة".
5- إضافة حالة الانتظار
يتم إنشاء الردود من النموذج اللغوي الكبير بشكل غير متزامن. أثناء انتظار الردّ، يجب أن توقِف واجهة المحادثة أزرار الإدخال وتعرض مؤشر تقدّم ليعرف المستخدم أنّ GenUI ينشئ المحتوى. لحسن الحظ، توفّر حزمة genui دالة Listenable يمكنك استخدامها لتتبُّع حالة المحادثة. تتضمّن قيمة ConversationState هذه سمة isWaiting لتحديد ما إذا كان النموذج ينشئ محتوًى.
يجب تضمين عناصر التحكّم في الإدخال في ValueListenableBuilder
في طريقة build لـ _MyHomePageState في lib/main.dart، ابحث عن أداة SafeArea في أسفل Column، ثم لفّ العنصر الفرعي Row (الذي يحتوي على TextField وElevatedButton) بعنصر ValueListenableBuilder يستمع إلى _conversation.state. من خلال فحص state.isWaiting، يمكنك إيقاف الإدخال أثناء إنشاء النموذج للمحتوى:
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'),
),
],
);
},
),
),
),
إضافة شريط تقدّم
في طريقة build من _MyHomePageState، عليك تضمين التطبيق المصغّر الرئيسي Column داخل Stack، وإضافة ValueListenableBuilder يعرض LinearProgressIndicator كعنصر فرعي ثانٍ لـ Stack. عند الانتهاء، من المفترض أن يظهر body من Scaffold على النحو التالي:
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. الاحتفاظ بمساحة عرض GenUI
حتى الآن، تم عرض قائمة المهام في سلسلة المحادثات القابلة للتمرير، مع إضافة كل رسالة أو سطح جديد إلى القائمة عند وصوله. في الخطوة التالية، ستتعرّف على كيفية تسمية مساحة عرض وعرضها في مكان محدّد ضمن واجهة المستخدم.
أولاً، في أعلى lib/main.dart، قبل void main()، أعلِن عن ثابت لاستخدامه كمعرّف سطح:
const taskDisplaySurfaceId = 'task_display';
ثانيًا، في initState()، عدِّل عبارة switch في أداة معالجة Conversation للتأكّد من عدم إضافة أي مساحة عرض تحمل هذا المعرّف إلى _items. لتحقيق ذلك، عدِّل الفرع case ConversationSurfaceAdded added: داخل _conversation.events.listen من خلال تضمين السطرَين _items.add(...) و_scrollToBottom() في عبارة 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 ...
بعد ذلك، افتح بنية تنسيق شجرة التطبيقات المصغّرة في _MyHomePageState.build لإنشاء مساحة للسطح المثبَّت قبل سجلّ المحادثات مباشرةً. أدرِج AnimatedSize وconst Divider() كأول عنصرَين ثانويَين في Column الرئيسي، قبل رمز 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 ...
حتى الآن، كان لدى وكيلك حرية إنشاء مساحات العرض واستخدامها بالشكل الذي يراه مناسبًا. لتقديم تعليمات أكثر تحديدًا، عليك إعادة النظر في طلب النظام. أضِف قسم ## USER INTERFACE التالي إلى نهاية الطلب المخزّن في الثابت 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.
''';
من المهم تقديم تعليمات واضحة للوكيل حول حالات استخدام مساحات واجهة المستخدم وكيفية استخدامها. من خلال إخبار البرنامج باستعمال عنصر محدّد من الفهرس ومعرّف سطح (وإعادة استخدام مثيل واحد)، يمكنك المساعدة في التأكّد من أنّه ينشئ واجهة المستخدم التي تريد رؤيتها.
هناك المزيد من العمل الذي يجب القيام به، ولكن يمكنك محاولة تشغيل تطبيقك مرة أخرى لمعرفة كيف ينشئ الوكيل مساحة عرض المهام في أعلى واجهة المستخدم.
7. إنشاء تطبيق مصغّر مخصّص للكتالوج
في هذه المرحلة، لا يتوفّر عنصر الكتالوج "TaskDisplay". في الخطوات القليلة التالية، ستصلح ذلك من خلال إنشاء مخطط بيانات، وفئة لتحليل هذا المخطط، وأداة، وعنصر الكتالوج الذي يجمع كل شيء معًا.
أولاً، أنشئ ملفًا جديدًا باسم task_display.dart ضمن الدليل lib/ الخاص بمشروعك وأضِف عمليات الاستيراد التالية:
import 'package:flutter/material.dart';
import 'package:genui/genui.dart';
import 'package:json_schema_builder/json_schema_builder.dart';
إنشاء مخطط البيانات
بعد ذلك، حدِّد مخطط البيانات الذي سيقدّمه الوكيل عندما يريد إنشاء عرض للمهام. تستخدم هذه العملية بعض الدوال الإنشائية المتقدّمة من حزمة json_schema_builder، ولكنّك في الأساس تحدّد مخطط JSON المستخدَم في الرسائل من الوكيل وإليه.
ابدأ بـ S.object أساسي يشير إلى اسم المكوّن:
final taskDisplaySchema = S.object(
properties: {
'component': S.string(enumValues: ['TaskDisplay']),
},
);
بعد ذلك، أضِف title وtasks وname وisCompleted وcompleteAction إلى سمات المخطط.
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.',
),
},
),
),
},
);
اطّلِع على السمة completeAction. يتم إنشاؤه باستخدام A2uiSchemas.action، وهو أداة إنشاء لسمة مخطط تمثّل إجراء A2UI. من خلال إضافة إجراء إلى المخطط، يخبر التطبيق الوكيل بشكل أساسي، "عندما تعطيني مهمة، قدّم أيضًا الاسم والبيانات الوصفية لإجراء يمكنني استخدامه لإخبارك بأنّ هذه المهمة قد اكتملت". بعد ذلك، سيستدعي التطبيق هذا الإجراء عندما ينقر المستخدم على مربّع اختيار.
بعد ذلك، أضِف حقول required إلى المخطط. توجّه هذه التعليمات الوكيل لملء سمات معيّنة في كل مرة. في هذه الحالة، يجب ملء كل سمة.
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'],
);
إنشاء فئات تحليل البيانات
عند إنشاء مثيلات لهذا المكوّن، سيرسل الوكيل بيانات تطابق المخطط. أضِف فئتَين لتحليل ملف JSON الوارد إلى عناصر Dart ذات نوع قوي. لاحظ كيف يتعامل _TaskDisplayData مع بنية الجذر، بينما يفوّض تحليل الصفيف الداخلي إلى _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');
}
}
}
إذا سبق لك إنشاء تطبيقات باستخدام Flutter، من المحتمل أن تكون هذه الفئات مشابهة لتلك التي أنشأتها. وهي تقبل JsonMap وتعرض عنصرًا مكتوبًا بقوة يحتوي على بيانات تم تحليلها من JSON.
اطّلِع على الحقلَين actionName وactionContext في _TaskData. ويتم استخراجها من السمة completeAction في ملف JSON وتحتوي على اسم الإجراء وسياق بياناته (إشارة إلى موقع الإجراء في نموذج بيانات GenUI). سيتم استخدام هذه البيانات لاحقًا لإنشاء UserActionEvent.
نموذج البيانات هو مخزن مركزي يمكن تتبّعه لجميع حالات واجهة المستخدم الديناميكية، وتتم إدارته من خلال مكتبة genui. عندما ينشئ الوكيل مكوّن واجهة مستخدم من الكتالوج، ينشئ أيضًا عنصر بيانات يتطابق مع مخطط المكوّن. يتم تخزين عنصر البيانات هذا في نموذج البيانات في العميل، بحيث يمكن استخدامه لإنشاء التطبيقات المصغّرة والإشارة إليه في الرسائل اللاحقة إلى الوكيل (مثل completeAction الذي أنت على وشك ربطه بتطبيق مصغّر).
إضافة التطبيق المصغّر
الآن، أنشئ تطبيق مصغّر لعرض القائمة. ويجب أن تقبل مثيلاً من فئة _TaskDisplayData ودالة ردّ نداء لاستدعائها عند اكتمال مهمة.
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);
}
},
),
),
],
);
}
}
إنشاء CatalogItem
بعد إنشاء المخطط والمحلّل اللغوي والتطبيق المصغّر، يمكنك الآن إنشاء CatalogItem لربطها معًا.
في أسفل task_display.dart، أنشئ taskDisplay كمتغيّر على أعلى مستوى، واستخدِم _TaskDisplayData لتحليل JSON الوارد، وأنشئ مثيلاً للأداة _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!
},
);
},
);
تنفيذ onCompleteTask
لكي يعمل التطبيق المصغّر، يجب أن يتواصل مع الوكيل عند اكتمال المهمة. استبدِل العنصر النائب الفارغ onCompleteTask بالرمز التالي لإنشاء حدث وإرساله باستخدام completeAction من بيانات المهمة.
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,
),
);
}
تسجيل عنصر في الكتالوج
أخيرًا، افتح main.dart واستورِد الملف الجديد وسجِّله مع عناصر الكتالوج الأخرى.
أضِف عملية الاستيراد هذه إلى أعلى lib/main.dart:
import 'task_display.dart';
استبدِل catalog = BasicCatalogItems.asCatalog(); في دالة initState() بما يلي:
// 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]);
لقد أنهيت عملك! أعِد تشغيل التطبيق بسرعة للاطّلاع على التغييرات.
8. جرِّب طرقًا مختلفة للتفاعل مع الوكيل

بعد إضافة التطبيق المصغّر الجديد إلى "الكتالوج" وتخصيص مساحة له في واجهة مستخدم التطبيق، حان الوقت للاستمتاع بالعمل مع الوكيل. من المزايا الرئيسية لواجهة GenUI أنّها توفّر طريقتَين للتفاعل مع بياناتك: من خلال واجهة مستخدم التطبيق، مثل الأزرار ومربّعات الاختيار، ومن خلال وكيل يفهم اللغة الطبيعية ويمكنه تحليل البيانات. ننصحك بتجربة كليهما.
- استخدِم حقل النص لوصف ثلاث أو أربع مهام، وشاهِدها تظهر في القائمة.
- استخدِم مربّع اختيار لتبديل حالة مهمة إلى "مكتملة" أو "غير مكتملة".
- أنشئ قائمة تضم 5 أو 6 مهام، ثم اطلب من الوكيل إزالة المهام التي تتطلّب منك القيادة إلى مكان ما.
- اطلب من الوكيل إنشاء قائمة مهام متكررة كعناصر فردية ("أريد شراء بطاقة معايدة لأمي وأبي وجدتي. أنشئ مهامًا منفصلة لتلك المهام").
- اطلب من الوكيل وضع علامة على جميع المهام على أنّها مكتملة أو غير مكتملة، أو وضع علامة على أول مهمتَين أو ثلاث مهام.
9. تهانينا
تهانينا! لقد أنشأت تطبيقًا لتتبُّع المهام مستندًا إلى الذكاء الاصطناعي باستخدام واجهة المستخدم التوليدية وFlutter.
ما تعلّمته
- التفاعل مع النماذج الأساسية من Google باستخدام حزمة تطوير البرامج (SDK) لمنصّة Flutter Firebase
- عرض مساحات تفاعلية من إنشاء Gemini باستخدام GenUI
- تثبيت المساحات في التنسيقات باستخدام معرّفات العرض الثابت المحدّدة مسبقًا
- تصميم مخططات مخصّصة وكتالوجات تطبيقات مصغّرة لإنشاء حلقات تفاعل قوية