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

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

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

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

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

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

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

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

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

قبل البدء:

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

• تعرَّف على أساسيات لغة Nix واحفظ المرجع متاحًا.

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

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

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

• idx-template.nix هو ملف مكتوب بلغة Nix يحتوي على ملف نصي لنظام التشغيل Bash (ملف نصي مُغلف في دالة 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}
  '';
}

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

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

يدير فريق 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/project-idx/community-templates/tree/main/vite-vanilla
   

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

تخصيص النموذج

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

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

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

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

يمكنك إتاحة حِزم نظام إضافية لنص التمهيد من خلال تحديد packages في ملف idx-template.nix، تمامًا كما يمكنك تخصيص مساحة عمل باستخدام حِزم نظام إضافية من خلال الإضافة إلى packages في ملف dev.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"
  ''
}

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

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

لإضافة مَعلمات، عليك اتّباع الخطوات التالية:

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

وصف المَعلمة في 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.

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

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

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

استنادًا إلى المثال في القسم السابق، إذا كانت لديك مَعلمة واحدة بالمعرّف language وهي مصنّف بقيم محتملة هي 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" }

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

من المستحسن تخصيص الملفات التي يجب فتحها للتعديل عند إنشاء مساحات عمل جديدة باستخدام النموذج. على سبيل المثال، إذا كان النموذج مخصّصًا لموقع إلكتروني أساسي، قد تحتاج إلى فتح ملفات 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.

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

إنّ أبسط طريقة لاختبار النموذج من البداية إلى النهاية هي إنشاء مساحة عمل جديدة باستخدامه. يُرجى الانتقال إلى الرابط التالي، مع استبدال المثال بعنوان 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".

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

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

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