レイアウト

Module の詳細・一覧・検索の各画面は、レイアウトの中に Field を配置して作ります。 3 種類のレイアウトを入れ子に組み合わせて画面を構成します。

レイアウト	特徴	主な用途
Grid	行 × 列のグリッドに配置（最も一般的）	業務アプリの入力画面の基本
Canvas	ピクセル座標で自由配置	ダッシュボード・帳票風画面
Tab	複数の内容をタブで切替	画面が長くなる時の分割

Module の Root 要素は Grid です。多くの場合 Grid を基本にして、必要に応じて Canvas・Tab・入れ子の Grid を組み合わせます。

補足: Grid の IsFlowLayout をオンにすると「行・列構造を無視して横一列に並べて折り返す Flow モード」になります。タグ列・ボタンバーなどに使います。詳細は Wrap 系の使い分けを参照。

全レイアウト共通のプロパティ

すべてのレイアウト（Grid / Canvas / Tab）で使えるプロパティ:

プロパティ	説明
Name	レイアウトの識別子（スクリプトから参照する名前）
IsViewOnly	読み取り専用
BackgroundColor	背景色（指定なしは親からカスケード）

このほか、スクリプトからは IsEnabled / IsVisible / Color / FontFamily / FontSize も全レイアウト共通で操作できます（スクリプトから参照）。

Grid レイアウト

行と列のグリッドに要素を配置します。入れ子が可能で、セルの中にさらに Grid や Canvas を入れられます。

列幅の決定ルール

列幅は以下の優先度で決まります（上から順に最初に該当したものが適用）:

IsAutoFillWrap（Grid または Row） — CSS Grid の auto-fit で均等折り返し。MinWidth 必須、カラム個別の Width/MaxWidth は無効
IsProportionalScale（Row） — 行内の各列の Width を固定 px ではなく比率として扱い、行幅に合わせて列幅の比率を保ったまま拡大縮小（下記参照）
Width 指定（固定幅） — カラムは正確に指定 px に固定
IgnoreContentWidth（中身のサイズで幅を広げない） — 行の残り幅を均等に分け合った幅で確定し、中身の大きさでは広がらない。MinWidth / MaxWidth と併用可（下記参照）
MinWidth 指定 — 均等に伸び、最小幅を保証。MaxWidth を併用すると伸びすぎ防止
センタリングパターン — 行が [空 \| 中身 \| 空] の 3 列構成のとき、中身カラムはコンテンツ幅にフィット
指定なし — 均等に伸びてコンテンツが幅を決める

プロパティ	用途
Width	固定幅（px）。`IsProportionalScale` 行では比率
MinWidth	最小幅。不足時に折り返す
MaxWidth	最大幅（`MinWidth` と併用）
IsAutoFillWrap	折り返し時に自動で均等割り（`MinWidth` 必須、`MaxWidth` は無効）
IsProportionalScale	行単位。各列の `Width` を比率として拡大縮小
IgnoreContentWidth	中身のサイズで幅を広げない（`Width` 指定の列では効果なし）
AllowOverflow	幅が確定している列で、収まらない中身を切り取らずにはみ出して表示する

中身のサイズで幅を広げない（IgnoreContentWidth）

幅を指定していない列は、中身（幅の広い ListField など）の大きさに合わせて広がります。その結果、行やページ全体が画面幅より広くなり、ページ全体に横スクロールが出ることがあります。

Column の 「中身のサイズで幅を広げない」（IgnoreContentWidth: true）を有効にすると、列幅は行の残り幅を分け合った幅で確定し、中身の大きさでは広がらなくなります。

中身が ListField の場合は、ページではなく一覧の中で横スクロールします。ListField の列固定（FixedColumnCount）と組み合わせると、画面幅に対して列固定が自然に効きます
MinWidth / MaxWidth と併用すると、分け合う幅に下限・上限を付けられます
Width を指定した列では効果がありません（幅がすでに確定しているため）
IsProportionalScale の行には使えません（比率の行は全列に Width が必要）。センタリングパターンの中身の列に指定すると中央寄せが解除されます。IsAutoFillWrap の行では効果がありません

幅が確定している列のはみ出し（AllowOverflow）

Width を指定した列と IgnoreContentWidth の列は幅が先に決まるため、中身が収まらないことがあります。この場合、列からはみ出した部分は切り取られて表示されません（わずかな余裕はあります）。

セル内からポップアップを出す場合など、はみ出して表示させたいときは Column の 「はみ出しを許可」（AllowOverflow: true）を有効にします。はみ出した部分は周囲に重なって表示され、スクロールは発生しません。幅を指定していない列はもともと中身に合わせて広がるため、指定する必要はありません。

列幅を比率で拡大縮小（IsProportionalScale）

Row の 「列幅を比率で拡大縮小」（IsProportionalScale: true）を有効にすると、その行の各列の Width を比率として扱い、画面幅が変わっても列幅の比率を保ったまま行幅いっぱいに拡大縮小します。例えば Width を 100 / 200 / 100 と指定すると、実際の幅は常に行幅の 25% / 50% / 25% になります。

制約（デザインチェックで検証されます）:

行内のすべての列に Width の指定が必須
MinWidth / MaxWidth は指定不可
列のリサイズ（CanResize）は使用不可
折り返し（IsWrap / IsAutoFillWrap）、フローレイアウト（IsFlowLayout）とは併用不可

動くサンプルは標準パターン集の レイアウト/列幅を比率で拡大縮小 を参照してください。

標準のマージン・パディング

Grid は標準でいくつかのマージン・パディングを持ち、要素間に適切なスペースが確保されています。

Grid — 通常はなし。IsBordered オン時は内側に上下 1rem / 左右 0.625rem のパディング
Row — 上下それぞれに 1rem のマージン
Column — 左右に 0.375rem のパディング。BorderStyle を指定した Column はさらに上下 0.5rem のパディング

優先順位は 個別の Padding / Margin プロパティ > CSS 変数 > 既定値。

特定の 1 箇所だけ変えたいなら、その Grid・Row・Column の Padding / Margin プロパティ
アプリ全体の既定値を変えたいなら、app.css で CSS 変数を上書き

CSS 変数名・既定値の一覧はカスタマイズ可能な CSS 変数を参照してください。

Grid プロパティ

プロパティ	説明
Name	識別子
IsViewOnly	読み取り専用
IsBordered	枠付き（カード）として描画。`background-color` は標準で透過
UseBorderedShrinkWrap	`IsBordered` 併用時、カード幅を中身のコンテンツに合わせて縮める。左右に余白ができ、結果として画面中央寄せのカードになる
Padding	内側のパディング（上下左右指定）。指定するとそのカード個別の値になり、CSS 変数より優先される
BackgroundColor	背景色（指定なしは親からカスケード）
IsFillAvailable	このグリッドが root のとき、ページの残り高さを埋めるよう末尾 Normal 行を伸ばす（FillAvailable 参照）
ScrollDirection	スクロール方向。`Unset` / `Vertical` / `Horizontal`。`Flags` なので `Vertical, Horizontal` の組合せ指定で両方向スクロール可
IsFlowLayout	行・列構造を無視して横並び＋折り返しのフロー配置（Wrap 系の使い分け参照）
IsAutoFillWrap	全行を CSS Grid `auto-fit` で均等折り返し（`MinWidth` 必須。Wrap 系の使い分け参照）
OnKeyDown	非推奨（プロパティパネルには表示されません）。このグリッド内でキーが押された時のスクリプト。Enter キーでのフォーカス移動などはフォーカス制御を使ってください（OnKeyDown イベント参照）
IsExpandable / ExpanderLabel / IsExpanderDefaultOpened	折りたたみグリッド機能。`IsExpandable` で折りたたみ可能になり、`ExpanderLabel` でヘッダ文言、`IsExpanderDefaultOpened` で初期状態（開く / 閉じる）を指定

.card の背景透過: IsBordered をオンにすると Bootstrap の .card クラスでレンダリングされますが、標準で background-color: transparent が当たっています。背景色を付けたい場合は BackgroundColor を明示的に設定してください。

Row プロパティ

プロパティ	説明
Height	行の高さ（px）
GridRowType	`Normal` / `Header` / `Footer`。`IsFillAvailable` のとき末尾の `Normal` 行が伸びる対象
Margin	行のマージン（上下左右）
BackgroundColor	行全体の背景色
CanResize	ユーザーによる行サイズ変更を許可
IsWrap	列が入りきらないときに折り返す
IsAutoFillWrap	この行だけ `auto-fit` で均等折り返しにする（`MinWidth` 必須）
IsProportionalScale	列幅を比率で拡大縮小。各列の `Width` を比率として扱い、行幅に合わせてスケール（詳細）
KeepInFillAvailableGrid	最終行フィットモード時でも Grid 内に保持。`IsFillAvailable` で伸ばす末尾の行の中身が Button や Label のような高さの決まった要素のときにオンにする（FillAvailable 参照）

Column プロパティ

プロパティ	説明
Width / MinWidth / MaxWidth	幅指定（列幅の決定ルール参照）
IgnoreContentWidth	中身のサイズで幅を広げない（詳細）
AllowOverflow	はみ出しを許可（幅が確定しているカラムのみ。詳細）
Padding	カラム内のパディング（上下左右）。指定するとそのカラム個別の値になり、CSS 変数より優先される
BackgroundColor	カラムの背景色
BorderStyle	上下左右それぞれの罫線（太さ・色を辺ごとに指定）。指定すると `--default-column-border-padding-top/bottom`（既定 0.5rem）の上下パディングが追加される
HorizontalAlignment	水平位置。`Start` / `Center` / `End` / `Stretch`（既定: Stretch）
VerticalAlignment	垂直位置。`Top` / `Middle` / `Bottom` / `Stretch`（既定: Stretch）
CanResize	ユーザーによる列サイズ変更を許可

横アライメントの副作用: Stretch 以外（Start / Center / End）にすると、中身がカラム幅にフィットせずコンテンツの固有幅になります。長いテキストはカラム幅をはみ出す可能性があるので注意してください。

Canvas レイアウト

ピクセル座標で自由に要素を配置します。デザイナ上でドラッグ＆ドロップでサイズと位置を決めます。

Canvas プロパティ

プロパティ	説明
Name	識別子
IsViewOnly	読み取り専用
IsBordered	枠を描画
BackgroundColor	背景色
ScrollDirection	スクロール方向。`Unset` / `Vertical` / `Horizontal`

Element（Canvas 上の各要素）のプロパティ

プロパティ	説明
Left / Top	配置座標（px）
Width / Height	サイズ（px）
ZIndex	重なり順

Element 自体には Name がないため、スクリプトから個別の Element を直接操作することはできません。Element の中に置いた Layout（Grid / Canvas / Tab）の Name を介して操作してください。

Tab レイアウト

複数のレイアウトをタブで切替表示します。情報量の多い画面の分割に便利です。

Tab プロパティ

プロパティ	説明
Name	識別子
Tabs	タブヘッダのラベル一覧（順番がタブの並び順）
Padding	タブパネル内側のパディング。指定すると CSS 変数（`--default-tab-padding-*`、既定上下 0.625rem / 左右 1rem）より優先される
IsBordered	タブパネルを枠付きで描画
Color	タブヘッダ（非選択タブ）の文字色
SelectedColor	選択中タブの文字色
BackgroundColor	背景色
IsViewOnly	読み取り専用
OnSelectedIndexChanged	タブ切替「後」のスクリプト
OnSelectedIndexChanging	タブ切替「前」のスクリプト。`bool` を返し、`false` で切替キャンセル

各タブの中身（Layouts）には Grid / Canvas / Tab をそれぞれ配置できます。

スクリプトから操作

// 現在選択中のタブインデックス（0 始まり）
var idx = MyTabs.SelectedIndex;

// プログラム的に切替
MyTabs.SelectedIndex = 2;

// 切替前バリデーション
bool MyTabs_OnSelectedIndexChanging(int index)
{
    if (index == 2 && string.IsNullOrEmpty(NameField.Value))
    {
        Toaster.Warn("名前を入力してください");
        return false;  // 切替キャンセル
    }
    return true;
}

SearchGridLayout（検索画面の Grid）

検索画面で使う Grid は SearchGridLayout という派生型で、条件結合の演算子を持ちます。

プロパティ	説明
Operator	子条件の結合方法。`And` / `Or` / `UserSpecified`（画面上でユーザーに選ばせる）

入れ子の SearchGridLayout で複雑な条件式（A AND (B OR C) 等）を組み立てます。詳細はモジュール検索設定を参照。

Wrap 系の使い分け（`IsFlowLayout` / `IsAutoFillWrap` / `IsWrap`）

折り返しまわりは似た名前のプロパティが複数あります。違いを整理します。

プロパティ	適用範囲	挙動
`IsWrap`	Row	カラムが入りきらないとき、行内で折り返す
`IsAutoFillWrap`	Grid または Row	CSS Grid `auto-fit` で均等幅にして折り返す（`MinWidth` 必須）
`IsFlowLayout`	Grid	行・列の構造を完全に無視して横並び＋折り返しのフロー配置にする

やりたいこと	推奨
入力フォームで横が狭くなったら折り返したい	Row の `IsWrap`
カードを画面幅に応じて 2 列・3 列・4 列と均等に並べたい	Grid または Row の `IsAutoFillWrap` + `MinWidth`
タグ・アイコン列・ボタンバーで自然に流したい	Grid の `IsFlowLayout`

FillAvailable（残領域に広げる）

Grid の IsFillAvailable をオンにすると、そのグリッドが Module の root のとき、ページの残り領域を埋める高さまで末尾の Normal 行が伸びます。

対象は GridRowType = Normal の行のうち最後のもの。Header / Footer の行は対象外
ListField を画面いっぱいの高さで表示したい場面でよく使います
伸ばす行は既定では残り領域の高さに固定され、中身の ListField などが内側でスクロールします。中身が Button や Label のような高さの決まった要素で、Grid の枠をはみ出してしまう場合は、その行の KeepInFillAvailableGrid（最終行フィットモード時でも Grid 内に保持）をオンにします。行は残り領域の高さを最小として中身に合わせて伸び、収まらない分はページ全体のスクロールになります。ListField を置いた行でオンにすると画面下端まで広がらなくなるので、通常はオフのままにします

入れ子

各レイアウトはセル / Element / タブの中に別のレイアウトを入れられます。

Grid のセル → Grid / Canvas / Tab
Canvas の Element → Grid / Canvas / Tab
Tab の各タブ → Grid / Canvas / Tab

これにより「上半分は Grid で入力フォーム、下半分は Tab で関連情報」のような複雑な画面構成が可能です。

OnKeyDown イベント

非推奨: OnKeyDown はデザイナのプロパティパネルに表示されなくなりました。設定済みの既存デザインでは引き続き動作します。Enter キーで次の入力欄へ移動する、といったキー操作によるフォーカス移動はフォーカス制御で設定してください。

Grid の OnKeyDown プロパティにスクリプトを設定すると、そのグリッド内でキーが押された時に呼び出されます。Enter / Escape / Ctrl+S 等のキー操作に応じた処理を書けます。

void GridLayoutDesign_OnKeyDown(KeyboardEventArgs e)
{
    if (e.Key == "Enter")
    {
        // 何か処理
    }
}

`KeyboardEventArgs` の主なプロパティ

プロパティ	説明
`Key`	押されたキー文字列。`"Enter"` / `"Escape"` / `"a"` / `"ArrowUp"` 等
`Code`	物理キーコード
`CtrlKey` / `ShiftKey` / `AltKey` / `MetaKey`	修飾キー押下状態
`Repeat`	長押しによるリピートか

IME 変換中のキーは届かない

日本語入力（IME）で変換中に押される Enter キー（変換確定）等は OnKeyDown には届きません。フレームワーク側で IME 変換中のキー入力を除外しているため、変換確定の Enter で意図せず処理が走る心配は不要です。

Enter 押下時の入力値の確定タイミング

入力中のフィールド（TextField 等）にフォーカスがある状態で Enter を押した場合、OnKeyDown が呼ばれた瞬間はまだ Field の Value に値が反映されていません。これはブラウザの仕様で、入力ボックスの値は keydown イベントの後に確定するためです。

確定後の値を見たい場合は、ハンドラの先頭で Task.Delay(1) を呼んでください。

void GridLayoutDesign_OnKeyDown(KeyboardEventArgs e)
{
    if (e.Key == "Enter")
    {
        Task.Delay(1);  // ブラウザの値確定処理が走るのを待つ
        Toaster.Success(NameField.Value);  // ここでは反映済み
    }
}

なぜ `Task.Delay(1)` で解決できるのか

ブラウザはキー入力をおおよそ次の順で処理します:

keydown ← OnKeyDown が呼ばれる（この時点では Value 未確定）
（内部処理）入力ボックスの値を確定 → Field の Value に反映
keyup

Task.Delay(1) は「1 ミリ秒後にスクリプトの続きを実行」という意味ですが、その 1 ミリ秒の間にブラウザが上記 2 番の値確定処理を行います。続きの処理が走る時点では Value が最新の状態になっているため、自然に最新値が読めます。

Task.Delay(0) でも動作する場合がありますが、Task.Delay(1) の方が確実です。

フォーカスが入力中フィールド以外の場合

ボタンに焦点が当たっている、画面のどこも入力中でない、といった状態で Enter を押した場合は、Value は既に確定済みです。Task.Delay(1) は不要で、いきなり値を読んで構いません。

「入力中のフィールド」かどうかは Field.HasFocus() で判定できます。

void GridLayoutDesign_OnKeyDown(KeyboardEventArgs e)
{
    if (e.Key != "Enter") return;

    // 入力中なら値確定を待つ
    if (NameField.HasFocus())
    {
        Task.Delay(1);
    }

    Toaster.Success(NameField.Value);
}

Field のレイアウト個別プロパティ

レイアウトに配置した Field は、Field 本来のプロパティのほかに配置場所固有のプロパティを持ちます。

プロパティ	説明
ClassName	任意の CSS クラス名を付与（独自スタイル用）。詳細は css.md
ContextMenu	右クリック時に表示する ContextMenuField を Field 名で指定
FontFamily / FontSize	フォント指定（指定なしは親からカスケード）
FontWeight / FontStyle	フォントウェイト・スタイル（カスケード対象外、明示指定したフィールドにだけ適用される）
Color	文字色（指定なしは親からカスケード）

同じ Field を別レイアウトに配置すると、レイアウト個別プロパティは配置ごとに別々に持てます（例: 一覧では小さく、詳細では大きく表示）。

カスケード（Color / Font / BackgroundColor）

Color / BackgroundColor / FontFamily / FontSize の 4 つだけが、明示的に指定しない場合、親レイアウトから値を引き継ぎます。FontWeight / FontStyle は親に値があっても継承しません — 明示的に指定したフィールドにだけ適用されます。

Module (詳細レイアウトの Color/Font 設定)
  └── Grid （未指定 → Module から継承）
        └── Row → Column
              └── Field (未指定 → 上位レイアウトから継承)

このため、Module の詳細レイアウトのプロパティで全体のフォントサイズを変えれば、内側の全 Field に伝わります。個別に変えたい箇所だけ Field 配置側で上書きします。

デザイナ上の表示との差異

デザイナ上の表示は、ブラウザ上の表示と完全には一致しません。最終的な表示はデプロイ後に Web ブラウザで確認してください。

特に次の項目はデザイナ上で実際の見た目と乖離しやすいです:

IsFillAvailable の伸び（実際のブラウザ高さに依存）
IsFlowLayout / IsAutoFillWrap の折り返し（ブラウザ幅に依存）
カスケードした Color / Font の表示

スクリプトから

全レイアウト共通

プロパティ	型	説明
`Name`	string	レイアウト名
`LayoutName`	string	親モジュールの現在のレイアウト名
`ModuleLayoutType`	ModuleLayoutType	`None` / `Detail` / `List` / `Search`（通常は Detail / List / Search のいずれか）
`IsEnabled`	bool	有効・無効
`IsVisible`	bool	表示・非表示
`IsViewOnly`	bool	読み取り専用
`BackgroundColor`	string?	背景色（取得時は親からカスケードした値も返す）
`Color`	string?	文字色（カスケード反映）
`FontFamily`	string?	フォント（カスケード反映）
`FontSize`	int?	フォントサイズ（カスケード反映）

Grid 固有

プロパティ	型	説明
`IsExpanded`	bool	折りたたみグリッドの開閉状態（`IsExpandable` のとき有効）

Tab 固有

プロパティ	型	説明
`SelectedIndex`	int	現在選択中のタブ（取得・設定可。設定すると `OnSelectedIndexChanged` も発火）

SearchGridLayout 固有

プロパティ	型	説明
`IsOrMatch`	bool?	OR 検索かどうか。`null` のときは設定の `Operator` に従う

よく使う例

// 初期化前にリストのロードを止める
void DetailLayoutDesign_OnBeforeInitialization()
{
    ListCookingStep.AllowLoad = false;
}

// 条件に応じてセクションを隠す
AdvancedGrid.IsVisible = IsAdmin.Value;

// プログラム的にタブを切り替える
SettingTabs.SelectedIndex = 1;

// 折りたたみグリッドを開く
DetailGrid.IsExpanded = true;

// OR 検索に切り替える（SearchGridLayout）
SearchLayout.IsOrMatch = true;

FilesExpand file tree

layout.md

Latest commit

History