Syntax für das GitHub-Formularschema

Note

Das Formularschema von GitHub befindet sich derzeit in der public preview. Änderungen bleiben vorbehalten.

Informationen zum Formularschema von GitHub

Du kannst mit dem Formularschema von GitHub Formulare für unterstützte Features konfigurieren. Weitere Informationen findest du unter Issuevorlagen für Dein Repository konfigurieren.

Ein Formular ist ein Satz von Elementen zum Anfordern von Benutzereingaben. Du kannst ein Formular konfigurieren, indem du eine YAML-Formulardefinition erstellst, die ein Array von Formularelementen ist. Jedes Formularelement ist ein Satz von Schlüssel-Wert-Paaren, die den Typ des Elements, die Eigenschaften des Elements und die Einschränkungen bestimmen, die du auf das Element anwenden möchtest. Bei einigen Schlüsseln ist der Wert ein weiterer Satz von Schlüssel-Wert-Paaren.

Die folgende Formulardefinition enthält beispielsweise vier Formularelemente: einen Textbereich für die Bereitstellung des Betriebssystems des Benutzers, ein Dropdownmenü zum Auswählen der Softwareversion, die der Benutzer ausführt, ein Kontrollkästchen, um die Verhaltensregeln zu bestätigen, und Markdown, um dem Benutzer zum Ausfüllen des Formulars zu danken.

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:
      - 1.0.2 (Default)
      - 1.0.3 (Edge)
    default: 0
  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)
    default: 0
  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!"

Tasten

Für jedes Formularelement kannst du die folgenden Schlüssel festlegen.

Schlüssel	BESCHREIBUNG	type	Gültige Werte
`type`	Der Typ des Elements, das du definieren möchtest.	String	`checkboxes` `dropdown` `input` `markdown` `textarea`
`id`	Der Bezeichner für das Element, außer wenn `type` auf `markdown` gesetzt ist. Kann nur alphanumerische Zeichen, `-`und `_` verwenden. Muss in der Formulardefinition eindeutig sein. Wenn angegeben, ist `id` der kanonische Bezeichner für das Feld im URL-Abfrageparameter.	String
`attributes`	Ein Satz von Schlüssel-Wert-Paaren, die die Eigenschaften des Elements definieren.	Karte
`validations`	Ein Satz von Schlüssel-Wert-Paaren, die Einschränkungen für das Element festlegen.	Karte

Du hast die Wahl zwischen den folgenden Typen von Formularelementen. Jeder Typ hat eindeutige Attribute und Validierungen.

type	BESCHREIBUNG
`markdown`	Markdown-Text, der im Formular angezeigt wird, um dem Benutzer zusätzlichen Kontext zu bieten, jedoch nicht übermittelt wird.
`textarea`	Ein mehrzeiliges Textfeld.
`input`	Ein einzeiliges Textfeld.
`dropdown`	Ein Dropdownmenü.
`checkboxes`	Ein Satz von Kontrollkästchen.

`markdown`

Mit einem markdown-Element kannst du Markdown in deinem Formular anzuzeigen, um dem Benutzer zusätzlichen Kontext zu bieten, Markdown wird aber nicht übermittelt.

Attribute für `markdown`

Für den Wert des Schlüssels attributes kannst du die folgenden Schlüssel festlegen.

Schlüssel	BESCHREIBUNG	Erforderlich	type	Standard	Gültige Werte
`value`	Der Text, der gerendert wird. Markdown-Formatierung wird unterstützt.		String

Tip

Die YAML-Verarbeitung behandelt das Hashsymbol als Kommentar. Um Markdown-Kopfzeilen einzufügen, schließe den Text in Anführungszeichen ein.

Für mehrzeiligen Text kannst du den Pipe-Operator verwenden.

Beispiel für `markdown`

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.

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`

Du kannst mit einem textarea-Element deinem Formular ein mehrzeiliges Textfeld hinzufügen. Mitwirkende können auch Dateien in textarea-Feldern anfügen.

Attribute für `textarea`

Für den Wert des Schlüssels attributes kannst du die folgenden Schlüssel festlegen.

Schlüssel	BESCHREIBUNG	type	Standard	Gültige Werte
`label`	Eine auch im Formular angezeigte kurze Beschreibung der erwarteten Benutzereingabe.	String
`description`	Eine im Formular angezeigte Beschreibung des Textbereichs, die Kontext oder Anleitungen bereitstellt.	String	Leere Zeichenfolge
`placeholder`	Ein halbdurchsichtiger Platzhalter, der im Textbereich gerendert wird, wenn er leer ist.	String	Leere Zeichenfolge
`value`	Im Textbereich als Vorgabe angezeigter Text.	String
`render`	Wenn ein Wert angegeben wird, wird übermittelter Text in einen Codeblock formatiert. Wenn dieser Schlüssel bereitgestellt wird, wird der Textbereich nicht für Dateianlagen oder Markdown-Bearbeitung erweitert.	String		Sprachen, die GitHub bekannt sind. Weitere Informationen findest du in der YAML-Datei der Sprachen.

Überprüfungen für `textarea`

Für den Wert des Schlüssels validations kannst du die folgenden Schlüssel festlegen.

Schlüssel	BESCHREIBUNG	Erforderlich	type	Standard	Gültige Werte
`required`	Verhindert die Formularübermittlung, bis das Element abgeschlossen ist. Nur für öffentliche Repositorys.		Boolesch	false

Beispiel für `textarea`

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

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`

Du kannst mit einem input-Element deinem Formular ein einzeiliges Textfeld hinzufügen.

Attribute für `input`

Für den Wert des Schlüssels attributes kannst du die folgenden Schlüssel festlegen.

Schlüssel	BESCHREIBUNG	type	Standard
`label`	Eine auch im Formular angezeigte kurze Beschreibung der erwarteten Benutzereingabe.	String
`description`	Eine im Formular angezeigte Beschreibung des Felds, die Kontext oder Anleitungen bereitstellt.	String	Leere Zeichenfolge
`placeholder`	Ein halbdurchsichtiger Platzhalter, der im Feld gerendert wird, wenn es leer ist.	String	Leere Zeichenfolge
`value`	Im Feld als Vorgabe angezeigter Text.	String

Überprüfungen für `input`

Für den Wert des Schlüssels validations kannst du die folgenden Schlüssel festlegen.

Schlüssel	BESCHREIBUNG	Erforderlich	type	Standard	Gültige Werte
`required`	Verhindert die Formularübermittlung, bis das Element abgeschlossen ist. Nur für öffentliche Repositorys.		Boolesch	false

Beispiel für `input`

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

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

Mit einem dropdown-Element kannst du deinem Formular ein Dropdownmenü hinzufügen.

Für den Wert des Schlüssels attributes kannst du die folgenden Schlüssel festlegen.

Schlüssel	BESCHREIBUNG	type	Standard
`label`	Eine im Formular angezeigte kurze Beschreibung der erwarteten Benutzereingabe.	String
`description`	Eine im Formular angezeigte Beschreibung des Dropdownmenüs, die zusätzlichen Kontext oder Anleitungen bereitstellt.	String	Leere Zeichenfolge
`multiple`	Bestimmt, ob der Benutzer mehrere Optionen auswählen kann.	Boolean	false
`options`	Ein Array von Optionen, aus dem der Benutzer auswählen kann. Kann nicht leer sein, und alle Auswahlmöglichkeiten müssen eindeutig sein.	Zeichenfolgenarray
`default`	Index der vorgewählten Option im `options` Array. Wenn eine Standardoption angegeben wird, können Sie „Keine“ oder „n/a“ nicht als Optionen einschließen.	Ganzzahl

Für den Wert des Schlüssels validations kannst du die folgenden Schlüssel festlegen.

Schlüssel	BESCHREIBUNG	Erforderlich	type	Standard	Gültige Werte
`required`	Verhindert die Formularübermittlung, bis das Element abgeschlossen ist. Nur für öffentliche Repositorys.		Boolesch	false

YAML

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

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

`checkboxes`

Du kannst mit dem checkboxes-Element deinem Formular einen Satz von Kontrollkästchen hinzufügen.

Attribute für `checkboxes`

Für den Wert des Schlüssels attributes kannst du die folgenden Schlüssel festlegen.

Schlüssel	BESCHREIBUNG	type	Standard
`label`	Eine im Formular angezeigte kurze Beschreibung der erwarteten Benutzereingabe.	String
`description`	Eine im Formular angezeigte Beschreibung des Satzes von Kontrollkästchen. Unterstützt Markdown-Formatierung.	String	Leere Zeichenfolge
`options`	Ein Array von Kontrollkästchen, die der Benutzer auswählen kann. Syntax siehe unten.	Array

Für jeden Wert im options-Array kannst du die folgenden Schlüssel festlegen.

Schlüssel	BESCHREIBUNG	Erforderlich	type	Standard	Optionen
`label`	Der Bezeichner für die Option, der im Formular angezeigt wird. Markdown wird für Fett- oder Kursivformatierungen und Hyperlinks unterstützt.		String
`required`	Verhindert die Formularübermittlung, bis das Element abgeschlossen ist. Nur für öffentliche Repositorys.		Boolesch	false

Überprüfungen für `checkboxes`

Für den Wert des Schlüssels validations kannst du die folgenden Schlüssel festlegen.

Schlüssel	BESCHREIBUNG	Erforderlich	type	Standard	Gültige Werte
`required`	Verhindert die Formularübermittlung, bis das Element abgeschlossen ist. Nur für öffentliche Repositorys.		Boolesch	false

Beispiel für `checkboxes`

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

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

Weiterführende Themen

YAML

Syntax für das GitHub-Formularschema

In diesem Artikel