Nota: El esquema de formato de GitHub se encuentra actualmente en versión beta y está sujeto a cambios.
Acerca del modelado de formatos de GitHub
Puedes utilizar el modelado de formato de GitHub para configurar los formatos para las características compatibles. Para obtener más información, vea «Configurar las plantillas de reporte de problemas para tu repositorio».
Un formato es un conjunto de elemotos para solicitar la aportación de un usuario. Puedes configurar un formato si creas una definición de formato YAML, la cual es un arreglo de elementos de formato. Cada elemento de formato es un conjunto de pares de valor-llave que determinan el tipo y las propiedades del elemento y las restricciones que quieres aplicarle. Para algunas claves, el valor es otro conjunto de pares de clave-valor.
Por ejemplo, la siguente definición de formato incluye cuatro elementos de formato: un área de texto para proporcionar el sistema operativo del usuario, un menú desplegable para elegir la versión de software que está ejecutando el usuario, una casilla de verificación para reconocer que se leyó y aceptó el código de conducta y el lenguaje de marcado que agradece al usuario por haber completado el formato.
- type: textarea
attributes:
label: Operating System
description: What operating system are you using?
placeholder: "Example: macOS Big Sur"
value: operating system
validations:
required: true
- type: dropdown
attributes:
label: Version
description: What version of our software are you running?
multiple: false
options:
- 1.0.2 (Default)
- 1.0.3 (Edge)
validations:
required: true
- type: checkboxes
attributes:
label: Code of Conduct
description: The Code of Conduct helps create a safe space for everyone. We require
that everyone agrees to it.
options:
- label: I agree to follow this project's [Code of Conduct](link/to/coc)
required: true
- type: markdown
attributes:
value: "Thanks for completing our form!"
- type: textarea
attributes:
label: Operating System
description: What operating system are you using?
placeholder: "Example: macOS Big Sur"
value: operating system
validations:
required: true
- type: dropdown
attributes:
label: Version
description: What version of our software are you running?
multiple: false
options:
- 1.0.2 (Default)
- 1.0.3 (Edge)
validations:
required: true
- type: checkboxes
attributes:
label: Code of Conduct
description: The Code of Conduct helps create a safe space for everyone. We require
that everyone agrees to it.
options:
- label: I agree to follow this project's [Code of Conduct](link/to/coc)
required: true
- type: markdown
attributes:
value: "Thanks for completing our form!"
Teclas
Para cada elemento de formato, puedes configurar las siguientes claves.
| Clave | Descripción | Obligatorio | Tipo | Valor predeterminado | Valores válidos |
|---|---|---|---|---|---|
type | El tipo de elemento que quieres definir. | String |
| ||
id | Identificador del elemento, excepto cuando type se establece en markdown. Solo puede usar caracteres alfanuméricos, - y _. Debe ser única en la definición de formato. Si se proporciona, id es el identificador canónico para el campo en los valores previamente rellenados de parámetro de la consulta de URL. | String | |||
attributes | Un conjunto de pares clave-valor que definen las propiedades del elemento. | Asignación | |||
validations | Un conjunto de pares de clave-valor que configuran las restricciones en el elemento. | Asignación |
Puedes elegir desde los siguientes tipos de elementos de formato. Cada tipo tiene atributos y validaciones únicos.
| Tipo | Descripción |
|---|---|
markdown | El texto de Markdown que se muestra en el formulario para proporcionar contexto adicional al usuario, pero que no se envía. |
textarea | Un campo de texto de línea múltiple. |
input | Un campo de texto de línea sencilla. |
dropdown | Un menú desplegable. |
checkboxes | Un conjunto de casillas de verificación. |
markdown
Puede usar un elemento markdown para mostrar Markdown en el formulario que proporcione contexto adicional al usuario, pero que no se envíe.
Atributos para markdown
Para el valor de la clave attributes, puede establecer las claves siguientes.
| Clave | Descripción | Obligatorio | Tipo | Valor predeterminado | Valores válidos |
|---|---|---|---|---|---|
value | El texto se interpreta. El formateo en lenguaje de marcado es compatible. | String |
Sugerencias: el procesamiento de YAML tratará el símbolo hash como un comentario. Para insertar encabezados con lenguaje de marcado, pon tu texto entre comillas.
Para el texto de línea múltiple, puedes utilizar el operador de pipa.
Ejemplo de markdown
body:
- type: markdown
attributes:
value: "## Thank you for contributing to our project!"
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report.
body:
- type: markdown
attributes:
value: "## Thank you for contributing to our project!"
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report.
textarea
Puede usar un elemento textarea para agregar un campo de texto de varias líneas al formulario. Los colaboradores también pueden adjuntar archivos en campos textarea.
Atributos para textarea
Para el valor de la clave attributes, puede establecer las claves siguientes.
| Clave | Descripción | Obligatorio | Tipo | Valor predeterminado | Valores válidos |
|---|---|---|---|---|---|
label | Una descripción breve de la entrada que se espera del usuario, lo cual también se muestra en el formato. | String | |||
description | Una descripción del área de texto para proporcionar contexto u orientación, la cual se muestra en el formato. | String | Cadena vacía | ||
placeholder | Un marcador de posición que interpreta en el área de texto cuando está vacía. | String | Cadena vacía | ||
value | El texto se pre-llena en el área de texto. | String | |||
render | Si se proporciona un valor, el texto emitido se formatea en un bloque de código. Cuando se proporciona esta llave, el áera de texto no se expandirá para los adjuntos de archivo o la edición de lenguaje de marcado. | String | Los lenguajes que conoce GitHub. Para más información, vea el archivo YAML de lenguajes. |
Validaciones para textarea
Para el valor de la clave validations, puede establecer las claves siguientes.
| Clave | Descripción | Obligatorio | Tipo | Valor predeterminado | Valores válidos |
|---|---|---|---|---|---|
required | Impide el envío del formulario hasta que se complete el elemento. Solo para repositorios públicos. | Boolean | false |
Ejemplo de textarea
body:
- type: textarea
id: repro
attributes:
label: Reproduction steps
description: "How do you trigger this bug? Please walk us through it step by step."
value: |
1.
2.
3.
...
render: bash
validations:
required: true
body:
- type: textarea
id: repro
attributes:
label: Reproduction steps
description: "How do you trigger this bug? Please walk us through it step by step."
value: |
1.
2.
3.
...
render: bash
validations:
required: true
input
Puede usar un elemento input para agregar un campo de texto de una sola línea al formulario.
Atributos para input
Para el valor de la clave attributes, puede establecer las claves siguientes.
| Clave | Descripción | Obligatorio | Tipo | Valor predeterminado | Valores válidos |
|---|---|---|---|---|---|
label | Una descripción breve de la entrada que se espera del usuario, lo cual también se muestra en el formato. | String | |||
description | Una descripción del campo para proporcionar contexto u orientación, la cual se muestra en el formato. | String | Cadena vacía | ||
placeholder | Un marcador de posición semi-transparente que interpreta en el campo cuando está vacío. | String | Cadena vacía | ||
value | El texto se pre-llenó en el campo. | String |
Validaciones para input
Para el valor de la clave validations, puede establecer las claves siguientes.
| Clave | Descripción | Obligatorio | Tipo | Valor predeterminado | Valores válidos |
|---|---|---|---|---|---|
required | Impide el envío del formulario hasta que se complete el elemento. Solo para repositorios públicos. | Boolean | false |
Ejemplo de input
body:
- type: input
id: prevalence
attributes:
label: Bug prevalence
description: "How often do you or others encounter this bug?"
placeholder: "Example: Whenever I visit the personal account page (1-2 times a week)"
validations:
required: true
body:
- type: input
id: prevalence
attributes:
label: Bug prevalence
description: "How often do you or others encounter this bug?"
placeholder: "Example: Whenever I visit the personal account page (1-2 times a week)"
validations:
required: true
dropdown
Puede usar un elemento dropdown para agregar un menú desplegable en el formulario.
Atributos para dropdown
Para el valor de la clave attributes, puede establecer las claves siguientes.
| Clave | Descripción | Obligatorio | Tipo | Valor predeterminado | Valores válidos |
|---|---|---|---|---|---|
label | Una descripción de la entrada que se espera del usuario, lo cual también se muestra en el formato. | String | |||
description | Una descripción del menú desplegable para proporcionar contexto adicional u orientación, la cual se muestra en el formato. | String | Cadena vacía | ||
multiple | Determina si el usuario puede seleccionar más de una opción. | Boolean | false | ||
options | Un arreglo de opciones que puede elegir el usuario. No puede estar vacío y todas las elecciones deben ser distintas. | Matriz de cadena | |||
default | Índice de la opción preseleccionada en la matriz options. Cuando se especifica una opción predeterminada, no puedes incluir "None" o "n/a" como opciones. | Entero |
Validaciones para dropdown
Para el valor de la clave validations, puede establecer las claves siguientes.
| Clave | Descripción | Obligatorio | Tipo | Valor predeterminado | Valores válidos |
|---|---|---|---|---|---|
required | Impide el envío del formulario hasta que se complete el elemento. Solo para repositorios públicos. | Boolean | false |
Ejemplo de dropdown
body:
- type: dropdown
id: download
attributes:
label: How did you download the software?
options:
- Built from source
- Homebrew
- MacPorts
- apt-get
validations:
required: true
body:
- type: dropdown
id: download
attributes:
label: How did you download the software?
options:
- Built from source
- Homebrew
- MacPorts
- apt-get
validations:
required: true
checkboxes
Puede usar el elemento checkboxes para agregar un conjunto de casillas al formulario.
Atributos para checkboxes
Para el valor de la clave attributes, puede establecer las claves siguientes.
| Clave | Descripción | Obligatorio | Tipo | Valor predeterminado | Valores válidos |
|---|---|---|---|---|---|
label | Una descripción de la entrada que se espera del usuario, lo cual también se muestra en el formato. | String | |||
description | Una descripción del conjunto de casillas de verificación, la cual se muestra en el formato. Es compatible con el formateo de lenguaje de marcado. | String | Cadena vacía | ||
options | Un arreglo de casillas de verificación que puede seleccionar el usuario. Para conocer la sintaxis, consulta a continuación. | Array |
Para cada valor de la matriz options, puede establecer las siguientes claves.
| Clave | Descripción | Obligatorio | Tipo | Valor predeterminado | Opciones |
|---|---|---|---|---|---|
label | El identificador para la opción, el cual se muestra en el formato. Hay compatibilidad con lenguaje de marcado para formateo de texto en itálicas o negritas y para los hipervínculos. | String | |||
required | Impide el envío del formulario hasta que se complete el elemento. Solo para repositorios públicos. | Boolean | false |
Validaciones para checkboxes
Para el valor de la clave validations, puede establecer las claves siguientes.
| Clave | Descripción | Obligatorio | Tipo | Valor predeterminado | Valores válidos |
|---|---|---|---|---|---|
required | Impide el envío del formulario hasta que se complete el elemento. Solo para repositorios públicos. | Boolean | false |
Ejemplo de checkboxes
body:
- type: checkboxes
id: operating-systems
attributes:
label: Which operating systems have you used?
description: You may select more than one.
options:
- label: macOS
- label: Windows
- label: Linux
body:
- type: checkboxes
id: operating-systems
attributes:
label: Which operating systems have you used?
description: You may select more than one.
options:
- label: macOS
- label: Windows
- label: Linux