Projekt IDX jest w wersji beta. Usługi i funkcje w wersji beta mogą mieć ograniczoną obsługę, a zmiany w usługach i funkcjach w wersji beta mogą być niezgodne z ich poprzednimi wersjami.

Ta strona została przetłumaczona przez Cloud Translation API.

Tworzenie szablonu niestandardowego

IDX oferuje szeroką gamę wbudowanych szablonów obejmujących wszystkie pliki, pakiety systemowe (np. kompilatory) i rozszerzenia, których użytkownik może potrzebować, aby szybko rozpocząć pracę z językiem lub platformą.

Możesz także tworzyć własne szablony, które można konfigurować przez użytkowników. Na przykład:

Jeśli tworzysz własną platformę, bibliotekę lub usługę, możesz umożliwić użytkownikom szybkie rozpoczęcie pracy z technologią bez opuszczania przeglądarki, korzystając z pełnych możliwości maszyny wirtualnej w chmurze.
Jeśli masz preferowany stos technologiczny do swoich projektów, możesz uprościć własny proces rozpoczynania nowych projektów przy użyciu szablonu niestandardowego.
Jeśli uczysz innych, na przykład w ramach ćwiczeń z programowania, możesz usunąć niektóre początkowe kroki dla uczniów, konfigurując punkt początkowy ćwiczenia jako szablon niestandardowy.

Po przygotowaniu szablonu niestandardowego możesz utworzyć dla niego link i umieścić go w swojej witrynie, pliku README repozytorium Git, na stronie szczegółów pakietu (np. w NPM) lub w innych miejscach, z których użytkownicy mogą chcieć zacząć korzystać z Twojej technologii.

Wymagania wstępne

Zanim zaczniesz, upewnij się, że wiesz, jak dostosowywać środowisko za pomocą plików .idx/dev.nix.

W szablonach używa się też języka Nix, więc możesz odświeżyć podstawowe informacje lub zachować je jako materiał pomocniczy.

Struktura pliku szablonu

Szablon to publiczne repozytorium GitHub (albo folder lub gałąź w repozytorium), które zawiera co najmniej 2 pliki:

Tworzenie nowego obszaru roboczego z użyciem szablonu niestandardowego

idx-template.json zawiera metadane szablonu, w tym jego nazwę widoczną dla użytkowników, opis i parametry dostępne dla użytkowników do jego konfigurowania. Możesz na przykład zezwolić użytkownikom na wybór jednego z wielu języków programowania lub wskazać przykładowe zastosowania. IDX wykorzystuje te informacje, aby przygotować interfejs wyświetlany użytkownikom, którzy wybiorą nowy obszar roboczy na podstawie Twojego szablonu.
idx-template.nix to plik napisany w języku Nix, który zawiera skrypt powłoki Bash (opakowany w funkcję Nix) odpowiedzialny za:
1. Utworzę katalog roboczy nowego obszaru roboczego.
2. Konfigurowanie środowiska przez utworzenie pliku .idx/dev.nix. Pamiętaj, że w tym skrypcie możesz też uruchomić narzędzie do tworzenia rusztowań projektu, takie jak flutter create lub npm init, albo własny skrypt napisany w języku Go, Python, Node.js lub innym.
Ten plik zostanie uruchomiony z parametrami określonymi przez użytkownika podczas konfigurowania szablonu.

Obok tych 2 plików można dołączyć także inne pliki do wykorzystania w idx-template.nix na potrzeby utworzenia instancji szablonu. Możesz na przykład uwzględnić końcowy plik .idx/dev.nix, a nawet umieścić wszystkie pliki rusztowania bezpośrednio w repozytorium.

Podstawowy przykład: przekształcenie dowolnego publicznego repozytorium GitHub w szablon

Zanim przejdziemy do szczegółów definicji znaczników idx-template.json i idx-template.nix, warto przyjrzeć się podstawowym szablonom przykładowym, który:

Nie zawiera parametrów, które można skonfigurować przez użytkownika
Wystarczy skopiować wszystkie pliki z repozytorium szablonów (oprócz dwóch plików idx-template) do obszaru roboczego użytkownika. Powinien już istnieć podfolder .idx z plikiem dev.nix definiującym środowisko.

Dodanie poniższych plików do dowolnego publicznego repozytorium GitHub (lub podfolderu lub gałęzi) w praktyce przekształci to repozytorium w szablon 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}
  '';
}

Używanie dodatkowych pakietów systemowych w skrypcie `bootstrap`

W poprzednim przykładzie używamy tylko podstawowych poleceń POSIX do kopiowania plików we właściwe miejsce. Skrypt bootstrap Twojego szablonu może wymagać zainstalowania dodatkowych plików binarnych, np. git, node, python3 itp.

Możesz udostępnić dodatkowe pakiety systemowe dla skryptu wczytywania, określając packages w pliku idx-template.nix (tak samo jak w przypadku dostosowania obszaru roboczego za pomocą dodatkowych pakietów systemowych) – dodając do packages w pliku dev.nix.

Oto przykład dodawania elementu pkgs.nodejs, który zawiera pliki binarne, takie jak node, npx i 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"
  ''
}

Dodaj parametry konfigurowane przez użytkownika

Aby umożliwić użytkownikom dostosowanie punktu początkowego dla nowego projektu, możesz utworzyć wiele szablonów lub jeden szablon z parametrami. Jest to świetne rozwiązanie, gdy różne punkty początkowe to różne wartości przekazywane do narzędzia interfejsu wiersza poleceń (np. --language=js i --language=ts).

Aby dodać parametry:

Opisz parametr w obiekcie params w pliku metadanych idx-template.json. IDX wykorzystuje informacje z tego pliku, aby przygotować interfejs (np. pola wyboru, menu i pola tekstowe) wyświetlany użytkownikom szablonu.
Zaktualizuj proces wczytywania idx-template.nix, aby używać wartości wybranych przez użytkownika podczas tworzenia instancji szablonu.

Opisz swój parametr w polu `idx-template.json`

Oto przykład dodawania parametru enum, który IDX wyświetla jako menu lub grupę przycisków w zależności od liczby opcji:

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

Ponieważ istnieją 2 wartości (JavaScript i TypeScript), interfejs użytkownika renderuje grupę opcji dla 2 opcji i przekazuje wartość ts lub js do skryptu idx-template.nix.

Każdy obiekt parametru ma te właściwości:

USŁUGA	TYP	OPIS
id	`string`	Unikalny identyfikator parametru podobny do nazwy zmiennej.
nazwa	`string`	Wyświetlana nazwa tego parametru.
Niestandardowy typ treści	`string`	Określa komponent interfejsu, który zostanie użyty w przypadku tego parametru, oraz typ danych, które mają być przekazywane do skryptu wczytywania. Prawidłowe wartości to: `"enum"` – pokazuje grupę rozwijaną lub opcję i przekazuje wartość `string` do wczytywania. `"boolean"` – wyświetla pole wyboru i przekazuje wartość `true` lub `false`. `"text"` – wyświetla pole tekstowe i przekazuje `string`
Opcje	`object`	W przypadku parametrów `enum` jest to opcja wyświetlania użytkowników. Przykład: jeśli opcje to `{"js": "JavaScript", ...}`, opcja „JavaScript” będzie wyświetlana jako opcja, a po jej wybraniu wartość tego parametru to `js`.
default	`string` lub `boolean`	Ustawia wartość początkową w interfejsie użytkownika. W przypadku parametrów `enum` musi to być jeden z kluczy w parametrze `options`. W przypadku parametrów `boolean` powinna to być wartość `true` lub `false`.
wymagane	`boolean`	Wskazuje, że ten parametr jest wymagany.

Używaj wartości parametrów w polu `idx-template.nix`

Po zdefiniowaniu obiektu params w pliku idx-template.json możesz zacząć dostosowywać skrypt wczytywania na podstawie wartości parametrów wybranych przez użytkownika.

Zgodnie z przykładem z poprzedniej sekcji, jeśli masz pojedynczy parametr o identyfikatorze language, który jest wyliczeniem z możliwymi wartościami ts lub js, możesz go użyć w ten sposób:

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

Innym typowym wzorcem jest warunkowe uwzględnianie treści w zależności od wartości ciągu. Inny sposób zapisu poprzedniego przykładu:

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

Wybierz pliki, które mają być domyślnie otwierane

Dobrze jest dostosować, które pliki mają być otwierane do edycji podczas tworzenia nowych obszarów roboczych w szablonie. Na przykład jeśli szablon jest przeznaczony dla podstawowej witryny, możesz otworzyć główne pliki HTML, JavaScript i CSS.

Aby określić, które pliki powinny otwierać się domyślnie, zaktualizuj plik .idx/dev.nix (nie plik idx-template.nix), aby zawierał punkt zaczepienia obszaru roboczego onCreate z atrybutem openFiles. Na przykład:

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

Tworzenie nowego obszaru roboczego na podstawie szablonu

Najprostszym sposobem na kompleksowe przetestowanie szablonu jest utworzenie z nim nowego obszaru roboczego. Kliknij ten link, zastępując przykład adresem URL repozytorium GitHub Twojego szablonu:

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

Możesz opcjonalnie dodać gałąź i podfolder. Wszystkie te warunki są prawidłowe, o ile są dostępne publicznie:

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

Jest to również adres URL, który udostępnisz innym, by mogli oni używać Twojego nowego szablonu. Adres URL, do którego prowadzi link, należy kliknąć przyciskiem „Otwórz w IDX”.

Gdy upewnisz się, że szablon działa zgodnie z oczekiwaniami, opublikuj go w repozytorium GitHub i udostępnij ten sam link, który został użyty podczas tworzenia obszaru roboczego do testowania.

Aby ułatwić użytkownikom znajdowanie Twojego szablonu, dodaj przycisk „Otwórz w IDX” do pliku README swojej witryny lub repozytorium.