useDashboardGrid

comins-grid-layout@0.3.0React

React 상태를 생성하고 DashboardGrid에 연결하는 초기 옵션·반환값·이벤트 계약.

호출 형태

export declare function useDashboardGrid<TData = unknown>(options?: UseDashboardGridOptions<TData>): UseDashboardGridResult<TData>;

UseDashboardGridOptions

export type UseDashboardGridOptions<TData = unknown> = {
    initialColumns?: number;
    initialWidgets?: DashboardWidget<TData>[];
    onLayoutMutation?: (event: DashboardLayoutMutationEvent<TData>) => void;
};

옵션	기본값	의미
`initialColumns`	`12`	최초 열 수. 1–12로 정규화합니다.
`initialWidgets`	`[]`	최초 위젯 배열. `id`와 `layout.id`를 일치시키십시오.
`onLayoutMutation`	없음	reducer 상태 전이 후 effect에서 전달되는 이벤트. 저장용 snapshot을 사용할 수 있습니다.

초기 옵션은 최초 마운트에서 한 번 읽습니다. 이후 initialWidgets prop을 바꾸는 것으로 상태를 동기화하지 않습니다. 외부 상태 전체를 가져오려면 restoreLayout, 부분 변경에는 개별 commands를 사용합니다. 초기 입력 객체를 직접 변형하지 마십시오.

이벤트는 kind, widgetIds, columns, snapshot을 제공합니다. snapshot은 전이 이후의 전체 state snapshot입니다. 새 상태 객체가 반환된 관찰 대상 명령에 대해 전달하며, refreshLayout과 읽기 명령에는 전달하지 않습니다. 콜백은 저장을 자동 수행하지 않습니다.

UseDashboardGridResult

export type UseDashboardGridResult<TData = unknown> = {
    state: DashboardLayoutState<TData>;
    widgets: DashboardWidget<TData>[];
    columns: DashboardLayoutState<TData>["columns"];
    refreshVersion: number;
    commands: DashboardGridCommands<TData>;
};

필드	사용 방법
`state`	전체 현재 상태. 직접 수정하지 않습니다.
`widgets`	`state.widgets`; `DashboardGrid.widgets`에 연결합니다.
`columns`	`state.columns`; `DashboardGrid.columns`에 연결합니다.
`refreshVersion`	`DashboardGrid.refreshKey`에 연결합니다.
`commands`	20개 상태 명령. 현재 렌더의 객체를 사용합니다.

컴포넌트 연결

상태를 화면에 전달하고 onLayoutCommit을 다시 commands에 연결해야 사용자 드래그 결과가 React 상태에 반영됩니다. 이 훅은 위젯 콘텐츠를 렌더링하지 않습니다. React 함수 컴포넌트 또는 custom hook의 최상위에서 호출하십시오.

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/react/use-dashboard-grid.d.ts
npm 0.3.0 · Source snapshot