테이블 기본 옵션

comins-table@0.2.2React

CominsTable의 React props 사전입니다. 일반 배열, Tree, Viewport의 차이와 기본값을 먼저 확인하고 기능별 사전으로 이동합니다. ?가 없는 속성은 해당 타입에서 필수입니다. 기본값은 comins-table 0.2.2 배포 코드 기준이며, “미지정”은 내부 상태의 기본값과 구분합니다.

clipboardPaste

clipboardPaste?: boolean;

기본값은 false입니다. 네이티브 paste 이벤트의 text/plain TSV를 받아 현재 선택부터 붙여넣습니다. cellSelection과 onChangeData가 필요하며 clipboard(복사)와 독립적입니다. 로딩 중에는 적용하지 않고 입력 요소의 기본 편집은 유지합니다. 경계 밖은 잘라내며 보호된 대상은 건너뜁니다.

fillHandle

fillHandle?: boolean;

기본값은 false입니다. cellSelection과 onChangeData를 함께 설정하면 연속 선택의 모서리에서 값을 반복해 채울 수 있습니다. 드래그 중에는 미리보기만 표시하고 놓을 때 한 번 반영합니다. Escape로 취소하며 숫자·날짜 연속값 생성이나 축소 시 삭제는 지원하지 않습니다.

onClipboardError

onClipboardError?: (error: Error) => void;

붙여넣기·채우기 실패를 전달하는 선택적 콜백입니다. 잘못된 TSV, 입력 크기 제한, 변환·검증 실패 또는 미로딩 Viewport 범위를 처리합니다. 오류 메시지 표시는 애플리케이션이 담당합니다. 거절된 작업은 데이터를 부분 반영하지 않습니다.

모드별 조합

모드	data / 필수 설정	사용할 수 없는 주요 조합
일반 배열	readonly TData[], columns	아래 기능의 제한을 따릅니다.
필터 적용 배열	위 설정 + columnFiltering.model	Tree, Viewport, 추가 로딩, Row Drag, tableTransfer
그룹 배열	위 설정 + rowGrouping	Tree, Viewport, pagination, 추가 로딩
Tree	tree: true, CominsTreeNode<TData>[], getRowId	필터, 그룹, pagination, 추가 로딩, 행 상세, tableTransfer
Viewport	CominsViewportData<TData>, viewportDatasource, getRowId, onViewportRequest	Tree, 필터, 그룹, pagination, 추가 로딩, summary, 행 상세, Row Drag, tableTransfer

그룹과 필터는 함께 사용할 수 있지만 그룹의 pagination 제한과 필터의 Row Drag 제한이 모두 적용됩니다. tableTransfer는 필터·추가 로딩 없이 일반/그룹 배열에서 사용합니다. 모든 옵션을 한 객체에 합쳐 타입 단언으로 전달하지 마십시오.

상태 소유권

data는 부모가 소유합니다. 편집·행 이동 결과는 onChangeData로 반영합니다. 필터·그룹·행 상세 펼침도 각각 값과 변경 콜백을 연결합니다. 반면 이 React API에는 selection, sort, sortModel, columnLayout 입력 prop이 없습니다. 선택·정렬·컬럼 배치는 내부 상태이며 변경 콜백은 알림입니다. 외부 명령은 CominsTableRef를 사용합니다. Core 상태 생성 옵션을 React props와 혼동하지 마십시오.

선택·ref 실행 예제

CominsTable

columns

columns: Array<CominsTableColumn<TData>>;

필수. 컬럼 정의 배열입니다. 필드·렌더러·고정·정렬은 컬럼 옵션을 참고합니다.

data

data: readonly TData[];

필수. 부모가 소유하는 읽기 전용 행 배열입니다. Tree와 Viewport는 아래 타입으로 대체합니다.

getRowId

getRowId?: (row: TData, index: number) => CominsRowId;

일반 배열에서는 선택 사항, Tree·Viewport에서는 필수입니다. 안정적인 고유 ID를 반환하십시오. index를 업무 ID로 사용하면 재정렬·삽입 시 선택이 다른 행을 가리킬 수 있습니다.

columnGroups

columnGroups?: Array<CominsTableColumnGroup>;

미지정 시 그룹 헤더 없음. children은 컬럼 ID를 참조합니다. 컬럼 옵션 참고.

cellSelection

cellSelection?: boolean;

기본 true. 셀 및 범위 선택을 활성화합니다. 행 클릭 선택과 별개입니다.

rowSelectionOnClick

rowSelectionOnClick?: boolean;

기본 true. 클릭·컨텍스트 메뉴에 의한 행 선택을 제어합니다. false로 해도 ref 선택 명령은 사용할 수 있습니다.

clipboard

clipboard?: boolean;

기본 false. 키보드 복사·붙여넣기를 활성화합니다. ref.copySelection 호출은 별도입니다. 0.2.0의 클립보드 계약을 확인합니다.

multiSort

multiSort?: boolean;

기본 false. true이면 다중 정렬을 사용할 수 있습니다. 컬럼별 sort 설정도 필요합니다. 변경 모델은 onChangeSortModel로 관찰합니다.

pagination

pagination?: Partial<CominsPaginationState>;

일반 배열 전용 부분 설정입니다. pageIndex 기본 0, pageSize 기본 max(data.length, 1)입니다. 그룹·Tree·Viewport에서는 금지됩니다.

rowProps

rowProps?: CominsTableRowProps<TData>;

행 스타일·disabled·draggable 설정입니다. 아래 CominsTableRowProps를 참고합니다.

showHeader

showHeader?: boolean;

기본 true. 헤더 표시 여부입니다.

showColumnMoveHandle

showColumnMoveHandle?: boolean;

기본 true. 컬럼 이동 핸들을 표시합니다. 고정 위치 제한은 컬럼 lockPosition으로 설정합니다.

className

className?: string;

미지정 시 사용자 클래스 없음. 테이블 루트에 추가합니다.

style

style?: React.CSSProperties;

미지정 시 사용자 인라인 스타일 없음. 높이 100%를 사용하려면 부모 높이도 정해져 있어야 합니다.

data-testid

"data-testid"?: string;

미지정 시 사용자 테스트 ID 없음. 루트 요소를 테스트에서 식별할 때 사용합니다.

theme

theme?: CominsTableTheme;

밀도·클래스·스타일 설정입니다. 아래 CominsTableTheme를 참고합니다.

summary

summary?: CominsTableSummaryConfig<TData>;

미지정 시 합계 행 없음. 전체 데이터의 집계 설정입니다. 필터가 있으면 페이지 적용 전의 필터 결과를 사용합니다. Viewport에서는 지원하지 않습니다.

tree

tree?: false;

일반 배열에서 생략하거나 false입니다. true이면 CominsTreeTableProps를 사용해야 합니다.

CominsTreeTableProps

data

data: readonly CominsTreeNode<TData>[];

필수. item과 children으로 구성한 Tree 노드 배열입니다. 일반 행 배열과 다릅니다.

getRowId

getRowId: (item: TData, index: number) => CominsRowId;

필수. Tree의 item에서 고유 ID를 반환합니다.

defaultExpandAll

defaultExpandAll?: boolean;

기본 true. 최초 마운트의 기본 펼침 정책입니다. 개별 node.expand가 우선하며, 이후 이 prop 변경으로 모든 노드를 재설정하지 않습니다.

treeRowDrag

treeRowDrag?: CominsTreeRowDragConfig<TData>;

미지정 시 Tree Drag 설정 없음. 목적지·키보드 이동 정책은 Tree 가이드에서 확인합니다.

tree

tree: true;

Tree 모드의 필수 판별자 true입니다.

CominsViewportTableProps

data

data: CominsViewportData<TData>;

필수. 전체 행 수와 로딩 블록을 담은 controlled snapshot입니다. 데이터 로딩 참고.

getRowId

getRowId: (row: TData, index: number) => CominsRowId;

필수. index는 서버 데이터의 절대 인덱스입니다. 로딩된 부분 배열의 인덱스로 해석하지 않습니다.

CominsTableRowProps

className

className?: CominsRowPropValue<TData, CominsClassValue>;

문자열·boolean 클래스 맵 또는 행별 resolver입니다. 미지정 시 사용자 클래스 없음.

disabled

disabled?: CominsRowPropValue<TData, boolean | undefined>;

기본 false. true인 행은 사용자 선택·행 이벤트·드래그가 제한됩니다. 행별 resolver도 가능합니다.

draggable

draggable?: CominsRowPropValue<TData, boolean | undefined>;

일반 행 드래그는 기본 비활성입니다. rowProps={{ draggable: true }} 또는 행별 resolver가 true를 반환해야 활성화됩니다. 일반 행 재정렬은 onChangeData 없이도 내부 순서에 반영되며, 새 data 배열을 전달하면 교체됩니다. 필터 모드에서는 지정할 수 없습니다. Tree 이동은 별도 treeRowDrag 계약을 따릅니다.

style

style?: CominsRowPropValue<TData, React.CSSProperties | undefined>;

행별 인라인 스타일 또는 resolver입니다. 자동 높이는 getRowHeight로 설정합니다.

CominsTableTheme

className

className?: string;

테마에 추가할 클래스입니다. 기본 사용자 클래스 없음.

density

density?: CominsTableDensity;

comfortable, compact, spacious 중 선택합니다. 생략 시 기본 테마 밀도를 사용합니다.

style

style?: React.CSSProperties;

테마 인라인 스타일입니다. CSS 변수 설정은 스타일 가이드를 참고합니다.

CominsTableSummaryConfig

columns

columns: Partial<Record<string, CominsSummaryColumn<TData>>>;

필수. 컬럼 ID별 집계 지정입니다. sum/avg/min/max/count, 사용자 함수, 상세 설정 객체를 받습니다.

className

className?: string;

합계 행에 추가할 클래스. 기본 없음.

label

label?: React.ReactNode;

합계 행의 표시 라벨입니다. 미지정 시 기본 표시 정책을 따릅니다.

style

style?: React.CSSProperties;

합계 행의 인라인 스타일. 기본 없음.

CominsSummaryColumnConfig

aggregate

aggregate: CominsSummaryBuiltin | CominsSummaryAggregator<TData>;

필수. 내장 집계 이름 또는 rows/values/column을 받는 사용자 집계 함수입니다.

className

className?: string;

해당 합계 셀의 추가 클래스. 기본 없음.

colSpan

colSpan?: number;

합계 셀이 차지할 열 수입니다. 병합할 표시 컬럼 범위를 확인하십시오.

format

format?: (payload: CominsSummaryFormatPayload<TData>) => React.ReactNode;

집계 결과 value를 표시용 ReactNode로 변환합니다. 원본 rows/values도 전달합니다.

style

style?: React.CSSProperties;

해당 합계 셀의 인라인 스타일. 기본 없음.

필터 모드

columnFiltering

columnFiltering: CominsColumnFilteringConfig;

부모가 소유하는 필터 설정입니다. model과 열기/변경 콜백을 필터 사전처럼 연결합니다.

그룹 및 테이블 간 이동

rowGrouping

rowGrouping: CominsRowGroupingConfig<TData, TGroup>;

필수 그룹 설정입니다. groups와 소속/펼침 제어는 그룹 사전을 참고합니다.

tableTransfer

tableTransfer?: CominsTableTransferConfig<TData, TGroup>;

미지정 시 테이블 간 이동 없음. coordinator/scope/tableId 및 충돌 정책은 테이블 간 이동 가이드를 참고합니다.

관련 API

• 이벤트

• 컬럼

• 데이터 로딩

• 필터

• 그룹

• 행 상세

• Tree 이동 옵션

• 테이블 간 이동 옵션

treeSlots

treeSlots?: never;

Tree 모드의 렌더링 슬롯입니다. Flat 모드에서는 지정할 수 없습니다.

treeSlots

treeSlots?: CominsTreeSlots<TData>;

Tree 모드의 렌더링 슬롯입니다. Flat 모드에서는 지정할 수 없습니다.

CominsTreeSlotParams

export type CominsTreeSlotParams<TData> = CominsVisibleTreeRow<TData> & {
    defaultContent: React.ReactNode;
};

CominsVisibleTreeRow의 item·rowId·depth·hasChildren·expanded 등 현재 행 정보를 상속합니다. 슬롯은 첫 Tree 컬럼에만 적용하며 기본 드래그 핸들과 펼침 토글은 슬롯 밖에 유지합니다.

속성	동작
defaultContent	기본 셀 내용입니다. content 슬롯에서 재사용합니다.

CominsTreeSlots

export type CominsTreeSlots<TData> = {
    /** Prefer { render }. Direct callbacks remain in 0.x; removal target: 1.0.0. */
    leading?: ((params: CominsTreeSlotParams<TData>) => React.ReactNode) | {
        render?: (params: CominsTreeSlotParams<TData>) => React.ReactNode;
    };
    /** Prefer { render }. Direct callbacks remain in 0.x; removal target: 1.0.0. */
    content?: ((params: CominsTreeSlotParams<TData>) => React.ReactNode) | {
        render?: (params: CominsTreeSlotParams<TData>) => React.ReactNode;
    };
    /** Prefer { render }. Direct callbacks remain in 0.x; removal target: 1.0.0. */
    trailing?: ((params: CominsTreeSlotParams<TData>) => React.ReactNode) | {
        render?: (params: CominsTreeSlotParams<TData>) => React.ReactNode;
    };
};

모든 슬롯은 선택 사항이며 ReactNode를 반환합니다. content를 생략하면 기본 내용을 표시합니다. 폴더·리프와 가상화에서 사용하며 Flat·Viewport 모드에는 지원하지 않습니다. 슬롯의 대화형 요소 클릭·키보드·클립보드 이벤트는 기본 행 선택과 Table 클립보드 동작에서 분리합니다. 접근 가능한 이름을 지정합니다.

속성	동작
leading	내용 앞에 렌더링합니다.
content	기본 내용을 대체합니다. defaultContent로 기본 내용을 포함합니다.
trailing	내용 뒤에 렌더링합니다.

render

render?: (payload: CominsSummaryRenderPayload<TData>) => React.ReactNode;

표준 렌더링 경로와 반환값은 0.2.2 전환 가이드를 참고하십시오.

emptyContent

emptyContent?: {
        render?: () => React.ReactNode;
    };

0.2.2의 표준 콘텐츠 렌더링 옵션입니다. render가 있으면 정적 콘텐츠보다 먼저 사용하며, 반환값을 표시 콘텐츠로 사용합니다. 렌더링 전환 가이드에서 위치별 우선순위와 제한을 확인하십시오.

loadingContent

loadingContent?: {
        render?: () => React.ReactNode;
    };

0.2.2의 표준 콘텐츠 렌더링 옵션입니다. render가 있으면 정적 콘텐츠보다 먼저 사용하며, 반환값을 표시 콘텐츠로 사용합니다. 렌더링 전환 가이드에서 위치별 우선순위와 제한을 확인하십시오.