Skip to main content

Syntax für das GitHub-Formularschema

Du kannst mit dem Formularschema von GitHub Formulare für unterstützte Features konfigurieren.

Hinweis: Das Formularschema von GitHub befindet sich derzeit in der Betaphase und kann noch geändert werden.

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!"

Tasten

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

SchlüsselBESCHREIBUNGErforderlichtypeStandardGültige Werte
typeDer Typ des Elements, das du definieren möchtest.String
  • checkboxes
  • dropdown
  • input
  • markdown
  • textarea
idDer 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
attributesEin Satz von Schlüssel-Wert-Paaren, die die Eigenschaften des Elements definieren.Karte
validationsEin 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.

typeBESCHREIBUNG
markdownMarkdown-Text, der im Formular angezeigt wird, um dem Benutzer zusätzlichen Kontext zu bieten, jedoch nicht übermittelt wird.
textareaEin mehrzeiliges Textfeld.
inputEin einzeiliges Textfeld.
dropdownEin Dropdownmenü.
checkboxesEin 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üsselBESCHREIBUNGErforderlichtypeStandardGültige Werte
valueDer Text, der gerendert wird. Markdown-Formatierung wird unterstützt.String

Tipp: 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.

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üsselBESCHREIBUNGErforderlichtypeStandardGültige Werte
labelEine auch im Formular angezeigte kurze Beschreibung der erwarteten Benutzereingabe.String
descriptionEine im Formular angezeigte Beschreibung des Textbereichs, die Kontext oder Anleitungen bereitstellt.StringLeere Zeichenfolge
placeholderEin halbdurchsichtiger Platzhalter, der im Textbereich gerendert wird, wenn er leer ist.StringLeere Zeichenfolge
valueIm Textbereich als Vorgabe angezeigter Text.String
renderWenn 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.StringSprachen, 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üsselBESCHREIBUNGErforderlichtypeStandardGültige Werte
requiredVerhindert die Formularübermittlung, bis das Element abgeschlossen ist. Nur für öffentliche Repositorys.Booleschfalse

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

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üsselBESCHREIBUNGErforderlichtypeStandardGültige Werte
labelEine auch im Formular angezeigte kurze Beschreibung der erwarteten Benutzereingabe.String
descriptionEine im Formular angezeigte Beschreibung des Felds, die Kontext oder Anleitungen bereitstellt.StringLeere Zeichenfolge
placeholderEin halbdurchsichtiger Platzhalter, der im Feld gerendert wird, wenn es leer ist.StringLeere Zeichenfolge
valueIm 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üsselBESCHREIBUNGErforderlichtypeStandardGültige Werte
requiredVerhindert die Formularübermittlung, bis das Element abgeschlossen ist. Nur für öffentliche Repositorys.Booleschfalse

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

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

Attribute für dropdown

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

SchlüsselBESCHREIBUNGErforderlichtypeStandardGültige Werte
labelEine im Formular angezeigte kurze Beschreibung der erwarteten Benutzereingabe.String
descriptionEine im Formular angezeigte Beschreibung des Dropdownmenüs, die zusätzlichen Kontext oder Anleitungen bereitstellt.StringLeere Zeichenfolge
multipleBestimmt, ob der Benutzer mehrere Optionen auswählen kann.Booleanfalse
optionsEin Array von Optionen, aus dem der Benutzer auswählen kann. Kann nicht leer sein, und alle Auswahlmöglichkeiten müssen eindeutig sein.Zeichenfolgenarray
defaultIndex der vorgewählten Option im options Array. Wenn eine Standardoption angegeben wird, können Sie „Keine“ oder „n/a“ nicht als Optionen einschließen.Integer

Überprüfungen für dropdown

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

SchlüsselBESCHREIBUNGErforderlichtypeStandardGültige Werte
requiredVerhindert die Formularübermittlung, bis das Element abgeschlossen ist. Nur für öffentliche Repositorys.Booleschfalse

Beispiel für dropdown

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

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üsselBESCHREIBUNGErforderlichtypeStandardGültige Werte
labelEine im Formular angezeigte kurze Beschreibung der erwarteten Benutzereingabe.String
descriptionEine im Formular angezeigte Beschreibung des Satzes von Kontrollkästchen. Unterstützt Markdown-Formatierung.StringLeere Zeichenfolge
optionsEin 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üsselBESCHREIBUNGErforderlichtypeStandardOptionen
labelDer Bezeichner für die Option, der im Formular angezeigt wird. Markdown wird für Fett- oder Kursivformatierungen und Hyperlinks unterstützt.String
requiredVerhindert die Formularübermittlung, bis das Element abgeschlossen ist. Nur für öffentliche Repositorys.Booleschfalse

Überprüfungen für checkboxes

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

SchlüsselBESCHREIBUNGErforderlichtypeStandardGültige Werte
requiredVerhindert die Formularübermittlung, bis das Element abgeschlossen ist. Nur für öffentliche Repositorys.Booleschfalse

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

Weiterführende Themen