DashboardGridHandle

comins-grid-layout@0.3.0React

마운트된 GridStack 엔진을 조회·갱신하는 9개 ref 메서드.

ref 준비와 상태 소유권

useRef<DashboardGridHandle>(null)을 DashboardGrid.ref에 전달합니다. React ref가 생긴 뒤에도 엔진은 비동기 초기화 중일 수 있으므로 조회 결과의 null까지 처리하십시오. unmount 후에는 ref를 다시 사용하지 않습니다.

DashboardGridHandle은 엔진을 조회·측정·정리하며, DashboardGridCommands는 React 상태를 변경합니다. onLayoutCommit={grid.commands.applyLayoutSnapshot}을 연결하여 배치 변경을 반영합니다.

전체 메서드 — 9개

getGridStack

getGridStack(): GridStack | null;

활성 GridStack 인스턴스를 반환합니다. 엔진 준비 전에는 null입니다. React가 위젯 DOM과 해제를 소유하므로 반환 객체에서 addWidget, removeWidget, load, destroy로 구성 요소를 직접 변경하지 마십시오. Comins 상태 명령을 사용합니다.

getColumnCount

getColumnCount(): number | null;

엔진이 현재 사용 중인 열 수를 반환합니다. 반응형 구성에서는 입력한 기본 columns와 다를 수 있습니다. 준비 전 null.

getRowCount

getRowCount(): number | null;

엔진이 사용하는 그리드 행 수를 반환합니다. 위젯 개수 또는 픽셀 높이가 아닙니다. 준비 전 null.

getFloat

getFloat(): boolean | null;

엔진의 현재 float 설정을 반환합니다. false는 유효한 설정이며 미준비를 의미하는 null과 구분합니다.

isAreaEmpty

isAreaEmpty(layout: Omit<DashboardWidgetLayout, "id">): boolean | null;

ID를 제외한 layout을 입력받고 (x, y, w, h) 영역이 비어 있는지 반환합니다. 위젯을 삽입하거나 상태를 예약하지 않습니다. 준비 전 null.

willItFit

willItFit(layout: Omit<DashboardWidgetLayout, "id">): boolean | null;

ID 없는 layout이 엔진 제약(예: maxRow) 내에 들어갈 수 있는지 사전 조회합니다. 실제 삽입 결과나 빈 영역 판정과 동일하지 않습니다. 준비 전 null.

refresh

refresh(): void;

크기와 드래그 핸들을 갱신하고 다음 animation frame에서 다시 측정합니다. sizeToContent가 활성화되면 콘텐츠 크기도 반영합니다. 반환값은 void이며 완료 대기용 Promise가 아닙니다. 엔진 준비 전에는 동작하지 않습니다.

compact

compact(layout?: CompactOptions, doSort?: boolean): DashboardLayoutSnapshot | null;

기본값은 layout="compact", doSort=true입니다. "compact"는 빈 공간을 채우며 순서가 바뀔 수 있고 "list"는 좌우 순서를 유지합니다. 정렬은 엔진 좌표 기준입니다. 엔진 배치를 변경하고 commit 경로를 거쳐 geometry snapshot을 반환합니다. 준비 전 null. 반환 타입은 GridStack의 fluent API와 다릅니다.

commitLayout

commitLayout(): DashboardLayoutSnapshot | null;

현재 엔진 geometry snapshot을 읽고 필요한 경우 onWidgetLayoutChange와 onLayoutCommit을 알립니다. 이전 commit과 동일하면 콜백을 반복하지 않습니다. 비반응형 상태에서 엔진 열 수와 controlled columns가 다르면 snapshot만 반환하고 알림을 생략합니다. 준비 전 null. 네트워크 저장은 수행하지 않습니다.

외부 타입 경계

GridStack과 CompactOptions는 설치된 gridstack@13.2.0의 타입입니다. 이 페이지는 Comins wrapper의 위 9개 메서드를 설명합니다. 나머지 엔진 기능은 고급 GridStack 접근 가이드와 해당 버전의 선언을 기준으로 확인하십시오.

실행 예제

미리보기

코드

GridApiDemo.tsx

import { useRef, useState } from 'react';
import { DashboardGrid, useDashboardGrid, type DashboardGridHandle } from 'comins-grid-layout';
import 'gridstack/dist/gridstack.min.css';
import 'comins-grid-layout/styles.css';

export default function GridApiDemo({ lang = 'ko' }: { lang?: string }) {
  const ko = lang === 'ko';
  const handle = useRef<DashboardGridHandle>(null);
  const sequence = useRef(0);
  const [inspection, setInspection] = useState('');
  const grid = useDashboardGrid({ initialColumns: 12, initialWidgets: [
    { id: 'first', title: 'A', layout: { id: 'first', x: 0, y: 0, w: 4, h: 2 } },
    { id: 'second', title: 'B', layout: { id: 'second', x: 6, y: 0, w: 4, h: 2 } },
  ] });
  return <div className="demo grid-demo" data-demo="grid-api">
    <div className="demo-toolbar">
      <button onClick={() => {
        const id = `added-${++sequence.current}`;
        grid.commands.addWidget({ id, title: id, layout: { id, x: 0, y: 0, w: 3, h: 2 } });
      }}>{ko ? '위젯 추가' : 'Add widget'}</button>
      <button onClick={() => grid.commands.resizeWidget('first', { w: 8, h: 3 })}>{ko ? 'A 크기 8×3' : 'Resize A to 8×3'}</button>
      <button onClick={() => grid.commands.restoreWidget('first')}>{ko ? 'A 크기 복원' : 'Restore A size'}</button>
      <button onClick={() => grid.commands.removeWidget('first')}>{ko ? 'A 삭제' : 'Remove A'}</button>
      <button onClick={() => {
        const snapshot = handle.current?.compact('list');
        setInspection(snapshot ? JSON.stringify(snapshot, null, 2) : (ko ? '그리드 준비 중' : 'Grid is initializing'));
      }}>compact('list')</button>
      <button onClick={() => {
        const ref = handle.current;
        const probe = { x: 0, y: 20, w: 2, h: 1 };
        setInspection(JSON.stringify({ columns: ref?.getColumnCount() ?? null, rows: ref?.getRowCount() ?? null,
          float: ref?.getFloat() ?? null, empty: ref?.isAreaEmpty(probe) ?? null,
          fits: ref?.willItFit(probe) ?? null }, null, 2));
      }}>{ko ? '그리드 조회' : 'Inspect grid'}</button>
      <button onClick={() => { grid.commands.resetLayout(); setInspection(''); }}>{ko ? '초기화' : 'Reset'}</button>
    </div>
    <DashboardGrid ref={handle} widgets={grid.widgets} columns={grid.columns}
      refreshKey={grid.refreshVersion} onLayoutCommit={grid.commands.applyLayoutSnapshot}
      editable movable resizable showControls={false}
      engineOptions={{ cellHeight: 60, margin: 6, animate: false }}
      renderWidget={widget => <div className="widget-content">{widget.title}</div>}
    />
    <p role="status">{ko ? '위젯 수' : 'Widget count'}: <span data-widget-count>{grid.widgets.length}</span></p>
    <details open><summary>{ko ? '현재 React 상태' : 'Current React state'}</summary>
      <pre data-grid-state>{JSON.stringify(grid.commands.serializeLayout(), null, 2)}</pre>
    </details>
    {inspection && <pre data-grid-inspection aria-live="polite">{inspection}</pre>}
  </div>;
}

근거

아래 npm 선언과 고정 소스 snapshot을 대조했습니다. snapshot은 공개 artifact의 provenance에 기록된 커밋입니다.

• comins-grid-layout/dist/gridstack/adapter.d.ts
• npm 0.3.0 · Source snapshot