행·셀 선택
comins-table@0.2.2
아래 Playground 경로는 해당 모듈 저장소에서 개발 서버를 실행한 뒤 사용하는 로컬 경로입니다. 현재 문서 사이트의 실행 링크는 아닙니다.
Selection은 Row, 단일/비연속 Cell, 직사각형 Cell range를 지원합니다. React ref method는 화면에 보이는 visible Row index 기준으로 Row selection을 설정합니다.
0.2.x에서 루트와 /selection은 React state 계약을 사용합니다. 중립 state에는 /core의 선택 helper를 사용합니다. 0.2.0 마이그레이션을 참고하고 state 생성과 선택 연산의 계약을 일치시킵니다.
일반·Tree 테이블에서 행 ID 순서가 바뀌면(Tree 접기·펼치기 포함) 선택이 초기화되고 onChangeSelection으로 전달됩니다. 동일한 ID와 순서를 유지하는 값 변경은 선택을 보존합니다. 이미 빈 선택은 행이 바뀌어도 중복 변경 알림을 발생시키지 않습니다.
const tableRef = useRef<CominsTableRef<Row>>(null);
<CominsTable ref={tableRef} columns={[{ field: "name", label: "Name" }]} data={data} getRowId={(row) => row.id} onChangeSelection={(selection) => setSelection(selection)}/>
tableRef.current?.setSelectedRow(1);tableRef.current?.setSelectedRows([0, 2]);Core helper는 selectRow, selectRows, selectCell, selectCellRange, getCominsSelectedCellRange, clearCominsSelection을 제공합니다. CominsCellSelectionOptions의 multi와 toggle로 selectCell 비연속 선택을 제어합니다. 이전 selectCominsRow, selectCominsCell, selectCominsCellRange 이름은 공개 API에서 제거했습니다.
cellSelection={false}를 사용하면 cell/range selection state와 스타일을 적용하지 않습니다. Row selection과 일반 cell event callback은 별개로 유지됩니다.
일반 클릭은 선택 Row와 Cell을 교체합니다. Ctrl/Cmd+클릭은 Row와 해당 Cell을 함께 추가/해제하며, Shift+클릭은 마지막 anchor부터 visible Row range와 직사각형 Cell range를 선택합니다. cellSelection을 활성화한 상태에서 Cell 사이를 drag해도 직사각형 Cell range가 생성됩니다.
CominsSelectionState.cell은 active focus와 단일 Cell Clipboard 주소를 유지합니다. CominsSelectionState.cells는 Ctrl/Cmd 비연속 Cell 집합이며 application이 만든 legacy state와의 호환성을 위해 optional입니다. range는 별도 상태이고 range 선택 시 비연속 집합을 clear합니다. clipboard 활성화 시 비연속 Cell 집합도 미선택 위치가 비어 있는 Clipboard matrix로 복사할 수 있습니다.
controlled React 사용법은 /examples/selection-clipboard (/examples/selection-clipboard)에서 확인합니다. 이 예제는 onChangeSelection 전체 payload와 copyable, pasteable guard를 함께 표시합니다.
/api/ref (/api/ref) live 예제는 setSelectedRow(index)와 setSelectedRows(indexes)를 실행합니다. 두 method의 index는 sort와 pagination 적용 후 현재 보이는 Row 기준입니다.
Column Filtering은 숨겨진 Row의 selected business Row ID를 dormant 상태로 유지하여 Filter 변경 후 다시 나타날 수 있게 합니다. Hidden Cell selection 또는 Cell range는 visible address가 더 이상 유효하지 않으므로 clear합니다.
Row·Cell 독립 선택 및 조회
섹션 제목: “Row·Cell 독립 선택 및 조회”rowSelectionOnClick={false}를 설정하면 Cell 클릭, Ctrl/Cmd 클릭, Shift 범위 선택과 우클릭이 Row 선택을 변경하지 않습니다. Row 선택은 application의 체크박스와 기존 setSelectedRows로 제어합니다. 기본값 true는 기존 Row 클릭 흐름을 유지합니다. clipboard를 활성화하면 비연속 Cell도 미선택 위치를 비운 행렬로 복사할 수 있습니다.
CominsTableRef<TData>는 getSelectedRows(): TData[], getSelectedCells(): CominsSelectedCell[], getSelection(): CominsSelectionState를 제공합니다. CominsSelectedCell은 원본 값을 포함하는 { rowId, columnId, value }입니다. 조회는 복사나 선택 변경을 수행하지 않습니다. Row 결과는 데이터 순서, Cell 범위는 투영된 표시 순서를 따릅니다. 선택 배열과 주소는 복사본이며 Row 객체와 Cell 값은 application 소유 참조를 유지합니다.
조회는 로딩된 Row만 반환하고 Viewport 요청을 실행하지 않습니다. getSelection().rowIds의 선택 ID와 실제 조회 가능한 Row 데이터를 구분해야 합니다. 큰 범위는 조회 시 열거 비용이 있으므로 매 렌더링 대신 필요한 시점에 호출합니다.
const tableRef = useRef<CominsTableRef<PersonRow>>(null);
<CominsTable ref={tableRef} columns={columns} data={rows} getRowId={(row) => row.id} onChangeData={setRows} cellSelection rowSelectionOnClick={false} clipboard/>;
// 애플리케이션 조작으로 Cell 선택과 별개로 Row 5개를 선택합니다.tableRef.current?.setSelectedRows([0, 1, 2, 3, 4]);// 사용자가 Cell 3개를 선택한 뒤에도 Row 5개와 Cell 3개를 각각 조회합니다.const selectedRows = tableRef.current?.getSelectedRows();const selectedCells = tableRef.current?.getSelectedCells();const selection = tableRef.current?.getSelection();전체 데이터를 보유한 위 예제에서 Cell 3개를 선택해도 Row 5개 선택은 유지됩니다. copySelection()은 Cell을, copySelection("rows")는 Row를 명시적으로 복사합니다. 사용자 조작 조건과 오류 처리는 Clipboard를 참고합니다. Viewport에서 선택 setter는 절대 인덱스를 받고 미로딩 Row를 건너뛰며, getter는 현재 로딩된 선택 데이터만 반환합니다.