# @eternl/formats 中文文档

规范地址：https://npmcn.com/package/%40eternl/formats/

版本：0\.55\.0
npm 元数据更新时间：2026-11-10T15:48:06.151Z
中文译文更新时间：2026-11-14T03:11:34.161Z
软件包许可：BUSL-1\.1

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

原始 npm 页面：https://www.npmjs.com/package/%40eternl/formats
原文对照：https://npmcn.com/package/%40eternl/formats/?lang=original

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

- 包体积（解压后）：256 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2025-10-06T18:45:33.278Z
- 最新版本发布：2026-11-10T15:48:05.821Z
- 近 30 天下载量：2428（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：129（近 12 个月 107 个）

## 中文简介

Locale-aware 显示和 CSV 格式化的帮助器用于数字数据.

## 安装

```sh
npm install @eternl/formats
```

也可以使用：`pnpm add @eternl/formats`、`yarn add @eternl/formats`、`bun add @eternl/formats`

## README

# @eternl/格式

Locale-aware显示格式化和CSV-安全数字帮助器,用于基于浏览器的仪表板和导出.

## 安装

```bash
npm install @eternl/formats
```

## 快速启动

```ts
import Big from 'big.js'
import {
  buildCsv,
  csvCurrencyCode,
  formatCsvDate,
  formatCsvNumber,
  formatCsvPercent,
  formatDisplayCurrency,
  formatDisplayPercent,
  formatDisplayCompact
}                             from '@eternl/formats'

const amount = new Big('1234567.890123')

const priceUS = formatDisplayCurrency(amount, {
  locale: 'en-US',
  currencyCode: 'USD',
  minDecimals: 2,
  maxDecimals: 2,
  useSymbol: true
}) // "$1,234,567.89"

const priceDE = formatDisplayCurrency(amount, {
  locale: 'de-DE',
  currencyCode: 'EUR',
  minDecimals: 2,
  maxDecimals: 2,
  useSymbol: true
}) // "1.234.567,89 €"

const adaDisplay = formatDisplayCurrency('123456789.123456', {
  locale: 'en-US',
  currencyCode: 'ADA',
  customSymbols: { ADA: '₳' },
  minDecimals: 2,
  maxDecimals: 6
}) // "₳123,456,789.123456"
const masked = formatDisplayCurrency('1234.5', {
  locale: 'en-US',
  currencyCode: 'USD',
  minDecimals: 2,
  maxDecimals: 2,
  isHidden: true
}) // "$*.**"

const maskedWithDash = formatDisplayCurrency('1234.5', {
  locale: 'en-US',
  currencyCode: 'USD',
  minDecimals: 2,
  maxDecimals: 2,
  isHidden: true,
  hiddenCharacter: '-'
}) // "$-.--"


const pctDisplay = formatDisplayPercent('0.125', {
  locale: 'en-US',
  minDecimals: 1,
  maxDecimals: 2
}) // "12.5%"

const compact = formatDisplayCompact('9876543', {
  locale: 'en-US',
  compact: true,
  maxDecimals: 1
}) // "9.9M"

const csvNumber = formatCsvNumber(amount, { maxDecimals: 6, trimTrailingZeros: true })
const csvPercent = formatCsvPercent('0.125')
const csvCurrency = csvCurrencyCode('ADA', { ADA: '₳' }, false)

const rows = [
  { ts: new Date('2025-10-06T12:00:00Z'), amount, currency: 'ADA', ratio: '0.125' }
]

const csv = buildCsv(rows, [
  { header: 'date', accessor: (row) => row.ts, formatter: (value) => formatCsvDate(value as Date) },
  { header: 'amount', accessor: (row) => row.amount, formatter: (value) => formatCsvNumber(value as Big, { maxDecimals: 6 }) },
  { header: 'currency', accessor: (row) => row.currency, formatter: (value) => csvCurrencyCode(String(value), { ADA: '₳' }, false) },
  { header: 'percent', accessor: (row) => row.ratio, formatter: (value) => formatCsvPercent(value as string, { maxDecimals: 4 }) }
])
```

生成的 CSV 完全为 ASCII (`.` 十进制分隔符,不分组),并清洁地导入到Google Sheets, Koinly,和CoinTracking.

## 显示格式

-   `formatDisplayNumber` 处理带有分组、可选标志显示和四舍五入控件的本地化小数.
-   `formatDisplayCurrency` 组合 `Intl.NumberFormat` 带有可选自定义符号(₳,₿等). 保留了来自主机地块的间距,除非一个自定义符号去掉.
-   `formatDisplayPercent` 在尊重小数和百分比符号的同时, 将显示数字乘以100.
-   `formatDisplayCompact` 应用精确的可配置 K/M/B/T后缀 `big.js` 算术(无科学注释).

共同选项 :

```ts
{
  minDecimals?: number
  maxDecimals?: number
  precision?: number        // significant digits
  roundingMode?: 'roundDown' | 'roundHalfUp' | 'roundHalfEven' | 'roundUp'
  trimTrailingZeros?: boolean (default: false)
  signDisplay?: 'auto' | 'always' | 'exceptZero' | 'never' | 'negative'
  useGrouping?: boolean
  isHidden?: boolean            // mask digits with maskCharacter (default '*')
  hiddenCharacter?: string
}
```

## CSV 格式化

-   `formatCsvNumber` 输出平方 ASCII 位数和一个点小数分隔符, 纪念分数/最大小数, 精确度, 并裁剪 .
-   `formatCsvPercent` 将比值乘以100并发出一个无标记的数字字符串( 无) `%`) (中文(简体) ).
-   `csvCurrencyCode` 将货币符号或代码保存在专栏中,这样数字字段保持干净.

```ts
formatCsvNumber('0.00000001', { maxDecimals: 8 }) // "0.00000001"
formatCsvPercent('0.125', { maxDecimals: 4 })      // "12.5"
csvCurrencyCode('btc', { BTC: '₿' }, true)        // "₿"
```

## CSV 构建器

`buildCsv(rows, columns, delimiter = ',', lineEnding = '\n')` 应用分栏存取器和格式化器,引用字段并加上分栏、引文或新行(RFC 4180)。 数字结果 `formatCsvNumber` 绝不需要引用,所以进口仍然是数字.

## 约会助手

-   `formatDisplayDate(input, locale, options)` 缓存 `Intl.DateTimeFormat` 实例.
-   `formatIsoDate(input, { timeZone })` 发射 `YYYY-MM-DD` 使用请求的时区.
-   `formatIsoDateTime(input, { timeZone })` 以空间分隔符和时区偏移发布 ISO 日期.
-   `formatCsvDate(input)` 发射 ISO-8601 字符串 : `YYYY-MM-DD` 协调世界时午夜,否则 `YYYY-MM-DD HH:mm:ssZ`。 。 。 .

## 发展

```bash
pnpm --filter @eternl/formats typecheck
pnpm --filter @eternl/formats test
pnpm --filter @eternl/formats build
```

测试套件包括地方差异、四舍五入的边缘外壳、百分比处理、大小尺寸和CSV引用规则.

## 许可证

商业来源许可证1.1(`BUSL-1.1`) (中文(简体) ).

额外使用赠款 : `None`。 。 。 . 商业用途需要从塔斯滕昆斯特获得单独的许可证. 联系人 : [https://tastenkunst.com/ (中文(简体) )](https://tastenkunst.com/)

## 常见问题

### @eternl/formats 是什么？

Locale-aware 显示和 CSV 格式化的帮助器用于数字数据\.

### 如何安装 @eternl/formats？

在项目目录运行 npm install @eternl/formats，或使用 pnpm add / yarn add / bun add。

### @eternl/formats 支持 TypeScript 吗？

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

### @eternl/formats 支持 ESM 还是 CommonJS？

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

### @eternl/formats 可以商用吗？

@eternl/formats 使用 BUSL-1\.1 许可。声明的许可为 BUSL-1\.1，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @eternl/formats 的下载量有多少？

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

### @eternl/formats 还在维护吗？

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