メモ
GitHub のフォーム スキーマは現在 パブリック プレビュー 段階であり、変更される可能性があります。
GitHub のフォームスキーマについて
GitHub のフォームスキーマを使用して、サポートされている機能のフォームを設定できます。 詳しくは、「リポジトリ用に Issue テンプレートを設定する」をご覧ください。
フォームは、ユーザ入力を要求するための要素のセットです。 フォームを設定するには、フォーム要素の配列である YAML フォーム定義を作成します。 各フォーム要素は、要素のタイプ、要素のプロパティ、および要素に適用する制約を決定するキー/値ペアのセットです。 一部のキーでは、値はキー/値ペアの別のセットです。
たとえば、次のフォーム定義には、ユーザのオペレーティングシステムを提供するためのテキスト領域、ユーザが実行しているソフトウェアバージョンを選択するためのドロップダウンメニュー、行動規範を確認するためのチェックボックス、およびフォームへの入力を完了したユーザに感謝する Markdown の 4 つのフォーム要素が含まれます。
- 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!"
[キー]
フォーム要素ごとに、次のキーを設定できます。
| キー | 説明 | 必須 | タイプ | デフォルト | 有効な値 |
|---|---|---|---|---|---|
type | 定義する要素のタイプ。 | String |
| ||
id | 要素の識別子。ただし、type が markdown に設定されている場合を除きます。 英数字、-、および _ のみを使用できます。 フォーム定義中で一意でなければなりません。 指定されている場合、id は URL クエリ パラメーターの事前入力のフィールドの正規識別子です。 | String | |||
attributes | 要素のプロパティを定義するキー/値ペアのセット。 | マップ | |||
validations | 要素に制約を設定するキー/値ペアのセット。 | マップ |
以下のタイプのフォーム要素から選択できます。 各タイプには、固有の属性と検証があります。
| タイプ | 説明 |
|---|---|
markdown | Markdownテキストは、フォームに表示されてユーザーに追加のコンテキストを提供しますが、送信されません。 |
textarea | 複数行のテキストフィールド。 |
input | 単一行のテキストフィールド。 |
dropdown | ドロップダウンメニュー。 |
checkboxes | チェックボックスのセット。 |
markdown
`markdown` 要素を使用して、ユーザーに追加のコンテキストを提供する Markdown をフォームに表示できますが、これは送信されません。
`markdown` の attributes
attributes キーの値については、次のキーを設定できます。
| キー | 説明 | 必須 | タイプ | デフォルト | 有効な値 |
|---|---|---|---|---|---|
value | テキストがレンダリングされます。 Markdown フォーマットはサポートされています。 | String |
ヒント
YAML の処理では、ハッシュ記号はコメントとして扱われます。 Markdown ヘッダを挿入するには、テキストを引用符で囲みます。
複数行のテキストの場合は、パイプ演算子を使用できます。
`markdown` の例
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
`textarea` 要素を使用して、フォームに複数行のテキスト フィールドを追加できます。 共同作成者は、`textarea` フィールドにファイルを添付することもできます。
`textarea` の attributes
attributes キーの値については、次のキーを設定できます。
| キー | 説明 | 必須 | タイプ | デフォルト | 有効な値 |
|---|---|---|---|---|---|
label | 予想されるユーザ入力の簡単な説明。これもフォームに表示されます。 | String | |||
description | フォームに表示される、コンテキストまたはガイダンスを提供するテキスト領域の説明。 | String | 空の文字列 | ||
placeholder | 空のときにテキスト領域に表示される半透明のプレースホルダ。 | String | 空の文字列 | ||
value | テキスト領域に事前入力されているテキスト。 | String | |||
render | 値が指定されている場合、送信されたテキストはコードブロックにフォーマットされます。 このキーを指定すると、添付ファイルや Markdown 編集のためにテキスト領域が拡張されません。 | String | GitHub に知られている言語。 詳細については、言語 YAML ファイルに関するページを参照してください。 |
`textarea` の検証
validations キーの値については、次のキーを設定できます。
| キー | 説明 | 必須 | タイプ | デフォルト | 有効な値 |
|---|---|---|---|---|---|
required | 要素が完了するまでフォームの送信を禁止します。 パブリック リポジトリの場合のみ。 | ブール値 | false |
`textarea` の例
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
`input` 要素を使用して、フォームに単一のテキスト フィールドを追加できます。
`input` の attributes
attributes キーの値については、次のキーを設定できます。
| キー | 説明 | 必須 | タイプ | デフォルト | 有効な値 |
|---|---|---|---|---|---|
label | 予想されるユーザ入力の簡単な説明。これもフォームに表示されます。 | String | |||
description | フォームに表示される、コンテキストまたはガイダンスを提供するフィールドの説明。 | String | 空の文字列 | ||
placeholder | フィールドが空のときに表示される半透明のプレースホルダー。 | String | 空の文字列 | ||
value | フィールドに事前に入力されているテキスト。 | String |
`input` の検証
validations キーの値については、次のキーを設定できます。
| キー | 説明 | 必須 | タイプ | デフォルト | 有効な値 |
|---|---|---|---|---|---|
required | 要素が完了するまでフォームの送信を禁止します。 パブリック リポジトリの場合のみ。 | ブール値 | false |
`input` の例
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
dropdown
`dropdown` 要素を使用して、フォームにドロップダウン メニューを追加できます。
`dropdown` の attributes
attributes キーの値については、次のキーを設定できます。
| キー | 説明 | 必須 | タイプ | デフォルト | 有効な値 |
|---|---|---|---|---|---|
label | フォームに表示される、予想されるユーザ入力の簡単な説明。 | String | |||
description | フォームに表示される、追加のコンテキストまたはガイダンスを提供するドロップダウンの説明。 | String | 空の文字列 | ||
multiple | ユーザが複数のオプションを選択できるかどうかを指定します。 | ブール値 | false | ||
options | ユーザが選択できるオプションの配列。 空にすることはできず、すべての選択肢を区別する必要があります。 | 文字列配列 | |||
default |
`options` 配列内の事前選択されたオプションのインデックス。 既定のオプションが指定されている場合、オプションを「None」または「n/a」にはできません。 | <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-x" aria-label="x icon" role="img"><path d="M3.72 3.72a.75.75 0 0 1 1.06 0L8 6.94l3.22-3.22a.749.749 0 0 1 1.275.326.749.749 0 0 1-.215.734L9.06 8l3.22 3.22a.749.749 0 0 1-.326 1.275.749.749 0 0 1-.734-.215L8 9.06l-3.22 3.22a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042L6.94 8 3.72 4.78a.75.75 0 0 1 0-1.06Z"></path></svg> | 整数 | <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-dash" aria-label="dash icon" role="img"><path d="M2 7.75A.75.75 0 0 1 2.75 7h10a.75.75 0 0 1 0 1.5h-10A.75.75 0 0 1 2 7.75Z"></path></svg> | <svg version="1.1" width="16" height="16" viewBox="0 0 16 16" class="octicon octicon-dash" aria-label="dash icon" role="img"><path d="M2 7.75A.75.75 0 0 1 2.75 7h10a.75.75 0 0 1 0 1.5h-10A.75.75 0 0 1 2 7.75Z"></path></svg> |
`dropdown` のバリデーション
validations キーの値については、次のキーを設定できます。
| キー | 説明 | 必須 | タイプ | デフォルト | 有効な値 |
|---|---|---|---|---|---|
required | 要素が完了するまでフォームの送信を禁止します。 パブリック リポジトリの場合のみ。 | ブール値 | false |
`dropdown` の例
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
`checkboxes` 要素を使用して、フォームにチェック ボックスのセットを追加できます。
`checkboxes` の attributes
attributes キーの値については、次のキーを設定できます。
| キー | 説明 | 必須 | タイプ | デフォルト | 有効な値 |
|---|---|---|---|---|---|
label | フォームに表示される、予想されるユーザ入力の簡単な説明。 | String | |||
description | フォームに表示されるチェックボックスのセットの説明。 Markdown フォーマットをサポートします。 | String | 空の文字列 | ||
options | ユーザが選択できるチェックボックスの配列。 構文については、以下を参照してください。 | Array |
options 配列の各値については、次のキーを設定することができます。
| Key | 説明 | 必須 | Type | Default | オプション |
|---|---|---|---|---|---|
label | オプションの識別子で、フォームに表示されます。 太字や斜体のテキスト書式、及びハイパーリンクについてMarkdownがサポートされています。 | String | |||
required | 要素が完了するまでフォームの送信を禁止します。 パブリック リポジトリの場合のみ。 | ブール値 | false |
`checkboxes` の検証
validations キーの値については、次のキーを設定できます。
| キー | 説明 | 必須 | タイプ | デフォルト | 有効な値 |
|---|---|---|---|---|---|
required | 要素が完了するまでフォームの送信を禁止します。 パブリック リポジトリの場合のみ。 | ブール値 | false |
`checkboxes` の例
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
参考資料
-
[YAML](https://yaml.org)