إنشاء نموذج مخصّص

Firebase Studio يوفّر مجموعة كبيرة من النماذج المضمّنة التي تتضمّن جميع الملفات، وحِزم النظام (مثل أدوات الترجمة البرمجية)، و الإضافات التي تحتاج إليها للبدء بسرعة بلغة أو إطار عمل.

يمكنك أيضًا تشغيل مساحة عمل Firebase Studio باستخدام نماذج المنتدى المستضافة على GitHub. لمزيد من المعلومات حول تشغيل مساحة عمل جديدة من نموذج، يُرجى الاطّلاع على مقالة إنشاء مساحة عمل Firebase Studio.

سيستخدم معظم المستخدمين النماذج المضمّنة أو يستوردون المشاريع من Git، ولكن في حالات الاستخدام الأكثر تقدّمًا، يمكنك إنشاء نماذجك الخاصة:

• إذا كنت تنشئ إطار عمل أو مكتبة أو خدمة، يمكنك أن تسمح للمستخدمين بالبدء بسرعة باستخدام التكنولوجيا بدون مغادرة المتصفّح، مع الاستفادة من الإمكانات الكاملة لجهاز افتراضي مستند إلى السحابة الإلكترونية.

• إذا كان لديك مجموعة تكنولوجيات مفضّلة لمشاريعك، يمكنك تبسيط عملية بدء مشاريع جديدة باستخدام نموذج مخصّص.

• إذا كنت تعلّم الآخرين، مثلاً من خلال دليل توجيهي/تعليمي أو درس تطبيقي حول الترميز، يمكنك إزالة بعض الخطوات الأولية لطلابك من خلال الضبط المسبق لنقطة البداية في الدرس التطبيقي حول الترميز كنموذج مخصص.

بعد إنشاء النموذج المخصّص واختباره، يمكنك إنشاء رابط له ووضعه على موقعك الإلكتروني أو ملف README في مستودع Git أو صفحة تفاصيل الحزمة (مثلاً في NPM) أو أي مكان آخر تتوقّع أن يبدأ المستخدمون فيه باستخدام التكنولوجيا.

ملاحظة: يمكنك أيضًا إنشاء رابط للمستخدمين لإنشاء مساحة عمل جديدة عن طريق استنساخ مستودع Git. على الرغم من أنّ هذا الخيار أقل قابلية للضبط من إنشاء نموذج Firebase Studio الخاص بك، لا يتطلّب أي تغييرات في مستودع Git. مزيد من المعلومات في مقالة إنشاء مساحة عمل.

المتطلبات الأساسية

قبل البدء:

• تعرَّف على كيفية استخدام ملف idx/dev.nix لـ تخصيص بيئتك.

• تعرَّف على أساسيات لغة Nix واحتفِظ بالمرجع في متناول يدك.

بنية ملف النموذج

نموذج Firebase Studio هو مستودع Git علني (أو مجلد أو فرع في مستودع) يحتوي على ملفَين على الأقل:

• يتضمّن ملف idx-template.json البيانات الوصفية للنموذج، بما في ذلك اسمه ووصفه والمعلَمات التي يمكن للمستخدمين ضبطها في النموذج. على سبيل المثال، يمكنك السماح للمستخدمين بالاختيار من بين عدد من لغات البرمجة أو أمثلة حالات الاستخدام. Firebase Studio يستخدم هذه المعلومات لإعداد واجهة المستخدم التي تظهر للمستخدمين عندما يختارون إنشاء مساحة عمل جديدة من النموذج.

• idx-template.nix هو ملف مكتوب بلغة Nix يحتوي على نص برمجي لـ Bash shell (مغلّف في دالة Nix) ينفّذ ما يلي:

  1. إنشاء دليل العمل لمساحة العمل الجديدة

  2. إعداد بيئته من خلال إنشاء ملف .idx/dev.nix يُرجى العِلم أنّه يمكنك أيضًا تشغيل أداة إنشاء هيكل المشروع، مثل flutter create أو npm init في هذا النص البرمجي، أو تشغيل نص برمجي مخصّص مكتوب بلغة Go أو Python أو Node.js أو لغة أخرى.

     سيتم تنفيذ هذا الملف باستخدام المعلَمات التي يحدّدها المستخدم عندما يحمّل Firebase Studio النموذج.

يمكن تضمين ملفات أخرى بجانب هذَين الملفَين لاستخدامها في idx-template.nix من أجل إنشاء النموذج. على سبيل المثال، يمكنك تضمين ملف .idx/dev.nix النهائي، أو حتى تضمين جميع ملفات إنشاء الهيكل مباشرةً في المستودع.

إنشاء نموذج أساسي

لتسريع عملية إنشاء النماذج، ننصحك بالبدء بإحدى الطريقتَين التاليتَين لإنشاء نموذج Firebase Studio يمكنك تخصيصه بشكل أكبر:

• تحويل أي مستودع GitHub علني إلى نموذج
• استخدام نموذج رسمي أو نموذج متوفّر في المنتدى كأساس لنموذجك

مثال أساسي: تحويل أي مستودع GitHub علني إلى نموذج

قبل الخوض في تفاصيل كيفية تحديد idx-template.json وidx-template.nix، من المفيد الاطّلاع على نموذج أساسي ينفّذ ما يلي:

• لا يحتوي على أي معلَمات يمكن للمستخدم ضبطها
• ينسخ جميع الملفات في مستودع النموذج (باستثناء ملفَي idx-template) إلى مساحة عمل المستخدم يجب أن يكون هناك مجلد فرعي .idx يحتوي على ملف dev.nix يحدّد البيئة.

إذا أضفت الملفَين التاليَين إلى أي مستودع GitHub علني (أو مجلد فرعي أو فرع)، سيؤدي ذلك فعليًا إلى تحويل هذا المستودع إلى Firebase Studio نموذج.

idx-template.json

{
  "name": "Hello world",
  "description": "A template for a CLI program that prints 'hello world'",
  "icon": "https://www.gstatic.com/images/branding/productlogos/studio/v1/192px.svg",
  "params": []
}

idx-template.nix

# No user-configurable parameters
{ pkgs, ... }: {
  # Shell script that produces the final environment
  bootstrap = ''
    # Copy the folder containing the `idx-template` files to the final
    # project folder for the new workspace. ${./.} inserts the directory
    # of the checked-out Git folder containing this template.
    cp -rf ${./.} "$out"

    # Set some permissions
    chmod -R +w "$out"

    # Remove the template files themselves and any connection to the template's
    # Git repository
    rm -rf "$out/.git" "$out/idx-template".{nix,json}
  '';
}

ملاحظة: بالإضافة إلى $out، يمكنك أيضًا الحصول على رقم تعريف مساحة العمل الجديدة باستخدام المتغيّر $WS_NAME variable.

انتقِل إلى تخصيص نموذجك للتعرّف على التغييرات الإضافية التي يمكنك إجراؤها لتخصيص نموذجك.

إنشاء نموذج مخصّص باستخدام نموذج رسمي أو نموذج متوفّر في المنتدى

يحتفظ فريق Firebase Studio بمستودعَين لنماذج Firebase Studio:

• النماذج الرسمية: هي النماذج التي تختارها مباشرةً من Firebase Studio لوحة البيانات عند إنشاء تطبيق جديد.

• نماذج المنتدى: تسمح هذه النماذج بالمساهمات من المنتدى المفتوح المصدر. لاستخدام نموذج متوفّر في المنتدى، استنسِخ مستودع Git لنماذج المنتدى. يمكنك استخدام الرابط الكامل للنموذج الذي تريد استخدامه.

  **ملاحظة:** للمساهمة في المنتدى عن طريق إضافة نماذج جديدة أو تعديل النماذج الحالية، أرسِل طلب سحب.

لإنشاء نموذج مخصّص باستخدام نموذج حالي كأساس:

1. حدِّد النموذج الذي تريد استخدامه كأساس لنموذجك المخصّص، ثم استنسِخ المشروع.

2. خصِّص idx-template.json وidx-template.nix و.idx/dev.nix حسب الحاجة، بدءًا من تخصيص نموذجك.

3. احفظ التغييرات في المستودع.

4. اتّبِع الخطوات الواردة في مقالة إنشاء مساحة عمل جديدة لنموذجك لـ نشر نموذجك واختباره. إذا كنت تستخدم مستودعًا متداخلاً، يمكنك الربط به مباشرةً في عنوان URL. على سبيل المثال، إذا كنت تستخدم نموذج "Vanilla Vite" من المنتدى، عليك توفير مساحة عمل جديدة واختبارها باستخدام عنوان URL التالي:

   https://studio.firebase.google.com/new?template=https://github.com/firebase-studio/community-templates/tree/main/vite-vanilla
   

انتقِل إلى تخصيص نموذجك للتعرّف على التغييرات الإضافية التي يمكنك إجراؤها لتخصيص نموذجك.

تخصيص نموذجك

بعد إنشاء نموذج أساسي يمكنك البناء عليه، يمكنك تعديل ملفات idx-template.json وidx-template.nix و.idx/dev.nix لتتطابق مع متطلباتك. قد تحتاج إلى تخصيص إعدادات إضافية:

• أضِف حِزم النظام إلى النص البرمجي bootstrap.
• إضافة معلَمات يمكن للمستخدم ضبطها
• اختيار الملفات التي يجب فتحها تلقائيًا
• اختيار رمز تلقائي لمساحة العمل

استخدام حِزم نظام إضافية في النص البرمجي bootstrap

لا يستخدم المثال الأساسي سوى أوامر POSIX الأساسية لنسخ الملفات إلى المكان الصحيح. قد يتطلّب النص البرمجي bootstrap في نموذجك تثبيت ملفات ثنائية إضافية، مثل git أو node أو python3 أو غيرها.

يمكنك إتاحة حِزم نظام إضافية للنص البرمجي bootstrap من خلال تحديد packages في ملف idx-template.nix، تمامًا كما يمكنك تخصيص مساحة عمل باستخدام حِزم نظام إضافية من الحِزم عن طريق إضافة packages إلى ملف dev.nix الخاص بها.

ملاحظة: idx-template.nix يستخدم دائمًا stable-23.11 قناة Nix.

في ما يلي مثال على إضافة pkgs.nodejs، التي تتضمّن ملفات ثنائية مثل node و npx وnpm:

# idx-template.nix
{pkgs}: {
  packages = [
    # Enable "node", "npm" and "npx" in the bootstrap script below.
    # Note, this is NOT the list of packages available to the workspace once
    # it's created. Those go in .idx/dev.nix
    pkgs.nodejs
  ];

  bootstrap = ''
    mkdir "$out"
    # We can now use "npm"
    npm init --yes my-boot-strap@latest "$out"
  ''
}

ملاحظة مهمة: **لا يمكن أن يكون** النص البرمجي bootstrap **تفاعليًا**. إذا كان ينتظر إدخال المستخدم، سيتعذّر إنشاء النموذج بشكل صحيح.

إضافة معلَمات يمكن للمستخدم ضبطها

للسماح للمستخدمين بتخصيص نقطة البداية لمشروعهم الجديد، يمكنك إما إنشاء نماذج متعددة أو إنشاء نموذج واحد يحتوي على معلَمات. هذا خيار رائع إذا كانت نقاط البداية المختلفة مجرد قيم مختلفة يتم تمريرها إلى أداة سطر الأوامر (على سبيل المثال، --language=js مقابل --language=ts).

لإضافة معلَمات، عليك تنفيذ ما يلي:

1. وصف المَعلمة في العنصر params في ملف البيانات الوصفية idx-template.json Firebase Studio يستخدم المعلومات الواردة في هذا الملف لإعداد واجهة المستخدم (مثل مربّعات الاختيار والقوائم المنسدلة وحقول النص) التي تظهر لمستخدمي النموذج.
2. تعديل النص البرمجي bootstrap في idx-template.nix لاستخدام القيم التي اختارها المستخدم أثناء إنشاء النموذج

وصف المَعلمة في idx-template.json

في ما يلي مثال على إضافة مَعلمة enum، التي Firebase Studio يعرضها إما كقائمة منسدلة أو مجموعة أزرار اختيار، حسب عدد الخيارات:

{
  "name": "Hello world",
  "description": "A hello world app",
  "params": [
    {
      "id": "language",
      "name": "Programming Language",
      "type": "enum",
      "default": "ts",
      "options": {
        "js": "JavaScript",
        "ts": "TypeScript"
      },
      "required": true
    }
  ]
}

بما أنّ هناك قيمتَين (JavaScript وTypeScript)، ستعرض واجهة المستخدم مجموعة أزرار اختيار للخيارَين وتمرِّر إما القيمة ts أو js إلى النص البرمجي idx-template.nix.

يحتوي كل عنصر مَعلمة على الخصائص التالية:

الخاصية	النوع	الوصف
id	string	رقم التعريف الفريد للمَعلمة، على غرار اسم المتغيّر
name	string	الاسم المعروض لهذه المَعلمة
type	string	يحدّد مكوِّن واجهة المستخدم الذي سيتم استخدامه لهذه المَعلمة ونوع البيانات التي سيتم تمريرها إلى النص البرمجي bootstrap القيم الصالحة هي: "enum" - يعرض قائمة منسدلة أو مجموعة أزرار اختيار، ويمرِّر string إلى النص البرمجي bootstrap "boolean" - يعرض مربّع اختيار ويمرِّر true أو false "text" - يعرض حقل نص ويمرِّر string
options	object	بالنسبة إلى معلَمات enum، يمثّل هذا الخيارات التي يتم عرضها للمستخدمين. على سبيل المثال، إذا كانت الخيارات هي {"js": "JavaScript", ...}، سيتم عرض "JavaScript" كخيار، وعند اختياره، ستكون قيمة هذه المَعلمة js.
default	string أو boolean	يضبط القيمة الأولية في واجهة المستخدم. بالنسبة إلى معلَمات enum، يجب أن تكون هذه القيمة إحدى المفاتيح في options. بالنسبة إلى معلَمات boolean، يجب أن تكون هذه القيمة true أو false.
required	boolean	يشير إلى أنّ هذه المَعلمة مطلوبة

استخدام قيم المَعلمات في idx-template.nix

بعد تحديد العنصر params في ملف idx-template.json، يمكنك البدء بتخصيص النص البرمجي bootstrap استنادًا إلى قيم المَعلمات التي يختارها المستخدم.

باتّباع المثال في القسم السابق، إذا كان لديك مَعلمة واحدة برقم التعريف language وهي `enum` تحتوي على القيمتَين المحتملتَين ts أو js، يمكنك استخدامها على النحو التالي:

# idx-template.nix
# Accept additional arguments to this template corresponding to template
# parameter IDs, including default values (language=ts by default in this example).
{ pkgs, language ? "ts", ... }: {
  packages = [
    pkgs.nodejs
  ];

  bootstrap = ''
    # We use Nix string interpolation to pass the user's chosen programming
    # language to our script.
    npm init --yes my-boot-strap@latest "$out" -- --lang=${language}
  ''
}

هناك نمط شائع آخر وهو تضمين المحتوى بشكل مشروط استنادًا إلى قيمة سلسلة. في ما يلي طريقة أخرى لكتابة المثال السابق:

npm init --yes my-boot-strap@latest "$out" -- \
    ${if language == "ts" then "--lang=ts" else "--lang=js" }

ملاحظة مهمة: تذكَّر أن تنشئ دائمًا ملف .idx/dev.nix في الدليل $out كجزء من النص البرمجي bootstrap. إذا كانت بيئة مساحة العمل التي تم إنشاؤها بحاجة إلى أن تختلف استنادًا إلى المَعلمات التي يضبطها المستخدم (على سبيل المثال، تضمين حِزم نظام مختلفة أو تخصيص الخطاف onCreate)، يمكنك استخدام معالجة السلاسل في Nix أو استدعاء محرّك إنشاء نماذج مثل jinja2.

اختيار الملفات التي يجب فتحها تلقائيًا

من المستحسن تخصيص الملفات التي يجب فتحها للتعديل عند إنشاء مساحات عمل جديدة باستخدام النموذج. على سبيل المثال، إذا كان النموذج مخصّصًا لموقع إلكتروني أساسي، قد تريد فتح ملفات HTML وJavaScript وCSS الرئيسية.

لتخصيص الملفات التي يجب فتحها تلقائيًا، عدِّل ملف .idx/dev.nix (وليس ملف idx-template.nix!) لتضمين خطاف مساحة عمل onCreate يحتوي على السمة openFiles، على النحو التالي:

# .idx/dev.nix
{pkgs}: {
  ...
  idx = {
    # Workspace lifecycle hooks
    workspace = {
      # Runs when a workspace is first created with this `dev.nix` file
      onCreate = {
        # Open editors for the following files by default, if they exist.
        # The last file in the list will be focused.
        default.openFiles = [
          "src/index.css"
          "src/index.js"
          "src/index.html"
        ];
        # Include other scripts here, as needed, for example:
        # installDependencies = "npm install";
      };
      # To run something each time the workspace is (re)started, use the `onStart` hook
    };
    # Enable previews and customize configuration
    previews = { ... };
  };
}

اختيار رمز تلقائي لمساحة العمل

يمكنك اختيار الرمز التلقائي لمساحات العمل التي تم إنشاؤها باستخدام النموذج، وذلك عن طريق وضع ملف PNG باسم icon.png بجانب ملف dev.nix داخل الدليل .idx.

ملاحظة: يتضمّن ملف idx-template.json أيضًا خاصية icon اختيارية، يجب أن تشير إلى عنوان URL علني بتنسيق PNG أو SVG، إذا تم توفيره. لا يتم استخدام هذا الحقل في Firebase Studio

.

اختبار النموذج في مساحة عمل جديدة

أسهل طريقة لاختبار النموذج من البداية إلى النهاية هي إنشاء مساحة عمل جديدة باستخدام النموذج. انتقِل إلى الرابط التالي، مع استبدال المثال بعنوان URL لمستودع GitHub الخاص بالنموذج:

https://idx.google.com/new?template=https://github.com/my-org/my-repo

يمكنك اختياريًا تضمين فرع ومجلد فرعي. جميع ما يلي صالح، طالما أنّه يمكن الوصول إليه علنًا:

• https://github.com/my-org/my-repo/
• https://github.com/my-org/my-repo/tree/main/path/to/myidxtemplate
• https://github.com/my-org/my-repo/tree/branch
• https://github.com/my-org/my-repo/tree/branch/path/to/myidxtemplate

هذا هو أيضًا عنوان URL الذي ستشاركه مع الآخرين ليتمكّنوا من استخدام النموذج الجديد ، أو عنوان URL الذي ستربطه من زر "الفتح في Firebase Studio" button.

---

مشاركة النموذج

بعد التأكّد من أنّ النموذج يعمل على النحو المتوقّع، انشره في مستودع GitHub وشارِك الرابط نفسه الذي استخدمته عند إنشاء مساحة عمل للاختبار.

ولتسهيل عثور المستخدمين على النموذج، أضِف زر "الفتح في Firebase Studio" إلى موقعك الإلكتروني أو ملف README في المستودع.