Dự án IDX đang ở giai đoạn thử nghiệm. Các tính năng và sản phẩm trong giai đoạn beta có thể bị hỗ trợ hạn chế, đồng thời các thay đổi đối với sản phẩm và tính năng trong giai đoạn beta có thể không tương thích với các phiên bản trước.

Trang này được dịch bởi Cloud Translation API.

Tạo mẫu tuỳ chỉnh

IDX cung cấp nhiều mẫu tích hợp sẵn, bao gồm tất cả các tệp, gói hệ thống (ví dụ: trình biên dịch) và tiện ích mà người dùng có thể cần để nhanh chóng bắt đầu với ngôn ngữ hoặc khung.

Bạn cũng có thể muốn tạo mẫu của riêng mình, có thể định cấu hình người dùng. Ví dụ:

Nếu đang xây dựng khung, thư viện hoặc dịch vụ của riêng mình, bạn có thể cho phép người dùng nhanh chóng làm quen với công nghệ mà không cần rời khỏi trình duyệt với toàn bộ sức mạnh của máy ảo trên đám mây.
Nếu có một ngăn xếp công nghệ ưu tiên cho các dự án, bạn có thể đơn giản hoá quy trình của riêng mình để bắt đầu các dự án mới bằng một mẫu tuỳ chỉnh.
Nếu đang dạy cho người khác, chẳng hạn như thông qua một lớp học lập trình, bạn có thể xoá một số bước ban đầu cho học viên bằng cách định cấu hình trước điểm bắt đầu cho lớp học lập trình của mình dưới dạng một mẫu tuỳ chỉnh.

Sau khi đã có sẵn một mẫu tuỳ chỉnh, bạn có thể tạo một đường liên kết cho mẫu đó để đặt trên trang web của bạn, tệp README kho lưu trữ Git, trang chi tiết về gói (ví dụ: trong TLD) hoặc những vị trí khác mà người dùng có thể muốn bắt đầu sử dụng công nghệ của bạn.

Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo bạn đã quen với việc tuỳ chỉnh môi trường bằng tệp .idx/dev.nix.

Mẫu cũng sử dụng ngôn ngữ Nix, vì vậy, bạn nên ôn lại một số kiến thức cơ bản hoặc giữ lại để tham khảo.

Cấu trúc tệp mẫu

Mẫu là một kho lưu trữ GitHub (hoặc thư mục hay nhánh trong kho lưu trữ) có chứa ít nhất 2 tệp:

Tạo không gian làm việc mới từ mẫu tuỳ chỉnh

idx-template.json chứa siêu dữ liệu cho mẫu, bao gồm tên hiển thị cho người dùng, nội dung mô tả và các tham số có sẵn để người dùng định cấu hình mẫu. Ví dụ: bạn có thể cho phép người dùng chọn trong số một số ngôn ngữ lập trình hoặc ví dụ về trường hợp sử dụng. IDX sử dụng thông tin này để chuẩn bị giao diện người dùng hiển thị cho người dùng khi họ chọn tạo không gian làm việc mới từ mẫu của bạn.
idx-template.nix là một tệp được viết bằng ngôn ngữ Nix có chứa tập lệnh shell Bash (được gói trong hàm Nix) chịu trách nhiệm về:
1. Tạo thư mục làm việc của không gian làm việc mới và
2. Thiết lập môi trường bằng cách tạo một tệp .idx/dev.nix. Xin lưu ý rằng bạn cũng có thể chỉ cần chạy công cụ khung dự án (scaffolding) cho dự án như flutter create hoặc npm init trong tập lệnh này hoặc chạy tập lệnh tuỳ chỉnh được viết bằng Go, Python, Node.js hoặc một ngôn ngữ khác.
Tệp này sẽ được thực thi với các tham số do người dùng chỉ định khi họ định cấu hình mẫu.

Các tệp khác có thể được đưa vào cùng với 2 tệp này để dùng trong idx-template.nix nhằm tạo thực thể cho mẫu. Ví dụ: bạn có thể đưa tệp .idx/dev.nix cuối cùng vào hoặc thậm chí đưa tất cả các tệp khung (scaffolding) vào ngay trong kho lưu trữ.

Ví dụ cơ bản: biến mọi kho lưu trữ công khai trên GitHub thành một mẫu

Trước khi tìm hiểu chi tiết về cách xác định idx-template.json và idx-template.nix, bạn nên xem một mẫu ví dụ cơ bản:

Không có thông số có thể định cấu hình người dùng
Bạn chỉ cần sao chép tất cả các tệp trong kho lưu trữ mẫu của mình (ngoại trừ 2 tệp idx-template) vào không gian làm việc của người dùng. Phải có một thư mục con .idx có tệp dev.nix xác định môi trường.

Việc thêm các tệp sau vào bất kỳ kho lưu trữ GitHub công khai nào (hoặc thư mục con hoặc nhánh) sẽ biến kho lưu trữ đó thành một mẫu IDX một cách hiệu quả.

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

Sử dụng các gói hệ thống bổ sung trong tập lệnh `bootstrap`

Ví dụ trước chỉ sử dụng các lệnh POSIX cơ bản để sao chép các tệp vào đúng vị trí. Tập lệnh bootstrap của mẫu có thể yêu cầu cài đặt thêm các tệp nhị phân, chẳng hạn như git, node, python3 hoặc các tệp khác.

Bạn có thể cung cấp thêm các gói hệ thống cho tập lệnh Tự thân khởi động bằng cách chỉ định packages trong tệp idx-template.nix, giống như cách bạn tuỳ chỉnh không gian làm việc với các gói hệ thống bổ sung bằng cách thêm vào packages trong tệp dev.nix.

Dưới đây là ví dụ về cách thêm pkgs.nodejs, bao gồm các tệp nhị phân như node, npx và 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"
  ''
}

Thêm thông số mà người dùng có thể định cấu hình

Để cho phép người dùng tuỳ chỉnh điểm bắt đầu cho dự án mới của họ, bạn có thể tạo nhiều mẫu hoặc tạo một mẫu duy nhất có các tham số. Đây là một lựa chọn tuyệt vời nếu các điểm xuất phát khác nhau chỉ là các giá trị khác nhau được truyền đến một công cụ CLI (ví dụ: --language=js so với --language=ts).

Để thêm thông số, bạn cần:

Mô tả tham số của bạn trong đối tượng params của tệp siêu dữ liệu idx-template.json. IDX sử dụng thông tin trong tệp này để chuẩn bị giao diện người dùng (chẳng hạn như hộp đánh dấu, trình đơn thả xuống và trường văn bản) được hiển thị cho người dùng mẫu của bạn.
Cập nhật quy trình khởi động idx-template.nix để sử dụng các giá trị mà người dùng đã chọn trong khi tạo thực thể cho mẫu.

Mô tả thông số của bạn trong `idx-template.json`

Dưới đây là ví dụ về cách thêm tham số enum, IDX hiển thị dưới dạng trình đơn thả xuống hoặc nhóm nút chọn, tuỳ thuộc vào số lượng lựa chọn.:

{
  "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
    }
  ]
}

Vì có hai giá trị (JavaScript và TypeScript), nên giao diện người dùng sẽ kết xuất nhóm nút chọn cho hai tuỳ chọn và chuyển giá trị ts hoặc js đến tập lệnh idx-template.nix.

Mỗi đối tượng tham số có các thuộc tính sau:

TÀI SẢN	TYPE	NỘI DUNG MÔ TẢ
id	`string`	Mã nhận dạng duy nhất của tham số, tương tự như tên biến.
tên	`string`	Tên hiển thị cho thông số này.
loại	`string`	Chỉ định thành phần giao diện người dùng để sử dụng cho tham số này và loại dữ liệu cần truyền vào tập lệnh tự khởi động. Các giá trị hợp lệ là: `"enum"` – Hiển thị nhóm nút chọn hoặc trình đơn thả xuống và truyền `string` đến quy trình tự khởi động `"boolean"` – Hiện hộp đánh dấu và vượt qua `true` hoặc `false` `"text"` – Hiện trường văn bản và truyền một `string`
tùy chọn	`object`	Đối với tham số `enum`, thuộc tính này thể hiện các lựa chọn để hiển thị cho người dùng. Ví dụ: nếu các tuỳ chọn là `{"js": "JavaScript", ...}`, thì "JavaScript" sẽ được thể hiện dưới dạng tuỳ chọn và khi bạn chọn, giá trị của tham số này sẽ là `js`.
mặc định	`string` hoặc `boolean`	Đặt giá trị ban đầu trong giao diện người dùng. Đối với tham số `enum`, đây phải là một trong các khoá trong `options`. Đối với các tham số `boolean`, giá trị này phải là `true` hoặc `false`.
bắt buộc	`boolean`	Cho biết rằng đây là tham số bắt buộc.

Sử dụng các giá trị tham số trong `idx-template.nix`

Sau khi xác định đối tượng params trong tệp idx-template.json, bạn có thể bắt đầu tuỳ chỉnh tập lệnh Tự khởi động dựa trên các giá trị tham số mà người dùng chọn.

Theo ví dụ ở phần trước, nếu bạn có một tham số duy nhất có mã nhận dạng language là một enum với các giá trị có thể có là ts hoặc js, thì bạn có thể sử dụng như sau:

# 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}
  ''
}

Một mẫu phổ biến khác là đưa nội dung vào theo điều kiện tuỳ thuộc vào giá trị của chuỗi. Một cách khác để viết ví dụ trước là:

npm init --yes my-boot-strap@latest "$out" -- \
    ${if language == "ts" then "--lang=ts" else "--lang=js" }

Chọn tệp sẽ mở theo mặc định

Bạn nên tuỳ chỉnh tệp nào sẽ được mở để chỉnh sửa khi không gian làm việc mới được tạo bằng mẫu của bạn. Ví dụ: nếu mẫu của bạn dành cho một trang web cơ bản, bạn nên mở các tệp HTML, JavaScript và CSS chính.

Để tuỳ chỉnh tệp nào sẽ mở theo mặc định, hãy cập nhật tệp .idx/dev.nix (không phải tệp idx-template.nix!) để thêm một hook không gian làm việc onCreate có thuộc tính openFiles, chẳng hạn như:

# .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 = { ... };
  };
}

Tạo không gian làm việc mới từ mẫu của bạn

Cách đơn giản nhất để thử nghiệm mẫu của bạn từ đầu đến cuối là tạo một không gian làm việc mới bằng mẫu đó. Hãy truy cập đường liên kết sau, thay thế ví dụ này bằng URL kho lưu trữ GitHub của mẫu:

https://idx.google.com/new?template=https://github.com/my-org/my-repo

Bạn có thể bao gồm một nhánh và thư mục con nếu muốn. Tất cả những yêu cầu sau đây đều hợp lệ, miễn là chúng có thể truy cập công khai:

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

Đây cũng là URL bạn sẽ chia sẻ với người khác để họ có thể sử dụng mẫu mới của bạn hoặc URL mà bạn sẽ liên kết từ nút "Mở trong IDX".

Sau khi bạn xác nhận rằng mẫu của mình hoạt động như dự kiến, hãy xuất bản mẫu đó lên kho lưu trữ GitHub và chia sẻ cùng một đường liên kết mà bạn đã sử dụng khi tạo không gian làm việc để kiểm thử.

Để người dùng dễ dàng tìm thấy mẫu của bạn hơn nữa, hãy thêm nút"Mở trong IDX" vào tệp README của trang web hoặc kho lưu trữ của bạn.