TaskList コンポーネント
TaskList は、ページ上に Spark Tasks を表示するコンポーネントです。Task Designer に保存された Filter を基本データ範囲として使用し、タスク権限、タスクフィールド、タスク詳細、実行時検索機能を再利用します。
このガイドでは、次の設定方法を説明します。
- Task Filter で TaskList の基本タスク範囲を限定する
- Task Form で高度な検索条件を表示する
- システムフィールドとカスタムフィールドをテーブル列として追加する
- 列の順序、タイトル、幅、ソート、固定位置、省略表示を調整する
- Task Key または別の列をタスクリンクとして設定する
- フィルターバー、列設定、ページサイズを制御する
- Assignee、Select、Date、DateTime フィールドの検索動作を検証する
1. TaskList を使用する場面
TaskList は次のような場面に適しています。
- ビジネスページに特定のタスクタイプ、または一連のタスクを表示する
- TQL でタスクタイプ、ステータス、ステップなどの基本条件を固定する
- タイトル、担当者、日時、カスタムフィールドで結果を絞り込めるようにする
- リストのタスク番号やビジネスフィールドをクリックしてタスク詳細を開く
- タスクのシステムフィールドとビジネス用カスタムフィールドを同じテーブルに表示する
TaskList、DataList、ProTable では扱うデータの範囲が異なります。
| コンポーネント | 主なデータ | 検索定義 | 代表的な用途 |
|---|---|---|---|
| TaskList | Spark Tasks | Task Filter + 実行時条件 | タスクリスト、承認リスト、業務用ワークキュー |
| DataList | Business Object | DQL + モデルフィルター | 注文、顧客、設備などのオブジェクトデータ |
| ProTable | Custom URL またはモデルデータソース | HTTP リクエストパラメーターまたはモデルクエリ | 外部 API、集計データ、独自ページネーションプロトコル |
ページに表示するデータがタスクでない場合は、DataList または ProTable を使用してください。
2. 前提知識とサンプルの参照元
TaskList は Spark Tasks のプロセスタスクを表示します。設定を始める前に、次の内容を完了しておくことをお勧めします。
- Process Designer の概要を読み、Task Type、フィールド、フォーム、ステップ、ワークフロー、権限スキームの関係を理解する。
- クイックスタート：購買承認ワークフローを完了し、DEV で Purchase Request を作成、処理できることを確認する。
このガイドでは、クイックスタートで設定済みの購買承認ワークフローをそのまま再利用し、プロセス資産は再作成しません。クイックスタートには次の基本資産が含まれます。
| 資産 | サンプル設定 |
|---|---|
| Task Type | PURCHASE / Purchase Request |
| Workflow | Purchase Approval |
| カスタムフィールド | Finance Review Result、Department Review Result、Required Date などの購買申請フィールド |
| 実行データ | DEV で作成し、異なる承認分岐を検証済みの Purchase Request |
これらのプロセス資産を基に、このガイドでは TaskList に必要なリスト資産とページプロパティを設定します。
| 資産またはプロパティ | このガイドの設定 |
|---|---|
| Task Filter | All Purchase Request Tasks |
| Filter TQL | taskType = "PURCHASE" ORDER BY createdAt DESC |
| Query Form | purchaseQueryForm |
| Query Form フィールド | Assignee、Finance Review Result、Department Review Result、Required Date |
| Columns | Task Key、Title、Task Type、Current Step、Created At |
| Page Size | 20 |
| Show Filter Bar | オン |
| Show Column Settings | オン |
3. 必要な資産を準備する
3.1 タスク資産を準備する
現在のアプリケーションとデザインバージョンに、次の資産が保存されていることを確認します。
- Task Type にワークフロー、権限スキーム、必要なフォームが設定されている。
- 表示または検索するカスタムフィールドが Task Type に追加されている。
- TaskList から参照できる Task Filter が 1 つ以上存在する。
- 高度な検索が必要な場合は、専用の Task Form が作成されている。
TaskList の候補は、現在の App + Version に基づいて読み込まれます。DEV では、現在の開発バージョンに保存されたタスク資産を使用できます。TEST または PROD で検証する場合は、対応するバージョンが対象環境に公開済みであることを確認してください。
3.2 Task Filter を作成する
Task Designer → Data & Permission → Filters を開き、Filter を作成して TQL を保存します。このガイドでは次の TQL を使用します。
taskType = "PURCHASE" ORDER BY createdAt DESC
taskType = と入力したら、現在のバージョンの候補リストから Purchase Request を選択します。TQL では安定した Task Type Key である PURCHASE を使用します。表示名で Key を置き換えないでください。
Task Filter は TaskList の基本タスク範囲を決定します。実行時ユーザーがこの TQL を削除することはできず、Filter によってタスク権限が拡張されることもありません。構文と権限境界については、Filter と TQLを参照してください。
3.3 Query Form を作成する
Query Form は任意の設定であり、検索領域を表示するための必須条件ではありません。Show Filter Bar をオンにすると、Query Form を選択していない場合でも TaskList はデフォルトの検索条件を表示します。
- 1 行目のクイック条件：Title、Status、Task Type、Created At。
- More をクリックした後の高度な条件：Current Step、SLA Status、Assignee、Updated At。
Search は検索領域右側の主要ボタンとして表示されます。その直後に More と Reset のアイコンボタンが続き、操作グループの末尾に列設定が配置されます。Query Form を設定した場合も TaskList は上記のデフォルト条件を保持し、More 領域に Query Form のカスタムフィールドを追加します。Query Form がデフォルト条件を置き換えることはありません。Show Filter Bar をオフにすると、デフォルト条件と Query Form はどちらも表示されません。
ビジネス用のカスタム検索フィールドを追加する場合は、ユーザーが検索に本当に必要とするフィールドだけを含む専用 Task Form を作成してください。読み取り専用の詳細や添付フィールドが多数ある業務フォームをそのままコピーしないでください。
このガイドでは purchaseQueryForm を使用します。
| フィールド | フィールドタイプ | 実行時検索コントロール |
|---|---|---|
| Assignee | User | ユーザーセレクター |
| Finance Review Result | Select | Approved / Rejected の選択リスト |
| Department Review Result | Select | Approved / Rejected の選択リスト |
| Required Date | Date | 日付範囲ピッカー |
検索で使用する Query Form は、特定の Task Type にバインドする必要はありません。ただし、フィールド定義は現在のアプリケーションとバージョンから取得されるため、フォームが参照するフィールドが削除されていないことを確認してください。
4. TaskList を追加して設定する
- 対象ページを Page Designer で開きます。
- コンポーネントパレットの Task グループを展開します。
- TaskList を受け入れ可能なコンテナへドラッグします。
- TaskList を選択し、プロパティパネルで基本設定を行います。
TaskList の主なプロパティは次のとおりです。
| プロパティ | 必須 | 説明 |
|---|---|---|
| Task Filter | はい | Task Designer に保存された Filter を選択し、実行時に Filter Key で TQL を読み込む |
| Query Form | いいえ | デフォルト検索条件に加えて、Task Form のフィールドを More 領域に追加する |
| Columns | いいえ | システムフィールドとカスタムフィールドを順番に設定する。未設定の場合はタスクリストのデフォルト列を使用する |
| Show Filter Bar | いいえ | 検索領域全体を表示するかどうかを制御する |
| Show Column Settings | いいえ | 右上の列設定入口を制御する。フィルターバーが表示されている場合のみ表示される |
| Page Size | いいえ | 1 ページあたりのデフォルト件数。デフォルトは 20、許容範囲は 1 から 200 |
このガイドでは次の値を使用します。
Task Filter: All Purchase Request Tasks
Query Form: purchaseQueryForm
Show Filter Bar: On
Show Column Settings: On
Page Size: 20
Show Filter Bar をオフにすると、クイック条件、More、Search、Reset、列設定入口がすべて非表示になります。ページにはタスクテーブルとページネーションだけが残ります。検索範囲が固定されており、ユーザーに条件を変更させないページに適しています。
5. Columns を設定する
5.1 列を追加して並べ替える
TaskList 配下の Columns を展開し、Add をクリックします。追加するたびに左側のツリーに個別の Task Column が作成され、すべての列が 1 つの複数選択コントロールに保存されることはありません。
各列について次の設定を行います。
- Task Field でシステムフィールドまたはカスタムフィールドを選択します。
- 自動設定された Column Title を確認し、必要に応じてページの意味に合わせて変更します。
- Advanced を開き、必要に応じて幅、タスクリンク、ソート、固定位置、省略表示を設定します。
- 左側のツリーで Task Column をドラッグし、実行時の列順序を変更します。
デザインキャンバスのテーブルヘッダーは、Task Field、Column Title、列順序の変更に追従します。Column Title が列の表示名をすでに提供するため、追加の Display Name を管理する必要はありません。
5.2 選択可能なフィールド
Task Field の候補は 2 つのグループに分かれます。
- System Fields：Task Key、Title、Task Type、Status、Current Step、Assignee、Creator、Created At、Updated At、SLA など。
- Custom Fields：現在のアプリケーションとバージョンで定義されたタスクフィールド。Amount、Category、Required Date、Department Review Result など。
カスタムフィールドが単独の Worklist のデフォルト表示列でない場合でも、ページ作成者は TaskList に明示的に追加できます。
5.3 列の詳細プロパティ
| プロパティ | 説明 |
|---|---|
| Width | ピクセル単位の列幅 |
| Task Link | 列の値をクリックしたときにタスクを開く |
| Enable Sorting | その列によるソートを許可する。バックエンドがソートをサポートするフィールドにのみ有効 |
| Fixed Column | 列をテーブルの左側または右側に固定する |
| Show Ellipsis | 内容が列幅を超えた場合に省略表示する |
SLA ステータス列が表示される場合は、常に先頭列に固定されます。その直後に Task Key と Title を配置し、両方で Task Link をオンにすることをお勧めします。その他のビジネスフィールドもタスクリンクにできます。特定の列で Task Link を明示的にオフにすると、その列は通常のテキストとして表示されます。
実行時の列設定では、設定済みの列を一時的に非表示にしたり、順序を変更したりできます。Page Designer の列構造や順序が変更されることはありません。
6. 実行時の検索領域
6.1 クイック検索条件
Show Filter Bar をオンにすると、TaskList の上部にはデフォルトで次のクイック条件が表示されます。
- Title
- Status
- Task Type
- Created At
これらのコントロールは Placeholder で用途を示し、可視 Label を重複して表示しません。右側には Search、More、Reset、列設定の順で配置されます。More と Reset は Tooltip 付きのアイコンボタンです。検索条件と操作グループは同じ水平線上で垂直方向に中央揃えされます。
More をクリックすると、次の条件が表示されます。
- Current Step
- SLA Status
- Assignee
- Updated At
- Query Form に設定されたフィールド
組み込みの高度な条件も Placeholder を使用し、Label を重複して表示しません。Query Form のフィールドはフォーム固有のタイトルとレイアウトを保持するため、カスタムビジネス条件を識別できます。
6.2 Search と Reset
- Search：現在のクイック条件と Query Form の値を読み取り、1 ページ目から再検索します。
- More アイコン：高度な条件と Query Form を展開または折りたたみます。
- Reset アイコン：実行時条件と Query Form の値をクリアし、再検索します。
- Enter：Title 入力欄で Enter キーを押すと、直接検索を実行します。
空の値は検索に含まれません。Task Filter、クイック条件、Query Form の条件は AND で結合されます。テナント、アプリケーション、環境、タスク閲覧権限は常にバックエンドで強制されます。
たとえば、このガイドの基本 Filter はすでに taskType = "PURCHASE" に限定されています。さらに Assignee と Required Date を選択すると、結果は次のすべてを満たす必要があります。
Purchase Request の基本範囲
AND 現在の Assignee
AND Required Date の範囲
AND 現在のユーザーのタスク閲覧権限
7. Query Form フィールドの検索ルール
検索コントロールはフィールドの実際のタイプで決まり、フィールド名から推測されることはありません。
| フィールドタイプ | 検索動作 |
|---|---|
| Text、Textarea、Rich Text、Markdown | 部分一致 |
| Select、Radio、Switch | 完全一致 |
| 複数選択フィールド | IN によるコレクション一致 |
| Number | 完全一致 |
| User、Assignee | ユーザーセレクターはユーザー ID を送信し、画面には引き続きユーザー名を表示する |
| Department | 部門ツリーセレクター |
| Date、DateTime | 開始と終了の両方の境界を含む範囲検索 |
| Attachment | 検索モードでは表示しない |
非表示フィールドは Query Form に含まれません。業務フォームでの Required 設定は検索モードでは強制されず、値が入力されていない条件は無視されます。
7.1 Assignee
Assignee は現在のアプリケーションで利用可能なユーザーディレクトリを検索します。ユーザーを選択すると、検索リクエストは安定したユーザー ID を使用しますが、コントロールには引き続きユーザー名またはアカウントが表示されます。Search をクリックした後に数値 ID へ変わってはいけません。
7.2 Select
Select はフィールドに設定された Options に従って表示する必要があります。このガイドの Department Review Result と Finance Review Result は、どちらも次の値を表示します。
Approved
Rejected
フィールド名に Department が含まれていても、Select が部門セレクターに変わることはありません。実際のタイプが Department のフィールドだけが部門ツリーを表示します。
7.3 Date と DateTime
Query Form の Date と DateTime は範囲ピッカーを使用します。
- 開始値だけを選択：
field >= startで検索 - 終了値だけを選択：
field <= endで検索 - 両方を選択：
field >= start AND field <= endで検索
両方の境界が含まれます。Date フィールドは日付値で検索し、DateTime フィールドでは具体的な時刻を選択できます。
8. タスクを開く操作とページインタラクション
列で Task Link をオンにすると、その列の値をクリックしてタスクを開けます。
onTaskClick未設定：Spark 標準のタスク詳細ページを新しいブラウザータブで開き、現在のビジネスページはそのまま保持します。onTaskClick設定済み：現在のページで Page Designer のインタラクションを実行し、taskとrecordのコンテキストを提供します。この場合、標準のタスク詳細ページは自動的に開きません。- Ctrl または Command キーを押しながらのクリックなど：ブラウザー標準のリンク動作を保持します。
ページ内の別のボタンから TaskList を更新するには、この Component API を対象コンポーネントに対して呼び出します。
reloadTable
9. サンプルの検証チェックリスト
このガイドで使用する DEV 実行ページで、次の項目を順番に確認します。
- リストには Filter の範囲内にある Purchase Request だけが返される。
- ヘッダーが Task Key、Title、Task Type、Current Step、Created At の順に表示される。
- Task Key と Title がどちらもリンクになり、クリックすると対応するタスクが新しいブラウザータブで開く。
- More を展開すると、
purchaseQueryFormの 4 フィールドが表示される。 - Assignee を選択して Search をクリックした後も、コントロールにユーザー名が表示される。
- Department Review Result に部門ツリーではなく Approved / Rejected が表示される。
- タスクの日付を含まない Required Date 範囲を選択すると、そのタスクが結果から除外される。
- Reset をクリックすると、Task Filter で定義された基本結果に戻る。
- 列設定で列を一時的に非表示にし、ソート可能なフィールドを切り替えられる。
- テーブルの最終行の直後に区切り線付きのページネーション領域が続き、大きな空白がない。