§Gravity UI ChartKit ·

Componente React baseado em plugins que fornece uma interface unificada de renderização para múltiplas bibliotecas de gráficos. Você registra um ou mais plugins e renderiza gráficos através de <ChartKit type="..." data={...} /> — o ChartKit despacha para o renderizador correto automaticamente.

Cada renderizador de plugin é carregado sob demanda (lazy-loaded), então o código da biblioteca subjacente só é baixado quando o ChartKit é realmente renderizado na UI. O ChartKit também lida com a exibição de tooltips amigáveis para dispositivos móveis nativamente. Você pode usar os plugins embutidos ou implementar os seus próprios.

Quando usar:

• Você precisa de gráficos declarativos modernos (gravity-charts) ou gráficos de séries temporais / monitoramento (yagr)
• Você precisa de múltiplos tipos de gráficos sob uma única API consistente
• Você está desenvolvendo no ecossistema Gravity UI

Quando não usar:

• Você só precisa de uma biblioteca de gráficos específica — prefira usar @gravity-ui/charts diretamente

§Sumário

• Primeiros passos
• Atualizando pacotes de gráficos
• Desenvolvimento

§Primeiros passos

§Requisitos

• React 16, 17 ou 18
• [@gravity-ui/uikit](https://github.com/gravity-ui/uikit) — dependência peer obrigatória (fornece temas e primitivas de UI)

§Instalação

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

§Estilos

Importe os estilos de @gravity-ui/uikit no seu ponto de entrada:

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

Para detalhes completos de configuração, consulte o guia de estilos do uikit.

§Uso básico

O ChartKit usa um registro global de plugins. Chame settings.set uma vez no ponto de entrada do seu aplicativo para registrar os plugins que você precisa. Quando <ChartKit type="..." /> renderiza, ele procura o plugin correspondente — se nenhum for encontrado, um erro é lançado. O renderizador de cada plugin é um componente React.lazy, então seu código é buscado apenas quando o ChartKit aparece pela primeira vez na UI.

Você pode registrar múltiplos plugins de uma vez:

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

Ou chame settings.set múltiplas vezes — ele mescla a lista de plugins em vez de substituí-la.

Exemplo básico:

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>
  );
}

O ChartKit se adapta ao tamanho do seu elemento pai — certifique-se de que o contêiner tenha uma altura explícita.

§Atualizando pacotes de gráficos

O ChartKit agrupa duas bibliotecas de gráficos do Gravity UI como dependências:

• @gravity-ui/charts — alimenta o plugin gravity-charts
• @gravity-ui/yagr — alimenta o plugin yagr

Se você precisar de uma versão mais recente de um desses pacotes, abra uma solicitação de atualização de pacote Package update request e selecione o(s) pacote(s) que você precisa. Os mantenedores atualizarão os pacotes selecionados e lançarão a atualização.

§Desenvolvimento

§Pré-requisitos

• Node.js 22 (veja .nvmrc)
• npm 10 ou superior

§Configuração

Clone o repositório e instale as dependências:

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

§Executando o Storybook

npm run start

O Storybook estará disponível em http://localhost:7007.

§Desenvolvendo com uma dependência local

Para trabalhar em uma dependência (por exemplo, @gravity-ui/charts) e ver suas alterações ao vivo no Storybook sem publicar no npm:

1. Vincule o pacote local

# No seu clone local de @gravity-ui/charts:
git clone https://github.com/gravity-ui/charts.git
cd charts
npm ci
# faça suas alterações
npm run build
npm link

# No ChartKit:
npm link @gravity-ui/charts

2. Configure o watch para o pacote local

Crie um arquivo .env.local na raiz do ChartKit (ele é ignorado pelo git):

LOCAL_PKG=@gravity-ui/charts

Isso instrui o Vite a monitorar esse pacote em node_modules e pular a pré-compilação dele. Após reconstruir @gravity-ui/charts, o Storybook recarregará automaticamente.

Para múltiplos pacotes, use uma lista separada por vírgulas:

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

3. Inicie o Storybook

npm run start

4. Restaure o pacote original

Quando terminar:

1. Comente LOCAL_PKG em .env.local
2. Execute npm install no ChartKit — isso substitui o link simbólico pela versão do registro

# No ChartKit:
npm ci

§Executando testes

npm test

Testes de regressão visual são executados no Docker para garantir capturas de tela consistentes entre ambientes:

npm run test:docker

Para atualizar as capturas de tela de referência após alterações intencionais na UI:

npm run test:docker:update

§Contribuição

Por favor, consulte o guia de contribuição antes de enviar um pull request.

§Licença

Distribuído sob a Licença MIT. Veja LICENSE para detalhes.

§Para agentes de IA

Um componente React que despacha plugins e renderiza gráficos de múltiplas bibliotecas de gráficos do Gravity UI através de uma única API <ChartKit type="..." data={...} /> — utilize-o quando precisar de um ponto de entrada único para carregamento preguiçoso (lazy-loading) de tipos de gráficos mistos, em vez de importar cada biblioteca de gráficos diretamente.

§Quando usar

• Renderizar mais de um motor de gráficos (por exemplo, gravity-charts + yagr) sob um componente consistente.
• Carregamento preguiçoso de pacotes de gráficos — o renderizador de cada plugin é React.lazy, então o código de uma biblioteca só é buscado quando seu tipo de gráfico é realmente exibido.
• Agrupar gráficos em um aplicativo Gravity UI que deseja tooltips amigáveis para dispositivos móveis e temas unificados prontos para uso.

§Quando não usar

• Para apenas um tipo de gráfico, importe @gravity-ui/charts (geral) ou @gravity-ui/yagr (séries temporais de alta performance) diretamente — o registro de plugins é um overhead para um único motor.
• Para compor uma grade de dashboard com widgets, use @gravity-ui/dashkit — ChartKit renderiza um gráfico; DashKit organiza múltiplos widgets.

§Armadilhas comuns

• Renderizar <ChartKit> antes de settings.set({plugins: [...]}) — o registro global de plugins deve ser populado na entrada do aplicativo; um type não registrado lançará um erro no momento da renderização.
• Prop chartType / library alucinada — a prop de despacho é type (por exemplo, type="gravity-charts"), e os dados são data.
• Esquecer a altura do contêiner — ChartKit preenche seu pai; sem uma altura explícita no wrapper, o gráfico colapsa para zero.
• Esperar que os plugins sejam empacotados — os renderizadores de plugins (@gravity-ui/chartkit/gravity-charts, .../yagr) são preguiçosos; a primeira renderização de um tipo busca seu pacote.
• Faltando a importação dos estilos do uikit — o tema depende de @gravity-ui/uikit/styles/styles.css; sem ele, os gráficos são renderizados sem estilo.

§Documentação para agentes de IA

A documentação legível por agente para a versão instalada está localizada em node_modules/@gravity-ui/chartkit/build/docs/INDEX.md.