Gravity UI ChartKit ·

플러그인 기반 React 컴포넌트로, 여러 차트 라이브러리에 대한 통합 렌더링 인터페이스를 제공합니다. 하나 이상의 플러그인을 등록하고 <ChartKit type="..." data={...} />를 통해 차트를 렌더링하면, ChartKit이 자동으로 올바른 렌더러로 디스패치합니다.

각 플러그인 렌더러는 지연 로딩(lazy-loaded)되므로, 해당 라이브러리 코드는 ChartKit이 UI에 실제로 렌더링될 때만 다운로드됩니다. ChartKit은 또한 모바일 친화적인 툴팁 표시를 기본적으로 지원합니다. 내장된 플러그인을 사용하거나 자신만의 플러그인을 구현할 수 있습니다.

언제 사용해야 할까요?

최신 선언형 차트(gravity-charts) 또는 시계열/모니터링 차트(yagr)가 필요할 때
단일하고 일관된 API 아래에서 여러 차트 유형을 사용해야 할 때
Gravity UI 생태계 내에서 개발하고 있을 때

언제 사용하지 않아야 할까요?

특정 차트 라이브러리 하나만 필요한 경우 — 이때는 @gravity-ui/charts를 직접 사용하는 것이 좋습니다.

시작하기

요구 사항

React 16, 17, 또는 18
[@gravity-ui/uikit](https://github.com/gravity-ui/uikit) — 필수 peer dependency (테마 및 UI 기본 요소를 제공합니다)

설치

npm install @gravity-ui/chartkit @gravity-ui/uikit

스타일

진입점에서 @gravity-ui/uikit의 스타일을 가져옵니다:

import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

전체 설정 세부 정보는 uikit 스타일 가이드를 참조하세요.

기본 사용법

ChartKit은 전역 플러그인 레지스트리를 사용합니다. 앱 진입점에서 settings.set을 한 번 호출하여 필요한 플러그인을 등록하세요. <ChartKit type="..." />가 렌더링될 때, 일치하는 플러그인을 찾습니다. 만약 찾지 못하면 오류가 발생합니다. 각 플러그인의 렌더러는 React.lazy 컴포넌트이므로, 해당 코드의 가져오기는 ChartKit이 UI에 처음 나타날 때만 수행됩니다.

여러 플러그인을 한 번에 등록할 수 있습니다:

settings.set({plugins: [GravityChartsPlugin, YagrPlugin]});

또는 settings.set을 여러 번 호출해도 됩니다. 이때 플러그인 목록이 대체되는 것이 아니라 병합됩니다.

기본 예제:

import {ThemeProvider} from '@gravity-ui/uikit';
import ChartKit, {settings} from '@gravity-ui/chartkit';
import {GravityChartsPlugin} from '@gravity-ui/chartkit/gravity-charts';

import '@gravity-ui/uikit/styles/fonts.css';
import '@gravity-ui/uikit/styles/styles.css';

settings.set({plugins: [GravityChartsPlugin]});

const data = {
  series: {
    data: [
      {
        type: 'line',
        name: 'Series',
        data: [
          {x: 0, y: 10},
          {x: 1, y: 25},
          {x: 2, y: 18},
          {x: 3, y: 30},
        ],
      },
    ],
  },
};

export default function App() {
  return (
    <ThemeProvider theme="light">
      <div style={{height: 300}}>
        <ChartKit type="gravity-charts" data={data} />
      </div>
    </ThemeProvider>
  );
}

ChartKit은 부모 요소의 크기에 맞춰 조정됩니다. 컨테이너에 명시적인 높이를 지정해야 합니다.

차트 패키지 업데이트

ChartKit은 두 개의 Gravity UI 차트 라이브러리를 종속성으로 번들링합니다:

@gravity-ui/charts — gravity-charts 플러그인을 구동합니다.
@gravity-ui/yagr — yagr 플러그인을 구동합니다.

이러한 패키지의 최신 버전을 사용해야 하는 경우, Package update request 이슈를 열고 필요한 패키지를 선택하세요. 유지보수자가 선택한 패키지의 버전을 올리고 업데이트를 릴리스할 것입니다.

개발

사전 요구 사항

Node.js 22 (참조: .nvmrc)
npm 10 이상

설정

저장소를 클론하고 종속성을 설치합니다:

git clone https://github.com/gravity-ui/ChartKit.git
cd ChartKit
npm ci

Storybook 실행

npm run start

Storybook은 http://localhost:7007에서 사용할 수 있습니다.

로컬 종속성으로 개발하기

종속성(예: @gravity-ui/charts)을 수정하고 npm에 게시하지 않고 Storybook에서 변경 사항을 실시간으로 확인하려면 다음 단계를 따르세요:

1. 로컬 패키지 링크

# 로컬 @gravity-ui/charts 복제본에서:
git clone https://github.com/gravity-ui/charts.git
cd charts
npm ci
# 변경 사항 적용
npm run build
npm link

# ChartKit에서:
npm link @gravity-ui/charts

2. 로컬 패키지 감시 설정

ChartKit 루트에 .env.local 파일을 생성합니다 (이 파일은 gitignore됩니다):

LOCAL_PKG=@gravity-ui/charts

이렇게 하면 Vite가 node_modules에서 해당 패키지를 감시하고 사전 번들링을 건너뛰도록 지시합니다. @gravity-ui/charts를 다시 빌드하면 Storybook이 자동으로 핫 리로드됩니다.

여러 패키지의 경우 쉼표로 구분된 목록을 사용합니다:

LOCAL_PKG=@gravity-ui/charts,@gravity-ui/uikit

3. Storybook 실행

npm run start

4. 원래 패키지로 복원

완료 후:

.env.local 파일에서 LOCAL_PKG 줄을 주석 처리합니다.
ChartKit에서 npm install을 실행합니다. 이렇게 하면 심볼릭 링크가 레지스트리 버전으로 대체됩니다.

# ChartKit에서:
npm ci

테스트 실행

npm test

시각적 회귀 테스트는 Docker에서 실행되어 환경 간 일관된 스크린샷을 보장합니다:

npm run test:docker

의도적인 UI 변경 후 참조 스크린샷을 업데이트하려면 다음을 실행합니다:

npm run test:docker:update

기여

풀 리퀘스트를 제출하기 전에 기여 가이드를 참조하세요.

라이선스

MIT 라이선스에 따라 배포됩니다. 자세한 내용은 LICENSE를 참조하세요.

AI 에이전트용

하나의 <ChartKit type="..." data={...} /> API를 통해 여러 Gravity UI 차트 라이브러리에서 차트를 렌더링하는 플러그인 디스패치 React 컴포넌트입니다. 각 차트 라이브러리를 직접 가져오는 대신, 혼합 차트 유형에 대한 단일 지연 로딩 진입점이 필요할 때 사용하세요.

언제 사용해야 할까요?

여러 차트 엔진(gravity-charts + yagr 등)을 하나의 일관된 컴포넌트 뒤에서 렌더링할 때
차트 번들을 지연 로딩할 때 — 각 플러그인의 렌더러는 React.lazy이므로, 해당 차트 유형이 실제로 표시될 때만 라이브러리 코드가 가져와집니다.
차트를 Gravity UI 앱에 번들링하여 모바일 친화적인 툴팁과 통합된 테마를 즉시 사용할 때

언제 사용하지 않아야 할까요?

단일 차트 유형만 사용하는 경우, @gravity-ui/charts (일반) 또는 @gravity-ui/yagr (고성능 시계열)를 직접 가져오세요 — 플러그인 레지스트리는 단일 엔진에 대한 오버헤드입니다.
위젯 대시보드 그리드를 구성하려면 @gravity-ui/dashkit을 사용하세요 — ChartKit은 차트를 렌더링하고, DashKit은 여러 위젯을 배열합니다.

일반적인 함정

settings.set({plugins: [...]}) 전에 <ChartKit> 렌더링 — 전역 플러그인 레지스트리는 앱 진입점에서 채워져야 합니다. 등록되지 않은 type은 렌더링 시 오류를 발생시킵니다.
환각적인 chartType / library prop — 디스패치 prop은 type (예: type="gravity-charts")이며, 데이터는 data입니다.
컨테이너 높이 누락 — ChartKit은 부모 요소를 채웁니다. 래퍼에 명시적인 높이가 없으면 차트가 0으로 축소됩니다.
플러그인이 번들링될 것으로 예상 — 플러그인 렌더러(@gravity-ui/chartkit/gravity-charts, .../yagr)는 지연 로딩됩니다. 유형의 첫 번째 렌더링은 해당 번들을 가져옵니다.
uikit 스타일 가져오기 누락 — 테마는 @gravity-ui/uikit/styles/styles.css에 의존합니다. 이것이 없으면 차트가 스타일 없이 렌더링됩니다.

AI 에이전트용 문서

설치된 버전에 대한 에이전트 읽기 가능 문서는 node_modules/@gravity-ui/chartkit/build/docs/INDEX.md에 있습니다.

ChartKit

§Gravity UI ChartKit ·

§목차

§시작하기

§요구 사항

§설치

§스타일

§기본 사용법

§차트 패키지 업데이트

§개발

§사전 요구 사항

§설정

§Storybook 실행

§로컬 종속성으로 개발하기

§테스트 실행

§기여

§라이선스

§AI 에이전트용

§언제 사용해야 할까요?

§언제 사용하지 않아야 할까요?

§일반적인 함정

§AI 에이전트용 문서