Amazon CodeCatalyst 不再向新客戶開放。現有客戶可以繼續正常使用該服務。如需詳細資訊，請參閱[如何從 CodeCatalyst 遷移](migration.md)。

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用前端精靈修改藍圖功能
<a name="wizard-bp"></a>

CodeCatalyst 上的藍圖選擇精靈是由 `blueprint.ts` 檔案中的`Options`界面自動產生。前端精靈支援`Options`使用 [JSDOC 樣式註解和標籤的藍圖修改和](https://jsdoc.app/about-getting-started.html)功能。您可以使用 JSDOC 樣式註解和標籤來執行任務。例如，您可以選取選項上方顯示的文字、啟用輸入驗證等功能，或使選項可折疊。精靈的運作方式是解譯從`Options`界面的 TypeScript 類型產生的抽象語法樹 (AST)。精靈會自動將自己設定為盡可能最佳描述的類型。不支援所有類型。其他支援的類型包括區域選擇器和環境選擇器。

以下是使用 JSDOC 註解和標籤搭配藍圖 的精靈範例`Options`：

```
export interface Options {
  /**
   * What do you want to call your new blueprint?
   * @validationRegex /^[a-zA-Z0-9_]+$/
   * @validationMessage Must contain only upper and lowercase letters, numbers and underscores
   */
  blueprintName: string;

  /**
   * Add a description for your new blueprint.
   */
   description?: string;

   /**
    * Tags for your Blueprint:
    * @collapsed true
    */
  tags?: string[];
}
```

根據`camelCase`預設，`Options`界面的每個選項的顯示名稱會出現在 中。JSDOC 樣式註解中的純文字會在精靈中的 選項上方顯示為文字。

**Topics**
+ [支援的標籤](#supported-tags-bp)
+ [支援的 TypeScript 類型](#supported-typescript-bp)
+ [在合成期間與使用者通訊](#communication-mid-synthesis)

## 支援的標籤
<a name="supported-tags-bp"></a>

前端精靈`Options`中的自訂藍圖支援下列 JSDOC 標籤。

### @inlinePolicy ./path/to/policy/file.json
<a name="inline-policy-tag"></a>
+ **需要** - 選項為類型 `Role`。
+ **用量** - 可讓您傳達角色所需的內嵌政策。`policy.json` 路徑預期位於原始程式碼下。當您需要角色的自訂政策時，請使用此標籤。
+ **相依性** - `blueprint-cli 0.1.12` 及更高版本
+ **範例** - `@inlinePolicy ./deployment-policy.json`

```
environment: EnvironmentDefinition{
    awsAccountConnection: AccountConnection{
      /**
       * @inlinePolicy ./path/to/deployment-policy.json
       */
      cdkRole: Role[];
    };
   };
```

### @trustPolicy ./path/to/policy/file.json
<a name="trust-policy-tag"></a>
+ **需要** - 選項為類型 `Role`。
+ **用量** - 可讓您傳達角色所需的信任政策。`policy.json` 路徑預期位於原始程式碼下。當您需要角色的自訂政策時，請使用此標籤。
+ **相依性** - `blueprint-cli 0.1.12` 及更高版本
+ **範例** - `@trustPolicy ./trust-policy.json`

```
environment: EnvironmentDefinition{
    awsAccountConnection: AccountConnection{
      /**
       * @trustPolicy ./path/to/trust-policy.json
       */
      cdkRole: Role[];
    };
   };
```

### @validationRegex Regex 表達式
<a name="validation-regex-tag"></a>
+ **需要** - 選項為字串。
+ **用量** - 使用指定的 regex 表達式對 選項執行輸入驗證，並顯示 `@validationMessage`。
+ **範例** - `@validationRegex /^[a-zA-Z0-9_]+$/`
+ **建議** - 與 搭配使用`@validationMessage`。驗證訊息預設為空白。

### @validationMessage 字串
<a name="validation-message-tag"></a>
+ **需要** - `@validationRegex`或其他錯誤才能檢閱用量。
+ **用量** - 顯示`@validation*`失敗時的驗證訊息。
+ **範例** - `@validationMessage Must contain only upper and lowercase letters, numbers, and underscores`。
+ **建議** - 與 搭配使用`@validationMessage`。驗證訊息預設為空白。

### @collapsed 布林值 （選用）
<a name="collapsed-boolean-tag"></a>
+ **需要** - 不適用
+ **用量** - 允許可折疊子選項的布林值。如果有折疊的註釋，則其預設值為 true。將 值設定為 會`@collapsed false`建立最初開啟的可摺疊區段。
+ **範例** - `@collapsed true`

### @displayName 字串
<a name="display-name-tag"></a>
+ **需要** - 不適用
+ **Usage** - 變更選項顯示名稱。允許顯示名稱使用 camelCase 以外的格式。
+ **範例** - `@displayName Blueprint Name`

### @displayName 字串
<a name="display-name-tag"></a>
+ **需要** - 不適用
+ **用量** - 變更選項顯示名稱。允許顯示名稱使用 [camelCase](https://en.wikipedia.org/wiki/Camel_case) 以外的格式。
+ **範例** - `@displayName Blueprint Name`

### @defaultEntropy 號碼
<a name="default-entropy-tag"></a>
+ **需要** - 選項為字串。
+ **用量** - 將指定長度的隨機英數字串附加到 選項。
+ **範例** - `@defaultEntropy 5`

### @placeholder 字串 （選用）
<a name="placeholder-tag"></a>
+ **需要** - 不適用
+ **用量** - 變更預設文字欄位預留位置。
+ **範例** - `@placeholder type project name here`

### @textArea 號碼 （選用）
<a name="text-area-tag"></a>
+ **需要** - 不適用
+ **用量** - 將字串輸入轉換為文字區域元件，以用於較大的文字區段。新增數字可定義列數。預設為五列。
+ **範例** - `@textArea 10`

### @hidden 布林值 （選用）
<a name="hidden-tag"></a>
+ **需要** - 不適用
+ **用量** - 除非驗證檢查失敗，否則隱藏使用者的檔案。預設值為 true。
+ **範例** - `@hidden`

### @button 布林值 （選用）
<a name="button-tag"></a>
+ **需要** - 不適用
+ **用量** - 註釋必須位於布林值屬性上。新增選擇時將合成為 true 的按鈕。不是切換。
+ **範例** - `buttonExample: boolean;`

  ```
  /**
    * @button
    */
  buttonExample: boolean;
  ```

### @showName 布林值 （選用）
<a name="show-name-tag"></a>
+ **需要** - 不適用
+ **用量** - 只能用於 帳戶連線類型。顯示隱藏的名稱輸入。預設為 `default_environment`。
+ **範例** - `@showName true`

  ```
  /**
    * @showName true
    */
  accountConnection: AccountConnection<{
      ...
  }>;
  ```

### @showEnvironmentType 布林值 （選用）
<a name="show-environment-tag"></a>
+ **需要** - 不適用
+ **用量** - 只能用於 帳戶連線類型。顯示隱藏的環境類型下拉式選單。所有連線預設為 `production`。選項為**非生產**或**生產**。
+ **範例** - `@showEnvironmentType true`

  ```
  /**
    * @showEnvironmentType true
    */
  accountConnection: AccountConnection<{
      ...
  }>;
  ```

### @forceDefault 布林值 （選用）
<a name="force-default-tag"></a>
+ **需要** - 不適用
+ **用量** - 使用藍圖作者提供的預設值，而不是使用者先前使用的值。
+ **範例** - `forceDeafultExample: any;`

  ```
  /**
    * @forceDefault
    */
  forceDeafultExample: any;
  ```

### @requires blueprintName
<a name="requires-tag"></a>
+ **需要** - 註釋`Options`界面。
+ **用量** - 警告使用者將指定的 新增至`blueprintName`專案，作為目前藍圖的需求。
+ **範例** - `@requires '@amazon-codecatalyst/blueprints.blueprint-builder'`

  ```
  /*
   * @requires '@amazon-codecatalyst/blueprints.blueprint-builder'
   */
  export interface Options extends ParentOptions {
  ...
  ```

### @filter regex
<a name="filter-regex-tag"></a>
+ **需要** - 註釋 `Selector`或 `MultiSelect` 界面。
+ **用量** - 篩選精靈中的下拉式清單，使其選項符合指定的 regex。
+ **範例** - `@filter /blueprintPackageName/`

  ```
   /**
       * @filter /myPackageName/
       */
      blueprintInstantiation?: Selector<BlueprintInstantiation>;
  ...
  ```

## 支援的 TypeScript 類型
<a name="supported-typescript-bp"></a>

前端精靈`Options`中的自訂藍圖支援下列 TypeScript 類型。

### Number
<a name="number-ts-tag"></a>
+ **需要** - 選項為類型 `number`。
+ **用量** - 產生數字輸入欄位。
+ **範例** - `age: number`

```
{
  age: number
  ...
}
```

### 字串
<a name="string-ts-tag"></a>
+ **需要** - 選項為類型 `string`。
+ **用量** - 產生字串輸入欄位。
+ **範例** - `name: string`

```
{
  age: string
  ...
}
```

### 字串清單
<a name="string-list-ts-tag"></a>
+ **需要** - 選項為類型 的陣列`string`。
+ **用量** - 產生字串清單輸入。
+ **範例** - `isProduction: boolean`

```
{
  isProduction: boolean
  ...
}
```

### Checkbox
<a name="checkbox-ts-tag"></a>
+ **需要** - 選項為 `boolean`。
+ **用量** - 產生核取方塊。
+ **範例** - `isProduction: boolean`

```
{
  isProduction: boolean
  ...
}
```

### 無線電
<a name="radio-ts-tag"></a>
+ **需要** - 選項為三個或更少字串的聯集。
+ **用量** - 產生選取的無線電。
**注意**  
有四個或更多項目時，此類型會轉譯為下拉式清單。
+ **範例** - `color: 'red' | 'blue' | 'green'`

```
{
  color: 'red' | 'blue' | 'green'
  ...
}
```

### 下拉式清單
<a name="dropdown-ts-tag"></a>
+ **需要** - 選項為四個或更多字串的聯集。
+ **用量** - 產生下拉式清單。
+ **範例** - `runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'`

```
{
  runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'
  ...
}
```

### 可擴展區段
<a name="expandable-ts-tag"></a>
+ **需要** - 選項為物件。
+ **用量** - 產生可擴展的區段。物件中的選項將巢狀在精靈的可擴展區段內。
+ **範例** - 

```
{
     expandableSectionTitle: {
         nestedString: string;
         nestedNumber: number;
     }
}
```

### 雙組
<a name="tuple-ts-tag"></a>
+ **需要** - 類型為 的選項`Tuple`。
+ **用量** - 產生鍵值付費輸入。
+ **範例** - `tuple: Tuple[string, string]>`

```
{
    tuple: Tuple[string, string]>;
    ...
}
```

### 組合清單
<a name="tuple-list-ts-tag"></a>
+ **需要** - 選項為類型 的陣列`Tuple`。
+ **用量** - 產生元組清單輸入。
+ **範例** - `tupleList: Tuple[string, string]>[]`

```
{
  tupleList: Tuple[string, string]>[];
  ...
}
```

### 選擇器
<a name="selector-ts-tag"></a>
+ **需要** - 類型為 的選項`Selector`。
+ **用量** - 產生套用至專案的來源儲存庫或藍圖下拉式清單。
+ **範例** - `sourceRepo: Selector<SourceRepository>`

```
{
    sourceRepo: Selector<SourceRepository>;
    sourceRepoOrAdd: Selector<SourceRepository | string>;
    blueprintInstantiation: Selector<BlueprintInstantiation>;
  ...
}
```

### 多選
<a name="multiselect-ts-tag"></a>
+ **需要** - 類型為 的選項`Selector`。
+ **用量** - 產生多選輸入。
+ **範例** - `multiselect: MultiSelect['A' | 'B' | 'C' | 'D' | 'E']>`

```
{
  multiselect: MultiSelect['A' | 'B' | 'C' | 'D' | 'E']>;
  ...
}
```

## 在合成期間與使用者通訊
<a name="communication-mid-synthesis"></a>

身為藍圖作者，您可以僅與驗證訊息以外的使用者進行通訊。例如，空間成員可能會檢視產生不清楚藍圖的選項組合。自訂藍圖支援透過叫用合成，將錯誤訊息傳回給使用者的能力。基本藍圖會實作預期出現明確錯誤訊息的`throwSynthesisError(...)`函數。您可以使用下列方式叫用訊息：

```
//blueprint.ts
this.throwSynthesisError({
   name: BlueprintSynthesisErrorTypes.BlueprintSynthesisError,
   message: 'hello from the blueprint! This is a custom error communicated to the user.'
})
```