Amazon ya no CodeCatalyst está abierto a nuevos clientes. Los clientes existentes pueden seguir utilizando el servicio con normalidad. Para obtener más información, consulte [Cómo migrar desde CodeCatalyst](migration.md).
Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
# Modificación de las características del esquema con un asistente de front-end
La interfaz `Options` del archivo `blueprint.ts` genera automáticamente un asistente de selección de esquemas en CodeCatalyst. El asistente de front-end es compatible con las modificaciones y características de las `Options` de un esquema mediante [comentarios y etiquetas de estilo JSDOC](https://jsdoc.app/about-getting-started.html). Puede utilizar comentarios y etiquetas de estilo JSDOC para realizar tareas. Por ejemplo, puede seleccionar el texto que se muestra encima de una opción, habilitar características como la validación de entradas o hacer que una opción se pueda contraer. El asistente funciona interpretando un árbol de sintaxis abstracta (AST) generado a partir del tipo TypeScript desde la interfaz `Options`. El asistente se configura automáticamente según el tipo descrito de la mejor manera posible. No todos los tipos son compatibles. Entre otros tipos compatibles se incluyen el selector de región y el selector de entorno.
A continuación presentamos un ejemplo de un asistente que utiliza comentarios y etiquetas JSDOC con las `Options` del esquema:
```
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[];
}
```
El nombre de visualización de cada opción de la interfaz `Options` aparece de forma predeterminada en `camelCase`. El texto sin formato del comentario de estilo JSDOC aparece como texto encima de la opción en el asistente.
**Topics**
+ [Etiquetas compatibles](#supported-tags-bp)
+ [Tipos de TypeScript compatibles](#supported-typescript-bp)
+ [Comunicación con el usuario durante la síntesis](#communication-mid-synthesis)
## Etiquetas compatibles
Las siguientes etiquetas JSDOC son compatibles con las `Options` de un esquema personalizado en el asistente de front-end.
### @inlinePolicy ./path/to/policy/file.json
+ **Requiere**: la opción debe ser de tipo `Role`.
+ **Uso**: le permite comunicar las políticas integradas que necesita un rol. Se espera que la ruta `policy.json` esté bajo el código fuente. Use esta etiqueta cuando necesite una política personalizada para un rol.
+ **Dependencias**: `blueprint-cli 0.1.12` y posteriores
+ **Ejemplo**: `@inlinePolicy ./deployment-policy.json`
```
environment: EnvironmentDefinition{
awsAccountConnection: AccountConnection{
/**
* @inlinePolicy ./path/to/deployment-policy.json
*/
cdkRole: Role[];
};
};
```
### @trustPolicy ./path/to/policy/file.json
+ **Requiere**: la opción debe ser de tipo `Role`.
+ **Uso**: le permite comunicar las políticas de confianza que necesita un rol. Se espera que la ruta `policy.json` esté bajo el código fuente. Use esta etiqueta cuando necesite una política personalizada para un rol.
+ **Dependencias**: `blueprint-cli 0.1.12` y posteriores
+ **Ejemplo**: `@trustPolicy ./trust-policy.json`
```
environment: EnvironmentDefinition{
awsAccountConnection: AccountConnection{
/**
* @trustPolicy ./path/to/trust-policy.json
*/
cdkRole: Role[];
};
};
```
### Expresión regular @validationRegex
+ **Requiere**: la opción debe ser una cadena.
+ **Uso**: realiza la validación de entrada de la opción mediante la expresión regular dada y muestra `@validationMessage`.
+ **Ejemplo**: `@validationRegex /^[a-zA-Z0-9_]+$/`
+ **Recomendación**: debe usarse con `@validationMessage`. El mensaje de validación está vacío de forma predeterminada.
### Cadena @validationMessage
+ **Requiere**: `@validationRegex` u otros errores para revisar el uso.
+ **Uso**: muestra un mensaje de validación en caso de error de `@validation*`.
+ **Ejemplo**: `@validationMessage Must contain only upper and lowercase letters, numbers, and underscores`.
+ **Recomendación**: debe usarse con `@validationMessage`. El mensaje de validación está vacío de forma predeterminada.
### Booleano @collapsed (opcional)
+ **Requiere**: N/A
+ **Uso**: booleano que permite hacer que una subopción se pueda contraer. Si la anotación contraída está presente, su valor predeterminado es true. Si se establece el valor en `@collapsed false`, se crea una sección contraíble que inicialmente está abierta.
+ **Ejemplo**: `@collapsed true`
### Cadena de caracteres @displayName
+ **Requiere**: N/A
+ **Uso**: cambia el nombre de visualización de la opción. Admite formatos distintos de camelCase para el nombre de visualización.
+ **Ejemplo**: `@displayName Blueprint Name`
### Cadena de caracteres @displayName
+ **Requiere**: N/A
+ **Uso**: cambia el nombre de visualización de la opción. Admite formatos distintos de [camelCase](https://en.wikipedia.org/wiki/Camel_case) para el nombre de visualización.
+ **Ejemplo**: `@displayName Blueprint Name`
### Número @defaultEntropy
+ **Requiere**: la opción debe ser una cadena.
+ **Uso**: agrega a la opción una cadena alfanumérica aleatoria de una longitud específica.
+ **Ejemplo**: `@defaultEntropy 5`
### Cadena @placeholder (opcional)
+ **Requiere**: N/A
+ **Uso**: cambia el marcador de posición del campo de texto predeterminado.
+ **Ejemplo**: `@placeholder type project name here`
### Número @textArea (opcional)
+ **Requiere**: N/A
+ **Uso**: convierte la entrada de cadena en un componente de área de texto para secciones de texto más grandes. Al añadir un número se define el número de filas. El valor predeterminado es de cinco filas.
+ **Ejemplo**: `@textArea 10`
### Booleano @hidden (opcional)
+ **Requiere**: N/A
+ **Uso**: oculta el archivo al usuario a menos que se produzca un error en la comprobación de validación. El valor predeterminado es true.
+ **Ejemplo**: `@hidden`
### Booleano @button (opcional)
+ **Requiere**: N/A
+ **Uso**: la anotación debe estar en una propiedad booleana. Agrega un botón que se sintetizará como true cuando se seleccione. No es un conmutador.
+ **Ejemplo**: `buttonExample: boolean;`
```
/**
* @button
*/
buttonExample: boolean;
```
### Booleano @showName (opcional)
+ **Requiere**: N/A
+ **Uso**: solo se puede usar en un tipo de conexión de cuenta. Muestra la entrada de nombre oculta. El valor predeterminado es `default_environment`.
+ **Ejemplo**: `@showName true`
```
/**
* @showName true
*/
accountConnection: AccountConnection<{
...
}>;
```
### Booleano @showEnvironmentType (opcional)
+ **Requiere**: N/A
+ **Uso**: solo se puede usar en un tipo de conexión de cuenta. Muestra el menú desplegable de tipos de entornos ocultos. Todas las conexiones se establecen de forma predeterminada en `production`. Las opciones son **Non-production** o **Production**.
+ **Ejemplo**: `@showEnvironmentType true`
```
/**
* @showEnvironmentType true
*/
accountConnection: AccountConnection<{
...
}>;
```
### Booleano @forceDefault (opcional)
+ **Requiere**: N/A
+ **Uso**: utiliza el valor predeterminado proporcionado por el autor del esquema en lugar del valor que utilizaba anteriormente el usuario.
+ **Ejemplo**: `forceDeafultExample: any;`
```
/**
* @forceDefault
*/
forceDeafultExample: any;
```
### blueprintName @requires
+ **Requiere**: anota la interfaz `Options`.
+ **Uso**: advierte al usuario que agregue el `blueprintName` especificado al proyecto como requisito para el esquema actual.
+ **Ejemplo**: `@requires '@amazon-codecatalyst/blueprints.blueprint-builder'`
```
/*
* @requires '@amazon-codecatalyst/blueprints.blueprint-builder'
*/
export interface Options extends ParentOptions {
...
```
### Expresión regular @filter
+ **Requiere**: anota la interfaz `Selector` o `MultiSelect`.
+ **Uso**: filtra el menú desplegable del asistente según las opciones que coincidan con la expresión regular especificada.
+ **Ejemplo**: `@filter /blueprintPackageName/`
```
/**
* @filter /myPackageName/
*/
blueprintInstantiation?: Selector;
...
```
## Tipos de TypeScript compatibles
Los siguientes tipos de TypeScript son compatibles con las `Options` de un esquema personalizado en el asistente de front-end.
### Número
+ **Requiere**: la opción debe ser de tipo `number`.
+ **Uso**: genera un campo de entrada numérico.
+ **Ejemplo**: `age: number`
```
{
age: number
...
}
```
### Cadena
+ **Requiere**: la opción debe ser de tipo `string`.
+ **Uso**: genera un campo de entrada de cadena.
+ **Ejemplo**: `name: string`
```
{
age: string
...
}
```
### Lista de cadenas
+ **Requiere**: la opción debe ser una matriz de tipo `string`.
+ **Uso**: genera una entrada de lista de cadenas.
+ **Ejemplo**: `isProduction: boolean`
```
{
isProduction: boolean
...
}
```
### Casillla de verificación
+ **Requiere**: la opción debe ser un `boolean`.
+ **Uso**: genera una casilla de verificación.
+ **Ejemplo**: `isProduction: boolean`
```
{
isProduction: boolean
...
}
```
### Botón de opción
+ **Requiere**: la opción de ser una unión de tres cadenas o menos.
+ **Uso**: genera un botón de opción seleccionado.
**nota**
Cuando hay cuatro o más elementos, este tipo se representa como un menú desplegable.
+ **Ejemplo**: `color: 'red' | 'blue' | 'green'`
```
{
color: 'red' | 'blue' | 'green'
...
}
```
### Dropdown
+ **Requiere**: la opción de ser una unión de cuatro cadenas o más.
+ **Uso**: genera un menú desplegable.
+ **Ejemplo**: `runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'`
```
{
runtimes: 'nodejs' | 'python' | 'java' | 'dotnetcore' | 'ruby'
...
}
```
### Sección ampliable
+ **Requiere**: la opción debe ser un objeto.
+ **Uso**: genera una sección ampliable. Las opciones del objeto se anidarán dentro de la sección ampliable del asistente.
+ **Ejemplo**:
```
{
expandableSectionTitle: {
nestedString: string;
nestedNumber: number;
}
}
```
### Tupla
+ **Requiere**: la opción debe ser de tipo `Tuple`.
+ **Uso**: genera una entrada de par clave-valor.
+ **Ejemplo**: `tuple: Tuple[string, string]>`
```
{
tuple: Tuple[string, string]>;
...
}
```
### Lista de tuplas
+ **Requiere**: la opción debe ser una matriz de tipo `Tuple`.
+ **Uso**: genera una entrada de lista de tuplas.
+ **Ejemplo**: `tupleList: Tuple[string, string]>[]`
```
{
tupleList: Tuple[string, string]>[];
...
}
```
### Selector
+ **Requiere**: la opción debe ser de tipo `Selector`.
+ **Uso**: genera un menú desplegable con los repositorios de código fuente o los esquemas aplicados a un proyecto.
+ **Ejemplo**: `sourceRepo: Selector`
```
{
sourceRepo: Selector;
sourceRepoOrAdd: Selector;
blueprintInstantiation: Selector;
...
}
```
### Selección múltiple
+ **Requiere**: la opción debe ser de tipo `Selector`.
+ **Uso**: genera una entrada de selección múltiple.
+ **Ejemplo**: `multiselect: MultiSelect['A' | 'B' | 'C' | 'D' | 'E']>`
```
{
multiselect: MultiSelect['A' | 'B' | 'C' | 'D' | 'E']>;
...
}
```
## Comunicación con el usuario durante la síntesis
En calidad de autor de un esquema, puede comunicarse con los usuarios más allá de los mensajes de validación. Por ejemplo, un miembro del espacio podría ver una combinación de opciones que genere un esquema que no esté claro. Los esquemas personalizados permiten comunicar los mensajes de error a los usuarios mediante la invocación de la síntesis. El esquema de base implementa una función `throwSynthesisError(...)` que espera un mensaje de error claro. Puede invocar el mensaje mediante lo siguiente:
```
//blueprint.ts
this.throwSynthesisError({
name: BlueprintSynthesisErrorTypes.BlueprintSynthesisError,
message: 'hello from the blueprint! This is a custom error communicated to the user.'
})
```