Dialog
Dialogコンポーネントは、ユーザーにとって重要な情報や操作を表します。
- SmartHR UI v15.1.0
- Storybook
- ソースコード（GitHub）
SmartHR UIではActionDialog、MessageDialog、ModelessDialogです。
主に以下の目的で使用します。
- メインコンテンツの情報・状態を保持したまま、別の情報を操作する必要がある場合
- 重要な作業の確認（追加・編集・削除）を促す場合
- メッセージや警告をユーザーに表示する場合
タイトルのつけ方
Dialogは、コンポーネントの用途がそれぞれ明確にあり、タイトルのつけ方もそれぞれ異なります。冗長な表記をなるべく避けてください。複数行になる長いタイトルは見直しましょう。
ActionDialog
基本的に、Headingの見出しの書き方と同様に画面上のオブジェクトや操作を、簡潔に体言止めで書きます。
- アクションに関わる動詞（動名詞）は、基本的に「の」で接続して表記します。例えば、オブジェクトの追加のための操作を行なう場合、タイトルは、「[オブジェクト名]の追加」となります。
- データを永久に消去するなど、破壊的なアクションを示す際は、ユーザーに確認を促すために疑問形とします。例えば、オブジェクトの操作を行なう場合、「[オブジェクト名]の[操作名]をしますか？」とします。
MessageDialog
メッセージ確認を促す簡潔な文書を入れます。ユーザーに注意喚起を促す、お知らせをしたいなど、目的に合わせたタイトルを設定してください。
ModelessDialog
[WIP]
サブタイトルの使い方
原則利用しません。タイトルだけではオブジェクトや機能を特定できない場合にのみ利用してください。
モーダルダイアログを使う際の注意
- モーダルダイアログは、常にユーザーの操作（アクション）によって表示します。ユーザーの意図しないタイミングで表示するべきではありません。
- なんでもかんでもモーダルダイアログにしてはいけません。情報設計をしっかりおこない、より適切な整理ができないかよく考えましょう。
種類
ActionDialog
ActionDialogは、ユーザーに選択の確認や操作を求める場合に使用します。アクションボタンをPrimaryで強調表示します。
SmartHR UIではActionDialogです。
MessageDialog
MessageDialogは、ユーザーへの警告や確認、承認をメッセージを通して明示的におこないたい場合に利用します。
SmartHR UIではMessageDialogです。
ModelessDialog
ModelessDialogは、ユーザーに任意のタイミングや順序で、情報の確認や操作をさせたい場合に使用します。
SmartHR UIではModelessDialogです。
設計ガイド
モーダルダイアログを閉じるアクションと挙動のルール
「キャンセル」ボタン
ユーザーが、モーダルダイアログの操作を明示的に中断するためのアクションボタンです。
主にActionDialogで使用し、ActionDialogのセカンダリアクションとして配置します。
モーダルダイアログ内の情報の保持状態（フォームの入力状態など）を初期化して、モーダルダイアログを閉じる動作をします。 モーダルダイアログ内の情報を途中保存していたり、自動保存している場合は、再表示時にもっとも近い保存時点まで復帰します。
「閉じる」ボタン
ユーザーが、モーダルダイアログを閉じるためのアクションボタンです。
主にMessageDialogで使用し、MessageDialogの（唯一の）アクションとして配置します。 同じモーダルダイアログにおいて、閉じる役割が重複する「キャンセル」ボタンと同時に配置されることはありません。
基本的に、モーダルダイアログ内の情報を保持しない場合に利用しますが、例外として、モーダルダイアログ内にフォームなどを含む場合は、閉じる際に入力状態を保存し、再表示時には復帰することを推奨します。
モーダルダイアログ外の領域のクリック
モーダルダイアログが表示されている間、モーダルダイアログ外の領域（スクリム）に対する操作やインタラクションは基本的に受け付けません。
ただし、MessageDialogなど、モーダルダイアログ内の情報を保持する必要がない用途では、モーダルダイアログ外の領域のクリックによってモーダルダイアログを閉じる動作を許容します。
ESCキー
モーダルダイアログ表示中のキーボード操作として機能し、「キャンセル」（あるいは「閉じる」）と同じ動作をします。
基準サイズ
モーダルダイアログの横幅サイズの基準値は以下のとおりです。 インターフェースを設計するとき、サイズに意図がない場合は、下記の値から意図に近い値を選択してください。
デスクトップ・タブレット
| サイズ | 値 | 補足説明 |
|---|---|---|
| S | 480px | Dialogの最小値として使います。 |
| M | 640px | |
| L | 768px | |
| MAX | calc(100% - 32px) | Dialogの最大値として使います。 |
スマートフォン
スマートフォンは表示領域が狭いため、サイズの最大値/最小値は同じとします。
| サイズ | 値 | 補足説明 |
|---|---|---|
| 標準 | calc(100% - 32px) | Dialogの最大値/最小値として使います。 |
表示位置
インターフェース設計で意図的な場合をのぞき、モーダルダイアログは画面の天地中央（上下左右中央）に表示します。
Props
ActionDialog props
| Name | Required | Type | Default Value | Description |
|---|---|---|---|---|
| children | true | string,
number,
false,
true,
{},
ReactElement<any, string | JSXElementConstructor<any>>,
ReactNodeArray,
ReactPortal | Body of the dialog. | |
| title | true | string | Title of the dialog. | |
| subtitle | - | string | ||
| closeText | true | string | Label of close button. | |
| actionText | true | string | Label of action button. | |
| actionTheme | true | "primary",
"secondary",
"danger" | Action button style theme. | |
| onClickAction | true | (closeDialog: () => void) => void | Handler function when clicking on action button.<br /> Accepts a function that closes dialog as an argument. | |
| actionDisabled | - | false,
true | Whether action button should be disabled. | |
| closeDisabled | - | false,
true | Whether close button should be disabled. | |
| className | - | string | `className` of the component. | |
| onClickClose | true | (() => void) & (() => void) | Handler function when clicking on close button. | |
| responseMessage | - | responseMessageType | ||
| portalParent | - | HTMLElement | ||
| isOpen | true | false,
true | Whether to display a Dialog. | |
| onClickOverlay | - | () => void | Handler function when clicking on onverlay. | |
| onPressEscape | - | () => void | Handler function when pressing escape key. | |
| top | - | number | Specifies the top position of the Dialog content. | |
| right | - | number | Specifies the right position of the Dialog content. | |
| bottom | - | number | Specifies the bottom position of the Dialog content. | |
| left | - | number | Specifies the left position of the Dialog content. |
MessageDialog props
| Name | Required | Type | Default Value | Description |
|---|---|---|---|---|
| title | true | string | Title of the dialog. | |
| subtitle | - | string | ||
| description | true | string,
number,
false,
true,
{},
ReactElement<any, string | JSXElementConstructor<any>>,
ReactNodeArray,
ReactPortal | Description of the dialog. | |
| closeText | true | string | Label of close button. | |
| onClickClose | true | () => void | Handler function when clicking on close button. | |
| isOpen | true | false,
true | Whether to display a Dialog. | |
| onClickOverlay | - | () => void | Handler function when clicking on onverlay. | |
| onPressEscape | - | () => void | Handler function when pressing escape key. | |
| top | - | number | Specifies the top position of the Dialog content. | |
| right | - | number | Specifies the right position of the Dialog content. | |
| bottom | - | number | Specifies the bottom position of the Dialog content. | |
| left | - | number | Specifies the left position of the Dialog content. | |
| portalParent | - | HTMLElement |
ModelessDialog props
| Name | Required | Type | Default Value | Description |
|---|---|---|---|---|
| header | true | string,
number,
false,
true,
{},
ReactElement<any, string | JSXElementConstructor<any>>,
ReactNodeArray,
ReactPortal | ダイアログのヘッダ部分の内容 | |
| children | true | string,
number,
false,
true,
{},
ReactElement<any, string | JSXElementConstructor<any>>,
ReactNodeArray,
ReactPortal | ダイアログのコンテンツ部分の内容 | |
| footer | - | string,
number,
false,
true,
{},
ReactElement<any, string | JSXElementConstructor<any>>,
ReactNodeArray,
ReactPortal | ダイアログのフッタ部分の内容 | |
| isOpen | true | false,
true | ダイアログが開かれているかどうかの真偽値 | |
| onClickClose | - | (e: MouseEvent<HTMLButtonElement, MouseEvent>) => void | 閉じるボタンを押下したときのハンドラ | |
| onPressEscape | - | () => void | ダイアログが開いている状態で Escape キーを押下したときのハンドラ | |
| width | - | string,
number | ダイアログの幅 | |
| height | - | string,
number | ダイアログの高さ | |
| top | - | string,
number | ダイアログを開いたときの初期 top 位置 | |
| left | - | string,
number | ダイアログを開いたときの初期 left 位置 | |
| right | - | string,
number | ダイアログを開いたときの初期 right 位置 | |
| bottom | - | string,
number | ダイアログを開いたときの初期 bottom 位置 | |
| portalParent | - | HTMLElement | ポータルの container となる DOM 要素を追加する親要素 |