FreeGridv1.15.1English

새로고침해도 레이아웃 유지

stateKey는 컬럼 너비·순서·숨김·고정, 정렬 등을 브라우저에 저장해 다음 방문 때 되살립니다. 컬럼 초기화도 저장되고 clearSavedState는 지웁니다.

실행 예제레이아웃 유지

컬럼을 바꾸고 새로고침해 보세요.

이 데모의 코드
import { createGrid, type ColumnDef, type Row } from '@freegridjs/core';
import { makeRows } from '../data';
import { button, separator, text, tr, type DemoContext } from '../ui';

export default function mount(ctx: DemoContext) {
  const h = (en: string, ko: string) => tr(ctx.lang, { en, ko });
  const grid = createGrid(ctx.host, {
    columns: [{ field: 'id', header: 'ID', type: 'number', width: 70 }, { field: 'name', header: h('Name', '이름'), width: 170 }, { field: 'company', header: h('Company', '회사'), width: 160 }, { field: 'country', header: h('Country', '국가'), width: 140 }, { field: 'q1', header: h('Q1', '1분기'), type: 'number', format: '#,##0', width: 120 }],
    data: makeRows(500), locale: ctx.lang,
    stateKey: 'docs-saved-layout',
  });
  for (const ev of ['columnResize', 'columnMove', 'columnVisible', 'sortChange'] as const) grid.on(ev, () => ctx.log(`${ev} → saved`));
  text(ctx, h('Resize, move, hide (drag a header up) or sort, then reload the page: the layout comes back.',
    '컬럼 너비·순서를 바꾸거나 숨기거나(헤더를 위로 끌기) 정렬한 뒤 페이지를 새로고침해 보세요. 그대로 돌아옵니다.'));
  separator(ctx);
  button(ctx, h('Reset columns', '컬럼 초기화'), () => grid.resetColumnState());
  button(ctx, h('Forget the saved layout', '저장된 레이아웃 지우기'), () => { grid.clearSavedState(); ctx.log(h('cleared', '지웠습니다')); });
  return grid;
}

사용자는 컬럼을 넓히고 옮기고 숨기고 고정하며 행을 정렬합니다. stateKey를 주면 그리드가 이를 브라우저에 보관했다가 그리드를 다시 만들 때(새로고침, 새 탭, 다음 날) 되살립니다.

createGrid(el, {
  columns,
  data,
  stateKey: 'orders-grid',          // one key per grid (and per page that shows it)
});

옵션과 메서드

이름타입설명
stateKeystring저장 이름('freegrid:state:<key>'로 저장). 그리드마다 따로 주세요.
statePartsSavedStatePart[]저장할 것. 기본 ['calculatedColumns', 'columns', 'columnGroups', 'sort'].
stateStorage'local' | 'session'localStorage(기본, 방문이 바뀌어도 유지) 또는 sessionStorage(이 탭에서만).
resetColumnState()void컬럼 정의대로(너비·순서·숨김·고정) 되돌리고 그것도 저장합니다. 컬럼 메뉴의 컬럼 초기화와 같습니다.
clearSavedState()void저장한 것을 지웁니다(그리드는 다시 만들 때까지 그대로).

저장할 수 있는 것

항목내용
'columns'컬럼마다 너비·순서·숨김·고정
'columnGroups'열리고 닫힌 컬럼 그룹
'sort'정렬
'calculatedColumns'사용자가 추가한 계산 컬럼
'filters' · 'quickFilter' · 'advancedFilter'필터(행이 걸러져 있는 것을 모를 수 있으니 주의)
'groupBy' · 'expanded' · 'pivot'그룹핑, 펼친 그룹, 피벗
'page' · 'pageSize'페이지
'notes' · 'selected' · 'conditionalFormats'셀 메모, 체크한 행(getRowId 필요), 조건부 서식

저장·복원 시점

  • 변경(너비, 이동, 숨김, 고정, 정렬, 필터 …) 뒤 0.25초 후에 저장하고, 페이지를 떠나거나 그리드를 없앨 때는 바로 저장합니다.
  • 그리드를 만들 때 한 번 되살립니다. 정의에서 사라진 컬럼은 건너뛰고, 새 컬럼은 정의의 위치에 나옵니다.
  • 읽을 수 없는 저장값(직접 고친 경우)은 경고와 함께 무시하고 정의대로 시작합니다.
  • 저장소가 막혀 있으면(사생활 모드, 용량 부족) 저장만 안 되고 그리드는 평소대로 동작합니다.

사람마다 서버에 저장

stateKey는 한 브라우저에만 보관합니다. 다른 컴퓨터에서도 따라가게 하려면 getState()를 서버에 저장하고 setState()로 되돌리세요.

const grid = createGrid(el, { columns, data });
grid.setState(await fetch('/api/me/grid-state').then(r => r.json()), { parts: ['columns', 'sort'] });
let timer;
const save = () => {
  clearTimeout(timer);
  timer = setTimeout(() => fetch('/api/me/grid-state', { method: 'PUT', body: JSON.stringify(grid.getState()) }), 500);
};
['columnResize', 'columnMove', 'columnVisible', 'sortChange'].forEach(ev => grid.on(ev, save));

이 페이지에 대한 질문

페이지를 새로고침해도 컬럼 너비와 순서를 유지하려면?

그리드에 'orders-grid' 같은 stateKey를 주세요. 너비·순서·숨김·고정 컬럼과 정렬이 바뀔 때마다 localStorage에 저장되고, 다음에 그리드를 만들 때 되살아납니다.

저장된 컬럼 레이아웃을 초기화하려면?

컬럼 메뉴의 컬럼 초기화(또는 resetColumnState())는 컬럼 정의대로 되돌리고 그 상태를 저장합니다. clearSavedState()는 저장한 것을 지워 다음 방문 때 정의대로 시작합니다.