# @gravity-ui/date-components 中文文档

规范地址：https://npmcn.com/package/%40gravity-ui/date-components/

版本：5\.0\.0
npm 元数据更新时间：2026-11-02T09:33:46.731Z
中文译文更新时间：2026-11-16T23:42:06.015Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gravity-ui/date-components
原文对照：https://npmcn.com/package/%40gravity-ui/date-components/?lang=original
项目主页：https://github.com/gravity-ui/date-components#readme
源码仓库：https://github.com/gravity-ui/date-components

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.2 MB，791 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0，@types/react ^18\.0\.0 \|\| ^19\.0\.0，@gravity-ui/uikit ^8\.0\.0，@gravity-ui/date-utils ^2\.6\.0
- 首次发布：2023-08-06T21:34:37.506Z
- 最新版本发布：2026-11-02T09:33:46.412Z
- 近 30 天下载量：68558（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：52（近 12 个月 5 个）

## 中文简介

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

## 安装

```sh
npm install @gravity-ui/date-components
```

也可以使用：`pnpm add @gravity-ui/date-components`、`yarn add @gravity-ui/date-components`、`bun add @gravity-ui/date-components`

## README

# @gravity-ui/date-组件 [![npm package](https://img.shields.io/npm/v/@gravity-ui/date-components)](https://www.npmjs.com/package/@gravity-ui/date-components) [![CI](https://img.shields.io/github/actions/workflow/status/gravity-ui/date-components/.github/workflows/ci.yml?label=CI&logo=github)](https://github.com/gravity-ui/date-components/actions/workflows/ci.yml?query=branch:main) [![storybook](https://img.shields.io/badge/Storybook-deployed-ff4685)](https://preview.gravity-ui.com/date-components/) [![coverage](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fstorage.yandexcloud.net%2Fplaywright-reports%2Fdate-components%2Fpulls%2Fmain%2Fcoverage%2Fcoverage-summary.json&query=%24.total.lines.pct&suffix=%25&label=Coverage)](https://storage.yandexcloud.net/playwright-reports/date-components/pulls/main/coverage/lcov-report/index.html) [![tests-report](https://img.shields.io/badge/Tests-report-ff4685)](https://storage.yandexcloud.net/playwright-reports/date-components/pulls/main/html/index.html)

## 安装

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

## 使用量

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

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

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

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

### 本地化

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

// Load date locales that will be used in an application.
await settings.loadLocale('ru');

function App() {
  return (
    // Set the language to use with components.
    <Provider lang="ru">
      <h1>DatePicker</h1>
      <form>
        <label htmlFor="date-picker">Дата: </label>
        <DatePicker id="date-picker" name="date" />
      </form>
    </Provider>
  );
}
```

如果应用程序支持语言切换,则在应用程序首次加载时预加载所有支持的地块,或在切换语言前加载地块:

```jsx
// Preload locales
await Promise.all([settings.loadLocale('ru'), settings.loadLocale('nl')]);

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

// or load locales on demand.

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

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

  return <Provider lang={lang}>...</Provider>;
}
```

这些组成部分有英文和俄文翻译。 增加其他语文的翻译,使用 `addLanguageKeysets` 从 `@gravity-ui/uikit`数字 :

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

// Use the Keyset type to specify translations for all available components
addLanguageKeysets<Keysets>(lang, {...});

// or use the PartialKeysets type to specify only the ones you need
addLanguageKeysets<PartialKeysets>(lang, {...});

// To specify translations for some components
addLanguageKeysets<Pick<Keysets, 'g-date-calendar' | 'g-date-date-field' | 'g-date-date-picker'>>(lang, {...});
```

## 移徙

-   从 4.x 到 5.x (`@gravity-ui/uikit` v8) 时间轴: [文件/移民4至5.md](https://npmcn.com/package/%40gravity-ui/date-components/docs/migration-4-to-5.md)

## 发展

要启动开发服务器, 故事本运行如下 :

```shell
npm start
```

## 许可证

根据麻省理工学院的许可证分发。 见 [自由主义](https://npmcn.com/package/%40gravity-ui/date-components/LICENSE) 详细情况.

## 对于人工智能特工

对Gravity UI 应用软件的反应日期和时间控制——基于日期/时间取取器、日历和绝对/相对范围选择器 `@gravity-ui/date-utils`。 。 。 .

### 何时使用

-   单个日期或日期时间输入 : `DatePicker`, (中文(简体) ), `DateField`。 。 。 .
-   选定月/日的日历: `Calendar`, (中文(简体) ), `CalendarView`。 。 。 .
-   日期范围 : `RangeDatePicker`, (中文(简体) ), `RangeCalendar`, (中文(简体) ), `RangeDateField`。 。 。 .
-   相对和混合的绝对/相对范围(例如“最后7天”): `RelativeDatePicker`, (中文(简体) ), `RelativeRangeDatePicker`, (中文(简体) ), `RelativeDateField`。 。 。 .

### 不使用时

-   纯文本或数字输入、按钮或其他通用控件——使用 [`@gravity-ui/uikit`](https://github.com/gravity-ui/uikit)。 。 。 .
-   低等日期数学,解析,格式化,或没有UI的时区处理——使用 [`@gravity-ui/date-utils`](https://github.com/gravity-ui/date-utils) 直接说.

### 常见陷阱

-   **值为 `DateTime` 对象,而不是联署材料 `Date`。 。 。 .** 部门与 `dateTime()` 从 [`@gravity-ui/date-utils`](https://github.com/gravity-ui/date-utils); 通过并读取 `DateTime`,非本地语言 `Date` 或 ISO 字符串.
-   **需要uikit设置.** 内部渲染 `Provider` 从 `@gravity-ui/uikit` 导入 `@gravity-ui/uikit/styles/styles.css`· ; `@gravity-ui/uikit` 页:1 `@gravity-ui/date-utils` 需要同伴依赖关系.
-   **地产已经装入了, 不只是设定.** 通过 `Provider` `lang`,但首先加载语言数据 `settings.loadLocale('ru')` 从 `@gravity-ui/date-utils`,或者在默认的地块中提供日期.
-   **具体组成部分的翻译使用 `addLanguageKeysets`。 。 。 .** 外语 `en`编号 :`ru`,通过 `addLanguageKeysets` 从 `@gravity-ui/uikit/i18n` 使用 `Keysets`编号 :`PartialKeysets` 类型导出在此 .

## AI代理的文件

安装版本的可代理读取文档位于 `node_modules/@gravity-ui/date-components/dist/docs/INDEX.md`。 。 。 .

## 常见问题

### @gravity-ui/date-components 是什么？

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

### 如何安装 @gravity-ui/date-components？

在项目目录运行 npm install @gravity-ui/date-components，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）、@gravity-ui/uikit（^8\.0\.0）、@gravity-ui/date-utils（^2\.6\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gravity-ui/date-components 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gravity-ui/date-components 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gravity-ui/date-components 可以商用吗？

@gravity-ui/date-components 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gravity-ui/date-components 的下载量有多少？

根据 npm 官方下载统计，@gravity-ui/date-components 在 2026/10/17 – 2026/11/15 这 30 天内被下载 68,558 次，日均约 2,285 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gravity-ui/date-components 还在维护吗？

最新版本 5\.0\.0 发布于 2026/11/02（14 天前）；至今共发布 52 个版本，其中过去 12 个月发布了 5 个；首次发布于 2023/08/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

