다단 컬럼 헤더 플러그인

다단 컬럼 헤더 · columnGroupsPlugin

일반 컬럼 헤더 위에 상위·하위 그룹 제목을 표시합니다. 데이터 행을 그룹화하는 groupingPlugin과 용도가 다릅니다.

설치 함수: columnGroupsPlugin(config) · 해제 이름: columnGroups

설정 속성 · 기본값

필수값은 해당 입력에서 반드시 제공하는 값입니다. 조건부 필수값은 설명에 적힌 기능을 사용할 때 필요합니다. 표시가 없는 옵션은 생략할 수 있으며 기본값을 사용합니다. 빈 문자열·누락과 0·false를 혼동하지 마세요.

설정 위치와 동작
설정	기본값	설명
`groups` 조건부 필수값	[]	그룹 노드 배열입니다. 노드는 {title,fields} 또는 {title,children}으로 구성합니다. 다단 헤더를 표시하려면 그룹을 지정합니다. []이면 일반 헤더만 표시합니다.
`groups[].title`	사용자 지정	헤더에 표시할 그룹 제목입니다.
`groups[].fields` 조건부 필수값	컬럼 field 배열	그룹에 속한 컬럼 field를 지정합니다. 이동 후 떨어진 범위와 좌우 고정 경계는 별도 제목 구간으로 표시합니다. 데이터 rowKey가 아닙니다. 각 그룹은 fields 또는 children 중 하나로 대상 컬럼을 연결합니다.
`groups[].children` 조건부 필수값	하위 그룹 배열	중첩 노드로 헤더 계층을 만듭니다. 상위 범위는 하위 fields를 모아 계산합니다. 하위 그룹을 사용할 때 필요합니다. 말단 그룹은 fields로 연결합니다.

사용 순서

columns를 먼저 선언하고 그룹별 컬럼을 연속 순서로 배치합니다.
fields로 범위를 지정하거나 children으로 하위 그룹을 만듭니다.
여러 그룹 헤더 행과 마지막 일반 컬럼 헤더의 범위·너비를 확인합니다.

연결 API

플러그인 또는 연결된 Core API
호출	동작
`grid.install(columnGroupsPlugin({groups}))`	컬럼 그룹 구성을 설치합니다. 그룹 설정 전용 변경 API는 없습니다. 필수값 `grid.install` 인수: `plugin (name·install 함수 포함)`
`grid.uninstall("columnGroups")`	설치 전 renderHeader 동작을 복원합니다. 구성을 바꿀 때 해제 후 새 설정으로 다시 설치할 수 있습니다. 필수값 `grid.uninstall` 인수: `name`

설치 · 해제 · Vue 3 수명주기

생성 시 plugins에 등록하거나, 아직 설치하지 않은 인스턴스에서 grid.install을 호출합니다. 같은 name은 중복 설치할 수 없습니다. 설정에 쓰는 데이터·함수는 아래 전체 예제 소스를 참고하세요.

grid.install(columnGroupsPlugin({
      groups: [
        { title: '주문 정보', fields: ['name'] },
        {
          title: '금액 정보',
          children: [{ title: '수량과 단가', fields: ['qty', 'price'] }],
        },
      ],
    }));
grid.uninstall('columnGroups'); // 플러그인 해제
// Vue 3 컴포넌트가 종료될 때
onBeforeUnmount(() => grid.destroy());

renderHeader를 래핑해 그룹 헤더를 그립니다. 해제 시 설치 전 함수를 복원합니다. 행 데이터·변경 목록은 수정하지 않습니다.

실행 예제 · 실제 원본

아래 소스는 examples/features/headers.js와 Vue 원본입니다. 해당 예제 경로를 기준으로 import하며, 행 데이터는 별도 파일을 함께 사용합니다.

JavaScript 예제 실행 ↗ · Vue 3 예제 실행 ↗ · 행 데이터 원본

JavaScript 전체 소스 · headers.js

import { ZixoGrid, columnGroupsPlugin } from '../../src/index.js';
import { rows } from './headers.data.js';

const host = document.querySelector('#grid'),
  report = document.querySelector('#report');

const options = {
  rowKey: 'id',
  height: 360,
  rows: rows,
  columns: [
    { field: 'name', title: '주문', width: 240 },
    { field: 'qty', title: '수량', type: 'number', parse: Number },
    { field: 'price', title: '단가', type: 'number', parse: Number },
  ],
  plugins: [
    columnGroupsPlugin({
      groups: [
        { title: '주문 정보', fields: ['name'] },
        {
          title: '금액 정보',
          children: [{ title: '수량과 단가', fields: ['qty', 'price'] }],
        },
      ],
    }),
  ],
};

const grid = new ZixoGrid(host, options);

window.addEventListener('pagehide', () => grid.destroy(), { once: true });
grid.on(
  'validationerror',
  (detail) => (report.textContent = detail.error.message),
);

report.textContent =
  'fields로 그룹을 지정하고 children으로 하위 그룹을 만듭니다. 짧은 계층은 남은 그룹 행을 병합하며, 숨김·순서 변경·고정 경계에 맞춰 그룹 제목을 나누어 표시합니다. 일반 컬럼 행 높이는 headerHeight, 그룹 행은 단계당 25px입니다.';

Vue 3 전체 소스 · vue-headers.vue

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';
import { ZixoGrid, columnGroupsPlugin } from '../../src/index.js';
import { rows } from './headers.data.js';

// Instance and DOM belong to this component, never to window or a global ID.
const gridHost = ref(null);
const message = ref('');

let grid;
let alive = true;

onMounted(() => {
  const options = {
    rowKey: 'id',
    height: 360,
    rows: rows,
    columns: [
      { field: 'name', title: '주문', width: 240 },
      { field: 'qty', title: '수량', type: 'number', parse: Number },
      { field: 'price', title: '단가', type: 'number', parse: Number },
    ],
    plugins: [
      columnGroupsPlugin({
        groups: [
          { title: '주문 정보', fields: ['name'] },
          {
            title: '금액 정보',
            children: [{ title: '수량과 단가', fields: ['qty', 'price'] }],
          },
        ],
      }),
    ],
  };

  grid = new ZixoGrid(gridHost.value, options);

  grid.on(
    'validationerror',
    (detail) => (message.value = detail.error.message),
  );

  message.value =
    'fields로 그룹을 지정하고 children으로 하위 그룹을 만듭니다. 짧은 계층은 남은 그룹 행을 병합하며, 숨김·순서 변경·고정 경계에 맞춰 그룹 제목을 나누어 표시합니다. 일반 컬럼 행 높이는 headerHeight, 그룹 행은 단계당 25px입니다.';
});
onBeforeUnmount(() => {
  alive = false;
  grid?.destroy(); // Cancels grid requests, removes events and releases plugins.
  grid = undefined;
});
defineExpose({ getGrid: () => grid });
</script>

<template>
  <main>
    <h1>다단 컬럼 그룹</h1>

    <div ref="gridHost" class="vue-grid-host"></div>
    <div class="notes result" aria-live="polite">{{ message }}</div>
  </main>
</template>

제약 사항 · 주의할 동작

그룹 행은 단계당 25px이며 마지막 일반 컬럼 행은 headerHeight를 사용합니다. 짧은 계층은 남은 그룹 행을 병합합니다.
숨긴 컬럼은 그룹 범위에서 제외하며, 보이는 하위 그룹이 없는 단계는 표시하지 않습니다.
그룹을 가로지르는 이동이나 고정 경계에서는 제목이 여러 구간에 반복 표시됩니다. 그룹 전체 이동·그룹 제목 정렬/메뉴는 제공하지 않습니다.

연결 기능 메뉴

다단 컬럼 그룹 · 정렬 · 너비 · 순서 · 높이 · 컬럼 · 행 고정

이 플러그인 상세 페이지 독립 열기 ↗ · 플러그인 설명 전체