make-app-filter

make-app-filter

Make App のフィルタリングには、このスキルを使用してください。filter.expression を送信するキーワード検索のみの一覧では、パッケージコンパイラーを使用しますが、高度なフィルタリングは有効にしません。高度なフィルター、条件ビルダー、テーブルのフィルタリング、または CanvasTable のヘッダーにある「按该字段筛选」を使用するデスクトップ／タブレットの一覧では、次の機能を統合して提供します。

• @qfei-design/make-app-filter を使用した、パッケージに基づくツールバーの高度なフィルター
• ホストが所有する CanvasTable のヘッダーフィルター UI／メニュー
• ヘッダーの「按该字段筛选」から同じパッケージコントローラーとツールバーパネルへの連携
• Entity Preset による高度なフィルターの保存、読み込み、ハイドレーション、クリア動作
• Service の filter.expression ペイロード連携

高度なフィルタリングが対象の場合、スマートフォンでも同じパッケージコントローラー、Preset、Service の filter.expression を使用します。ただし、コンパクトなスマートフォン用ツールバーには中サイズのフィルタートリガーのみを表示し、@qfei-design/make-app-mobile/primitives の MobileFilterSheet 内で AdvancedFilterPanel layout="mobile" を使用します。スマートフォンの Select コントロールには /pickers エントリーの MobileFilterSelect を使用し、デスクトップ／タブレットのコントロールには既存の UI ライブラリを引き続き使用してください。スマートフォン上部のフィルターでは、CanvasTable ヘッダーとの連携は不要です。また、デスクトップ向けの要件を満たすために、非表示の CanvasTable をマウントしてはなりません。

デスクトップ／タブレットの Make レコード一覧ページでは、高度なフィルターだけ、またはヘッダーフィルターだけを実装してはなりません。両方を実装するか、どちらも実装しないでください。

このスキルが定めるのは、コンシューマー側のパッケージ連携契約、高度なフィルターの動作、フィールドのサポート、Entity Preset へのフィルターの永続化、Service のフィルターペイロード形式、ホストが所有するヘッダー連携のセマンティクス、URL／ディープリンクのフィルター反映、およびフィルター固有のテストです。make-app-permission から一覧アクセス状態を受け取りますが、権限ポリシーは定義しません。並べ替え（make-app-sort）、グループ化（make-app-group）、ページシェル／レイアウト（makeui）、CanvasTable のレンダリング内部やヘッダーメニュー API の詳細（canvas-table-integration）、Service のルート実装（make-app-service）、認証（make-app-auth）、ランタイムのパッケージング（make-app-runtime）、DSL のモデリング（makedsl）、Make CLI の実行（makecli）も対象外です。

機能モード

ワークフローに従う前に、モードを選択してください。以下のパネル、コントローラー、フィルター Preset、モバイルレイアウトの要件は、明記されていない限り advanced-filter にのみ適用されます。

モード	クエリ	フィルター Preset	UI とパッケージの要件
search-only	compileListFilter({ fields, searchText })	フィルター Preset の GET／PATCH またはハイドレーションなし	コントローラー、パネル、モバイルレイアウトの要件なし。パッケージのコアコンパイラーを使用
advanced-filter	compileListFilter({ fields, searchText, advancedFilter })	最初のレコードクエリの前に GET／ハイドレーションを行い、確認後にのみフィルターのディメンションを PATCH	パッケージのコントローラーとパネル。スマートフォンでは公開 API の layout="mobile" が必須

search-only では、フィルター UI がない状態で、保存済みの高度なフィルター式を読み込んだり適用したりしません。並べ替えまたはグループ化のために共有 Entity Preset が別途必要な場合は、独自のコーディネーターがその Preset を読み込んでもかまいません。このスキルは、高度なフィルタリングが有効になるまで、その filter ディメンションを使用しません。どちらのモードでも一覧アクセスのゲートに従い、パッケージコンパイラーの結果を変更せず Service に送信します。

クイックスタート

1. 「筛选」、「高级筛选」、「条件筛选」、「表格筛选」、「表头筛选」、「列头筛选」または「按字段筛选」を含む Make レコード一覧リクエストは、すべて同じフィルタリング要件として扱います。デスクトップ／タブレットでは、パッケージ提供のツールバー高度なフィルターと CanvasTable のヘッダー連携の両方を実装します。スマートフォンでは、パッケージ提供の上部フィルター入口を使用し、CanvasTable／ヘッダー連携は実装しません。
2. ホスト UI パッケージを確認します。通常は apps/ui/package.json です。UI パッケージが存在しない場合は、作業を中止してホストパッケージが見つからないことを報告します。
3. コンパイラーのみの使用、またはデスクトップ／タブレットでの使用では、@qfei-design/make-app-filter@^1.0.0 がインストールされていることを確認します。スマートフォンで高度なフィルタリングを行う場合は、ホストの互換性ゲートを通過した後、@qfei-design/make-app-filter@^1.1.0 と @qfei-design/make-app-mobile@^0.1.11 を併用します。前者は 32px の middle コントロールと、モバイルスコープのコントロールクラスを提供します。後者は MobileFilterSheet、MobileFilterSelect、および日付トリガーの className を提供します。解決済みのフィルターパッケージの公開 React 宣言で "mobile" レイアウトを確認します。以前の filter 1.0.0–1.0.3 にはこのレイアウトがありません。検索のみを行うスマートフォンの一覧では、モバイルパネルのいずれのゲートも必要なく、公開コアコンパイラーのみで対応できます。デフォルト／スタックレイアウトへの置き換えや、パッケージ内部の手書き実装は行わないでください。
4. コードを設計する前に、パッケージのドキュメントを読みます。インストール済みパッケージのドキュメントを優先してください。ホストがパッケージリポジトリ内で作業している場合は、ソースのドキュメントを読んでください。
5. 高度なフィルターモードでは、ホスト UI のエントリで @qfei-design/make-app-filter/styles.css を一度だけインポートします。検索のみでコンパイラーを使用する場合、パネルのスタイルは不要です。
6. どちらのモードでもパッケージのコアコンパイラーを使用します。高度なフィルターモードでは、さらにパッケージのパネル、コントローラー、アダプター、バリデーション、CEL 解析 API を使用します。これらの機能をホスト側にコピーしたり、手書きで実装したりしないでください。
7. 高度なフィルターモードでは、表示方式固有のツールバートリガー、デスクトップの Popover またはスマートフォンの MobileFilterSheet、適用済み状態、候補 API、Service リクエストアダプター、デスクトップ／タブレットの CanvasTable ヘッダーフィルター UI／メニューをホスト側に保持します。スマートフォンのパネルには layout="mobile" を渡し、MobileFilterSelect を使うモバイル専用コンポーネントアダプターを渡します。高さとスクロール境界はパッケージの Sheet が管理します。検索のみの場合、パネル UI はありません。デスクトップ／タブレットのコンポーネントアダプターでは、デフォルトの Make フィールド型アイコンを装飾として追加するのは、実際の「フィールドを選択」オプションのみとします。演算子、値、候補のオプションは変更しません。スマートフォンのフィールドオプションはプレーンテキストのままにします。
8. デスクトップ／タブレットでは、ヘッダーの「このフィールドで絞り込む」を同じパッケージコントローラー／パネルに接続します。ヘッダー専用の状態やローカルなフィルター実装は作成しないでください。スマートフォンにはヘッダー入口を設けません。
9. バックエンドのレコード一覧フィルター契約に準拠させます。Service は filter: { expression } を送信し、空の式はフィルターなしを意味します。フィールドの対応状況は、ランタイムメタデータとパッケージの公開 API の両方に準拠させます。compileListFilter の出力は変更せずに送信し、ホスト側で CEL／DNF を書き換えないでください。
10. エンティティのオブジェクト一覧では、make-app-permission の一覧アクセスゲートを使用します。高度なフィルタリングが有効で、一覧へのアクセスが許可されている場合に限り、最初のレコードクエリの前に現在の Entity Preset を読み込み、権限を考慮した { enabled, entityKey, generation } コンテキストを使用して、パッケージの公開 API で保存済みフィルターをハイドレートします。検索のみの場合、フィルター Preset の読み込みやハイドレートは行わず、ツールバー検索はセッション内のみで保持します。
11. フィルターの確定時には、Preset の filter ディメンションのみを PATCH します。成功後は適用済み状態を同期的に更新し、適用済み状態の変更を受けてレコードクエリを実行させます。永続化コールバック内で再読み込みしないでください。失敗した場合は、以前の適用済みフィルターと現在のドラフトを保持します。
12. 書き込み可能な一覧で make-app-actions を使用している場合、正常に適用されたフィルターの世代を引き継ぎ、新しいクエリを実行可能にする前に、選択状態をクリアして保留中の事前チェック／送信処理を無効化します。ドラフトの編集、キャンセル、保存／適用の失敗時には、現在のアクション選択を保持します。
13. 高度なフィルターモードでは、必須の固定 3 領域レイアウトを維持します。上部の固定ヘッダー、スクロール可能な条件本体、下部の固定フッターです。条件行をスクロールしている間も、ヘッダーとフッターのコントロールが常に表示されるようにします。
14. 完了前に、パッケージのコンパイル、空のフィルターの省略、Service ペイロードの形状、両モードでの一覧アクセス動作を検証します。検索のみの場合は、フィルター Preset の GET／PATCH、ハイドレート、パネル、モバイルレイアウトゲートがないことを確認します。高度なフィルタリングの場合は、固定パネルレイアウト、検索とのマージ、Preset の保存／読み込み／クリア、ドラフトの確定／破棄、候補、デスクトップ／タブレットのヘッダー連携、スマートフォンで CanvasTable を使用しないこと、ネストしたピッカーのスタッキング、パネル内の 32px コントロール、リモート検索中の選択値のエコー、パッケージとバックエンドのフィールド対応状況のずれ、条件付きアクション選択の無効化も検証します。

パッケージ導入前の確認

新規の Make Apps および明示的なランタイム移行を行う Apps では、make-app-runtime のランタイム契約を使用します。ワークスペースルートで "packageManager": "[email protected]" と "engines": { "node": "22.20.0", "pnpm": "10.20.0" } を宣言し、パッケージ操作は corepack pnpm 経由で実行します。これらの Apps では、実際の UI パッケージに依存関係をインストールしてください。たとえば、そのディレクトリで corepack pnpm add @qfei-design/make-app-filter@^1.0.0 を実行します。ロックファイルのない新規 App では、まずランタイム宣言を追加し、pnpm ワークスペースを生成する必要があります。

既存の Make Apps では、フィルターの作業中も宣言済みのランタイムを維持してください。インストールまたはアップグレードの前に、UI パッケージとワークスペースルートを特定し、packageManager、Node エンジン、React／React DOM のピア依存関係、既存のロックファイル、リポジトリで確立されているインストール／CI ワークフローを確認してください。既存のものと一致するパッケージマネージャーとワークスペースの対象を使用します。

• 互換性のある pnpm 宣言／ワークフローを伴う pnpm-lock.yaml がある場合：Corepack 経由で、そのプロジェクトに宣言された pnpm バージョンを使用し、UI パッケージに @qfei-design/make-app-filter@^1.0.0 を追加します。
• 互換性のある npm 宣言／ワークフローを伴う package-lock.json がある場合：既存の npm ワークスペースインストールコマンドで UI パッケージを対象にするか、リポジトリがワークスペースでなければ、そのパッケージのディレクトリからインストールします。
• 互換性のある Yarn 宣言／ワークフローを伴う yarn.lock がある場合：既存の Yarn ワークスペース追加コマンドで UI パッケージを対象にするか、リポジトリがワークスペースでなければ、そのパッケージのディレクトリから追加します。プロジェクトの Yarn バージョンと設定を維持してください。

フィルタリングを追加するだけのために、既存の App の packageManager、Node の選択、ワークスペースの構成、ロックファイルの種類を書き換えないでください。ロックファイルを二重に生成してはいけません。宣言、ロックファイル、CI ワークフロー、Node／ピア依存関係の制約、または対象ワークスペースが競合する場合、あるいは既存の App に明確なインストールワークフローがない場合は、そこで作業を止め、互換性の問題を make-app-runtime に報告してください。黙って移行したり、npm／Yarn プロジェクトに corepack pnpm を強制したりしてはいけません。phone フィルターパッケージのアップグレードにも同じ条件が適用されます。

phone の高度なフィルタリングでは、同じ既存のパッケージマネージャーと対象 UI パッケージを使用して、@qfei-design/make-app-filter@^1.1.0 と @qfei-design/make-app-mobile@^0.1.11 をまとめてインストールします。上記の ^1.0.0 の例は、コンパイラー／デスクトップの一般的なベースラインです。ロックファイルで実際に解決されたバージョンを確認してください。宣言された範囲だけでは、phone の両方の機能がインストールされている証拠にはなりません。

廃止された 1.0 より前のパッケージ依存関係があれば、@qfei-design/make-app-filter@^1.0.0 に移行し、公開インポートも同時に更新してください。無関係な高度なフィルターパッケージがすでに使用されている場合は、作業を止め、置き換える前に確認してください。1.0 より前のリリースにフォールバックしてはいけません。

インストール済みの 1.0.0+ パッケージに対する必須の読み取り手順：

1. node_modules/@qfei-design/make-app-filter/package.ai.json
2. package.ai.json.readOrder を解析し、各エントリーを node_modules/@qfei-design/make-app-filter からの相対パスとして解決します。
3. 参照されている各ファイルがインストール済みパッケージに存在することを確認してから、その内容を根拠として使用します。
4. すでに読み取った package.ai.json のエントリーを除き、宣言された順序で残りのエントリーを読み取ります。

package.ai.json.readOrder が唯一の信頼できる情報源です。docs/、examples/、その他のパッケージ内部のドキュメントパスをハードコードしないでください。パッケージのリポジトリで直接作業する場合は、同じエントリーをリポジトリルートから解決します。インストール済みパッケージが 1.0.0 より古い場合は、古いパッケージのドキュメントや推測した内部仕様に頼らず、先にアップグレードしてください。

トピック別参照マップ

タスク／トピック	参照先
高度なフィルタリングを使わずにfilter.expressionでキーワード検索する	references/service-translation.md、references/filter-model.mdのコンパイラーのみを使う方法
パッケージのインストール、インポート、ホストとパッケージの境界	references/package-integration.md
フィルター IR、コントローラーの下書き／確定のセマンティクス、検索のマージ、URL のエコー	references/filter-model.md
実行時のフィールド機能、演算子／値エディター API、候補値	references/operator-matrix.md
ホストの Popover／コンテナー、トリガー、パネルのサイズ、バリデーション表示	references/ui-style.md
フィルターパネルにおけるデスクトップ／タブレットのデフォルトのフィールド選択アイコン	makeui のフィールドタイプアイコン仕様
CanvasTable のヘッダー詳細メニューと高度なフィルターの連携	references/header-table-linkage.md
サービスのフィルター仕様と CEL 式のペイロード	references/service-translation.md
高度なフィルターの Entity Preset の読み込み、ハイドレーション、保存バリア、クリア、古いリクエスト	references/preset-integration.md
テスト、スモークチェック、よくあるリグレッション	references/testing-and-pitfalls.md
バックエンドの Record フィルター仕様、CEL サブセット、DateRange／File／Lookup／システム変数	makedslを使用し、EntityDataFilterUsage のリファレンスを参照してください
グループパス式の構成と record-groups のgroupFilter	make-app-groupを使用し、この Skill の DNF 式ルールを再利用してください
ツールバーの配置と周辺のページレイアウト	makeuiを使用してください
CanvasTable のsuffixRenderの仕組み	canvas-table-integrationを使用してください
サービスルートの実装とアダプターテスト	make-app-serviceを使用してください
書き込み可能なリストの選択アクションと適用済みクエリの無効化	make-app-actionsを使用してください

厳守事項

• ホストアプリで高度なフィルターの実装を新たに作成しないでください。パッケージが提供している場合、手書きの Filter IR ヘルパー、演算子マトリクス、バリデーター、CEL コンパイラー／パーサー、高度なフィルターパネルを作成しないでください。
• 高度なフィルタリングを部分的に実装しないでください。どちらのモードでも、パッケージのコンパイラーと Service の式ペイロードを使用します。高度なフィルターモードでは、さらにパッケージのコントローラーを使用します。デスクトップ／タブレットでの高度なフィルタリングでは、CanvasTable のヘッダー UI と連携を実装します。スマートフォンでの高度なフィルタリングでは、上部ツールバーのフィルター項目とモバイル対応パネルのみを使用し、CanvasTable のヘッダー連携は必要なく、表示もしません。
• スマートフォンでの高度なフィルタリングには、解決済みのバージョンで公開されている "mobile" パネルレイアウト、MobileFilterSheet、MobileFilterSelect、および AdvancedFilterPanel layout="mobile" が必要です。狭いビューポートでデスクトップ用 Popover を使うこと、layout="default" を使うこと、または条件行を CSS で縮小することは、モバイル対応ではありません。デスクトップ／タブレットの Popover の連携とレイアウトルールを維持し、共有フィルターパッケージのアップグレード後に、実際に描画されたコントロールを確認してください。検索のみの場合、モバイルパネルレイアウトやパッケージのモバイル用フィルターコンポーネントは必要ありません。
• 新しい連携では、コア API の @qfei-design/make-app-filter を使用します。高度なフィルターの連携では、さらに @qfei-design/make-app-filter/react と、任意で @qfei-design/make-app-filter/adapters/antd を使用します。
• 高度なフィルターの連携では、@qfei-design/make-app-filter/styles.css を一度だけインポートします。検索のみでコンパイラーを使用する場合、パネルのスタイルは必要ありません。ホストの CSS では外側のオーバーレイ／コンテナーをスタイル設定できますが、ホスト固有の包含上の問題を修正する場合を除き、パッケージの内部実装を分岐させないでください。
• 新しいフィルター出力では filter: { expression: string } を使用します。compileListFilter が undefined を返す場合は、filter を省略してください。
• compileListFilter は、ホストから呼び出す検索／高度なフィルターの唯一のコンパイラーです。結果は変更せずに送信してください。ホストのコードで CEL／DNF を解析、再配分、書き換えないでください。
• バックエンドの Record リストハンドラーは、Expression オブジェクトから filter.expression のみを読み取り、式がない場合、null の場合、または空白のみの場合はフィルターなしとして扱います。
• filter: []、filter: {}、{ expression: "" }、空白のみの生のフィルター文字列、旧形式のオブジェクト配列 DSL は送信しないでください。
• Make の Record リストをローカルでフィルタリングしないでください。リストのフィルタリングには Service／バックエンドのフィルター API を使用します。
• フィルターフィールドは、正規化された実行時のオブジェクト／フィールドメタデータから取得します。実行時のフィルターメタデータとして apps/dsl/**、コピーした YAML、行のサンプル、ハードコードされたデモデータを読み込まないでください。
• ホストのフィールドタイプレジストリは、共有の実行時メタデータの正規化に役立つことがありますが、フィルター演算子や値エディターを決定してはいけません。フィールドをパッケージに渡し、フィルターの信頼できる唯一の情報源として、その機能 API を使用してください。
• Lookup のフィルタリングでは、フィールドメタデータをパッケージに渡す前に、完全な実行時スキーマから relationKey、反対側の Entity、targetFieldKey を解決してください。Filter IR と CEL 式では、元の Lookup フィールドキーを維持してください。対象フィールドのメタデータは、演算子、値、検証の制御にのみ使用します。
• ユーザーと部署のフィルター値は、表示名ではなく ID です。候補の取得元は makeui／make-app-service が管理するホスト契約から取得してください。この Skill で通信ルートを定義しないでください。
• ユーザー／部署の選択肢を、フィールドスキーマの options、現在のテーブル行、ローカル配列、表示ラベルから取得しないでください。リモート候補の読み込み中にラベルを表示し続ける目的に限り、現在適用中の値を統合できます。
• バックエンドの Record フィルターは DateRange、File、Lookup のセマンティクスに対応していますが、UI でフィールドを公開できるのは、@qfei-design/make-app-filter の公開 API がそのフィールド／演算子の組み合わせをサポートしている場合のみです。バックエンドのドキュメントとパッケージの機能に相違がある場合は、パッケージのアップグレード／修正を行うか、不一致を報告してください。CEL を手書きしたり、パッケージの内部実装を推測したりしないでください。
• 高度なフィルターモードでは、Entity または権限が有効かどうかを判断するコンテキストが変更されるたびに、単調増加するリクエスト世代番号を更新し、ホストのパネル状態をリセットしてください。保存処理の完了時に entityKey だけを比較するのは安全ではありません。古い A -> B -> A の結果やアクセス権限の取り消し前の結果が、現在のものに見える可能性があるためです。検索のみの場合は、パネル状態を作成せずに古い Record クエリの応答を無効化します。
• 高度なフィルターモードでは、keyed wrapper と layout-effect のクリーンアップを組み合わせるなどして、確定済みコンテキストのリセットを行ってください。React のレンダリング中に、リクエスト世代番号、保存状態、コンテキストの ref を変更しないでください。
• 高度なフィルターモードで、現在のパッケージが保存済みの CEL をサポートしていない場合は、その生の式をバックエンドリクエストで引き続き有効にし、トリガーを有効状態で表示し、置き換えまたはクリアが明示的に保存されて成功するまで互換性に関する警告を表示してください。
• 高度なフィルターモードで、パッケージがサポートしていないフィールドは、デスクトップ／タブレットとスマートフォンのフィールドセレクター、およびデスクトップ／タブレットのヘッダーにある「按该字段筛选」から除外してください。不明なフィールド、無効なフィールドキー、またはパッケージがサポートしていないフィールド／演算子の組み合わせに対して openWithField を呼び出さないでください。
• デスクトップ／タブレットでは、ヘッダーメニューからのフィルタリングはホスト側の連携機能です。パッケージのコントローラーを通じて下書き条件を追加し、同じツールバーフィルターパネルを開きます。即時送信、Record の再読み込み、ヘッダー専用の状態の作成は行いません。スマートフォンにはヘッダーメニューはありません。
• デスクトップ／タブレットでは、テーブルのスクロール、オブジェクトの切り替え、外側のクリック、アンマウント時に、ヘッダーメニューを閉じ、ヘッダー末尾のアイコンをホバー時のみの状態に戻してください。
• 高度なフィルターパネルのレイアウトは必須です。すべての Make の高度なフィルターで、固定ヘッダー、スクロール可能な本文、固定フッターから成る 3 領域の固定レイアウトを使用してください。条件とともに追加／確定／クリアの操作もスクロールして見えなくなるパネルは、準備完了を判断する際の阻害要因です。準備完了、完成、提供済みとして報告してはいけません。
• 高度なフィルタリングが有効な場合に限り、その式を現在のユーザーの Entity Preset に保存し、最初の Record クエリより前に Preset のフィルターを読み込んで状態に反映してください。検索のみの場合、フィルター Preset の読み込み、状態への反映、書き込みは行いません。
• Preset の書き込みは必要な項目のみとします。フィルターの保存では { filter } のみを送信し、古い可能性のある sort や group は送信しません。
• 適用前に保存してください。Preset の保存に失敗した場合は、前回適用したフィルター、開いたパネル、現在の下書きを維持し、Record を再読み込みしてはいけません。
• make-app-actions が存在する場合、正常に適用されたフィルターの世代のみ、その選択状態をクリアし、保留中のアクション処理を無効化します。下書きの編集、パネルのキャンセル、検証エラー、Preset の保存失敗、リストクエリの失敗では、現在のアクション選択をクリアしたり変更したりしないでください。
• 高度なフィルターをクリアするときは filter: null を使用します。ツールバーのキーワード検索はセッション内のみとし、保存しないでください。
• リストへのアクセスが無効になった場合、新しいスキーマリクエストと Record リクエストをブロックし、進行中の結果を無効化してください。高度なフィルターモードでは、さらに Preset の GET／PATCH をブロックし、フィルター関連 UI を閉じ、entityKey または権限が有効かどうかの変更後に届いた古い Preset の読み込み／保存応答を無視してください。検索のみの場合、フィルター Preset のリクエストも、閉じるフィルター UI もありません。

デフォルトの動作

• 高度なフィルタリング UI は、どの表示モードでも任意の製品機能です。要求された場合、またはプロジェクトですでに使用されている場合にのみ、トリガーとパネルを生成します。標準のスマートフォン表示を有効にしただけでは追加されません。filter.expression を送信する検索専用リストでは、フィルタートリガー、パネル、フィルタープリセットの GET／PATCH、ハイドレーションを使わず、compileListFilter({ fields, searchText }) を使用します。明示的な undefined 値を渡すのではなく、advancedFilter は省略してください。高度なフィルタリングが対象に含まれる場合は、機能しないスマートフォン用トリガーを残すのではなく、スマートフォンでもデスクトップ／タブレットと同様に対応させてください。
• 高度なフィルタリングが対象に含まれる場合は、パッケージのコントローラー、AdvancedFilterPanel、ドラフトのライフサイクル、固定ヘッダー／本文／フッター、フィールドコントロール、Service の filter.expression を使用します。デスクトップ／タブレットでは、ツールバーのトリガー、ホストのポップオーバー、CanvasTable ヘッダーの openWithField 連携を使用します。スマートフォンでは、上部ツールバーの「フィルター」項目と、MobileFilterSheet 内のパッケージの layout="mobile" を使用します。CanvasTable、表ヘッダー、ヘッダーとの連携は不要です。
• デスクトップ／タブレットでは、高度なフィルターパネルの 3 つの領域を明確に保つ必要があります。上部のヘッダーは固定し、左側に「フィルター」、右側に「すべてクリア」を配置します。中央の本文には条件行／グループのみを含め、縦スクロールはこの領域だけで行います。下部のフッターは固定し、左側に「＋ 条件を追加」と「＋ 条件グループを追加」、右側に「確認」を配置します。スマートフォンでは 3 つの固定領域を維持しつつ、MobileFilterSheet 内でパッケージの layout="mobile" のデフォルト（「フィルター条件を設定」と「完了」）を使用します。このモードにデスクトップ用のラベルやインライン行のスタイルを適用しないでください。
• ホストは検索テキストを高度なフィルターの状態とは別に管理します。検索専用では compileListFilter({ fields, searchText }) をコンパイルに使用します。高度なフィルターモードでは、適用済みフィルターと検索を compileListFilter({ fields, searchText, advancedFilter }) で組み合わせます。
• デスクトップ／タブレットの Popover またはスマートフォンの Sheet を確定せずに閉じた場合、パッケージのコントローラーのリセット処理によって、確定前のドラフト変更を破棄します。
• クリア操作で変更されるのはドラフトのみです。適用済みフィルターに反映されるのは、現在のモードの確定操作（デスクトップ／タブレットでは「確認」、スマートフォンでは「完了」）が成功した後だけです。
• オブジェクト／エンティティまたは権限のコンテキストが変更された場合、一時的な検索状態をクリアし、古いリクエストを無効化します。高度なフィルターモードでは、フィルター／パネルの状態もクリアし、アクセスが有効な場合にのみ Entity Preset を再読み込みします。ヘッダー状態をクリアし、マウント済みであればデスクトップ／タブレットのテーブルにあるオブジェクトレベルの一時状態もリセットします。スマートフォンにはヘッダーのフィルター UI はありません。検索専用ではフィルタープリセットを再読み込みしません。

連携ルール

• makeuiとの連携：デスクトップ／タブレットのツールバー、スマートフォン用の独立した上部フィルター項目、ページシェル、周囲のレイアウト、候補ソースのUI契約にはmakeuiを使用します。このスキルでは、フィルターの動作とパッケージの統合を担当します。
• canvas-table-integrationとの連携：CanvasTableのuffixRenderとヘッダーメニューの仕組みには、そのスキルを使用します。このスキルでは、ホストの「按该字段筛选」アクションからパッケージに基づく高度なフィルターコントローラーへの連携方法を担当します。
• make-app-serviceとの連携：このスキルでは、フィルタークエリとプリセットフィルターのセマンティクスを定義します。サービスのルート検証、アダプターのログ記録、Makeリクエストの詳細はサービス側で扱います。
• make-app-sortとの連携：高度なフィルタリングが有効な場合、フィルターとソートは、親が所有する1つのEntity Presetコーディネーターとロードライフサイクルを共有しますが、それぞれのディメンションは独立して更新します。検索のみの場合、Presetのフィルターディメンションは使用しません。このスキルでは、ソートUIやソート検証を定義しません。
• make-app-groupとの連携：フィルターとグループでは式の構文を共有します。高度なフィルタリングが有効な場合は、Presetのライフサイクルを共有しますが、それぞれのディメンションは独立して更新します。このスキルではグローバルなfilter.expressionを担当し、make-app-groupでは一時的なパスgroupFilterの構成とレコードグループのタイミングを担当します。
• make-app-permissionとの連携：どちらの機能モードでも、解決済みのリストアクセスゲートを使用します。高度なフィルタリングでは、Presetリクエストの世代管理にも有効状態を含めます。このスキルでは、権限ポリシーや権限エンドポイントを定義しません。
• make-app-actionsとの連携：アクションワークフローを使用する書き込み可能なリストに限り、新しいクエリがアクション可能になる前に、正常に適用されたフィルターの世代を引き継ぎます。これにより、アクションで選択がクリアされ、保留中の処理が無効になります。下書きと失敗の経路では選択状態が維持されます。このスキルでは、CanvasTableの選択APIを直接操作しません。
• makedslとの連携：EntityDataFilterUsage.mdを参照し、DNF、システム変数、DateRange／File／Lookup、空のフィルターの扱い、エラーケースなど、バックエンドのフィルターセマンティクスを確認します。このスキルからDSLを生成しないでください。