لا يزال Project IDX في المرحلة التجريبية. قد يتم دعم المنتجات والميزات التجريبية بشكل محدود، وقد لا تتوافق التغييرات التي تطرأ على المنتجات والميزات التجريبية مع الإصدارات السابقة.

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

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

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

كما قد تحتاج إلى إنشاء نماذجك الخاصة والقابلة للتهيئة بواسطة المستخدم. مثلاً:

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

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

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

قبل البدء، احرص على معرفتك بتخصيص بيئتك باستخدام ملفات .idx/dev.nix.

تستخدم النماذج أيضًا لغة Nix، لذلك قد تحتاج إلى تحسين بعض الأساسيات أو جعلها مفيدة كمرجع.

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

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

إنشاء مساحة عمل جديدة من نموذج مخصّص

يتضمن idx-template.json البيانات الوصفية للنموذج، بما في ذلك الاسم المرئي للمستخدم ووصفه والمعلَمات المتاحة للمستخدمين لضبط النموذج. على سبيل المثال، يمكنك السماح للمستخدمين بالاختيار من بين عدد من لغات البرمجة أو أمثلة حالات الاستخدام. تستخدم أداة IDX هذه المعلومات لإعداد واجهة المستخدم التي تظهر للمستخدمين عند اختيار إنشاء مساحة عمل جديدة من النموذج.
idx-template.nix هو ملف مكتوب باللغة لغة Nix ويحتوي على نص هيكل باش (مغطى بدالة Nix) وهو مسؤول عن:
1. إنشاء دليل عمل مساحة العمل الجديدة
2. يتم إعداد البيئة من خلال إنشاء ملف .idx/dev.nix. تجدر الإشارة إلى أنّه يمكنك أيضًا تشغيل أداة نشر المشاريع، مثل flutter create أو npm init، في هذا النص البرمجي، أو تنفيذ نص برمجي مخصّص مكتوب بلغة Go أو Python أو Node.js أو لغة أخرى.
سيتم تنفيذ هذا الملف باستخدام المَعلمات التي حدّدها المستخدم عند ضبط النموذج.

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

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

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

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

تؤدي إضافة الملفات التالية إلى أي مستودع عام في GitHub (أو مجلد فرعي أو فرع) إلى تحويل المستودع بشكل فعال إلى نموذج IDX.

`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/idx/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}
  '';
}

استخدام حِزم النظام الإضافية في نص `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. تستخدم أداة IDX المعلومات في هذا الملف لإعداد واجهة المستخدم (مثل مربعات الاختيار والقوائم المنسدلة والحقول النصية) التي تظهر لمستخدمي النموذج.
عدِّل مقطع التشغيل idx-template.nix لاستخدام القيم التي اختارها المستخدم أثناء إنشاء مثيل للنموذج.

صِف المعلمة في `idx-template.json`.

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

{
  "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` إلى شريط التشغيل `"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 = { ... };
  };
}

إنشاء مساحة عمل جديدة من النموذج

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

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 الذي ستضع رابطًا إليه من الزر "Open in IDX".

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

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