צוללים לתבניות ולרשומות של Dart

1. מבוא

ב-Dart 3 נוספו דפוסים לשפה, קטגוריה חשובה של דקדוק. מעבר לדרך הזו לכתיבת קוד Dart, ‏Dart 3 כוללת כמה שיפורים נוספים בשפה:

  • רשומות לאיסוף נתונים מסוגים שונים.
  • מגדירי מחלקות (כמו sealed) לשליטה בגישה ולהפעלת בדיקת מיצוי.
  • ביטויי switch, הצהרות if-case וסעיפי guard משופרים.

התכונות האלה מרחיבות את האפשרויות שלכם כשאתם כותבים קוד Dart. ב-Codelab הזה, אתם משתפים פעולה עם Google Antigravity כדי ללמוד איך להשתמש בהם כדי להפוך את הקוד שלכם לקומפקטי, יעיל וגמיש יותר.

מה תפתחו

ב-Codelab הזה תשתפו פעולה עם Google Antigravity כדי ליצור אפליקציה שמציגה מסמך JSON מובנה ב-Flutter. האפליקציה מדמה קובץ JSON שמגיע ממקור חיצוני ומכיל מטא-נתונים של מסמכים (כותרת ותאריך שינוי) ובלוקים של תוכן (כותרות, פסקאות ותיבות סימון של משימות).

תנחו את Antigravity לארוז נתונים ברשומות כדי שיהיה אפשר להעביר ולפרוק אותם בכל מקום שבו הווידג'טים של Flutter צריכים אותם, תשתמשו בתבניות כדי לאמת ולפרק נתוני JSON למשתנים מקומיים, ותתאימו בין ביטויי switch לבין מחלקות sealed כדי ליצור את הווידג'ט המתאים לכל בלוק תוכן.

האפליקציה הסופית שתיצרו ב-Codelab הזה, שבה מוצג מסמך עם כותרת, תאריך שינוי יחסי, כותרות, פסקאות ותיבת סימון

תהליך הלמידה שלך

בשיעור ה-Codelab הזה תלמדו איך ליצור את הכלי לצפייה במסמכים, שלב אחרי שלב:

  1. הגדרת סביבת Flutter – מגדירים את Flutter SDK ואת Google Antigravity לפלטפורמת היעד.
  2. יצירת פרויקט – הנחיה ל-Antigravity ליצור פיגומים ל-patterns_codelab עם נתוני JSON מדומים ב-lib/data.dart ו-DocumentScreen למתחילים ב-lib/main.dart.
  3. יצירה והחזרה של רשומות – החזרת כמה ערכים מסוגים שונים מ-getter באמצעות רשומה וקריאת השדות הממוקמים והשדות בעלי השמות.
  4. התאמה ופירוק באמצעות תבניות – פירוק שדות של רשומות ישירות למשתנים מקומיים באמצעות הצהרה על משתנה תבנית וקיצור שדה.
  5. שימוש בתבניות לחילוץ נתונים – אימות וחילוץ של ערכי JSON בתצוגת עץ באופן בטוח באמצעות תבניות מפה if-case שניתנות להפרכה.
  6. הכנת האפליקציה לתבניות נוספות – ניתוח מערך JSON למופעים של Block באמצעות תבניות מפה וליטרל של רשימת collection-for.
  7. שימוש בתבניות להצגת המסמך – עיבוד של פריטי Block בממשק המשתמש באמצעות הצהרות switch משופרות עם תבניות logical-or ותבניות של תווים כלליים לחיפוש.
  8. שימוש בביטויי switch – המרת ההצהרה switch לביטוי switch תמציתי שמחזיר ערך ישירות.
  9. שימוש בתבניות של אובייקטים – התאמה למאפיינים של Duration והחלת משפטי תנאי של when כדי ליצור פורמט של תאריכים יחסיים שקריאים לאנשים.
  10. הגדרת מחלקה כ-sealed כדי לאפשר החלפה ממצה – משנים את הקוד של Block להיררכיית מחלקות sealed כדי שהמנתח של Dart יאכוף החלפה ממצה בכל סוג משנה של בלוק.

מה תלמדו

  • איך לעבוד עם Google Antigravity כדי ליצור ולהתאים אישית צופה מסמכים ב-Flutter באמצעות תכונות השפה של Dart 3.
  • איך יוצרים רשומה שמאחסנת ומחזירה כמה ערכים מסוגים שונים.
  • איך להשתמש בתבניות כדי להתאים, לאמת ולפרק נתונים מרשומות, ממפות ומאובייקטים.
  • איך לקשר ערכים שתואמים לתבנית למשתנים מקומיים חדשים.
  • איך להשתמש ביכולות המשופרות של הצהרות switch, ביטויי switch, תנאי הגנה (when) והצהרות if-case.
  • איך לנצל את בדיקת המקיפות עם מחלקות sealed כדי לוודא שכל מקרה מטופל בהצהרת switch או בביטוי switch.

דרישות מוקדמות

ב-Codelab הזה אנחנו מניחים שאתם מכירים קצת את Flutter ו-Dart. אם אתם מרגישים שאתם צריכים קצת עזרה, כדאי להיעזר במקורות המידע הבאים כדי לרענן את הידע הבסיסי:

2. הגדרת סביבת Flutter

עריכה

ב-Codelab הזה נשתמש ב-Google Antigravity כסביבת הפיתוח שמתמקדת ב-AI. בכל שלב, אתם מנחים את Antigravity ליצור או לפתח את רכיבי האפליקציה, בודקים את המושגים העיקריים של תבניות ורשומות ב-Dart 3 בקוד שנוצר, ואם רוצים, בוחנים וריאציות.

התקנת Flutter

ההוראות העדכניות ביותר להתקנת Flutter SDK מופיעות תמיד בכתובת docs.flutter.dev.

כדי להשתמש ב-Codelab הזה, צריך להתקין את התוכנות הבאות:

  1. Flutter SDK
  2. ‫Google Antigravity עם הפלאגין הרשמי של Dart ו-Flutter מופעל (זמין ב-Plugin Marketplace בקטע פיתוח פתרונות עם Google).
  3. תוכנת קומפיילר ליעד הפיתוח שבחרתם (לדוגמה, Visual Studio ליעד Windows,‏ Xcode ליעד macOS או iOS, או Chrome ליעד אינטרנט).

כדי לוודא שהסביבה מוגדרת ליעד הפריסה שבחרתם, מריצים את הפקודה flutter doctor:

flutter doctor

3. יצירת פרויקט

לפני שנתחיל לעבוד עם תבניות, רשומות ותכונות אחרות של Dart 3, נבקש מ-Antigravity ליצור פרויקט Flutter עם שני קובצי Dart שנפתח במהלך ה-Codelab הזה:

  • lib/data.dart, שמכיל את מסמך ה-JSON המדומה ואת מחלקת הנתונים Document.
  • ‫lib/main.dart, שמכיל את הווידג'טים של Flutter שמעבדים את המסמך.

מזינים הנחיה ל-Antigravity כדי ליצור את הפרויקט

  1. מפעילים את Google Antigravity ופותחים ספרייה ריקה שבה רוצים ליצור את הפרויקט (בוחרים נתיב שלא דורש הרשאות מורחבות או מכיל רווחים, כמו תיקייה בספריית הבית או C:\src\).
  2. בחלונית הצ'אט של סוכן Antigravity, שולחים את ההנחיה הבאה כדי ליצור את פרויקט Flutter ולהגדיר את lib/data.dart ו-lib/main.dart:
Create a new empty Flutter project named `patterns_codelab` with a minimum Dart SDK constraint of `^3.0.0`, and add the `material_ui` package. Create `lib/data.dart` with a `Document` class that decodes a multi-line `documentJson` constant (containing a `"metadata"` object with `"title": "My Document"` and `"modified": "2023-05-10"`, and a `"blocks"` list with an `"h1"` header `"Section 1"`, a `"p"` paragraph `"Lorem ipsum dolor sit amet, consectetur adipiscing elit."`, and an unchecked `"checkbox"` `"Learn Dart 3"`) into a `final Map<String, Object?> _json` field. Then update `lib/main.dart` (importing `package:material_ui/material_ui.dart`) to run a `DocumentApp` widget whose home is `DocumentScreen(document: Document())`, rendering a `Scaffold` with placeholder `'Title goes here'` and `'Body goes here'` text.

הסבר על הקוד שנוצר

גרסת ה-SDK המינימלית ב-pubspec.yaml

העברת הדגל --empty אל flutter create יוצרת פרויקט Flutter מינימלי בלי קוד התבנית של אפליקציית ברירת המחדל של המונה. בקובץ pubspec.yaml, האילוץ של גרסת ה-SDK מציין את Dart 3 ואילך באמצעות תחביר של סימן קארט:

environment:
  sdk: ^3.0.0

הדמיה של JSON נכנס ב-lib/data.dart

דמיינו תוכנה שמקבלת נתונים ממקור חיצוני, כמו זרימת קלט/פלט (I/O) או בקשת HTTP. ב-lib/data.dart, documentJson מדמה את המטען הייעודי (payload) של ה-JSON הנכנס באמצעות מחרוזת מרובת שורות, וה-constructor של Document מנתח אותו ל-_json באמצעות jsonDecode:

import 'dart:convert';

class Document {
  final Map<String, Object?> _json;
  Document() : _json = jsonDecode(documentJson);
}

פיגומים DocumentApp ו-DocumentScreen ב-lib/main.dart

ב-lib/main.dart, ‏Antigravity מגדיר שני ווידג'טים ללא שמירת מצב:

  • ‫DocumentApp מגדיר את Material Design‏ (package:material_ui/material_ui.dart) כדי ליצור עיצוב לממשק המשתמש.
  • ‫DocumentScreen מספק את הפריסה החזותית של הדף באמצעות הווידג'ט של Scaffold:
class DocumentScreen extends StatelessWidget {
  final Document document;

  const DocumentScreen({required this.document, super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Title goes here')),
      body: const Column(children: [Center(child: Text('Body goes here'))]),
    );
  }
}

הפעלה ובדיקה של האפליקציה

מפעילים את האפליקציה בפלטפורמת היעד שבחרתם (למשל: Chrome,‏ macOS,‏ Windows,‏ Linux,‏ iOS או Android). אמור להופיע מסגרת של אפליקציה עם הטקסט של הפלייסהולדר title ו-body שמוגדר ב-DocumentScreen:

אפליקציית ההתחלה שבה מוצג &quot;הכותרת תופיע כאן&quot; בסרגל האפליקציה ו&quot;גוף הטקסט יופיע כאן&quot; בגוף הטקסט

4. יצירה והחזרה של רשומות

בשלב הזה, משתמשים ברשומה כדי להחזיר כמה ערכים מקריאת getter אחת, ואז ניגשים לשדות של הרשומה ב-DocumentScreen כדי להציג אותם בממשק המשתמש.

מבקשים מ-Antigravity להחזיר ולקרוא רשומה

שלחו את ההנחיה הבאה ב-Antigravity:

In `lib/data.dart`, add a `metadata` getter to `Document` with return type `(String, {DateTime modified})` that returns a hardcoded record `('My Document', modified: DateTime.now())`. In `lib/main.dart`, call `document.metadata` inside `DocumentScreen.build`, display the positional title field (`metadataRecord.$1`) in the `AppBar`, and display `'Last modified ${metadataRecord.modified}'` in the body.

הסבר על הקוד שנוצר

החזרת רשומה מ-Document.metadata

ב-lib/data.dart, ה-getter של metadata מחזיר רשומה עם שני שדות – אחד מסוג String והשני מסוג DateTime:

  (String, {DateTime modified}) get metadata {
    const title = 'My Document';
    final now = DateTime.now();

    return (title, modified: now);
  }

פקודת החזרה יוצרת רשומה חדשה על ידי הוספת שני הערכים בסוגריים: (title, modified: now). השדה הראשון הוא מיקומי וללא שם, והשדה השני נקרא modified.

גישה לשדות של רשומות לפי מיקום ולפי שם

ב-lib/main.dart, הפונקציה DocumentScreen.build מקצה את document.metadata ל-metadataRecord וקוראת את השדות שלו באמצעות פונקציות getter מובנות של רשומות:

  @override
  Widget build(BuildContext context) {
    final metadataRecord = document.metadata;

    return Scaffold(
      appBar: AppBar(title: Text(metadataRecord.$1)),
      body: Column(
        children: [
          Center(child: Text('Last modified ${metadataRecord.modified}')),
        ],
      ),
    );
  }
  • כדי לקבל שדה מיקום (שדה בלי שם, כמו title), משתמשים ב-getter $ ברשומה (החל מ-$1 ומדלגים על שדות עם שם).
  • לשדות בעלי שם כמו modified אין פונקציית getter לפי מיקום. אפשר לגשת אליהם ישירות לפי שם השדה, כמו metadataRecord.modified.

לדוגמה, ברשומה שמשלבת שדות עם שם ושדות לפי מיקום, פונקציות ה-getter לפי מיקום ממספרות רק את השדות ללא שם:

var record = (named: 'v', 'y', named2: 'x', 'z');
print(record.$1); // prints y
print(record.$2); // prints z

כל שדה ברשומה שומר על הסוג הסטטי שלו: Text() מקבל את metadataRecord.$1 בתור String, ו-metadataRecord.modified הוא DateTime שמומר ל-String באמצעות אינטרפולציה של מחרוזות.

הפעלה ובדיקה של האפליקציה

מבצעים Hot Reload לאפליקציה כדי לראות את הכותרת ואת חותמת הזמן הנוכחית שמוצגת במסך:

האפליקציה מציגה את &quot;המסמך שלי&quot; בסרגל האפליקציה ואת חותמת הזמן של השינוי האחרון בגוף המסמך

5. התאמה ופירוק מבנה באמצעות תבניות

רשומות יכולות לאסוף ביעילות סוגים שונים של נתונים ולהעביר אותם. עכשיו תשפרו את הקוד ב-DocumentScreen באמצעות תבניות.

תבנית מייצגת מבנה שערך אחד או יותר יכולים לקבל, כמו תוכנית. התבניות מושוות לערכים בפועל כדי לקבוע אם יש התאמה. כשיש התאמה לתבנית, אפשר לפרק את הערך התואם על ידי שליפת נתונים ממנו וקישור הערכים האלה למשתנים מקומיים.

מבקשים מ-Antigravity לפרק את הרשומה

שלחו את ההנחיה הבאה ב-Antigravity:

Refactor `DocumentScreen.build` in `lib/main.dart` to destructure `document.metadata` directly into local `title` and `modified` variables using the record pattern shorthand `final (title, :modified) = document.metadata;`, and use `title` and `modified` in the `AppBar` and body `Text` widgets.

הסבר על הקוד שנוצר

פירוק רשומה למשתנים מקומיים

במקום לאחסן את הרשומה במשתנה זמני ולקרוא את $1 ו-.modified, אפשר להפעיל הצהרה על משתנה תבנית:

  @override
  Widget build(BuildContext context) {
    final (title, :modified) = document.metadata;

    return Scaffold(
      appBar: AppBar(title: Text(title)),
      body: Column(children: [Center(child: Text('Last modified $modified'))]),
    );
  }

תבנית הרשומה (title, :modified) (שהיא קיצור של (title, modified: modified)) מכילה שתי תבניות משתנים שתואמות לשדות של הרשומה שמוחזרת על ידי metadata:

  • הביטוי תואם לתבנית כי התוצאה היא רשומה עם שני שדות, אחד לפי מיקום ואחד בשם modified.
  • בגלל שהם תואמים, תבנית הצהרת המשתנה מפרקת את הביטוי, ניגשת לערכים שלו ומקשרת אותם למשתנים מקומיים חדשים עם אותם סוגים ושמות: String title ו-DateTime modified.
  • כשהשם של שדה בעל שם והמשתנה שמאכלס אותו זהים, :modified הוא קיצור של modified: modified. אם רוצים משתנה מקומי עם שם אחר, אפשר לכתוב במקום זאת modified: localModified.

הפעלה ובדיקה של האפליקציה

מבצעים Hot Reload לאפליקציה כדי לוודא שהתוצאה זהה לשלב הקודם, ועכשיו היא כתובה בקוד תמציתי וקריא יותר.

6. שימוש בתבניות לחילוץ נתונים

בהקשרים מסוימים, תבניות לא רק מתאימות ומפרקות – הן יכולות גם לקבל החלטה לגבי מה שהקוד עושה על סמך השאלה אם התבנית מתאימה או לא. התבניות האלה נקראות תבניות שניתנות להפרכה.

תבנית הצהרת המשתנה שהשתמשתם בה בשלב הקודם היא תבנית שאי אפשר להפריך: הערך חייב להתאים לתבנית, אחרת תהיה שגיאה בזמן הקימפול, והפירוק לא יקרה (בדיוק כמו שאי אפשר להקצות ערך למשתנה מסוג אחר).

תבניות שניתנות להפרכה, לעומת זאת, משמשות בהקשרים של זרימת בקרה:

  • הם מצפים שחלק מהערכים שהם משווים לא יהיו זהים.
  • הם נועדו להשפיע על זרימת הבקרה, על סמך השאלה אם הערך תואם או לא.
  • הם לא קוטעים את ההפעלה עם שגיאה אם אין התאמה, אלא פשוט עוברים להצהרה או להסתעפות הבאה.
  • הם יכולים לפרק ולחבר משתנים שניתן להשתמש בהם רק בהסתעפות שבה הם תואמים.

הנחיה ל-Antigravity לנתח מטא-נתונים באמצעות תבנית מפה

שלחו את ההנחיה הבאה ב-Antigravity:

Update the `metadata` getter in `lib/data.dart` to read and validate the JSON structure using an `if-case` map pattern (`if (_json case {'metadata': {'title': String title, 'modified': String localModified}})`) that returns `(title, modified: DateTime.parse(localModified))` and throws a `FormatException('Unexpected JSON')` otherwise.

הסבר על הקוד שנוצר

השוואה בין אימות ידני של קובץ JSON לבין תבניות של מפות

בלי התאמת דפוסים, כדי לקרוא ולאמת ערכים בתצוגת עץ מ-_json צריך לבצע כמה בדיקות בתצוגת עץ והמרות סוגים מפורשות:

  (String, {DateTime modified}) get metadata {
    if (_json.containsKey('metadata')) {
      final metadataJson = _json['metadata'];
      if (metadataJson is Map) {
        final title = metadataJson['title'] as String;
        final localModified = DateTime.parse(
          metadataJson['modified'] as String,
        );
        return (title, modified: localModified);
      }
    }
    throw const FormatException('Unexpected JSON');
  }

בעזרת תבנית מפה שניתנת להפרכה בתוך הצהרת if-case (שהוצגה ב-Dart 3), אתם יכולים לוודא של-JSON יש את המבנה הצפוי ולחלץ את הערכים בשלב אחד:

  (String, {DateTime modified}) get metadata {
    if (_json case {
      'metadata': {'title': String title, 'modified': String localModified},
    }) {
      return (title, modified: DateTime.parse(localModified));
    } else {
      throw const FormatException('Unexpected JSON');
    }
  }

הגוף של case מופעל רק אם התבנית של המפה תואמת לנתונים ב-_json. התבנית הזו מאמתת את הדברים הבאים:

  • ‫_json הוא מסוג Map ולא null.
  • ‫_json מכיל מפתח 'metadata'.
  • ‫_json['metadata'] הוא גם סוג Map שאינו null.
  • ‫_json['metadata'] מכיל את המפתחות 'title' ו-'modified'.
  • ‫title ו-localModified הם ערכי String שאינם null.

אם הערך לא תואם לאף אחד מהתנאים האלה, התבנית דוחה את ההתאמה והביצוע ממשיך לסעיף else. אם ההתאמה מצליחה, התבנית מפרקת את המחרוזות title ו-modified מהמפה ומקשרת אותן למשתנים מקומיים חדשים.

הרשימה המלאה של התבניות מופיעה במאמרי העזרה בנושא תבניות באתר dart.dev.

הפעלה ובדיקה של האפליקציה

מבצעים Hot Reload לאפליקציה. חותמת הזמן של Last modified משקפת עכשיו את "2023-05-10" מ-documentJson במקום את DateTime.now(), והאזהרה unused_field ב-_json נעלמה.

7. הכנת האפליקציה לתבניות נוספות

עד עכשיו טיפלתם בחלק metadata של נתוני ה-JSON. בשלב הזה, תוסיפו מחלקה מסוג Block ו-method מסוג getBlocks() ב-lib/data.dart כדי לנתח את הרשימה blocks מ-documentJson, כך שתוכלו להציג אותה בממשק המשתמש.

מבקשים מ-Antigravity לנתח את הרשימה blocks

שלחו את ההנחיה הבאה ב-Antigravity:

In `lib/data.dart`, add a `Block` class with `final String type` and `final String text` fields and a `factory Block.fromJson(Map<String, dynamic> json)` constructor that uses an `if-case` map pattern (`{'type': final type, 'text': final text}`) to return a `Block` or throw a `FormatException('Unexpected JSON format')`. Then add a `List<Block> getBlocks()` method to `Document` that matches `_json` against `{'blocks': List blocksJson}` and returns `[for (final blockJson in blocksJson) Block.fromJson(blockJson)]` (or throws a `FormatException('Unexpected JSON format')`).

הסבר על הקוד שנוצר

התעלמות ממפתחות נוספים בתבניות של מפות (Block.fromJson)

ב-lib/data.dart, ה-factory constructor של Block.fromJson() משתמש בהצהרת if-case עם תבנית מפה כדי לחלץ את 'type' ו-'text':

class Block {
  final String type;
  final String text;
  Block(this.type, this.text);

  factory Block.fromJson(Map<String, dynamic> json) {
    if (json case {'type': final type, 'text': final text}) {
      return Block(type, text);
    } else {
      throw const FormatException('Unexpected JSON format');
    }
  }
}

שימו לב שהבלוק השלישי ב-documentJson ("type": "checkbox") כולל גם מפתח "checked": false שלא מוזכר בתבנית. תבניות של מפות עדיין תואמות גם כשהמפה מכילה מפתחות נוספים שלא מופיעים בתבנית – הן מאמתות ומחלצות את המפתחות שציינתם ומתעלמות מכל רשומה נוספת במפה.

מתבצע חילוץ של הרשימה בDocument.getBlocks

ב-Document, ה-method‏ getBlocks() מאמתת ש-_json מכיל רשימת 'blocks' ויוצרת List:

  List<Block> getBlocks() {
    if (_json case {'blocks': List blocksJson}) {
      return [for (final blockJson in blocksJson) Block.fromJson(blockJson)];
    } else {
      throw const FormatException('Unexpected JSON format');
    }
  }

ההצהרה if-case מאמתת ש-_json['blocks'] הוא List ומקשרת אותו ל-blocksJson (בלי תבניות, צריך המרה מפורשת או toList()). בתוך הליטרל של הרשימה, אוסף for מבצע איטרציה על blocksJson כדי ליצור את רשימת האובייקטים של Block.

הפעלה ובדיקה של האפליקציה

מבצעים Hot Reload לאפליקציה כדי לוודא שאין שגיאות בניתוח או שגיאות זמן ריצה. בשלב הבא, תציגו את הפריטים המנותחים של Block במסך.

8. שימוש בתבניות להצגת המסמך

השתמשתם בהצהרות if-case ובתבניות שניתנות להפרכה כדי לפרק ולהרכיב מחדש את נתוני ה-JSON. עכשיו תיישמו תבניות שניתנות להפרכה על הצהרות switch כדי לעצב ולעבד כל Block ב-lib/main.dart.

מבקשים מ-Antigravity לעבד את הבלוקים של המסמך

שלחו את ההנחיה הבאה ב-Antigravity:

In `lib/main.dart`, create a `BlockWidget` `StatelessWidget` that takes a `required Block block` and uses a `switch` statement on `block.type` to assign `textStyle` (`displayMedium` for `'h1'`, `bodyMedium` for `'p' || 'checkbox'`, and `bodySmall` for the wildcard `_`), rendering `Text(block.text, style: textStyle)` inside an 8px-margin `Container`. Then update `DocumentScreen.build` to call `document.getBlocks()` and display `'Last modified: $modified'` above an `Expanded` `ListView.builder` that renders a `BlockWidget` for each block.

הסבר על הקוד שנוצר

התאמת דפוסים בהצהרות switch

ב-lib/main.dart, BlockWidget.build מפעיל את block.type באמצעות שלוש תכונות של דפוסים:

class BlockWidget extends StatelessWidget {
  final Block block;

  const BlockWidget({required this.block, super.key});

  @override
  Widget build(BuildContext context) {
    TextStyle? textStyle;
    switch (block.type) {
      case 'h1':
        textStyle = Theme.of(context).textTheme.displayMedium;
      case 'p' || 'checkbox':
        textStyle = Theme.of(context).textTheme.bodyMedium;
      case _:
        textStyle = Theme.of(context).textTheme.bodySmall;
    }

    return Container(
      margin: const EdgeInsets.all(8),
      child: Text(block.text, style: textStyle),
    );
  }
}
  1. תבנית מחרוזת קבועה (case 'h1':): התאמה אם block.type שווה לקבוע 'h1'.
  2. תבנית OR לוגית (case 'p' || 'checkbox':): התאמה אם block.type תואם לאחת מתבניות המשנה 'p' או 'checkbox'. (יש גם תמיכה בתבניות AND לוגיות באמצעות &&).
  3. תבנית של תו כללי לחיפוש (case _:): התאמה לכל ערך בלי לקשר משתנה. בהצהרת switch, ‏case _: מתנהג כמו פסוקית default: (שעדיין מותרת, רק קצת יותר מילולית), ואפשר להשתמש בו גם בכל הקשר של תבנית – כמו var (title, _) = document.metadata; כדי למחוק את שדה הרשומה השני.

הצגת רשימת החסימה בDocumentScreen

ב-DocumentScreen.build, קריאה ל-document.getBlocks() מאכלסת Expanded ListView.builder שיוצר BlockWidget לכל פריט:

    final (title, :modified) = document.metadata;
    final blocks = document.getBlocks();

    return Scaffold(
      appBar: AppBar(title: Text(title)),
      body: Column(
        children: [
          Text('Last modified: $modified'),
          Expanded(
            child: ListView.builder(
              itemCount: blocks.length,
              itemBuilder: (context, index) {
                return BlockWidget(block: blocks[index]);
              },
            ),
          ),
        ],
      ),
    );

הפעלה ובדיקה של האפליקציה

מבצעים Hot Reload לאפליקציה כדי לראות את הבלוקים מ-documentJson מוצגים במסך:

האפליקציה מציגה את כותרת המסמך, את טקסט הפסקה ואת הטקסט &quot;Learn Dart 3&quot; מהקטע blocks של נתוני ה-JSON

9. שימוש בביטויי מתג

תבניות מוסיפות יכולות הבעה ל-switch ול-case. כדי שיהיה אפשר להשתמש בהם במקומות נוספים – כמו מאתחלי משתנים, פקודות חזרה ועצי ווידג'טים – ב-Dart 3 יש ביטויי switch, שמעריכים סדרה של מקרים של תבניות ומפיקים ערך באופן ישיר.

מבקשים מ-Antigravity להמיר לביטוי switch

שלחו את ההנחיה הבאה ב-Antigravity:

Refactor `BlockWidget.build` in `lib/main.dart` to replace the `switch` statement on `block.type` with a `switch` expression that assigns `textStyle` directly.

הסבר על הקוד שנוצר

תחביר הביטויים של switch

ב-lib/main.dart, BlockWidget.build מקצה עכשיו את textStyle ישירות מביטוי switch:

  @override
  Widget build(BuildContext context) {
    final textStyle = switch (block.type) {
      'h1' => Theme.of(context).textTheme.displayMedium,
      'p' || 'checkbox' => Theme.of(context).textTheme.bodyMedium,
      _ => Theme.of(context).textTheme.bodySmall,
    };

    return Container(
      margin: const EdgeInsets.all(8),
      child: Text(block.text, style: textStyle),
    );
  }

ביטוי switch דומה להצהרת switch, עם שלושה הבדלים בתחביר:

  • היא משמיטה את מילת המפתח case לפני כל תבנית.
  • הוא משתמש ב-=> במקום ב-: כדי להפריד בין כל תבנית לבין גוף הביטוי שלה.
  • הוא מפריד בין מקרים באמצעות פסיקים (,) ואפשר להשתמש בו בכל מקום שבו צפוי ביטוי.

הפעלה ובדיקה של האפליקציה

מבצעים Hot Reload לאפליקציה כדי לוודא שבלוקי המסמכים ממשיכים להופיע עם סגנונות הטקסט הצפויים.

10. שימוש בתבניות של אובייקטים

‫Dart היא שפה מונחית עצמים, והתבניות חלות על כל האובייקטים של Dart. בשלב הזה, תתאימו לתבניות של אובייקטים ותפרקו את ה-getters של האובייקטים – בשילוב עם when guard clauses – כדי להציג תאריך שינוי יחסי שקריא לאנשים (כמו "today",‏ "yesterday" או "2 weeks ago").

הנחיה ל-Antigravity לעצב תאריכים יחסיים באמצעות תבניות אובייקטים

שלחו את ההנחיה הבאה ב-Antigravity:

Add a `String formatDate(DateTime dateTime)` function in `lib/main.dart` that computes `final difference = dateTime.difference(DateTime.now())` and returns a `switch` expression matching `Duration` object patterns: `'today'` for `0` days, `'tomorrow'` for `1` day, `'yesterday'` for `-1` days, `'${days ~/ 7} weeks from now'` when `days > 7`, `'${days.abs() ~/ 7} weeks ago'` when `days < -7`, `'${days.abs()} days ago'` when `isNegative: true`, and `'$days days from now'` for any remaining `Duration(inDays: final days)`. Update `DocumentScreen.build` to format `modified` with `formatDate(modified)` and display `'Last modified: $formattedModifiedDate'`.

הסבר על הקוד שנוצר

פירוק של פונקציות getter באמצעות תבניות אובייקטים של Duration

ב-lib/main.dart, formatDate מחשב את Duration בין dateTime ל-DateTime.now() ומפעיל את difference:

String formatDate(DateTime dateTime) {
  final today = DateTime.now();
  final difference = dateTime.difference(today);

  return switch (difference) {
    Duration(inDays: 0) => 'today',
    Duration(inDays: 1) => 'tomorrow',
    Duration(inDays: -1) => 'yesterday',
    Duration(inDays: final days) when days > 7 => '${days ~/ 7} weeks from now',
    Duration(inDays: final days) when days < -7 =>
      '${days.abs() ~/ 7} weeks ago',
    Duration(inDays: final days, isNegative: true) => '${days.abs()} days ago',
    Duration(inDays: final days) => '$days days from now',
  };
}

למרות ש-Duration(inDays: ...) נראה כמו קריאה ל-constructor, בהקשר של תבנית הוא תבנית אובייקט שמאמתת שהערך הוא Duration וקוראת ל-getters של inDays ו-isNegative ב-difference:

  • בשלושת המקרים הראשונים נעשה שימוש בתבניות משנה קבועות (0,‏ 1 ו--1) כדי להתאים ל-difference.inDays ולהחזיר את 'today',‏ 'tomorrow' או 'yesterday'.
  • שני המקרים האחרונים מטפלים במשכי זמן של יותר מיום אחד על ידי קישור של inDays ל-final days: אם isNegative תואם לקבוע הבוליאני true, התאריך הוא בעבר ('${days.abs()} days ago'). אחרת, המקרה שנותר תופס משכי זמן חיוביים ('$days days from now').

סינון התאמות באמצעות when תנאי הגנה

כדי לעצב טווחי זמן ארוכים מ-7 ימים כשבועות, שני המקרים האמצעיים מוסיפים סעיפי הגנה:

    Duration(inDays: final days) when days > 7 => '${days ~/ 7} weeks from now',
    Duration(inDays: final days) when days < -7 =>
      '${days.abs() ~/ 7} weeks ago',
  • סעיף הגנה משתמש במילת המפתח when אחרי תבנית case, ואפשר להשתמש בו בהצהרות if-case, בהצהרות switch ובביטויי switch.
  • היא בודקת תנאי בוליאני שרירותי אחרי שהתבנית תואמת וקושרת את המשתנים שלה (days).
  • אם הערך של ביטוי ה-guard הוא false, התבנית נדחית וההרצה עוברת ל-case הבא במקום לצאת מה-switch.

הפעלה ובדיקה של האפליקציה

מבצעים Hot Reload לאפליקציה כדי לראות את תאריך השינוי היחסי בפורמט ב-DocumentScreen (נסו לשנות את "modified" ב-documentJson לתאריך מלפני שבועיים כדי לראות את "Last modified: 2 weeks ago"):

האפליקציה מציגה תאריך שינוי יחסי באמצעות הפונקציה formatDate

11. איטום מחלקה למעבר ממצה

שימו לב שבשלב הקודם, לא היה צורך בתו כללי לחיפוש (_) בסוף של formatDate כי Duration(inDays: final days) מתייחס לכל ערך אפשרי של Duration. כשמטפלים בכל ערך אפשרי ב-switch, זה נקרא exhaustive switch.

ב-Dart 3, משתנה המחלקה sealed מרחיב את בדיקת המקיפות להיררכיות של מחלקות. בשלב האחרון הזה, תבצעו ארגון קוד מחדש של Block למחלקה ראשית sealed עם שלוש מחלקות משנה (HeaderBlock,‏ ParagraphBlock ו-CheckboxBlock) ותשתמשו בביטוי switch ממצה ב-BlockWidget כדי להציג כל סוג בלוק – כולל שורת Checkbox אינטראקטיבית ל-CheckboxBlock.

מבקשים מ-Antigravity לאטום את Block ולעבד את כל סוגי המשנה של הבלוקים

שלחו את ההנחיה הבאה ב-Antigravity:

In `lib/data.dart`, refactor `Block` into a `sealed class Block` with three subclasses (`HeaderBlock(this.text)`, `ParagraphBlock(this.text)`, and `CheckboxBlock(this.text, this.isChecked)`) and replace `Block.fromJson` (`Map<String, Object?> json`) with a `switch` expression matching map patterns for `'h1'`, `'p'`, and `'checkbox'`. Then update `BlockWidget.build` in `lib/main.dart` to use an exhaustive `switch (block)` expression directly as the `Container`'s `child`, destructuring `HeaderBlock(:final text)`, `ParagraphBlock(:final text)`, and `CheckboxBlock(:final text, :final isChecked)` (rendering a `Row` with a `Checkbox` and `Text` for `CheckboxBlock`).

הסבר על הקוד שנוצר

בניית מודל של היררכיית מחלקות ב-sealed ב-lib/data.dart

ב-lib/data.dart, Block מסומן באמצעות משנה המחלקה sealed ומורחב על ידי HeaderBlock, ParagraphBlock ו-CheckboxBlock:

sealed class Block {
  Block();

  factory Block.fromJson(Map<String, Object?> json) {
    return switch (json) {
      {'type': 'h1', 'text': String text} => HeaderBlock(text),
      {'type': 'p', 'text': String text} => ParagraphBlock(text),
      {'type': 'checkbox', 'text': String text, 'checked': bool checked} =>
        CheckboxBlock(text, checked),
      _ => throw const FormatException('Unexpected JSON format'),
    };
  }
}

class HeaderBlock extends Block {
  final String text;
  HeaderBlock(this.text);
}

class ParagraphBlock extends Block {
  final String text;
  ParagraphBlock(this.text);
}

class CheckboxBlock extends Block {
  final String text;
  final bool isChecked;
  CheckboxBlock(this.text, this.isChecked);
}

מילת המפתח sealed מציינת שאפשר Blockלהרחיב או להטמיע את רק באותה ספרייה (lib/data.dart). מכיוון שמנתח Dart מכיר את הקבוצה המלאה והסגורה של סוגי המשנה הישירים של Block, הוא יכול לוודא אם switch כלשהו במופע של Block מטפל בכל סוג משנה.

החלפת תבנית אובייקט מקיפה ב-BlockWidget

ב-lib/main.dart, הפונקציה BlockWidget.build מעבירה ביטוי switch (block) ישירות למאפיין child של Container, מתאימה לכל מחלקת משנה עם תבנית אובייקט ומפרקת את השדות שלה באמצעות קיצור הדרך :final:

class BlockWidget extends StatelessWidget {
  final Block block;

  const BlockWidget({required this.block, super.key});

  @override
  Widget build(BuildContext context) {
    return Container(
      margin: const EdgeInsets.all(8),
      child: switch (block) {
        HeaderBlock(:final text) => Text(
          text,
          style: Theme.of(context).textTheme.displayMedium,
        ),
        ParagraphBlock(:final text) => Text(text),
        CheckboxBlock(:final text, :final isChecked) => Row(
          children: [
            Checkbox(value: isChecked, onChanged: (_) {}),
            Text(text),
          ],
        ),
      },
    );
  }
}

הפעלה ובדיקה של האפליקציה

מבצעים Hot Reload לאפליקציה כדי לראות את בלוק תיבת הסימון שעבר עיבוד עם ווידג'ט Material Checkbox בפעם הראשונה:

האפליקציה מציגה את כותרת המסמך, טקסט של פסקה ותיבת סימון לא מסומנת של &quot;למידה של Dart 3&quot;

12. מזל טוב

מעולה! עבדתם עם Google Antigravity כדי ליצור כלי להצגת מסמכים ב-Flutter, שמבוסס על רשומות, דפוסים, ביטויי switch משופרים ומחלקות sealed ב-Dart 3.

מה שיצרתם

  • החזרת ערכים מרובים עם רשומות: החזרת שדות לפי מיקום ולפי שם ((String, {DateTime modified})) מ-Document.metadata ופירוק שלהם בצורה נקייה למשתנים מקומיים באמצעות final (title, :modified) = document.metadata;.
  • אימות וחילוץ בטוחים של JSON: השתמשנו בהצהרות if-case ובביטויי switch שניתנים להפרכה עם תבניות מפה בתצוגת עץ כדי לאמת סוגים, לבדוק מפתחות ולחלץ ערכים בביטוי אחד.
  • הסתעפות של ממשק משתמש אקספרסיבי: שימוש בביטויי switch, תבניות אובייקטים (Duration(inDays: final days)) וסעיפי הגנה של when כדי לעצב חותמות זמן יחסיות וליצור ווידג'טים מוטבעים.
  • בדיקת מיצוי בזמן הקימפול: בניית מודל של בלוקי תוכן במסמכים כהיררכיית sealed class Block (HeaderBlock,‏ ParagraphBlock ו-CheckboxBlock) כדי שהקומפיילר יוודא שכל סוג בלוק עובר רינדור.

מה השלב הבא?

במסמכי התיעוד הרשמיים של Dart אפשר למצוא מידע נוסף על סוגי דפוסים, תכונות של רשומות ומשתני מחלקות:

מסמכי עזר

כדי לקבל מפרטים מעמיקים של השפה לכל תכונה שכלולה ב-Codelab הזה, כדאי לעיין במסמכי העיצוב המקוריים של שפת Dart: