Benutzerdefinierte Vorlage erstellen

IDX bietet eine große Auswahl an integrierten Vorlagen erstellen, die alle Dateien, System Pakete (z.B. Compiler) und Erweiterungen, die ein Nutzer schnell in eine Sprache oder ein Framework einsteigen.

Sie können auch eigene, vom Nutzer konfigurierbare Vorlagen erstellen. Beispiel:

• Wenn Sie ein eigenes Framework, eine eigene Bibliothek oder einen eigenen Dienst erstellen, haben Sie folgende Möglichkeiten: So können Ihre Nutzer schnell mit Ihrer Technologie loslegen, und dabei den Browser mit der vollen Leistung einer cloudbasierten virtuellen Maschine nutzen.

• Wenn Sie einen bevorzugten Technology Stack für Ihre Projekte haben, können Sie Ihren eigenen Prozess zum Starten neuer Projekte mit einer benutzerdefinierten Vorlage vereinfachen.

• Wenn du anderen Lehrkräften gibst, z. B. in einem Codelab, kannst du die ersten Schritte für Ihre Schüler, indem Sie die für Ihr Codelab als benutzerdefinierte Vorlage.

Sobald Sie eine benutzerdefinierte Vorlage erstellt haben, können Sie einen Link erstellen für es auf Ihrer Website platzieren möchten, das Git-Repository README. Datei, Paketdetailseite (z.B. in NPM) oder an anderen Stellen, an denen Nutzer Ihre Technologie nutzen möchten.

Hinweis :Sie können auch durch Klonen einen Link erstellen, über den Nutzer einen neuen Arbeitsbereich erstellen können. Ein Git-Repository, das weniger konfigurierbar ist als das Erstellen Ihres eigenen IDX Vorlage, erfordert aber keine Änderungen am Git-Repository.

Vorbereitung

Bevor Sie loslegen, sollten Sie sich mit der Anpassung des Umgebung mit .idx/dev.nix-Dateien.

Für Vorlagen wird auch die Sprache Nix verwendet, Sie können also einige Grundlagen auffrischen oder sie als Referenz Referenz.

Struktur der Vorlagendatei

Eine Vorlage ist ein öffentliches GitHub-Repository (oder ein Ordner oder Zweig in einem Repository) das mindestens zwei Dateien enthält:

• <ph type="x-smartling-placeholder">

  </ph> <ph type="x-smartling-placeholder">

  </ph> Neuen Arbeitsbereich aus einer benutzerdefinierten Vorlage erstellen

  idx-template.json enthält die Metadaten für die Vorlage, einschließlich: der für Nutzer sichtbare Name, die Beschreibung und die Parameter, konfigurieren Sie die Vorlage. Sie können Ihren Nutzern z. B. die Wahl zwischen verschiedenen Programmiersprachen und Beispiele für Anwendungsfälle. IDX nutzt um die UI vorzubereiten, die Nutzern angezeigt wird, wenn sie aus der Vorlage einen neuen Arbeitsbereich erstellen.

• idx-template.nix ist eine Datei, die mit der Nix- Sprache, die eine Bash-Shell enthält (in einer Nix-Funktion eingebettet), das für Folgendes zuständig ist:

  1. Arbeitsverzeichnis des neuen Arbeitsbereichs erstellen und
  2. Umgebung durch Erstellen einer .idx/dev.nix-Datei einrichten Beachten Sie, dass können Sie auch einfach ein Projekt-Scaffolding-Tool wie flutter create ausführen oder in diesem Skript npm init oder führen Sie ein benutzerdefiniertes Skript aus, das in Go, Python, Node.js oder eine andere Sprache verwenden.

  Diese Datei wird mit den vom Nutzer angegebenen Parametern ausgeführt wenn sie die Vorlage konfiguriert haben.

Neben diesen beiden Dateien können weitere Dateien zur Verwendung in idx-template.nix, um die Vorlage zu instanziieren. Zum Beispiel könnten Sie die endgültige .idx/dev.nix-Datei oder sogar das gesamte Gerüst Dateien direkt im Repository.

Einfaches Beispiel: Öffentliches GitHub-Repository in eine Vorlage umwandeln

Bevor Sie die Details zur Definition von idx-template.json und idx-template.nix, ist eine einfache Beispielvorlage nützlich, die:

• Keine vom Nutzer konfigurierbaren Parameter
• Es kopiert einfach alle Dateien in Ihrem Vorlagen-Repository (mit Ausnahme der beiden idx-template Dateien) in den Arbeitsbereich des Nutzers verschieben. Es sollte bereits eine Unterordner „.idx“ mit einer Datei dev.nix, die die Umgebung definiert.

Das Hinzufügen der folgenden Dateien zu einem beliebigen öffentlichen GitHub-Repository (oder Unterordner oder verwandelt dieses Repository effektiv in eine IDX-Vorlage.

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

Hinweis: Zusätzlich zu $out können Sie die ID des neuen Arbeitsbereichs auch mit $WS_NAME.

Zusätzliche Systempakete im Skript bootstrap verwenden

Im vorherigen Beispiel werden nur grundlegende POSIX-Befehle verwendet, um Dateien in die rechte Für das Skript bootstrap Ihrer Vorlage sind möglicherweise zusätzliche Binärdateien erforderlich installiert, z. B. git, node oder python3.

Sie können zusätzliche Systempakete für Ihr Bootstrap-Skript verfügbar machen, indem Sie indem Sie packages in der Datei idx-template.nix angeben, Arbeitsbereich mit zusätzlichen Systempaketen anpassen durch Hinzufügen zum packages in seiner dev.nix-Datei.

Hinweis: idx-template.nix verwendet immer die stable-23.11 Nix. Kanal

Hier ist ein Beispiel für das Hinzufügen von pkgs.nodejs, das Binärdateien wie node, npx und 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"
  ''
}

Wichtig: Das Bootstrap-Skript darf nicht interaktiv sein. Warten, bis der Nutzer Eingabe wird die Vorlage nicht richtig instanziiert.

Benutzerdefinierte Parameter hinzufügen

Damit Nutzer den Startpunkt für ihr neues Projekt anpassen können, haben Sie folgende Möglichkeiten: entweder mehrere Vorlagen oder eine einzelne Vorlage mit Parametern. Dies ist eine gute Option, wenn Ihre Startpunkte sich nur unterscheiden. Werte, die an ein CLI-Tool übergeben werden (z. B. --language=js im Vergleich zu --language=ts).

So fügen Sie Parameter hinzu:

1. Parameter im params-Objekt der idx-template.json beschreiben Metadatendatei. IDX verwendet Informationen in dieser Datei, um die UI vorzubereiten wie Kontrollkästchen, Dropdown-Menüs und Textfelder, die Nutzern Ihrer Website Vorlage.
2. idx-template.nix-Bootstrap aktualisieren, um die vom Nutzer ausgewählten Werte zu verwenden während Sie die Vorlage instanziieren.

Beschreiben Sie den Parameter in idx-template.json

Hier ist ein Beispiel für das Hinzufügen eines enum-Parameters, der in IDX entweder als Dropdown-Menü oder Optionsfeldgruppe, je nach Anzahl der Optionen:

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

Da zwei Werte vorhanden sind (JavaScript und TypeScript), gibt die Benutzeroberfläche eine Optionsfeldgruppe für die beiden Optionen und übergeben Sie entweder den Wert ts oder js an das Skript idx-template.nix.

Jedes Parameterobjekt hat die folgenden Eigenschaften:

PROPERTY	TYP	BESCHREIBUNG
id	string	Die eindeutige ID des Parameters, ähnlich einem Variablennamen.
Name	string	Der Anzeigename für diesen Parameter.
Typ	string	Gibt die UI-Komponente an, die für diesen Parameter verwendet werden soll, sowie den Datentyp, der an das Bootstrap-Skript übergeben werden soll. Gültige Werte sind: "enum": zeigt eine Drop-down- oder Optionsfeldgruppe an und übergibt ein string an den Bootstrap. "boolean" – zeigt ein Kästchen an und übergibt true oder false "text" – zeigt ein Textfeld an und übergibt ein string-Element
Optionen	object	Bei enum-Parametern stellt dies die Optionen dar, die Nutzern angezeigt werden. Beispiel: Wenn die Optionen {"js": "JavaScript", ...} lauten, „JavaScript“ wird als Option angezeigt. Wenn diese Option ausgewählt ist, lautet der Wert dieses Parameters js.
Standard	string oder boolean	Legt den Anfangswert in der Benutzeroberfläche fest. Für enum-Parameter muss dies einer der Schlüssel in options sein. Für boolean-Parameter sollte dies entweder true oder false sein.
erforderlich	boolean	Gibt an, dass dieser Parameter erforderlich ist.

Parameterwerte in idx-template.nix verwenden

Nachdem Sie das params-Objekt in der Datei idx-template.json definiert haben, können Sie mit der Anpassung des Bootstrap-Skripts auf Basis der Parameterwerte, auswählen.

Wenn Sie anhand des Beispiels im vorherigen Abschnitt mit der ID language, die eine Enum mit den möglichen Werten ts oder js ist, können Sie sieht es so aus:

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

Ein weiteres gängiges Muster besteht darin, Inhalte je nach -Wert einer Zeichenfolge. Das vorherige Beispiel könnte auch so geschrieben werden:

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

Wichtig: Erstellen Sie immer eine .idx/dev.nix-Datei im $out. als Teil des bootstrap-Skripts erstellt. Wenn der generierte Arbeitsbereich die Umgebung abhängig von den vom Nutzer konfigurierten Parametern (z.B. Systempakete oder den onCreate-Hook anpassen, können Sie Zeichenfolgenmanipulation in Nix oder rufen Sie eine Vorlagen-Engine wie jinja2.

Auswählen, welche Dateien standardmäßig geöffnet werden sollen

Sie können festlegen, welche Dateien zur Bearbeitung geöffnet werden sollen, wenn Sie Arbeitsbereiche werden mit Ihrer Vorlage erstellt. Wenn Ihre Vorlage z. B. für einer einfachen Website handelt, können Sie die Haupt-HTML-, JavaScript- und CSS-Dateien öffnen.

Wenn du anpassen möchtest, welche Dateien standardmäßig geöffnet werden sollen, aktualisiere die Datei .idx/dev.nix (nicht Ihre idx-template.nix-Datei!), um einen onCreate-Arbeitsbereich-Hook einzubinden. mit einem openFiles-Attribut. Beispiel:

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

Symbol für Standardarbeitsbereich auswählen

Sie können das Standardsymbol für Arbeitsbereiche auswählen, die mit Ihrer Vorlage erstellt wurden. indem Sie eine PNG-Datei mit dem Namen icon.png neben die Datei dev.nix im .idx.

Hinweis: Die Datei idx-template.json enthält auch ein optionales icon-Attribut. die auf eine öffentliche PNG- oder SVG-URL verweisen sollte (falls angegeben). Dieses Feld ist nicht in IDX verwendet, werden aber wahrscheinlich in Zukunft zusammen mit anderen Vorlagenmetadaten.

Neuen Arbeitsbereich aus Vorlage erstellen

Die einfachste Methode, Ihre Vorlage durchgängig zu testen, ist das Erstellen eines neuen Arbeitsbereichs. damit nichts. Rufen Sie den folgenden Link auf. Ersetzen Sie dabei das Beispiel durch das GitHub-Repository-URL:

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

Optional können Sie einen Zweig und einen Unterordner hinzufügen. Alle der folgenden Optionen sind gültig sein, solange sie öffentlich zugänglich sind:

• 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

Geben Sie diese URL auch an andere Personen weiter, damit diese Ihr neues oder der URL aus Ihrem „In IDX öffnen“ .

---

Vorlage teilen

Sobald Sie sich vergewissert haben, dass sich Ihre Vorlage wie erwartet verhält, können Sie sie auf einem GitHub-Repository und teilen Sie denselben Link, den Sie beim Erstellen eines Arbeitsbereichs verwendet haben. für Testzwecke.

Damit Nutzer Ihre Vorlage noch einfacher finden können, fügen Sie eine "Öffnen in IDX&quot; Schaltfläche zur README-Datei auf Ihrer Website oder im Repository.