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

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

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

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

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

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

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

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

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

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

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

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

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

يتضمن 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 يحدّد البيئة.

قد تكون إضافة الملفات التالية إلى أي مستودع عام في جيت هب (أو مجلد فرعي أو فرعها) يحول هذا المستودع بشكل فعال إلى نموذج 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 = { ... };
  };
}

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

يمكنك اختيار الرمز التلقائي لمساحات العمل التي تم إنشاؤها باستخدام النموذج الخاص بك، من خلال وضع ملف 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 الجديد أو عنوان URL الذي سيتم إنشاء رابط إليه في "فتح في IDX" .

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

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