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

Tạo mẫu tuỳ chỉnh

Firebase Studio 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à bạn cần để nhanh chóng bắt đầu với một ngôn ngữ hoặc khung.

Bạn cũng có thể khởi chạy một không gian làm việc Firebase Studio bằng cách sử dụng các mẫu Cộng đồng được lưu trữ trên GitHub. Để biết thêm thông tin về cách khởi chạy một không gian làm việc mới từ một mẫu, hãy xem phần Tạo không gian làm việc Firebase Studio.

Hầu hết người dùng sẽ sử dụng các mẫu tích hợp hoặc nhập dự án từ Git, nhưng đối với các trường hợp sử dụng nâng cao hơn, bạn có thể tạo mẫu của riêng mình:

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 bắt đầu sử dụng công nghệ của bạn 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ột máy ảo dựa trên đám mây.
Nếu có nền tảng công nghệ ưu tiên cho các dự án của mình, bạn có thể đơn giản hoá quy trình bắt đầu dự án mới bằng một mẫu tuỳ chỉnh.
Nếu dạy người khác, chẳng hạn như thông qua một hướng dẫn hoặc 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 dưới dạng một mẫu tuỳ chỉnh.

Sau khi tạo và kiểm thử 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, tệp README kho lưu trữ Git, trang chi tiết gói (ví dụ: trong NPM) hoặc bất kỳ vị trí nào khác mà bạn muốn người dùng bắt đầu sử dụng công nghệ của mình.

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

Trước khi bạn bắt đầu:

Tìm hiểu cách sử dụng tệp idx/dev.nix để tuỳ chỉnh môi trường.
Làm quen với những kiến thức cơ bản về ngôn ngữ Nix và luôn tham khảo tài liệu này.

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

Mẫu Firebase Studio là một kho lưu trữ Git công khai (hoặc thư mục hoặc nhánh trong một kho lưu trữ) chứa ít nhất hai tệp:

idx-template.json bao gồm siêu dữ liệu cho mẫu, bao gồm cả tên, nội dung mô tả và các tham số mà người dùng có thể thấy để đị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 các trường hợp sử dụng mẫu. Firebase Studio 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 một 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, chứa một tập lệnh shell Bash (được bao bọc trong một hàm Nix) có chức năng:
1. Tạo thư mục làm việc cho không gian làm việc mới.
2. Thiết lập môi trường bằng cách tạo tệp .idx/dev.nix. Xin lưu ý rằng bạn cũng có thể chỉ chạy một công cụ tạo khung dự án như flutter create hoặc npm init trong tập lệnh này, hoặc chạy một 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 bằng các tham số do người dùng chỉ định khi Firebase Studio tải 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 khởi tạo mẫu. Ví dụ: bạn có thể đưa tệp .idx/dev.nix cuối cùng hoặc thậm chí đưa tất cả các tệp giàn giáo ngay trong kho lưu trữ.

Tạo mẫu ban đầu

Để đẩy nhanh quá trình tạo mẫu, bạn nên bắt đầu bằng một trong các phương thức sau để tạo mẫu Firebase Studio mà bạn có thể tuỳ chỉnh thêm:

Biến mọi kho lưu trữ công khai trên GitHub thành một mẫu
Sử dụng mẫu chính thức hoặc mẫu do cộng đồng tạo làm cơ sở cho mẫu của bạn

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 đi vào 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 có:

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

Nếu bạn 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), thì điều này sẽ biến kho lưu trữ đó thành một mẫu 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}
  '';
}

Chuyển đến phần Tuỳ chỉnh mẫu để tìm hiểu về những thay đổi khác mà bạn có thể thực hiện để tuỳ chỉnh mẫu.

Tạo mẫu tuỳ chỉnh bằng mẫu chính thức hoặc mẫu của cộng đồng

Nhóm Firebase Studio duy trì 2 kho lưu trữ cho các mẫu Firebase Studio:

Mẫu chính thức: Đây là những mẫu mà bạn chọn trực tiếp trên trang tổng quan Firebase Studio khi tạo một ứng dụng mới.
Mẫu cộng đồng: Các mẫu này cho phép cộng đồng nguồn mở đóng góp. Để sử dụng mẫu cho cộng đồng, hãy sao chép kho lưu trữ Git của Mẫu cho cộng đồng. Bạn có thể sử dụng toàn bộ đường liên kết đến mẫu mà bạn muốn sử dụng.

Lưu ý: Để đóng góp cho cộng đồng bằng cách thêm mẫu mới hoặc cập nhật mẫu hiện có, hãy gửi yêu cầu kéo.

Cách tạo mẫu tuỳ chỉnh dựa trên một mẫu hiện có:

Quyết định mẫu nào sẽ dùng làm cơ sở cho mẫu tuỳ chỉnh của bạn, sau đó sao chép dự án.
Tuỳ chỉnh idx-template.json, idx-template.nix và .idx/dev.nix khi cần, bắt đầu bằng cách nhấp vào Tuỳ chỉnh mẫu.
Kiểm tra các thay đổi trong kho lưu trữ của bạn.
Làm theo hướng dẫn trong phần Tạo một không gian làm việc mới cho mẫu của bạn để xuất bản và kiểm thử mẫu. Nếu bạn sử dụng một kho lưu trữ lồng nhau, hãy liên kết trực tiếp đến kho lưu trữ đó trong URL. Ví dụ: nếu đang sử dụng mẫu "Vanilla Vite" của cộng đồng, bạn sẽ cung cấp và kiểm thử một không gian làm việc mới bằng URL sau:
```
https://studio.firebase.google.com/new?template=https://github.com/firebase-studio/community-templates/tree/main/vite-vanilla
```

Chuyển đến phần Tuỳ chỉnh mẫu để tìm hiểu về những thay đổi khác mà bạn có thể thực hiện để tuỳ chỉnh mẫu.

Tuỳ chỉnh mẫu

Giờ đây, khi đã tạo một mẫu cơ bản để xây dựng, bạn có thể chỉnh sửa các tệp idx-template.json, idx-template.nix và .idx/dev.nix cho phù hợp với yêu cầu của mình. Bạn nên tuỳ chỉnh các cấu hình bổ sung:

Thêm các gói hệ thống vào tập lệnh bootstrap.
Thêm các thông số mà người dùng có thể định cấu hình
Chọn những tệp sẽ mở theo mặc định
Chọn biểu tượng không gian làm việc mặc định

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

Ví dụ cơ bản chỉ sử dụng các lệnh POSIX cơ bản để sao chép tệp vào đúng vị trí. Tập lệnh bootstrap của mẫu có thể yêu cầu bạn 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 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 một không gian làm việc bằng 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 các 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, 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 phù hợp nếu các điểm bắt đầu khác nhau của bạn 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 tham số, bạn sẽ:

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. Firebase Studio 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) mà người dùng mẫu của bạn nhìn thấy.
Cập nhật quá 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ể mẫu.

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

Sau đây là ví dụ về cách thêm một tham số enum. Firebase Studio sẽ xuất hiện dưới dạng một 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ẽ hiển thị một nhóm nút chọn cho hai lựa chọn và truyền giá trị ts hoặc js đến tập lệnh idx-template.nix.

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

TÀI SẢN	LOẠI	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.
name	`string`	Tên hiển thị của thông số này.
loại	`string`	Chỉ định thành phần giao diện người dùng cần dùng cho tham số này và kiểu dữ liệu cần truyền đến tập lệnh khởi động. Các giá trị hợp lệ là: `"enum"` – Hiện một nhóm nút chọn hoặc trình đơn thả xuống và truyền một `string` đến bootstrap `"boolean"` – Hiện hộp đánh dấu và truyền `true` hoặc `false` `"text"` – Hiện một trường văn bản và truyền một `string`
tuỳ chọn	`object`	Đối với các tham số `enum`, điều này thể hiện các lựa chọn sẽ hiển thị cho người dùng. Ví dụ: nếu options là `{"js": "JavaScript", ...}`, "JavaScript" sẽ xuất hiện dưới dạng lựa chọn và khi được 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 các tham số `enum`, đây phải là một trong các khoá trong `options`. Đối với các tham số `boolean`, tham số này phải là `true` hoặc `false`.
bắt buộc	`boolean`	Cho biết rằng tham số này là bắt buộc.

Sử dụng giá trị thông 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 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 có một tham số duy nhất có giá trị nhận dạng language là một enum có các giá trị có thể có là ts hoặc js, thì bạn có thể sử dụng tham số đó 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 có điều kiện, tuỳ thuộc vào giá trị của một 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 những tệp cần mở để chỉnh sửa khi tạo không gian làm việc mới 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 có thể muốn mở các tệp HTML, JavaScript và CSS chính.

Để tuỳ chỉnh những tệp 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 lệnh gọi onCreate không gian làm việc có thuộc tính openFiles, như sau:

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

Chọn biểu tượng mặc định cho không gian làm việc

Bạn có thể chọn biểu tượng mặc định cho các không gian làm việc được tạo bằng mẫu của mình bằng cách đặt một tệp PNG có tên là icon.png bên cạnh tệp dev.nix, bên trong thư mục .idx.

Thử nghiệm mẫu trong một không gian làm việc mới

Cách đơn giản nhất để kiểm thử mẫu từ đầu đến cuối là tạo một không gian làm việc mới bằng mẫu đó. Truy cập vào đường liên kết sau, thay thế ví dụ 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ể thêm nhánh và thư mục con (không bắt buộc). Tất cả các URL sau đây đều hợp lệ, miễn là 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 mà 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 đến từ nút "Mở trong Firebase Studio".

Sau khi xác nhận rằng mẫu của bạn hoạt động như dự kiến, hãy xuất bản mẫu đó lên một kho lưu trữ trên GitHub và chia sẻ cùng một đường liên kết mà bạn đã dùng khi tạo một 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 Firebase Studio" vào trang web hoặc tệp README của kho lưu trữ.