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의 프로세스 작업을 표시합니다. 구성을 시작하기 전에 다음 내용을 완료하는 것이 좋습니다.

1. Process Designer 개요를 읽고 Task Type, 필드, 폼, 단계, 워크플로 및 권한 체계의 관계를 이해합니다.
2. 빠른 시작: 구매 승인 워크플로를 완료하고 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 작업 자산 준비

현재 애플리케이션과 디자인 버전에 다음 자산이 저장되어 있는지 확인합니다.

1. Task Type에 워크플로, 권한 체계 및 필요한 폼이 구성되어 있습니다.
2. 표시하거나 검색할 사용자 정의 필드가 Task Type에 추가되어 있습니다.
3. TaskList가 참조할 수 있는 Task Filter가 하나 이상 있습니다.
4. 고급 검색이 필요하면 전용 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가 기본 검색 조건을 제공합니다.

• 첫 번째 행의 빠른 조건: 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 추가 및 구성

1. 대상 페이지를 Page Designer에서 엽니다.
2. 컴포넌트 팔레트에서 Task 그룹을 확장합니다.
3. TaskList를 수용 가능한 컨테이너로 끌어 놓습니다.
4. TaskList를 선택하고 속성 패널에서 기본 구성을 완료합니다.

TaskList의 주요 속성은 다음과 같습니다.

속성	필수	설명
Task Filter	예	Task Designer에 저장된 Filter를 선택하며 런타임에 Filter Key로 TQL을 로드합니다
Query Form	아니요	기본 검색 조건 외에 Task Form 필드를 More 영역에 추가합니다
Columns	아니요	시스템 필드와 사용자 정의 필드를 순서대로 구성합니다. 비워 두면 작업 목록 기본 열을 사용합니다
Show Filter Bar	아니요	전체 검색 영역의 표시 여부를 제어합니다
Show Column Settings	아니요	오른쪽 위 열 설정 진입점을 제어합니다. 필터 바가 표시될 때만 나타납니다
Page Size	아니요	페이지당 기본 행 수입니다. 기본값은 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에서 시스템 필드 또는 사용자 정의 필드를 선택합니다.
2. 자동으로 입력된 Column Title을 확인하고 필요한 경우 페이지 의미에 맞게 수정합니다.
3. Advanced를 열고 필요에 따라 너비, 작업 링크, 정렬, 고정 위치 및 말줄임을 설정합니다.
4. 왼쪽 트리에서 Task Column을 끌어 런타임 열 순서를 변경합니다.

디자인 캔버스의 테이블 헤더는 Task Field, Column Title 및 열 순서의 변경에 따라 업데이트되어야 합니다. Column Title이 이미 열의 표시 이름을 제공하므로 별도의 Display Name을 관리할 필요가 없습니다.

5.2 선택 가능한 필드

Task Field 후보는 두 그룹으로 나뉩니다.

• 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에 구성된 필드

기본 제공 고급 조건도 Label을 반복하지 않고 Placeholder를 사용합니다. Query Form 필드는 폼 자체의 필드 제목과 레이아웃을 유지하므로 사용자 정의 비즈니스 조건을 구분할 수 있습니다.

6.2 Search 및 Reset

• Search: 현재 빠른 조건과 Query Form 값을 읽고 첫 페이지부터 다시 검색합니다.
• 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 런타임 페이지에서 다음 항목을 순서대로 확인합니다.

1. 목록에는 Filter 범위 내의 Purchase Request만 반환됩니다.
2. 헤더가 Task Key, Title, Task Type, Current Step, Created At 순서로 표시됩니다.
3. Task Key와 Title이 모두 링크로 표시되고 클릭하면 해당 작업이 새 브라우저 탭에서 열립니다.
4. More를 펼치면 purchaseQueryForm의 필드 네 개가 표시됩니다.
5. Assignee를 선택하고 Search를 클릭한 후에도 컨트롤에 사용자 이름이 표시됩니다.
6. Department Review Result에는 부서 트리가 아니라 Approved / Rejected가 표시됩니다.
7. 작업 날짜가 포함되지 않는 Required Date 범위를 선택하면 해당 작업이 결과에서 제외됩니다.
8. Reset을 클릭하면 Task Filter가 정의한 기본 결과로 돌아갑니다.
9. 열 설정에서 열을 일시적으로 숨기고 정렬 가능한 필드를 전환할 수 있습니다.
10. 테이블의 마지막 행 바로 뒤에 구분선이 있는 페이지네이션 영역이 이어지며 큰 빈 공간이 없습니다.

다음 단계

• Filter 및 TQL
• Task Form
• 작업 권한