개발 가이드

RealPivot2 라이브러리 사용 개요와 주의 사항을 안내합니다.

JavaScript로 작성된 예제 코드를 제외하고, API 문서는 정확한 자료형이 표시되는 TypeScript 스타일로 설명되어 있습니다. 업무용 앱의 신뢰성을 위해 가능한 한 자료형에 맞게 API를 사용해야 합니다.

기본적으로 OOP(객체지향 프로그래밍) 기반으로 설계·구현되었습니다. API 문서에는 기반(부모) 클래스, 상속받은 메서드·속성 등이 명시되어 있습니다. 구성 요소 모델은 PivotItem을 직간접적으로 계승합니다.

Namespace

RealPivot2 라이브러리의 전역 네임스페이스는 RealPivot2입니다. npm 패키지에서는 named export로 동일 API를 가져옵니다.

import {
  createDataSet,
  createCubeManager,
  createControl,
  setLicenseKey,
} from 'realpivot2';
 
// 또는 HTML에 스크립트를 포함(불러온) 후
// const control = RealPivot2.createControl(document, 'container', cm, config);

생성 흐름

RealPivot2는 보통 DataSet → CubeManager → Control 순으로 준비합니다.

함수	역할
`createDataSet`	테이블·스타 스키마 옵션으로 데이터를 로드합니다. 비동기입니다.
`createCubeManager`	DataSet을 기반으로 Cube 스키마를 생성(적용)합니다.
`createControl`	컨테이너에 피벗 컨트롤을 만들고 Book 설정을 로드합니다.

createDataSet

createDataSet은 비동기 함수입니다. 반환값이 항상 Promise이므로 DataSet 객체에 접근하려면 await 키워드를 사용해야 합니다. await 없이 호출하면 Promise 객체가 그대로 반환됩니다.

데이터는 테이블 옵션의 source 또는 sourceUrl 속성으로 전달합니다.

속성	설명
`source`	메모리의 데이터. 객체 배열(`any[]`) 또는 JSON 문자열(`string`)
`sourceUrl`	JSON/CSV를 fetch로 가져올 URL. `sourceType: 'csv'`면 CSV로 파싱
`table.fields`	컬럼 스키마

source에 JSON 배열 넘기기

이미 메모리에 있는 행 배열은 source에 그대로 전달하면 됩니다. JSON.parse 없이 setRowsAsync로 들어갑니다.

const rows = [
  { 국가: '한국', 판매수량: 10 },
  { 국가: '미국', 판매수량: 20 },
];
 
const ds = await createDataSet([
  {
    name: 'sales',
    source: rows,
    table: {
      fields: [
        { name: '국가', type: 'text' },
        { name: '판매수량', type: 'number' },
      ],
    },
  },
]);

JSON 문자열도 source에 넣을 수 있습니다.

source: '[{"국가":"한국","판매수량":10}]'

sourceUrl로 파일·원격 데이터 로드

const ds = await createDataSet([
  {
    name: 'sales',
    sourceUrl: '/data/sales.json',
    table: {
      fields: [
        { name: '국가', type: 'text' },
        { name: '판매수량', type: 'number' },
      ],
    },
  },
]);

로딩 인디케이터를 사용하려면 control 및 indicator 옵션을 함께 전달하면 됩니다.

const ds = await createDataSet(tableOptions, {
  control,
  indicator: 'progress',
});

createCubeManager

const cm = createCubeManager(ds, [
  {
    name: 'sales',
    table: 'sales',
    schema: {
      dimensions: [{ name: '국가', type: 'str' }],
      measures: [{ name: '판매수량', type: 'f64', aggregate: 'sum' }],
    },
  },
]);

createDataSet이 끝난 뒤 호출합니다.

createControl

const config = {
  general: { title: '매출 분석' },
  tables: {
    name: 'sales',
    cube: 'sales',
    fields: {
      rows: ['국가'],
      values: ['판매수량'],
    },
  },
};
 
const control = createControl(document, 'container', cm, config);

CubeManager와 PivotBookConfiguration을 넘기면 Book을 바로 로드합니다. 로드 완료 후 콜백이 필요하면 다섯 번째 인자로 전달합니다.

const control = createControl(document, 'container', cm, config, (book) => {
  // book 로드 완료
});

예제는 시작하기를 참고하세요.

외부 모듈 등록

탐색기에서 RealChart·RealMap을 쓰려면 use / useAll로 모듈을 등록합니다.

import * as RealChart from 'realchart';
import * as RealMap from 'realmap';
import { useAll } from 'realpivot2';
 
useAll({ RealChart, RealMap });

주의 사항

API 문서에 공개되지 않은 숨겨진 클래스·함수·속성을 사용해서는 안 됩니다. 특히 $나 _로 시작하는 함수·속성·객체는 내부 구현에 따라 언제든 바뀔 수 있으므로 절대 접근(호출·수정)해서는 안 됩니다.
API에 명시된 자료형대로 매개변수나 속성 값을 지정해야 합니다.
API에 명시된 enum 타입이나 string literal union에 없는 값을 사용해서는 안 됩니다.
옵션 값을 조회할 때는 options에 직접 접근하지 않고 prop()을 사용하며, 변경할 때는 updateOption / updateOptions(또는 Undo가 필요하면 Book의 updateItem / updateProp)를 사용하세요.

주의 — JavaScript는 런타임에 자료형 검사를 강제하지 않습니다. 위 사항을 지키지 않으면 에러가 나거나 의도하지 않은 동작이 생길 수 있으니 반드시 준수해야 합니다.