โปรเจ็กต์ IDX อยู่ในเวอร์ชันเบต้า ผลิตภัณฑ์และฟีเจอร์เบต้าอาจมีการสนับสนุนแบบจำกัด และการเปลี่ยนแปลงผลิตภัณฑ์และฟีเจอร์ของรุ่นเบต้าอาจใช้ไม่ได้กับเวอร์ชันก่อนหน้า

หน้านี้ได้รับการแปลโดย Cloud Translation API

สร้างเทมเพลตที่กำหนดเอง

IDX มีเทมเพลตในตัวที่หลากหลาย ซึ่งมีไฟล์ แพ็กเกจของระบบ (เช่น คอมไพเลอร์) และส่วนขยายที่ผู้ใช้อาจจำเป็นต้องเริ่มต้นใช้งานอย่างรวดเร็วด้วยภาษาหรือเฟรมเวิร์ก

คุณอาจต้องการสร้างเทมเพลตของคุณเองซึ่งผู้ใช้กำหนดเองได้ เช่น

หากคุณกำลังสร้างเฟรมเวิร์ก ไลบรารี หรือบริการของตนเอง คุณสามารถอนุญาตให้ผู้ใช้เริ่มต้นใช้งานเทคโนโลยีของคุณได้อย่างรวดเร็วโดยไม่ต้องออกจากเบราว์เซอร์ด้วยความสามารถเต็มรูปแบบของเครื่องเสมือนในระบบคลาวด์
หากมี Technology Stack ที่ต้องการสำหรับโปรเจ็กต์ของคุณ คุณสามารถลดความซับซ้อนของกระบวนการเริ่มต้นโปรเจ็กต์ใหม่ด้วยเทมเพลตที่กำหนดเอง
หากสอนผู้อื่นผ่าน Codelab คุณนำขั้นตอนเริ่มต้นบางส่วนออกให้กับนักเรียนได้โดยกำหนดค่าจุดเริ่มต้นสำหรับ Codelab ล่วงหน้าให้เป็นเทมเพลตที่กำหนดเอง

เมื่อมีเทมเพลตที่กำหนดเองพร้อมแล้ว คุณจะสร้างลิงก์สำหรับเทมเพลตเพื่อวางในเว็บไซต์, ไฟล์ที่เก็บ Git README, หน้ารายละเอียดแพ็กเกจ (เช่น ใน NPM) หรือที่อื่นๆ ที่ผู้ใช้อาจต้องการเริ่มต้นใช้งานเทคโนโลยีของคุณ

สิ่งที่ต้องดำเนินการก่อน

ก่อนเริ่มต้นใช้งาน โปรดทำความคุ้นเคยกับการปรับแต่งสภาพแวดล้อมด้วยไฟล์ .idx/dev.nix

เทมเพลตยังใช้ภาษา Nix ด้วย คุณจึงอาจต้องการทบทวนความรู้พื้นฐานบางอย่างหรือเก็บไว้ใช้เพื่อเป็นข้อมูลอ้างอิง

โครงสร้างไฟล์เทมเพลต

เทมเพลตคือที่เก็บ GitHub สาธารณะ (หรือโฟลเดอร์หรือสาขาในที่เก็บ) ที่มีไฟล์อย่างน้อย 2 ไฟล์ ได้แก่

การสร้างพื้นที่ทำงานใหม่จากเทมเพลตที่กำหนดเอง

idx-template.json จะมีข้อมูลเมตาสำหรับเทมเพลต ซึ่งรวมถึงชื่อ คำอธิบาย และพารามิเตอร์ที่ผู้ใช้มองเห็นได้ ซึ่งสามารถใช้กำหนดค่าเทมเพลตได้ ตัวอย่างเช่น คุณสามารถอนุญาตให้ผู้ใช้เลือกภาษาโปรแกรมต่างๆ หรือกรณีการใช้งานตัวอย่าง IDX ใช้ข้อมูลนี้เพื่อเตรียม UI ที่แสดงต่อผู้ใช้เมื่อเลือกที่จะสร้างพื้นที่ทำงานใหม่จากเทมเพลต
idx-template.nix คือไฟล์ที่เขียนด้วยภาษา Nix ซึ่งมีสคริปต์ Bash Shell (รวมไว้ในฟังก์ชัน Nix) ซึ่งมีหน้าที่ดังต่อไปนี้
1. สร้างไดเรกทอรีการทำงานและ
2. ตั้งค่าสภาพแวดล้อมโดยการสร้างไฟล์ .idx/dev.nix โปรดทราบว่าคุณสามารถเรียกใช้เครื่องมือโครงข่ายโปรเจ็กต์ เช่น flutter create หรือ npm init ในสคริปต์นี้ หรือเรียกใช้สคริปต์ที่กำหนดเองที่เขียนด้วย Go, Python, Node.js หรือภาษาอื่นได้อีกด้วย
ระบบจะเรียกใช้ไฟล์นี้ด้วยพารามิเตอร์ที่ผู้ใช้ระบุเมื่อกำหนดค่าเทมเพลต

ไฟล์อื่นๆ อาจรวมอยู่กับทั้ง 2 ไฟล์นี้ได้ เพื่อใช้ใน idx-template.nix เพื่อสร้างเทมเพลต ตัวอย่างเช่น คุณอาจรวมไฟล์ .idx/dev.nix สุดท้ายหรือรวมไฟล์นั่งร้านทั้งหมดไว้ในที่เก็บโดยตรง

ตัวอย่างพื้นฐาน: เปลี่ยนที่เก็บ GitHub สาธารณะเป็นเทมเพลต

ก่อนจะดูรายละเอียดเกี่ยวกับวิธีกำหนด idx-template.json และ idx-template.nix คุณควรดูตัวอย่างเทมเพลตพื้นฐานที่มีลักษณะดังนี้

ไม่มีพารามิเตอร์ที่ผู้ใช้กำหนดค่าได้
เพียงแค่คัดลอกไฟล์ทั้งหมดในที่เก็บเทมเพลต (ยกเว้น idx-template 2 ไฟล์) ลงในพื้นที่ทำงานของผู้ใช้ ควรมีโฟลเดอร์ย่อย .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 หรืออื่นๆ

คุณทำให้แพ็กเกจระบบเพิ่มเติมพร้อมใช้งานกับสคริปต์ Bootstrap ได้โดยระบุ packages ในไฟล์ idx-template.nix เหมือนที่คุณ ปรับแต่งพื้นที่ทำงานด้วยแพ็กเกจระบบเพิ่มเติม โดยเพิ่ม 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)

หากต้องการเพิ่มพารามิเตอร์ คุณจะต้องทำดังนี้

อธิบายพารามิเตอร์ในออบเจ็กต์ params ของไฟล์ข้อมูลเมตา idx-template.json IDX ใช้ข้อมูลในไฟล์นี้เพื่อเตรียม UI (เช่น ช่องทำเครื่องหมาย เมนูแบบเลื่อนลง และช่องข้อความ) ที่แสดงต่อผู้ใช้เทมเพลต
อัปเดต Bootstrap ของ 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
    }
  ]
}

เนื่องจากมี 2 ค่า (JavaScript และ TypeScript) UI จะแสดงกลุ่มปุ่มตัวเลือกสำหรับตัวเลือก 2 รายการ และส่งค่า ts หรือ js ไปยังสคริปต์ idx-template.nix

ออบเจ็กต์พารามิเตอร์แต่ละรายการมีพร็อพเพอร์ตี้ต่อไปนี้

พร็อพเพอร์ตี้	TYPE	คำอธิบาย
id	`string`	รหัสที่ไม่ซ้ำกันของพารามิเตอร์ ซึ่งคล้ายกับชื่อตัวแปร
ชื่อ	`string`	ชื่อที่แสดงของพารามิเตอร์นี้
ประเภท	`string`	ระบุคอมโพเนนต์ UI ที่จะใช้สำหรับพารามิเตอร์นี้ และประเภทข้อมูลที่จะส่งต่อไปยังสคริปต์ Bootstrap ค่าที่ใช้ได้มีดังนี้ `"enum"` - แสดงเมนูแบบเลื่อนลงหรือกลุ่มปุ่มตัวเลือก และส่ง `string` ไปยัง Bootstrap `"boolean"` - แสดงช่องทำเครื่องหมายและบัตร `true` หรือ `false` `"text"` - แสดงช่องข้อความและส่งผ่าน `string`
ตัวเลือก	`object`	สำหรับพารามิเตอร์ `enum` พารามิเตอร์นี้หมายถึงตัวเลือกที่จะแสดงผู้ใช้ เช่น หากตัวเลือกคือ `{"js": "JavaScript", ...}` ก็จะแสดง "JavaScript" เป็นตัวเลือก และเมื่อเลือกค่าของพารามิเตอร์นี้จะเป็น `js`
ค่าเริ่มต้น	`string` หรือ `boolean`	ตั้งค่าเริ่มต้นใน UI สำหรับพารามิเตอร์ `enum` ค่านี้ต้องเป็นคีย์ใน `options` สำหรับพารามิเตอร์ `boolean` ค่านี้ควรเป็น `true` หรือ `false`
จำเป็น	`boolean`	บ่งบอกว่าต้องมีพารามิเตอร์นี้

ใช้ค่าพารามิเตอร์ใน `idx-template.nix`

หลังจากกำหนดออบเจ็กต์ params ในไฟล์ idx-template.json แล้ว คุณจะเริ่มปรับแต่งสคริปต์ Bootstrap ตามค่าพารามิเตอร์ที่ผู้ใช้เลือกได้

จากตัวอย่างในส่วนก่อนหน้า หากคุณมีพารามิเตอร์เดียวที่มีรหัส language ซึ่งเป็น enum ที่มีค่าที่เป็นไปได้ 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" }

สำคัญ: อย่าลืมสร้างไฟล์ .idx/dev.nix ในไดเรกทอรี $out ซึ่งเป็นส่วนหนึ่งของสคริปต์ bootstrap เสมอ หากสภาพแวดล้อมของพื้นที่ทำงานที่สร้างขึ้นจำเป็นต้องแตกต่างกันไปตามพารามิเตอร์ที่ผู้ใช้กำหนดค่า (เช่น รวมแพ็กเกจระบบที่แตกต่างกัน หรือปรับแต่งฮุก onCreate) คุณสามารถใช้การจัดการสตริงใน Nix หรือเรียกไปยังเครื่องมือเทมเพลต เช่น jinja2

เลือกไฟล์ที่ควรเปิดโดยค่าเริ่มต้น

คุณควรปรับแต่งไฟล์ที่ควรเปิดเพื่อแก้ไขเมื่อมีการสร้างพื้นที่ทำงานใหม่ด้วยเทมเพลต ตัวอย่างเช่น หากเทมเพลตมีไว้สำหรับเว็บไซต์พื้นฐาน คุณอาจต้องการเปิดไฟล์ 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 = { ... };
  };
}

สร้างพื้นที่ทำงานใหม่จากเทมเพลต

วิธีที่ง่ายที่สุดในการทดสอบเทมเพลตตั้งแต่ต้นจนจบคือการสร้างพื้นที่ทำงานใหม่ด้วยเทมเพลตดังกล่าว ไปที่ลิงก์ต่อไปนี้ โดยแทนที่ตัวอย่างด้วย URL ที่เก็บ 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

และยังเป็น URL ที่คุณจะแชร์กับผู้อื่นเพื่อให้พวกเขาใช้เทมเพลตใหม่ของคุณ หรือ URL ที่คุณจะลิงก์จากปุ่ม "เปิดใน IDX" ได้ด้วย

เมื่อยืนยันแล้วว่าเทมเพลตทำงานตามที่คาดไว้ ให้เผยแพร่ไปยังที่เก็บ GitHub และแชร์ลิงก์เดียวกับที่คุณใช้เมื่อสร้างพื้นที่ทำงานสำหรับการทดสอบ

และเพื่อช่วยให้ผู้ใช้ค้นหาเทมเพลตได้ง่ายขึ้น โดยเพิ่มปุ่ม"เปิดใน IDX" ลงในเว็บไซต์หรือที่เก็บ README