# @fhir-toolkit/ucum 中文文档

规范地址：https://npmcn.com/package/%40fhir-toolkit/ucum/

版本：0\.2\.0
npm 元数据更新时间：2026-04-05T22:01:52.453Z
中文译文更新时间：2026-11-14T16:37:17.629Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：579 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2026-04-05T12:21:40.008Z
- 最新版本发布：2026-04-05T22:01:52.117Z
- 近 30 天下载量：2311（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

UCUM( 计量单位统一代码) 解析器和 TypeScript 转换器

## 安装

```sh
npm install @fhir-toolkit/ucum
```

也可以使用：`pnpm add @fhir-toolkit/ucum`、`yarn add @fhir-toolkit/ucum`、`bun add @fhir-toolkit/ucum`

## README

# @fhir-toolkit/ucum (英语)

UCUM(计量单位的统一代码)验证器,转换器,以及Node.js和浏览器的分析器.

## 安装

```bash
pnpm add @fhir-toolkit/ucum
# or
npm install @fhir-toolkit/ucum
```

## 基本用途

```typescript
import { createUcumService } from '@fhir-toolkit/ucum'

const service = createUcumService()
```

### 校验

```typescript
service.validate('mg/dL') // returns void — valid

service.validate('xyz')   // throws UcumValidationError
```

### 转换

```typescript
const mg = service.convert(1, 'g', 'mg')
console.log(mg) // 1000

const celsius = service.convert(37, 'Cel', '[degF]')
console.log(celsius) // 98.6

// Throws UcumConversionError if units are not comparable
service.convert(1, 'mg', 'Cel')
```

### 检查可比性

```typescript
service.isComparable('mg', 'g')    // true — same dimension (mass)
service.isComparable('mg', 'Cel')  // false — different dimensions
service.isComparable('kg.m/s2', 'N') // true — both resolve to force
```

### 条形

```typescript
// Returns the value and base-unit code
const result = service.canonical(1, 'kg.m/s2')
// { value: 1, code: 'g.m.s-2' }

const result2 = service.canonical(1, 'mg/dL')
// { value: 0.01, code: 'g.l-1' }
```

### 乘并相除

```typescript
const speed = service.multiply(
  { value: 100, code: 'm' },
  { value: 1,   code: 's-1' },
)
// { value: 100, code: 'm.s-1' }

const ratio = service.divide(
  { value: 10, code: 'g' },
  { value: 5,  code: 'L' },
)
// { value: 2, code: 'g.L-1' }
```

## 分析( )

返回 UCUM 表达式的可读描述 :

```typescript
service.analyze('mg/dL')   // 'milligram per deciliter'
service.analyze('kg.m/s2') // 'kilogrammetersecond-2'
service.analyze('Cel')     // 'degree Celsius'
```

## 建议()

通过代码前缀或名称子字符串自动完成单元搜索 :

```typescript
service.suggest('ki')    // [{ code: 'kg', name: 'kilogram' }, ...]
service.suggest('Cel')   // [{ code: 'Cel', name: 'degree Celsius' }, ...]

// Limit results (default: 20)
service.suggest('m', 5)  // at most 5 results
```

## 处理错误

```typescript
import { UcumValidationError, UcumConversionError } from '@fhir-toolkit/ucum'

try {
  service.validate('bad~code')
} catch (err) {
  if (err instanceof UcumValidationError) {
    console.error(err.message) // invalid UCUM code "bad~code": ...
  }
}

try {
  service.convert(1, 'mg', 'Cel')
} catch (err) {
  if (err instanceof UcumConversionError) {
    console.error(`${err.from} → ${err.to}: ${err.message}`)
  }
}
```

## 浏览器使用量

在任何现代浏览器中工作——不需要特殊的捆绑器配置:

```typescript
import { createUcumService } from '@fhir-toolkit/ucum'
const service = createUcumService()
```

## 从 `@lhncbc/ucum-lhc`

| `@lhncbc/ucum-lhc` | `@fhir-toolkit/ucum` |
| --- | --- |
| `UcumLhcUtils.getInstance().validateUnitString(code)` | `service.validate(code)` (推错) |
| `UcumLhcUtils.getInstance().convertUnitTo(value, from, to)` | `service.convert(value, from, to)` |
| `UcumLhcUtils.getInstance().commensurableTest(code1, code2)` | `service.isComparable(code1, code2)` |
| 手动字符串匹配 | `service.suggest(prefix, limit)` |

关键差异 :

-   `validate()` 掷出 `UcumValidationError` 而不是返回状态对象.
-   `convert()` 返回平面 `number` 而不是结果对象.
-   `canonical()` 接受 `(value, code)` 返回时 `{ value, code }`。 。 。 .

## 常见问题

### @fhir-toolkit/ucum 是什么？

UCUM\( 计量单位统一代码\) 解析器和 TypeScript 转换器

### 如何安装 @fhir-toolkit/ucum？

在项目目录运行 npm install @fhir-toolkit/ucum，或使用 pnpm add / yarn add / bun add。

### @fhir-toolkit/ucum 支持 TypeScript 吗？

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

### @fhir-toolkit/ucum 支持 ESM 还是 CommonJS？

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

### @fhir-toolkit/ucum 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @fhir-toolkit/ucum 可以商用吗？

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

### @fhir-toolkit/ucum 的下载量有多少？

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

### @fhir-toolkit/ucum 还在维护吗？

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