Skip to main content

Sintaxis para el modelado de formato de GitHub

Puedes utilizar el modelado de formato de GitHub para configurar los formatos para las características compatibles.

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 más información, vea "Configuración de plantillas de incidencia para el 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.

YAML
- 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:
      - label: 1.0.2 (Default)
      - label: 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.

ClaveDescripciónObligatorioTipoValor predeterminadoValores válidos
typeEl tipo de elemento que quieres definir.ObligatorioString
  • checkboxes
  • dropdown
  • input
  • markdown
  • textarea
idIdentificador 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.OpcionalesString
attributesUn conjunto de pares clave-valor que definen las propiedades del elemento.ObligatorioHash
validationsUn conjunto de pares de clave-valor que configuran las restricciones en el elemento.OpcionalesHash

Puedes elegir desde los siguientes tipos de elementos de formato. Cada tipo tiene atributos y validaciones únicos.

TipoDescripción
markdownEl texto de Markdown que se muestra en el formulario para proporcionar contexto adicional al usuario, pero que no se envía.
textareaUn campo de texto de línea múltiple.
inputUn campo de texto de línea sencilla.
dropdownUn menú desplegable.
checkboxesUn 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 el valor de la clave attributes, puede establecer las claves siguientes.

ClaveDescripciónObligatorioTipoValor predeterminadoValores válidos
valueEl texto se interpreta. El formateo en lenguaje de marcado es compatible.ObligatorioString

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

YAML
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 el valor de la clave attributes, puede establecer las claves siguientes.

ClaveDescripciónObligatorioTipoValor predeterminadoValores válidos
labelUna descripción breve de la entrada que se espera del usuario, lo cual también se muestra en el formato.ObligatorioString
descriptionUna descripción del área de texto para proporcionar contexto u orientación, la cual se muestra en el formato.OpcionalesStringCadena vacía
placeholderUn marcador de posición que interpreta en el área de texto cuando está vacía.OpcionalesStringCadena vacía
valueEl texto se pre-llena en el área de texto.OpcionalesString
renderSi 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.OpcionalesStringLos lenguajes que conoce GitHub. Para más información, vea el archivo YAML de lenguajes.

Validaciones

Para el valor de la clave validations, puede establecer las claves siguientes.

ClaveDescripciónObligatorioTipoValor predeterminadoValores válidos
requiredImpide el envío del formulario hasta que se complete el elemento.OpcionalBooleanofalso

Ejemplo

YAML
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 el valor de la clave attributes, puede establecer las claves siguientes.

ClaveDescripciónObligatorioTipoValor predeterminadoValores válidos
labelUna descripción breve de la entrada que se espera del usuario, lo cual también se muestra en el formato.ObligatorioString
descriptionUna descripción del campo para proporcionar contexto u orientación, la cual se muestra en el formato.OpcionalesStringCadena vacía
placeholderUn marcador de posición semi-transparente que interpreta en el campo cuando está vacío.OpcionalesStringCadena vacía
valueEl texto se pre-llenó en el campo.OpcionalesString

Validaciones

Para el valor de la clave validations, puede establecer las claves siguientes.

ClaveDescripciónObligatorioTipoValor predeterminadoValores válidos
requiredImpide el envío del formulario hasta que se complete el elemento.OpcionalBooleanofalso

Ejemplo

YAML
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

Puede usar un elemento dropdown para agregar un menú desplegable en el formulario.

Atributos

Para el valor de la clave attributes, puede establecer las claves siguientes.

ClaveDescripciónObligatorioTipoValor predeterminadoValores válidos
labelUna descripción de la entrada que se espera del usuario, lo cual también se muestra en el formato.ObligatorioString
descriptionUna descripción del menú desplegable para proporcionar contexto adicional u orientación, la cual se muestra en el formato.OpcionalesStringCadena vacía
multipleDetermina si el usuario puede seleccionar más de una opción.OpcionalesBooleanfalse
optionsUn arreglo de opciones que puede elegir el usuario. No puede estar vacío y todas las elecciones deben ser distintas.ObligatorioMatriz de cadena

Validaciones

Para el valor de la clave validations, puede establecer las claves siguientes.

ClaveDescripciónObligatorioTipoValor predeterminadoValores válidos
requiredImpide el envío del formulario hasta que se complete el elemento.OpcionalBooleanofalso

Ejemplo

YAML
body:
- type: dropdown
  id: download
  attributes:
    label: How did you download the software?
    options:
      - Homebrew
      - MacPorts
      - apt-get
      - Built from source
  validations:
    required: true

checkboxes

Puede usar el elemento checkboxes para agregar un conjunto de casillas al formulario.

Atributos

Para el valor de la clave attributes, puede establecer las claves siguientes.

ClaveDescripciónObligatorioTipoValor predeterminadoValores válidos
labelUna descripción de la entrada que se espera del usuario, lo cual también se muestra en el formato.ObligatorioString
descriptionUna 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.OpcionalesStringCadena vacía
optionsUn arreglo de casillas de verificación que puede seleccionar el usuario. Para conocer la sintaxis, consulta a continuación.ObligatorioArray

Para cada valor de la matriz options, puede establecer las siguientes claves.

ClaveDescripciónObligatorioTipoValor predeterminadoOpciones
labelEl 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.ObligatorioString

Ejemplo

YAML
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

Información adicional