使用前端精靈修改藍圖功能 - Amazon CodeCatalyst
支援的標籤支援的 TypeScript 類型在合成期間與使用者通訊

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

使用前端精靈修改藍圖功能

上的藍圖選取精靈由blueprint.ts檔案中的Options介面 CodeCatalyst 自動產生。前端精靈支援Options使用JSDOC樣式註解和標籤 進行藍圖的修改和功能。您可以使用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[];
}

Options 介面每個選項的顯示名稱camelCase預設為顯示在 中。JSDOC 樣式註解中的純文字會在精靈中的 選項上方顯示為文字。

支援的標籤

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

@inlinePolicy ./path/to/policy/file.json

  • 需要 - 選項為類型 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

  • 需要 - 選項為類型 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 表達式

  • 需要 - 選項 為字串。

  • 用量 - 使用指定的 regex 表達式對 選項執行輸入驗證，並顯示 @validationMessage。

  • 範例 - @validationRegex /^[a-zA-Z0-9_]+$/

  • 建議 - 搭配 使用@validationMessage。驗證訊息預設為空白。

@validationMessage string

  • 需要 - @validationRegex或其他錯誤才能檢閱用量。

  • 用量 - 顯示@validation*失敗時的驗證訊息。

  • 範例 - @validationMessage Must contain only upper and lowercase letters, numbers, and underscores。

  • 建議 - 搭配 使用@validationMessage。驗證訊息預設為空白。

@collapsed 布林值 （選用）

  • 需要 - 不適用

  • 用量 - 允許子選項折疊的布林值。如果存在摺疊註釋，則其預設值為 true。設定 值以@collapsed false建立最初開啟的可摺疊區段。

  • 範例 - @collapsed true

@displayName string

  • 需要 - 不適用

  • Usage - 變更選項顯示名稱。允許顯示名稱 camelCase 以外的格式。

  • 範例 - @displayName Blueprint Name

@displayName string

  • 需要 - 不適用

  • Usage - 變更選項顯示名稱。允許顯示名稱camelCase以外的格式。

  • 範例 - @displayName Blueprint Name

@defaultEntropy number

  • 需要 - 選項 為字串。

  • 用量 - 將指定長度的隨機英數字串附加到 選項。

  • 範例 - @defaultEntropy 5

@placeholder 字串 （選用）

  • 需要 - 不適用

  • Usage - 變更預設文字欄位預留位置。

  • 範例 - @placeholder type project name here

@textArea number （選用）

  • 需要 - 不適用

  • 用量 - 將字串輸入轉換為文字區域元件，以用於較大的文字區段。新增數字會定義列數。預設值為五列。

  • 範例 - @textArea 10

@hidden 布林值 （選用）

  • 需要 - 不適用

  • 用量 - 除非驗證檢查失敗，否則隱藏來自使用者的檔案。預設值為 true。

  • 範例 - @hidden

@button 布林值 （選用）

  • 需要 - 不適用

  • 用量 - 註釋必須位於布林屬性上。新增按鈕，當選擇時，該按鈕會合成為 true。不是切換。

  • 範例 - buttonExample: boolean;

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

@showName 布林值 （選用）

  • 需要 - 不適用

  • 用量 - 僅適用於帳戶連線類型。顯示隱藏的名稱輸入。預設為 default_environment。

  • 範例 - @showName true

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

@showEnvironmentType 布林值 （選用）

  • 需要 - 不適用

  • 用量 - 僅適用於帳戶連線類型。顯示隱藏的環境類型下拉式選單。所有連線預設為 production。選項為非生產或生產 。

  • 範例 - @showEnvironmentType true

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

@forceDefault 布林值 （選用）

  • 需要 - 不適用

  • Usage - 使用藍圖作者提供的預設值，而不是使用者先前使用的值。

  • 範例 - forceDeafultExample: any;

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

@需要 blueprintName

  • 需要 - 註釋Options介面。

  • 用量 - 警告使用者將指定新增至blueprintName專案，作為目前藍圖的需求。

  • 範例 - @requires '@amazon-codecatalyst/blueprints.blueprint-builder'

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

@filter regex

  • 需要 - 註釋 Selector或 MultiSelect 介面。

  • Usage：將精靈中的下拉式清單篩選為符合指定 regex 的選項。

  • 範例 - @filter /blueprintPackageName/

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

支援的 TypeScript 類型

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

Number

  • 需要 - 選項為類型 number。

  • 用量 - 產生數字輸入欄位。

  • 範例 - age: number

{
  age: number
  ...
}

字串

  • 需要 - 選項為類型 string。

  • Usage - 產生字串輸入欄位。

  • 範例 - name: string

{
  age: string
  ...
}

字串清單

  • 需要 - 選項 是類型 的陣列string。

  • 用量 - 產生字串清單輸入。

  • 範例 - isProduction: boolean

{
  isProduction: boolean
  ...
}

Checkbox

  • 需要 - 選項為 boolean。

  • Usage - 產生核取方塊。

  • 範例 - isProduction: boolean

{
  isProduction: boolean
  ...
}

無線電

  • 需要 - 選項為三個或更少字串的聯合。

  • 用量 - 產生選取的無線電。

    注意

    有四個或更多項目時，此類型會轉譯為下拉式清單。

  • 範例 - color: 'red' | 'blue' | 'green'

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

  • 需要 - 選項為包含四個或更多字串的聯合。

  • Usage - 產生下拉式清單。

  • 範例 - runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'

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

可擴展區段

  • 需要 - 選項 作為物件。

  • 用量 - 產生可擴展區段。物件中的選項將巢狀在精靈的可擴展區段內。

  • 範例 - 

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

雙管

  • 需要 - 類型為 的選項Tuple。

  • 用量 - 產生鍵值付費輸入。

  • 範例 - tuple: Tuple[string, string]>

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

組合清單

  • 需要 - 選項 是類型 的陣列Tuple。

  • 用量 - 產生組合清單輸入。

  • 範例 - tupleList: Tuple[string, string]>[]

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

選擇器

  • 需要 - 類型為 的選項Selector。

  • 用量 - 產生套用至專案的來源儲存庫或藍圖下拉式清單。

  • 範例 - sourceRepo: Selector<SourceRepository>

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

多選

  • 需要 - 類型為 的選項Selector。

  • 用量 - 產生多選輸入。

  • 範例 - multiselect: MultiSelect['A' | 'B' | 'C' | 'D' | 'E']>

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

在合成期間與使用者通訊

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

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