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

[キー]

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

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

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

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

markdown

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

markdown の attributes

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

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

ヒント

YAML の処理では、ハッシュ記号はコメントとして扱われます。 Markdown ヘッダを挿入するには、テキストを引用符で囲みます。

複数行のテキストの場合は、パイプ演算子を使用できます。

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 フィールドにファイルを添付することもできます。

textarea の attributes

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

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

textarea の validations

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

Key説明必須TypeDefault有効な値
required要素が完了するまでフォームの送信を禁止します。 パブリック リポジトリの場合のみ。ブール値false

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

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

input の attributes

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

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

input の validations

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

Key説明必須TypeDefault有効な値
required要素が完了するまでフォームの送信を禁止します。 パブリック リポジトリの場合のみ。ブール値false

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

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

dropdown の attributes

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

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

dropdown の validations

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

Key説明必須TypeDefault有効な値
required要素が完了するまでフォームの送信を禁止します。 パブリック リポジトリの場合のみ。ブール値false

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

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

checkboxes の attributes

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

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

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

Key説明必須TypeDefaultオプション
labelオプションの識別子で、フォームに表示されます。 太字や斜体のテキスト書式、及びハイパーリンクについてMarkdownがサポートされています。String
required要素が完了するまでフォームの送信を禁止します。 パブリック リポジトリの場合のみ。ブール値false

checkboxes の validations

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

Key説明必須TypeDefault有効な値
required要素が完了するまでフォームの送信を禁止します。 パブリック リポジトリの場合のみ。ブール値false

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

参考資料