# @cdx-ui/formatters 中文文档

规范地址：https://npmcn.com/package/%40cdx-ui/formatters/

版本：0\.3\.12
npm 元数据更新时间：2026-11-04T15:26:22.128Z
中文译文更新时间：2026-11-09T08:59:51.259Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40cdx-ui/formatters
原文对照：https://npmcn.com/package/%40cdx-ui/formatters/?lang=original
项目主页：https://github.com/dfh-candescent/forge-design-system#readme
源码仓库：https://github.com/dfh-candescent/forge-design-system

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

- 包体积（解压后）：429 kB，474 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-08-11T17:51:56.515Z
- 最新版本发布：2026-11-04T15:26:21.898Z
- 近 30 天下载量：3187（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：75（近 12 个月 75 个）

## 中文简介

![coverage](https://unpkg.com/@cdx-ui/formatters/coverage.svg)

## 安装

```sh
npm install @cdx-ui/formatters
```

也可以使用：`pnpm add @cdx-ui/formatters`、`yarn add @cdx-ui/formatters`、`bun add @cdx-ui/formatters`

## README

# @cdx-ui/格式化器

![coverage](https://unpkg.com/@cdx-ui/formatters/coverage.svg)

Forge UI 和 FI 应用程序的纯格式化器——将线条值转换为人可读的 UI 字符串 (和日期线标识的倒置). 无反应依赖.

样式与 `@candescent/ui-formatters` (在软件包根上显示帮助者;在下面显示日期帮助者) `dates/`) (中文(简体) ). 优先进口 `@cdx-ui/formatters` 仅 - 不导入 `date-fns` 或者说 `Intl` 包件的内部包装.

## 电线对显示( 日期)

| 代表权 | 示例 | 用于 |
| --- | --- | --- |
| **线** `DateId` 编号 : `MonthId` 编号 : `DateTimeId` | `'2026-07-28'` | 表格状态、 API 、 拾取器 |
| **显示** 字符串 | `'7/28/26'` 编号 : `'28/07/2026'` | 标签、信头——永远不存储 |

## 出口

> 下表是有代表性的进口指南,并非详尽无遗的清单 `src/index.ts` (再出口) `dates/index.ts`)是权威导出表面.

### 显示( 与银行用户界面格式化器共享)

| 导入 | 目的 |
| --- | --- |
| `formatNumber` | 地方小数格式化(已刻出) `Intl.NumberFormat`(中文(简体) ) |

### 日期线

| 导入 | 目的 |
| --- | --- |
| `parseDateId` 编号 : `formatDateId` 编号 : `isValidDateId` | `YYYY-MM-DD` 往返 |
| `parseMonthId` 编号 : `formatMonthId` 编号 : `isValidMonthId` | `YYYY-MM-01` 月编号 |
| `parseDateTimeId` 编号 : `formatDateTimeId` 编号 : `isValidDateTimeId` | 当地 `YYYY-MM-DDTHH:mm` |
| `todayDateId` 编号 : `todayMonthId` 编号 : `nowDateTimeId` | 设备本地“ 现在” |
| `toMonthId` 编号 : `clampDateParts` 编号 : `clampMonthParts` | 转换/夹住 |

### 显示日期

| 导入 | 目的 |
| --- | --- |
| `formatDateForDisplay` | 语言 `dateStyle` 短/中/长 |
| `formatMonthForDisplay` | 月加年标签 |
| `formatDateTimeForDisplay` | 日期+时间标签 |
| `formatDateRangeForDisplay` | 包含范围标签 |

### 区域( C)

| 导入 | 目的 |
| --- | --- |
| `normalizeDateRange` 编号 : `compareDateIds` 编号 : `eachDateIdInRange` | 范围数学 |
| `dateRangeFromLastNDays` 编号 : `dateRangeAroundDay` | 预设 |
| `getDateFieldSegments` 编号 : `getDateTimeFieldSegments` | 分块字段元数据 |
| `parseDateSegment` 编号 : `formatDateSegment` 编号 : `applyDateSegmentChange` | 片段编辑 |

### 日历/ 列表副本

| 导入 | 目的 |
| --- | --- |
| `formatCalendarMonthYear` 编号 : `getCalendarWeekdayLabels` | 日历铬 |
| `formatMonthCalendarMonth` 编号 : `formatMonthCalendarYear` | 月网格 |
| `formatDateTimeListDateRow` 编号 : `formatDateTimeListHour` /... (中文(简体) ) | 日期时间列表列 |

## 使用量

```ts
import {
  formatDateId,
  formatDateForDisplay,
  formatNumber,
  normalizeDateRange,
  type DateId,
} from '@cdx-ui/formatters';

formatNumber(3247.19); // '3,247.19'

const id: DateId = formatDateId({ year: 2026, month: 7, day: 28 }); // '2026-07-28'
formatDateForDisplay(id, { locale: 'en-US' }); // e.g. '7/28/26'

normalizeDateRange({ startId: '2026-07-28', endId: '2026-07-01' });
// → { startId: '2026-07-01', endId: '2026-07-28' }
```

```bash
pnpm --filter @cdx-ui/formatters test
```

## 文件布局

```
src/
  formatNumber.ts          # shared display helper (merge target with ui-formatters)
  types.ts / utils.ts      # package-private (not barrel-exported)
  __tests__/               # one test file per public helper
  dates/
    types.ts
    index.ts               # date barrel (re-exported from package root)
    wire/                  # DateId / MonthId parse, format, validate, today
    display/               # locale-aware format*ForDisplay
    ranges/                # compare, normalize, presets
    segments/              # segmented field helpers
    calendar/              # calendar + list row copy
    datetime/              # DateTimeId + list hour/minute/period
    labels/                # date-component accessibility label helpers
    internal/              # private adapters (not public API)
```

## 设计说明

-   **日期 - fns** a. 用于内部的线剖面; **输入** 用于显示和日历标签.
-   无效/ 无效输入返回 `''` 或者说 `null` 如每个帮助者所记录的 —— 绝不因显示输入不当而丢出.
-   软件包内部 `dates/internal/` 不属于公共API.

## 许可证

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

麻省理工学院 2026 Digital First Holdings LLC. 包装的许可证全文 `LICENSE`。 。 。 .

## 常见问题

### 如何安装 @cdx-ui/formatters？

在项目目录运行 npm install @cdx-ui/formatters，或使用 pnpm add / yarn add / bun add。

### @cdx-ui/formatters 支持 TypeScript 吗？

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

### @cdx-ui/formatters 支持 ESM 还是 CommonJS？

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

### @cdx-ui/formatters 可以商用吗？

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

### @cdx-ui/formatters 的下载量有多少？

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

### @cdx-ui/formatters 还在维护吗？

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