레퍼런스

Task와 작업 타입

작업의 필드와 의존성 항목, 네 가지 링크 문자

Task는 tasks prop에 넣는 항목 하나의 형태예요. TaskTransformed는 차트가 크기와 위치를 계산해서 넘겨주는 사본이에요. 클릭 콜백과 선택 콜백, onDetailChange, renderDetail, GanttRow.tasks가 이 타입을 받아요. 이 둘과 TaskDependency, DependencyType은 모두 패키지 루트에서 타입으로만 내보내요.

import type {
  DependencyType,
  Task,
  TaskDependency,
  TaskTransformed,
} from '@jaeungkim/gantt-chart';

동작은 가이드에서 다뤄요. 날짜와 sequence는 작업 데이터를, 상호작용 플래그는 작업 편집을 참고하세요.

DependencyType

export type DependencyType = 'FS' | 'SS' | 'FF' | 'SF';

F는 종료, S는 시작이에요. 첫 글자는 링크가 시작되는 선행 작업(predecessor)의 끝이에요. 두 번째 글자는 링크가 닿는 후행 작업(successor)의 끝이고요. 각 끝은 그 작업 막대의 한쪽 모서리예요.

값떠나는 선행 작업의 끝닿는 후행 작업의 끝
'FS'종료 (오른쪽 모서리)시작 (왼쪽 모서리)
'SS'시작 (왼쪽 모서리)시작 (왼쪽 모서리)
'FF'종료 (오른쪽 모서리)종료 (오른쪽 모서리)
'SF'시작 (왼쪽 모서리)종료 (오른쪽 모서리)

TaskDependency

export interface TaskDependency {
  /** 선행 작업의 id - 작업의 `dependencies`는 그 작업이 기다리는 작업들이에요 */
  targetId: string;
  type: DependencyType;
}
필드타입필수의미읽는 시점
targetIdstring예선행 작업의 id예요. tasks에 없는 id는 화살표나 경고 없이 건너뛰고 자기 id를 넣으면 같은 행으로 돌아오는 화살표를 그려요.항상
typeDependencyType예링크가 두 작업의 어느 막대 모서리에 붙는지 정해요. 네 가지 값이 아니면 화살표를 그리지 않고 DEV 빌드에서는 값마다 한 번씩 console.warn을 남겨요.항상

화살표를 그리고 고르고 지우는 방식은 의존성을 참고하세요.

Task

export interface Task {
  id: string;
  name: string;
  startDate: string;
  endDate: string;
  parentId: string | null;
  sequence: string;
  /** 진행률 0-100 (%) - 생략하면 진행률을 표시하지 않아요 */
  progress?: number;
  /** 막대 색 (CSS 색상이면 무엇이든) - 진행률 채움과 hover 음영을 여기서 뽑아내요. 생략하면 `--gantt-*` 토큰이 결정해요 */
  color?: string;
  /** 이 작업의 막대와 작업 목록 행에 함께 붙는 추가 클래스 이름 */
  className?: string;
  /** 이 작업이 행을 공유하는 레인 - 같은 레인끼리는 나란히 그리고, 겹치면 추가 행에 쌓여요 */
  lane?: string;
  dependencies?: TaskDependency[];
  /** 이 작업의 모든 제스처를 막아요 - 차트의 `readOnly` prop보다 우선해요 */
  readOnly?: boolean;
  /** 이 작업의 이동을 허용/차단해요 - 양쪽 `readOnly` 설정보다 우선해요 */
  allowMove?: boolean;
  /** 이 작업의 크기 조절을 허용/차단해요 - 양쪽 `readOnly` 설정보다 우선해요 */
  allowResize?: boolean;
  /** 이 작업의 진행률 핸들 드래그를 허용/차단해요 - 양쪽 `readOnly` 설정보다 우선해요 */
  allowProgressChange?: boolean;
  /** 이 작업에서 의존성 드래그를 시작하는 것을 허용/차단해요 - 양쪽 `readOnly` 설정보다 우선해요 */
  allowLinkCreate?: boolean;
  /** 이 작업이 가진 의존성을 지우는 것을 허용/차단해요 - 양쪽 `readOnly` 설정보다 우선해요 */
  allowLinkDelete?: boolean;
  /** 이 행을 다른 자리나 다른 부모로 끄는 것을 허용/차단해요 - opt-in이라, 이 값이나 차트의 `allowReorder`가 켜 주기 전까지 꺼져 있어요 */
  allowReorder?: boolean;
  /** 이 작업을 드래그할 수 있는 가장 이른 날짜 (ISO 문자열) - 차트의 `minDate`보다 우선해요 */
  minDate?: string;
  /** 이 작업을 드래그할 수 있는 가장 늦은 날짜 (ISO 문자열) - 차트의 `maxDate`보다 우선해요 */
  maxDate?: string;
}

필수 필드는 id, name, startDate, endDate, parentId, sequence 여섯 개예요. 날짜 파싱과 sequence 정렬, progress 범위 제한, 레인 패킹, minDate/maxDate 폴백 같은 필드별 규칙은 작업 데이터에서 다뤄요.

작업의 개별 플래그가 그 작업의 readOnly보다 우선해요. 그다음이 차트 단위의 같은 이름 설정이고 마지막이 차트의 readOnly예요. 전체 우선순위와 allowReorder가 따르는 더 짧은 순서는 GanttInteractionConfig를 참고하세요.

TaskTransformed

추가된 필드는 모두 차트가 계산해요. 전부 읽기 전용이에요. TaskTransformed는 출력 전용이에요. tasks는 언제나 Task[]이고 값을 바꾼 TaskTransformed는 다시 읽지 않아요.

export interface TaskTransformed extends Task {
  barLeft: number;
  barWidth: number;
  depth: number;
  order: number;
  originalOrder: number;
  /** 자식이 있는 행 - 날짜를 자식에서 롤업해서, 크기 조절과 진행률 편집이 꺼지고 드래그하면 하위 트리가 움직여요. */
  isSummary?: boolean;
  dependencies?: TaskDependency[];
}
필드타입계산 값들어오는 시점
Task의 모든 필드Task와 같음그대로 복사해요항상
barLeftnumber타임라인 원점에서 떨어진 px. 타임라인에 셀이 없으면 0항상
barWidthnumberpx. 최소 1로 제한해요. 타임라인에 셀이 없을 때만 0항상
depthnumberhierarchy가 켜져 있으면 parentId 체인의 깊이, 아니면 sequence의 점 개수항상
ordernumber레인 패킹을 마친 뒤의 1부터 시작하는 행 번호항상
originalOrdernumberorder를 다시 쓰기 전, sequence로 정렬한 배열에서의 1부터 시작하는 인덱스항상
isSummaryboolean작업에 자식이 있으면 true예요. hierarchy가 꺼져 있으면 항상 false이고 타입만 선택일 뿐 모든 작업에 값이 들어가요.항상

참고

normalizeProgress는 패키지 루트에서 내보내지 않아요. 소스에는 있고 src/shared/task.ts가 다시 내보내요. 하지만 src/index.ts에는 없어서 import { normalizeProgress } from '@jaeungkim/gantt-chart'는 실패해요. 대신 호스트 앱에서 Math.min(100, Math.max(0, progress))를 쓰세요. RenderedDependency도 내보내지 않아요.

Task에는 런타임 검증이 없어요. 필수 필드도, 날짜 파싱도, id 고유성도, 입력 progress 범위도 검사하지 않아요. 런타임 진단은 DEV 빌드에서 알 수 없는 DependencyType에 남기는 경고 하나뿐이에요.

레이아웃이 sequence.split('.')를 실행하기 때문에 sequence 없이 손으로 만든 작업은 예외를 던져요. 다른 필드는 빠져도 예외가 나지 않아요.

날짜는 dayjs.utc()가 파싱하는 값이면 무엇이든 들어가요. 반환되는 값은 Dayjs.toISOString()이 만드는 YYYY-MM-DDTHH:mm:ss.sssZ 형식이에요. 로컬 시간대 모드는 없어요.

관련 문서: GanttProps, GanttInteractionConfig, 작업 데이터.