CominsTableRef

comins-table@0.2.2React

CominsTableRef<TData>는 마운트된 테이블의 선택·정렬·컬럼 배치와 펼침 상태를 다루는 명령형 API입니다. ref.current는 마운트 전과 해제 후 null일 수 있으므로 이벤트 핸들러나 effect에서 준비 여부를 확인합니다.

전체 메서드 — 20개

copySelection

copySelection: (target?: CominsCopyTarget) => Promise<string | null>

“auto”(기본), “cells”, “rows”를 받습니다. 자동 우선순위는 여러 Cell → 선택 Row → 단일 Cell입니다. 복사된 문자열을 반환하며 복사 대상이 없으면 null입니다. OS 클립보드 쓰기 실패 시 reject하므로 사용자 클릭에서 호출하고 오류를 처리합니다. clipboard prop은 키보드 복사를 제어하며 이 ref 호출을 차단하지 않습니다.

getSelectedRows

getSelectedRows: () => TData[]

선택한 Row 데이터를 데이터 순서로 반환합니다. 선택을 변경하지 않습니다. Row 객체는 애플리케이션 소유 참조이며 Viewport에서는 현재 로딩된 선택 데이터만 반환합니다.

getSelectedCells

getSelectedCells: () => CominsSelectedCell[]

선택한 Cell의 rowId, columnId, 원본 value를 반환합니다. Cell 범위는 투영된 표시 순서를 따릅니다. Cell 값은 애플리케이션 소유 참조입니다.

getSelection

getSelection: () => CominsSelectionState

Row ID, Cell 주소와 범위의 선택 snapshot을 반환합니다. 선택 배열과 주소는 복사되며 호출로 선택을 바꾸지 않습니다.

setSelectedRow

setSelectedRow: (index: number) => void

일반 배열 Table에서는 정렬·페이지 적용 후 표시 인덱스로 한 행을 선택합니다. Viewport에서는 절대 인덱스를 사용하며 미로딩 행을 건너뜁니다.

setSelectedRows

setSelectedRows: (indexes: number[]) => void

인덱스 목록으로 Row 선택을 변경합니다. 빈 배열은 Row 선택 해제입니다. 인덱스 기준은 setSelectedRow와 같습니다.

getSortState

getSortState: () => CominsSortState | null

단일 정렬 상태를 반환합니다. 정렬이 없으면 null입니다. 다중 정렬 전체는 getSortModel을 사용합니다.

getSortModel

getSortModel: () => CominsSortModel

현재 정렬 모델 전체를 반환합니다. 반환 모델은 조회 용도로 사용하고 변경은 setter로 반영합니다.

setSortState

setSortState: (sort: CominsSortState | null) => void

내부 단일 정렬 상태를 반영합니다. null은 정렬 해제입니다. onChangeSort는 변경 알림이며 대응하는 sort 입력 prop은 없습니다.

setSortModel

setSortModel: (sortModel: CominsSortModel) => void

내부 정렬 모델을 반영합니다. 다중 정렬은 multiSort를 함께 설정합니다. onChangeSortModel은 변경 알림입니다.

clearSort

clearSort: () => void

내부 정렬을 해제하고 변경 콜백으로 알립니다. 정렬 해제를 위해 부모 data를 재정렬할 필요는 없습니다.

getColumnLayout

getColumnLayout: () => CominsColumnLayout

현재 컬럼 레이아웃을 직렬화하여 반환합니다. 전체 Row 데이터 snapshot은 아닙니다.

setColumnLayout

setColumnLayout: (layout: CominsColumnLayout) => void

컬럼 레이아웃을 적용하며 onChangeColumnLayout을 통해 변경을 알립니다. 현재 컬럼 정의와 호환되는 레이아웃을 사용합니다.

setMoveTargetRow

setMoveTargetRow: (targetIdx: number, sourceIdx: number) => void

일반 배열 Table에서 표시 인덱스 기준으로 source를 target 위치로 옮기며 정렬을 해제합니다. onChangeData로 새 데이터를 반영해야 합니다. Tree, Viewport, Row Grouping, columnFiltering 구성에서는 no-op입니다.

expand

expand: (nodeIds?: readonly CominsRowId[]) => void

Tree 노드를 펼칩니다. 생략하면 전체 대상 노드에 적용합니다. Tree 전용이며 일반 Table에서는 동작하지 않습니다. onChangeData로 전달된 Tree 노드 배열을 부모 data에 반영합니다.

fold

fold: (nodeIds?: readonly CominsRowId[]) => void

Tree 노드를 접습니다. 생략하면 전체 대상 노드에 적용합니다. expand와 같은 Tree 상태 계약을 따릅니다.

expandGroups

expandGroups: (groupIds?: readonly CominsRowId[]) => void

그룹을 펼칩니다. 생략하면 전체 그룹을 대상으로 합니다. 유효한 그룹과 rowGrouping.onChangeExpandedGroupIds가 필요하며 callback 결과를 부모가 반영합니다.

foldGroups

foldGroups: (groupIds?: readonly CominsRowId[]) => void

그룹을 접습니다. 생략하면 전체 그룹을 접습니다. expandGroups와 같은 controlled callback 계약을 따릅니다.

선택 행 조회 예제

첫 번째 행을 선택한 다음 getSelectedRows()를 누르십시오. 조회 버튼은 선택을 바꾸지 않으며 마지막 조회 결과를 표시합니다.

미리보기

코드

TableDemo.tsx

import { useRef, useState } from 'react';
import { CominsTable, type CominsTableRef, type CominsTableColumn } from 'comins-table';
import 'comins-table/styles.css';
import { modules } from '../../module-catalog';

type Module = { id: string; name: string; version: string };
const data: Module[] = modules.map(module => ({ id: module.id, name: module.label, version: module.version }));
const columns: CominsTableColumn<Module>[] = [
  { id: 'name', field: 'name', label: 'Module', width: 240, sort: true },
  { id: 'version', field: 'version', label: 'Version', width: 160 },
];
export default function TableDemo({ lang = 'ko' }: { lang?: string }) {
  const ref = useRef<CominsTableRef<Module>>(null);
  const [selected, setSelected] = useState<Module[]>([]);
  const ko = lang === 'ko';
  return <div className="demo" data-demo="table">
    <div className="demo-toolbar">
      <button onClick={() => ref.current?.setSelectedRow(0)}>{ko ? '첫 번째 행 선택' : 'Select first row'}</button>
      <button onClick={() => setSelected(ref.current?.getSelectedRows() ?? [])}>getSelectedRows()</button>
      <button onClick={() => { ref.current?.setSelectedRows([]); setSelected([]); }}>{ko ? '선택 해제' : 'Clear selection'}</button>
    </div>
    <div className="table-viewport"><CominsTable ref={ref} columns={columns} data={data} getRowId={row => row.id} rowSelectionOnClick /></div>
    <p role="status" className="demo-status">{ko ? '조회한 선택 행' : 'Retrieved selected rows'}: {selected.length ? selected.map(row => row.name).join(', ') : (ko ? '없음' : 'None')}</p>
  </div>;
}

상태 반영 시점

setter는 React 상태 갱신을 요청합니다. 같은 호출 스택에서 즉시 getter를 호출한 결과를 갱신 완료 증거로 취급하지 않습니다. controlled 데이터·Tree 노드·그룹 펼침은 부모가 callback 값을 반영해야 합니다. 정렬·선택은 내부 상태이며 콜백은 변경 알림입니다. 이 데모는 선택과 조회를 별도 사용자 이벤트로 수행합니다.

검색어

선택 행 조회, 선택된 행, 행 선택, 선택 해제, 정렬 초기화, 컬럼 배치, getSelectedRows, setSelectedRows, CominsTableRef.

근거

배포 기준 선택 가이드 · npm 0.2.0

fillSelection

fillSelection: (direction: "down" | "right") => boolean;

"down"은 선택의 첫 행을 아래로, "right"는 첫 컬럼을 오른쪽으로 반복합니다. fillHandle, cellSelection, onChangeData가 필요합니다. 실제 변경 시에만 true이며, 비활성·동일 값·거절이면 false입니다. 원본 타입을 유지하고 validateFill로 검증합니다. 미로딩 Viewport 구간은 요청하지 않습니다. 실행 예제.