§@gravity-ui/date-components ·

§Instalar

npm install react react-dom @gravity-ui/uikit @gravity-ui/date-components @gravity-ui/date-utils

§Uso

import {createRoot} from 'react-dom/client';
import {DatePicker} from '@gravity-ui/date-components';
import {ThemeProvider} from '@gravity-ui/uikit';

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

function App() {
  return (
    <ThemeProvider>
      <h1>DatePicker</h1>
      <form>
        <label htmlFor="date-picker">Data: </label>
        <DatePicker id="date-picker" name="date" />
      </form>
    </ThemeProvider>
  );
}

const root = createRoot(document.getElementById('root'));
root.render(<App />);

§Localização

import {settings} from '@gravity-ui/date-utils';

// Carrega os locais de data que serão usados na aplicação.
await settings.loadLocale('ru');

function App() {
  return (
    // Define o idioma a ser usado com os componentes.
    <ThemeProvider lang="ru">
      <h1>DatePicker</h1>
      <form>
        <label htmlFor="date-picker">Data: </label>
        <DatePicker id="date-picker" name="date" />
      </form>
    </ThemeProvider>
  );
}

Se o aplicativo suportar troca de idioma, pré-carregue todos os locais suportados quando o aplicativo for carregado pela primeira vez, ou carregue os locais antes de trocar o idioma:

// Pré-carrega os locais
await Promise.all([settings.loadLocale('ru'), settings.loadLocale('nl')]);

const root = createRoot(document.getElementById('root'));
root.render(<App />);

// ou carrega os locais sob demanda.

function App() {
  const [lang, setLang] = React.useState('en');

  const handleLangChange = (newLang) => {
    settings.loadLocale(newLang).then(() => {
      setLang(newLang);
    });
  };

  return <ThemeProvider lang={lang}>...</ThemeProvider>;
}

Os componentes possuem traduções para inglês e russo. Para adicionar traduções em outros idiomas, use addLanguageKeysets de @gravity-ui/uikit:

import {addLanguageKeysets} from '@gravity-ui/uikit/i18n';
import type {Keysets, PartialKeysets} from '@gravity-ui/date-components';

// Use o tipo Keyset para especificar traduções para todos os componentes disponíveis
addLanguageKeysets<Keysets>(lang, {...});

// ou use o tipo PartialKeysets para especificar apenas os que você precisa
addLanguageKeysets<PartialKeysets>(lang, {...});

// Para especificar traduções para alguns componentes
addLanguageKeysets<Pick<Keysets, 'g-date-calendar' | 'g-date-date-field' | 'g-date-date-picker'>>(lang, {...});

§Desenvolvimento

Para iniciar o servidor de desenvolvimento com storybook, execute o seguinte:

npm start

§Licença

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

§Para agentes de IA

Controles de data e hora em React para aplicativos Gravity UI — seletores de data/hora, calendários e seletores de intervalo absoluto/relativo construídos sobre @gravity-ui/date-utils.

§Quando usar

• Entrada de data ou data/hora única: DatePicker, DateField.
• Calendários para seleção de mês/dia: Calendar, CalendarView.
• Intervalos de datas: RangeDatePicker, RangeCalendar, RangeDateField.
• Intervalos relativos e mistos absoluto/relativo (por exemplo, "últimos 7 dias"): RelativeDatePicker, RelativeRangeDatePicker, RelativeDateField.

§Quando não usar

• Entradas de texto simples ou numéricas, botões ou outros controles genéricos — use @gravity-ui/uikit.
• Matemática de data de baixo nível, análise, formatação ou manipulação de fuso horário sem interface — use @gravity-ui/date-utils diretamente.

§Armadilhas comuns

• Valores são objetos DateTime, não Date do JS. Os componentes trabalham com dateTime() de @gravity-ui/date-utils; passe e leia DateTime, não Date nativo ou strings ISO.
• Requer configuração do uikit. Renderize dentro de ThemeProvider e importe @gravity-ui/uikit/styles/styles.css; @gravity-ui/uikit e @gravity-ui/date-utils são dependências obrigatórias.
• Local é carregado, não apenas definido. Defina o idioma via ThemeProvider lang, mas carregue os dados de local primeiro com settings.loadLocale('ru') de @gravity-ui/date-utils, ou as datas serão renderizadas no local padrão.
• Traduções específicas de componentes usam addLanguageKeysets. Para idiomas além de en/ru, registre conjuntos de chaves via addLanguageKeysets de @gravity-ui/uikit/i18n usando os tipos Keysets/PartialKeysets exportados aqui.

§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/date-components/dist/docs/INDEX.md.