개발 가이드

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 = {
  tables: {
    title: '매출 분석',
    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로 모듈을 등록한다. 탐색기 안에서는 RealPivot2 라이선스로 동작한다. 제품 단독 사용은 설치를 참고한다.

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는 런타임에 자료형 검사를 강제하지 않는다. 위 사항을 지키지 않으면 에러가 나거나 의도하지 않은 동작이 생길 수 있으니 반드시 준수해야 한다.