تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

قبل البدء:

تعرَّف على كيفية استخدام ملف 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 الخاص بنماذج المنتدى. يمكنك استخدام الرابط الكامل للنموذج الذي تريد استخدامه.

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

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

حدِّد النموذج الذي تريد استخدامه كأساس لنموذجك المخصّص، ثم استنسِخ المشروع.
خصِّص idx-template.json وidx-template.nix و.idx/dev.nix حسب الحاجة، بدءًا من تخصيص النموذج.
سجِّل التغييرات في المستودع.
اتّبِع الخطوات الواردة في إنشاء مساحة عمل جديدة للنموذج لنشر النموذج واختباره. إذا كنت تستخدم مستودعًا متداخلاً، يمكنك الربط به مباشرةً في عنوان 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 أو غيرها.

يمكنك إتاحة حِزم نظام إضافية لبرنامج نصي للتشغيل الأوّلي من خلال تحديد 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).

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

صِف المَعلمة في العنصر params ضمن ملف البيانات الوصفية idx-template.json. تستخدِم Firebase Studio المعلومات الواردة في هذا الملف لإعداد واجهة المستخدم (مثل مربّعات الاختيار والقوائم المنسدلة وحقول النص) التي تظهر لمستخدمي النموذج.
عدِّل 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.

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

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

استخدام قيم المَعلمات في `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 الخاص بالمستودع.