创建自定义模板

IDX 提供了多种内置功能 templates，其中包含所有文件、系统 软件包（例如编译器）和扩展 您需要快速上手使用某种语言或框架。

您可能还需要创建用户可配置的专属模板。例如：

  • 如果您要构建自己的框架、库或服务，可以执行以下操作： 让用户能够快速上手您的技术， 让您无需浏览器也能使用云端虚拟机的全部功能。

  • 如果您拥有适合自己项目的首选技术栈，则可以 使用自定义模板简化您启动新项目的流程。

  • 如果您正在教其他人（例如通过 Codelab），则可以移除 您可以预先配置 作为自定义模板

准备好自定义模板后，您可以为 放置在您的网站（Git 代码库 README）中 文件、文件包详情页面（如 NPM 中）或用户可从中 想要开始使用您的技术

前提条件

开始之前，请确保您熟悉如何自定义 包含 .idx/dev.nix 文件的环境。

模板还使用 Nix 语言， 因此您可能需要复习一些基本知识 参考。

模板文件结构

模板是公共 GitHub 代码库（或代码库中的文件夹或分支） 至少包含两个文件：

  • <ph type="x-smartling-placeholder">
    </ph> 用户在使用您的模板创建新工作区时看到的对话框 <ph type="x-smartling-placeholder">
    </ph> 通过自定义模板创建新工作区

    idx-template.json 包含模板的元数据，包括 用户可见的名称、说明和参数 配置模板。例如，您可以允许用户选择 多种编程语言或示例用例。IDX 使用 这些信息，以便用户在选择创建 创建新工作区。

  • idx-template.nix 是用 Nix 写入的文件 包含 Bash shell 的语言 脚本（封装在 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 等。

您可以通过以下命令向引导脚本提供其他系统软件包： 在 idx-template.nix 文件中指定 packages，就像 使用其他系统软件包自定义工作区 添加到 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）。

要添加参数，您需要：

  1. 在 idx-template.json 的 params 对象中描述参数 元数据文件。IDX 使用此文件中的信息来准备界面 （例如复选框、下拉菜单和文本字段） 模板。
  2. 更新 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 参数的唯一 ID，类似于变量名称。
name 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 中的参数值

在 idx-template.json 文件中定义 params 对象后，您可以执行以下操作： 根据用户的参数值开始自定义引导脚本 选择。

如果您有一个形参，则沿用上一部分中的示例 ID 为 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 = { ... };
  };
}

选择默认工作区图标

您可以为使用模板创建的工作区选择默认图标， 方法是将名为 icon.png 的 PNG 文件放在 dev.nix 文件旁边的 .idx 目录中。

基于模板创建新工作区

若要对模板进行端到端测试，最简单的方式是创建新的工作区 。访问以下链接，将示例替换为您模板的 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

这也是您要与他人分享的网址，以便他们可以使用您的新 模板或者您要链接到的网址，可在“在 IDX 中打开” 按钮。

共享模板

确认模板按预期运行后，将其发布到 GitHub 代码库并共享您在创建工作区时使用的同一链接 进行测试。

为了让用户更容易找到您的模板，请将“打开方式” IDX&quot;按钮添加到网站或代码库 README 文件中。