メイングリッド

MainGridコンポーネントはDataverseレコードを表示するための独立したグリッドです。SubGridとは異なり、親のRecordContextを必要とせず、指定されたテーブルやビューから直接レコードを読み込みます。

テーブル名による読み込み

TableNameパラメータを設定して、そのテーブルのすべての公開ビューを自動的に読み込むようにしてください。最初のデフォルトビューが最初に選択されます。

ビューIDによる読み込み

ViewIdsとDefaultViewIdを使って、どのビューが利用可能で、どのビューが読み込み時に選択されるかを正確に制御できます。また、CustomViewDefinitionsにインラインのFetchXMLを提供し、コード内で直接ビューを定義することもできます。

FetchXMLによるカスタムビュー

CustomViewDefinitionsを使ってカスタムFetchXMLクエリでビューを定義できます。これは、現在のユーザー、リンクされたエンティティ、その他の動的条件に基づくフィルターを含むビューに有用です。

注記

カスタムGridViewDefinitionのIdは、既存のDataverseビューに対応しない一意のランダムGUIDでなければなりません。既存のビューIDと一致すれば、Dataverseビューが優先され、カスタム定義は無視されます。

ディスプレイネーム

GridViewDefinitionのDisplayNameを設定して、ローカライゼーションファイルの入力を必要とせずにドロップダウンセレクターでビューのデフォルトラベルを提供します。tables.{TableName}.views.{Id}.labelにローカライゼーションキーが存在する場合、DisplayNameよりも優先されます。これは、ローカライゼーションエントリを追加せずにすぐに読みやすい名前を得たいカスタムビューに役立ちます。

ツールバーボタン

MainGridはSubGridと同じツールバーボタンをサポートしています。独立したグリッドでは、NavigateNewRecordGridButtonとNavigateOpenRecordGridButtonが別々のフォームページに移動するためによく使われます。利用可能なすべてのボタンとその設定オプションの完全な参考文献は、グリッドボタンのドキュメントをご覧ください。

検索ボックスの挙動

ユーザーがグリッドの検索ボックスに入力すると、設定されたビューは自動的に再クエリされ、ビュー内の検索対象となるすべての列に追加のフィルター条件が適用されます。条件は OR ロジックで結びついているため、表示される列 のいずれか が検索語と一致すればレコードが含まれます。デフォルトのマッチセマンティクスは列の種類によって異なります。

テキストおよび検索カラム

テキスト列 (文字列フィールド)や ルックアップ列 (ターゲットレコードのプライマリ名と照合)は、デフォルトで 検索開始 を使用します。 joh のタイプは、 joh で始まる値(例えば John や Johnson)に一致します。マッチングはFetchXMLの like オペレーターに委譲されており、Dataverseでは大文字に区別されません。

*をワイルドカードとして使い、より柔軟なマッチングを行ってください。*hnのタイプ入力は包含スタイルのマッチング(例:John、Johnson)を行います;j*nのタイプは、jとnの間に任意の文字が現れる値をマッチさせます(例:John、Joneson)。ワイルドカードはクエリ時にFetchXMLの%ワイルドカードに変換されます。

選択列

選択列 (オプションセット/ピックリスト)および 複数選択選択列 は、各選択肢の 局所的な表示ラベル と照合され、基となる整数値とは異なります。現在のユーザーの文化ではラベルは大格やアクセントに無神経に比較されるため、 cafe と入力すると Caféとラベル付けされたオプションと一致します。1つ以上のオプションラベルが一致すると、クエリはマッチするオプション値に対してFetchXML条件を発行します。これは単一選択選択列の場合は in 条件、複数選択選択列には contain-values 条件です。ラベルが一致しない場合、その列は条件を寄与しません( OR フィルターのコンパクトさを保ちます)。

選択列はテキスト列と同じワイルドカード*を尊重します。デフォルトではマッチは(Activeと入力actマッチ)で始まり、先頭*は「contains 」に切り替わり(*act入力するとさらにInactiveとマッチします)。一致する行は、テキストカラムマッチと同様にグリッド上でマッチした部分文字列がハイライトされます。

数値およびマネーカラム

数値列 (int、big int、decimal、double、money)は検索語の比較演算子をサポートします。検索ボックスはオプションの先頭演算子を解析し、対応するFetchXML条件演算子を適用します:

• = 100 または単に 100  —  等しい(演算子が指定されていない場合のデフォルト)
• > 100  —  より大きい
• < 100  —  より少なく
• >= 100  —  大きすぎるか等しい
• <= 100  —  以下または等しい

注記

すべての列タイプの検索条件が同じ OR フィルターグループに追加されるため、同じ検索語がテキスト列、検索欄、選択欄、数値列に対して同時に評価されます。名前列と金額列の両方があるグリッドに 100 を入力すると、名前が 100で始まる レコードや 金額が100のレコードと一致します。検索フィルターはビューの既存のフィルターの上に重ねられているため、ビューレベルの制約( statecode = 0 フィルターなど)は常に保持されます。

検索を無効にする

グリッド上の AllowSearch="false" を設定して検索ボックスを完全に隠します。これは、固定されたレコードの少数セットのみを含むグリッドや、外部でフィルタリングを行う場合(例えばカスタムツールバーを通じて)に有用です。

ページングモード

グリッドは PagingMode パラメータ(Blazor)/ pagingMode プロップ(React)を通じて2つのページング戦略をサポートしています。両モードは同じ基盤ビューであるFetchXML、ソート、検索を使い、行がユーザーに表示される方法が異なるだけです。

• Paged (デフォルト) — ページサイズセレクターを備えたクラシックな 「前/次の フッター」です。短い結果セットや、ページ番号で飛び回ったり、URL内で深くリンクされたページを共有したい場合に最適です。
• Virtualize — 無限巻物。ページャーフッターは隠されており、ユーザーがレンダリングされた下部をスクロールするごとに行が積み重なり、次のページは自動的に取得されます。合計が利用可能になると、読み取り専用の「Showing 1-N of M」カウンターがページャーに代わります。ユーザーがページごとにナビゲートするのではなく、長いリストをスキャンするのに最適です。

グリッドのページングモードを設定してオプトインしてください:

トレードオフ

• ページへのジャンプもありません。仮想化モードは常に最初のページから始まり、前方に引き出します。消費者はもはやNページにスキップできません。明確なページナビゲーションが必要なら、引き続きPaged。
• ページは永続化されていません。 ユーザーのスクロール位置は離散的なページ概念ではないため、 PersistedStateQueryParameter 仮想化モードで p キーを省略しています。選択した閲覧、ソート、(オプトイン)検索は依然としてURLを往復します。
• 検索やソートは依然として機能しますが、 スクロールインしたアキュムレータがリセットされます。アクティブビューの変更、新しいソートの適用、検索ボックスへの入力で読み込まれた行がドロップされ、上から再取得されます。
• ページャーやページサイズセレクターを隠します。 ページサイズセレクタは固定チャンクサイズに置き換えられます。 DefaultItemsPerPage (Blazor)/ pageSize (React)で初期値を設定し、スクロールトリガーページあたり何行取るかを制御します。

フルサイズモード

グリッドが親コンテナの全高を満たすように FullSize="true" 設定してください。これはグリッドがページの主要な内容である場合に有用です。

持続するグリッド状態

PersistedStateQueryParameterをクエリパラメータ名(例:"gridState")に設定すると、グリッドはそのインタラクティブな状態をその名前の下の単一のURLパラメータにミラーリングします。ユーザー主導の変更—選択したビューの切り替え、ページング、ページサイズの変更、列ヘッダーのクリックによるソート、または(オプトインの)検索ボックスでの入力—は状態を再エンコードし、URLパラメータをそのまま置き換えます。パラメータ(ブックマーク、共有リンク、リフレッシュ)が存在した状態でページを開くと、グリッドは最初の読み込み時にパラメータを読み取り、キャプチャされた状態をすべて復元してからデータを取得します。

何が持続するのか

クエリパラメータは、状態ごとに1つの短い鍵を持つコンパクトなJSONオブジェクトをエンコードします。キーは意図的に略されており、ブックマークされたURLを短く保っています。自然なデフォルトに合致するフィールドは省略されるため、ソートも検索もないページ1のグリッドは、5つのフィールドすべてが入っているグリッドよりもはるかに小さな塊になります。

• v — 選択したビューのGUID(小文字、ハイフン付き、括弧なし)。グリッドに設定された ViewIds / CustomViewDefinitions エントリのいずれかと一致します。
• p — 1ベースのページ番号。ユーザーが1ページ目(デフォルト)にいる場合は省略されます。
• ps — ページあたりの行数。ページのサイズドロップダウンでユーザーの最後の選択を反映します。グリッドの DefaultItemsPerPageと一致する場合は省略します。
• s — 秩序立てられた一種の指令配列。各エントリには c (列の論理名)とオプションの d (降順は true に設定されています。昇順は無標識のデフォルトなので d 、その場合は省略されます)。空/未ソート状態はフィールドを完全に省略します。多列ソートは優先順位で保存されます。
• q — 現在の検索ボックスのテキスト。グリッドが IncludeSearchInPersistedState="true" で設定されていて、かつボックスの値が空でない場合のみ含まれます。検索語は機密扱いになることがあるため(例:CRMの文脈での顧客名など)、デフォルトでオフにしています。

URLエンコーディング

状態はコンパクトなJSON(空白なし)としてシリアライズされ、クエリパラメータにURLでエンコードされます。連絡先ビューの3ページ目を、姓の順に並べ替え、「smith」を有効にして、以下のペイロードを往復で表示します。

URLエンコーディング後の実際のアドレスバー値は次のようになります(フレームワークはJSON文字列を書く前に encodeURIComponent を呼び出します):

デフォルト価値剥離

エンコーダはシリアライズ前に、自然なデフォルトに合致するフィールドを除去します。ページ1は p、空のソートリストは s、マークなしの昇順ソートは d、空の検索は qを落とします。ユーザーの操作なしに新たに読み込まれたグリッドは、 v と ps のみを含むブロブにエンコードされ、消費者が触れていない州のブックマークURLが増えないようにしています。

ブラウザ履歴の挙動

状態の変更はURLを history.replaceState で更新します — 新しいエントリーをバックスタックにプッシュするわけではありません。つまり、グリッドページから戻るボタンを押すと、前のソート/ページの組み合わせではなく、前の別個のページ(ユーザーのナビの原点)に戻るということです。このトレードオフは意図的で、単一のグリッドセッションで数十の状態変化が生じ、それぞれをナビゲーションエントリとして押し込むと、アプリの他の部分で戻るボタンが実質的に使えなくなります。

検索永続性の有効化

デフォルトでは検索テキストはURLから除外されているため、グリッドが敏感な用語でフィルタリングされていてもパラメータは安全に共有できます。 IncludeSearchInPersistedState="true" に現在の検索ボックス値を含めるように設定します(上記の q フィールドとして追加)。一度有効化されると、検索はブックマーク可能な状態の一部となり、ユーザーはURLをコピーでき、受信者は同じビュー、ページ、ソート、フィルターの組み合わせにたどり着きます。

クロススタック互換性

エンコードされたJSON形状は、BlazorとReactのグリッド実装で同一であり、同じパラメータ名、同じキー(v / p / ps / s / q)、同じ値の意味論を持っています。一方のスタックで生成されたリンクはもう一方のスタックで消費可能であるため、両方のサーフェス(例:公開向けのReactポータルと内部のBlazor管理アプリの両方)を運営する組織は、各stackの翻訳層なしでグリッドURLを共有できます。

1ページに複数のグリッドを配置

同じページ上の2つのグリッドは異なるPersistedStateQueryParameter名を使わなければなりません。各グリッドは自分のパラメータのみを読み書きするため、同じ名前を再利用すると両方のグリッドが同じURLスロットを奪い合うことになります。最後に書き込みた方が勝ち、変更ごとにもう一方のグリッドが状態を失います。一般的な規則として、パラメータはグリッドの役割を名付ける(例:contactsState + accountsState)。

マルチテーブルグリッド

MainGridは、ViewIdsコレクションに複数のテーブルからのビューIDを含めることで、異なるテーブルからのビューを表示できます。ユーザーがビューを切り替えると、グリッドは自動的に正しいテーブルのデータを読み込みます。ナビゲーションボタンのOnClickコールバックを使って、選択したビューのテーブル名に基づいて動的にURLを設定します。