亚马逊 CodeCatalyst 不再向新买家开放。现有客户可以继续正常使用该服务。有关更多信息，请参阅 [如何从中迁移 CodeCatalyst](migration.md)。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用前端向导修改蓝图功能
CodeCatalyst 上的蓝图选择向导由 `blueprint.ts` 文件中的 `Options` 接口自动生成。前端向导支持使用 [JSDOC style comments and tags](https://jsdoc.app/about-getting-started.html) 对蓝图的 `Options` 进行修改和特征化。您可以使用 JSDOC 样式注释和标签来执行任务。例如，您可以选择选项上方显示的文本，启用输入验证等功能，或使选项可折叠。该向导的工作原理是解释从 `Options` 接口的 TypeScript 类型生成的抽象语法树（AST）。该向导会根据描述的类型自动进行配置。并非所有类型均受支持。其它支持的类型包括区域选择器和环境选择器。
以下是一个在蓝图的 `Options` 中使用 JSDOC 注释和标签的向导示例：
```
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 样式注释中的纯文本将显示为选项上方的文本。
**Topics**
+ [支持的标签](#supported-tags-bp)
+ [支持的 TypeScript 类型](#supported-typescript-bp)
+ [在合成过程中与用户交流](#communication-mid-synthesis)
## 支持的标签
前端向导中的自定义蓝图的 `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 正则表达式
+ **必需** - 字符串选项。
+ **用法** - 使用给定的正则表达式对选项执行输入验证并显示 `@validationMessage`。
+ **示例** – `@validationRegex /^[a-zA-Z0-9_]+$/`
+ **建议** - 与 `@validationMessage` 一起使用。默认情况下，验证消息为空。
### @validationMessage 字符串
+ **必需** - `@validationRegex` 或其它错误来查看用法。
+ **用法** - `@validation*` 失败时显示验证消息。
+ **示例** - `@validationMessage Must contain only upper and lowercase letters, numbers, and underscores`。
+ **建议** - 与 `@validationMessage` 一起使用。默认情况下，验证消息为空。
### @collapsed 布尔值（可选）
+ **必需** - 不适用
+ **用法** - 使子选项能够折叠的布尔值。如果存在折叠的注释，则其默认值为 true。将该值设置为 `@collapsed false` 可创建最初处于打开状态的可折叠部分。
+ **示例** – `@collapsed true`
### @displayName 字符串
+ **必需** - 不适用
+ **用法** - 更改选项的显示名称。使显示名称能够使用除 camelCase 以外的格式。
+ **示例** – `@displayName Blueprint Name`
### @displayName 字符串
+ **必需** - 不适用
+ **用法** - 更改选项的显示名称。使显示名称能够使用除 [camelCase](https://en.wikipedia.org/wiki/Camel_case) 以外的格式。
+ **示例** – `@displayName Blueprint Name`
### @defaultEntropy 数字
+ **必需** - 字符串选项。
+ **用法** - 将指定长度的随机字母数字字符串附加到选项。
+ **示例** – `@defaultEntropy 5`
### @placeholder 字符串（可选）
+ **必需** - 不适用
+ **用法** - 更改默认文本字段占位符。
+ **示例** – `@placeholder type project name here`
### @textArea 数字（可选）
+ **必需** - 不适用
+ **用法** - 将字符串输入转换为文本区域组件，用于显示较大的文本部分。添加一个数字就定义了行数。默认为五行。
+ **示例** – `@textArea 10`
### @hidden 布尔值（可选）
+ **必需** - 不适用
+ **用法** - 除非验证检查失败，否则向用户隐藏文件。默认值为 true。
+ **示例** – `@hidden`
### @button 布尔值（可选）
+ **必需** - 不适用
+ **用法** - 注释必须是布尔属性的注释。添加一个按钮，选择后将合成为 true。不是切换按钮。
+ **示例** – `buttonExample: boolean;`
```
/**
* @button
*/
buttonExample: boolean;
```
### @showName 布尔值（可选）
+ **必需** - 不适用
+ **用法** - 只能用于账户连接类型。显示隐藏的名称输入。默认值为 `default_environment`。
+ **示例** – `@showName true`
```
/**
* @showName true
*/
accountConnection: AccountConnection<{
...
}>;
```
### @showEnvironmentType 布尔值（可选）
+ **必需** - 不适用
+ **用法** - 只能用于账户连接类型。显示隐藏的环境类型下拉菜单。所有连接都默认为 `production`。选项有 **Non-production** 或 **Production**。
+ **示例** – `@showEnvironmentType true`
```
/**
* @showEnvironmentType true
*/
accountConnection: AccountConnection<{
...
}>;
```
### @forceDefault 布尔值（可选）
+ **必需** - 不适用
+ **用法** - 使用蓝图作者提供的默认值，而不是用户之前使用的值。
+ **示例** – `forceDeafultExample: any;`
```
/**
* @forceDefault
*/
forceDeafultExample: any;
```
### @requires blueprintName
+ **必需** - `Options` 接口注释。
+ **用法** - 警告用户将指定的 `blueprintName` 添加到项目中，作为当前蓝图的要求。
+ **示例** – `@requires '@amazon-codecatalyst/blueprints.blueprint-builder'`
```
/*
* @requires '@amazon-codecatalyst/blueprints.blueprint-builder'
*/
export interface Options extends ParentOptions {
...
```
### @filter regex
+ **必需** - `Selector` 或 `MultiSelect` 接口注释。
+ **用法** - 将向导中的下拉菜单筛选为与指定正则表达式匹配的选项。
+ **示例** – `@filter /blueprintPackageName/`
```
/**
* @filter /myPackageName/
*/
blueprintInstantiation?: Selector;
...
```
## 支持的 TypeScript 类型
前端向导中的自定义蓝图的 `Options` 支持以下 TypeScript 类型。
### 数字
+ **必需** - `number` 类型选项。
+ **用法** - 生成数字输入字段。
+ **示例** – `age: number`
```
{
age: number
...
}
```
### 字符串
+ **必需** - `string` 类型选项。
+ **用法** - 生成字符串输入字段。
+ **示例** – `name: string`
```
{
age: string
...
}
```
### 字符串列表
+ **必需** - `string` 类型数组选项。
+ **用法** - 生成字符串列表输入。
+ **示例** – `isProduction: boolean`
```
{
isProduction: boolean
...
}
```
### Checkbox
+ **必需** - `boolean` 选项。
+ **用法** - 生成一个复选框。
+ **示例** – `isProduction: boolean`
```
{
isProduction: boolean
...
}
```
### 单选框
+ **必需** - 三个或更少字符串的组合选项。
+ **用法** - 生成选定的单选框。
**注意**
当有四个或更多项目时，此类型将以下拉列表的形式呈现。
+ **示例** – `color: 'red' | 'blue' | 'green'`
```
{
color: 'red' | 'blue' | 'green'
...
}
```
### 下拉菜单
+ **必需** - 四个或更多字符串的组合选项。
+ **用法** - 生成一个下拉列表。
+ **示例** – `runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'`
```
{
runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'
...
}
```
### 可扩展部分
+ **必需** - 对象选项。
+ **用法** - 生成可扩展部分。对象中的选项将嵌套在向导中的可扩展部分内。
+ **示例** -
```
{
expandableSectionTitle: {
nestedString: string;
nestedNumber: number;
}
}
```
### Tuple
+ **必需** - `Tuple` 类型选项。
+ **用法** - 生成键值对输入。
+ **示例** – `tuple: Tuple[string, string]>`
```
{
tuple: Tuple[string, string]>;
...
}
```
### Tuple 列表
+ **必需** - `Tuple` 类型数组选项。
+ **用法** - 生成 tuple 列表输入。
+ **示例** – `tupleList: Tuple[string, string]>[]`
```
{
tupleList: Tuple[string, string]>[];
...
}
```
### Selector
+ **必需** - `Selector` 类型选项。
+ **用法** - 生成应用于项目的源存储库或蓝图的下拉列表。
+ **示例** – `sourceRepo: Selector`
```
{
sourceRepo: Selector;
sourceRepoOrAdd: Selector;
blueprintInstantiation: Selector;
...
}
```
### Multiselect
+ **必需** - `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.'
})
```