Skip to main content

GitHub のフォームスキーマの構文

GitHub のフォームスキーマを使用して、サポートされている機能のフォームを設定できます。

注: GitHub のフォーム スキーマは現在ベータであり、変更される可能性があります。

GitHub のフォームスキーマについて

GitHub のフォームスキーマを使用して、サポートされている機能のフォームを設定できます。 詳細については、「リポジトリ用に Issue テンプレートを設定する」を参照してください。

フォームは、ユーザ入力を要求するための要素のセットです。 フォームを設定するには、フォーム要素の配列である YAML フォーム定義を作成します。 各フォーム要素は、要素のタイプ、要素のプロパティ、および要素に適用する制約を決定するキー/値ペアのセットです。 一部のキーでは、値はキー/値ペアの別のセットです。

たとえば、次のフォーム定義には、ユーザのオペレーティングシステムを提供するためのテキスト領域、ユーザが実行しているソフトウェアバージョンを選択するためのドロップダウンメニュー、行動規範を確認するためのチェックボックス、およびフォームへの入力を完了したユーザに感謝する Markdown の 4 つのフォーム要素が含まれます。

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

[キー]

フォーム要素ごとに、次のキーを設定できます。

Key説明必須TypeDefault有効な値
type定義する要素のタイプ。必須String
  • checkboxes
  • dropdown
  • input
  • markdown
  • textarea
id要素の識別子。ただし、typemarkdown に設定されている場合を除きます。 英数字、-、および _ のみを使用できます。 フォーム定義中で一意でなければなりません。 指定されている場合、id は URL クエリ パラメーターの事前入力のフィールドの正規識別子です。オプションString
attributes要素のプロパティを定義するキー/値ペアのセット。必須ハッシュ インデックス
validations要素に制約を設定するキー/値ペアのセット。オプションハッシュ インデックス

以下のタイプのフォーム要素から選択できます。 各タイプには、固有の属性と検証があります。

説明
markdownユーザーに追加のコンテキストを提供するためにフォームに表示されるが、未送信 である Markdown テキスト。
textarea複数行のテキストフィールド。
input単一行のテキストフィールド。
dropdownドロップダウンメニュー。
checkboxesチェックボックスのセット。

markdown

markdown 要素を使用して、ユーザーに追加のコンテキストを提供する Markdown をフォームに表示できますが、これは送信されません。

属性

attributes キーの値については、次のキーを設定できます。

Key説明必須TypeDefault有効な値
valueそのテキストはレンダリングされます。 Markdown フォーマットはサポートされています。必須String

ヒント: YAML の処理では、ハッシュ シンボルがコメントとして扱われます。 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

textarea 要素を使用して、フォームに複数行のテキスト フィールドを追加できます。 共同作成者は、textarea フィールドにファイルを添付することもできます。

属性

attributes キーの値については、次のキーを設定できます。

Key説明必須TypeDefault有効な値
label予想されるユーザ入力の簡単な説明。これもフォームに表示されます。必須String
descriptionフォームに表示される、コンテキストまたはガイダンスを提供するテキスト領域の説明。オプションString空の文字列
placeholder空のときにテキスト領域に表示される半透明のプレースホルダ。オプションString空の文字列
valueテキスト領域に事前入力されているテキスト。オプションString
render値が指定されている場合、送信されたテキストはコードブロックにフォーマットされます。 このキーを指定すると、添付ファイルや Markdown 編集のためにテキスト領域が拡張されません。オプションStringGitHub に知られている言語。 詳細については、言語 YAML ファイルに関するページを参照してください。

確認

validations キーの値については、次のキーを設定できます。

Key説明必須TypeDefault有効な値
required要素が完了するまでフォームの送信を禁止します。OptionalBooleanfalse

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

input 要素を使用して、フォームに単一のテキスト フィールドを追加できます。

属性

attributes キーの値については、次のキーを設定できます。

Key説明必須TypeDefault有効な値
label予想されるユーザ入力の簡単な説明。これもフォームに表示されます。必須String
descriptionフォームに表示される、コンテキストまたはガイダンスを提供するフィールドの説明。オプションString空の文字列
placeholder空のときにフィールドにレンダリングされる半透明のプレースホルダ。オプションString空の文字列
valueフィールドに事前に入力されているテキスト。オプションString

確認

validations キーの値については、次のキーを設定できます。

Key説明必須TypeDefault有効な値
required要素が完了するまでフォームの送信を禁止します。OptionalBooleanfalse

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

dropdown 要素を使用して、フォームにドロップダウン メニューを追加できます。

属性

attributes キーの値については、次のキーを設定できます。

Key説明必須TypeDefault有効な値
labelフォームに表示される、予想されるユーザ入力の簡単な説明。必須String
descriptionフォームに表示される、追加のコンテキストまたはガイダンスを提供するドロップダウンの説明。オプションString空の文字列
multipleユーザが複数のオプションを選択できるかどうかを指定します。オプションBooleanfalse
optionsユーザが選択できるオプションの配列。 空にすることはできず、すべての選択肢を区別する必要があります。必須文字列配列

確認

validations キーの値については、次のキーを設定できます。

Key説明必須TypeDefault有効な値
required要素が完了するまでフォームの送信を禁止します。OptionalBooleanfalse

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

checkboxes 要素を使用して、フォームにチェック ボックスのセットを追加できます。

属性

attributes キーの値については、次のキーを設定できます。

Key説明必須TypeDefault有効な値
labelフォームに表示される、予想されるユーザ入力の簡単な説明。必須String
descriptionフォームに表示されるチェックボックスのセットの説明。 Markdown フォーマットをサポートします。オプションString空の文字列
optionsユーザが選択できるチェックボックスの配列。 構文については、以下を参照してください。必須Array

options 配列の各値については、次のキーを設定することができます。

Key説明必須TypeDefaultオプション
labelオプションの識別子で、フォームに表示されます。 太字や斜体のテキスト書式、及びハイパーリンクについてMarkdownがサポートされています。必須String

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

参考資料