این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

یک قالب سفارشی ایجاد کنید

Firebase Studio طیف گسترده‌ای از قالب‌های داخلی را ارائه می‌دهد که شامل تمام فایل‌ها، بسته‌های سیستمی (به عنوان مثال، کامپایلرها) و افزونه‌هایی است که برای شروع سریع کار با یک زبان یا چارچوب نیاز دارید.

همچنین می‌توانید با استفاده از قالب‌های Community که در GitHub میزبانی می‌شوند، یک فضای کاری Firebase Studio راه‌اندازی کنید. برای اطلاعات بیشتر در مورد راه‌اندازی یک فضای کاری جدید از یک قالب، به بخش «ایجاد یک فضای کاری Firebase Studio مراجعه کنید.

بیشتر کاربران از قالب‌های داخلی استفاده می‌کنند یا پروژه‌ها را از گیت وارد می‌کنند، اما برای موارد استفاده پیشرفته‌تر، می‌توانید قالب‌های خودتان را ایجاد کنید:

اگر در حال ساخت چارچوب، کتابخانه یا سرویس خودتان هستید، می‌توانید به کاربران خود اجازه دهید بدون ترک مرورگر، با تمام قدرت یک ماشین مجازی مبتنی بر ابر، به سرعت با فناوری شما شروع به کار کنند.
اگر برای پروژه‌های خود از یک فناوری خاص استفاده می‌کنید، می‌توانید فرآیند شروع پروژه‌های جدید خود را با یک الگوی سفارشی ساده کنید.
اگر به دیگران آموزش می‌دهید، مثلاً از طریق یک آموزش یا codelab ، می‌توانید با پیکربندی اولیه نقطه شروع codelab خود به عنوان یک الگوی سفارشی، برخی از مراحل اولیه را برای دانش‌آموزان خود حذف کنید.

پس از ایجاد و آزمایش قالب سفارشی خود، می‌توانید لینکی برای آن ایجاد کنید تا آن را در وب‌سایت خود، فایل README مخزن گیت، صفحه جزئیات بسته (مثلاً در 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 یا حتی تمام فایل‌های scaffolding را مستقیماً در مخزن قرار دهید.

ایجاد یک الگوی اولیه

برای تسریع در ایجاد قالب، توصیه می‌کنیم با یکی از روش‌های زیر شروع کنید تا یک قالب Firebase Studio ایجاد کنید که بتوانید آن را بیشتر سفارشی‌سازی کنید:

هر مخزن عمومی 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 انتخاب می‌کنید.
قالب‌های انجمن : این قالب‌ها امکان مشارکت از سوی جامعه متن‌باز را فراهم می‌کنند. برای استفاده از یک قالب انجمن، مخزن گیت قالب‌های انجمن را کپی کنید. می‌توانید از لینک کامل قالبی که می‌خواهید استفاده کنید استفاده کنید.
نکته: برای مشارکت در جامعه با اضافه کردن قالب‌های جدید یا به‌روزرسانی قالب‌های موجود، یک درخواست pull ارسال کنید.

برای ایجاد یک الگوی سفارشی با استفاده از یک الگوی موجود به عنوان مبنا:

تصمیم بگیرید که از کدام الگو به عنوان پایه برای الگوی سفارشی خود استفاده کنید، سپس پروژه را کلون کنید.
در صورت نیاز، idx-template.json ، idx-template.nix و .idx/dev.nix را سفارشی کنید، و از گزینه‌ی «Customize your template» شروع کنید.
تغییرات را در مخزن خود بررسی کنید.
دنبال کنید یک فضای کاری جدید برای قالب خود ایجاد کنید تا آن را منتشر و آزمایش کنید. اگر از یک مخزن تو در تو استفاده می‌کنید، مستقیماً در 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 ، بسته‌های سیستمی اضافی را برای اسکریپت بوت‌استرپ خود در دسترس قرار دهید، همانطور که می‌توانید با اضافه کردن بسته‌های سیستمی اضافی به فایل dev.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"
  ''
}

اضافه کردن پارامترهای قابل تنظیم توسط کاربر

برای اینکه کاربران بتوانند نقطه شروع پروژه جدید خود را سفارشی کنند، می‌توانید چندین قالب ایجاد کنید، یا یک قالب واحد با پارامترها ایجاد کنید. اگر نقاط شروع مختلف شما فقط مقادیر متفاوتی هستند که به یک ابزار CLI ارسال می‌شوند (برای مثال --language=js در مقابل --language=ts )، این گزینه عالی است.

برای اضافه کردن پارامترها، باید:

پارامتر خود را در شیء params از فایل فراداده idx-template.json خود توصیف کنید. Firebase Studio از اطلاعات موجود در این فایل برای آماده‌سازی رابط کاربری (مانند کادرهای انتخاب، منوهای کشویی و فیلدهای متنی) که به کاربران قالب شما نشان داده می‌شود، استفاده می‌کند.
بوت‌استرپ 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
    }
  ]
}

از آنجایی که دو مقدار وجود دارد (جاوااسکریپت و تایپ‌اسکریپت)، رابط کاربری یک گروه دکمه رادیویی برای دو گزینه رندر می‌کند و مقدار ts یا js را به اسکریپت idx-template.nix ارسال می‌کند.

هر شیء پارامتری دارای ویژگی‌های زیر است:

ملک	نوع	شرح
شناسه	`string`	شناسه منحصر به فرد پارامتر، مشابه نام متغیر.
نام	`string`	نام نمایشی برای این پارامتر.
نوع	`string`	کامپوننت رابط کاربری که برای این پارامتر استفاده می‌شود و نوع داده‌ای که به اسکریپت بوت‌استرپ ارسال می‌شود را مشخص می‌کند. مقادیر معتبر عبارتند از: `"enum"` - یک گروه از دکمه‌های کشویی یا رادیویی را نمایش می‌دهد و یک `string` به بوت‌استرپ ارسال می‌کند. `"boolean"` - یک چک‌باکس نمایش می‌دهد و `true` یا `false` را برمی‌گرداند. `"text"` - یک فیلد متنی را نمایش می‌دهد و یک `string` ارسال می‌کند.
گزینه‌ها	`object`	برای پارامترهای `enum` ، این نشان‌دهنده‌ی گزینه‌هایی است که باید به کاربران نشان داده شود. برای مثال، اگر options برابر با `{"js": "JavaScript", ...}` باشد، "JavaScript" به عنوان گزینه نمایش داده می‌شود و هنگام انتخاب، مقدار این پارامتر `js` خواهد بود.
پیش‌فرض	`string` یا `boolean`	مقدار اولیه را در رابط کاربری تنظیم می‌کند. برای پارامترهای `enum` ، این باید یکی از کلیدهای موجود در `options` باشد. برای پارامترهای `boolean` ، این باید `true` یا `false` باشد.
مورد نیاز	`boolean`	نشان می‌دهد که این پارامتر الزامی است.

استفاده از مقادیر پارامترها در `idx-template.nix`

پس از تعریف شیء params در فایل idx-template.json ، می‌توانید سفارشی‌سازی اسکریپت bootstrap را بر اساس مقادیر پارامترهایی که کاربر انتخاب می‌کند، شروع کنید.

طبق مثال بخش قبل، اگر یک پارامتر واحد با language شناسه (ID 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" }

انتخاب کنید که کدام فایل‌ها باید به طور پیش‌فرض باز شوند

ایده خوبی است که هنگام ایجاد فضاهای کاری جدید با قالب خود، فایل‌هایی را که باید برای ویرایش باز شوند، سفارشی کنید. برای مثال، اگر قالب شما برای یک وب‌سایت ساده است، ممکن است بخواهید فایل‌های اصلی HTML، جاوا اسکریپت و 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 آیکون پیش‌فرض را برای فضاهای کاری ایجاد شده با الگوی خود انتخاب کنید.

قالب خود را در یک فضای کاری جدید آزمایش کنید

ساده‌ترین راه برای آزمایش کامل قالب شما، ایجاد یک فضای کاری جدید با آن است. به لینک زیر مراجعه کنید و مثال را با آدرس مخزن گیت‌هاب قالب خود جایگزین کنید:

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 Firebase Studio " به آن پیوند خواهید داد.

بعد از اینکه تأیید کردید که الگوی شما مطابق انتظار عمل می‌کند، آن را در یک مخزن گیت‌هاب منتشر کنید و همان لینکی را که هنگام ایجاد فضای کاری برای آزمایش استفاده کردید، به اشتراک بگذارید.

و برای اینکه کاربران راحت‌تر بتوانند الگوی شما را پیدا کنند، دکمه «باز کردن در Firebase Studio » را به وب‌سایت یا مخزن README خود اضافه کنید.