# @a2ui-sdk/utils 中文文档

规范地址：https://npmcn.com/package/%40a2ui-sdk/utils/

版本：0\.4\.0
npm 元数据更新时间：2026-02-02T07:39:43.573Z
中文译文更新时间：2026-11-05T23:17:52.212Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40a2ui-sdk/utils
原文对照：https://npmcn.com/package/%40a2ui-sdk/utils/?lang=original
项目主页：https://a2ui-sdk.js.org/
源码仓库：https://github.com/easyops-cn/a2ui-sdk

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

- 包体积（解压后）：81.4 kB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-01-13T07:35:09.338Z
- 最新版本发布：2026-02-02T07:39:43.427Z
- 近 30 天下载量：9723（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

A2UI公用事业

## 安装

```sh
npm install @a2ui-sdk/utils
```

也可以使用：`pnpm add @a2ui-sdk/utils`、`yarn add @a2ui-sdk/utils`、`bun add @a2ui-sdk/utils`

## README

# @a2ui-sdk/图利

与 A2UI 协议合作的功能 。 此软件包为数据绑定解析,路径操纵,字符串插入,以及验证提供了帮助.

## 安装

```bash
npm install @a2ui-sdk/utils
```

## 使用量

### v0.9 (最晚) (中文(简体) )

```tsx
import {
  // String interpolation
  hasInterpolation,
  interpolate,

  // Data binding utilities
  resolveValue,
  resolveStringValue,
  resolveNumberValue,
  resolveBooleanValue,
  isPathBinding,

  // Path utilities
  parsePath,
  joinPath,
  getValueAtPath,
  setValueAtPath,

  // Validation utilities
  evaluateCheckRule,
  validateChecks,
} from '@a2ui-sdk/utils/0.9'
```

### v. 0.8 (中文(简体) )

```tsx
import {
  // Data binding utilities
  resolveValue,
  resolveActionContext,
  resolveStringValue,
  resolveNumberValue,
  resolveBooleanValue,
  isPathBinding,

  // Path utilities
  normalizePath,
  isAbsolutePath,
  joinPaths,
  resolvePath,
  parsePath,
  joinPath,
  getValueAtPath,
  setValueAtPath,
} from '@a2ui-sdk/utils/0.8'
```

### 命名空间导入

```tsx
import { v0_8, v0_9 } from '@a2ui-sdk/utils'

// Use v0.9 utilities
const { interpolate, hasInterpolation } = v0_9
```

## API 密码

### 范围和路径分辨率(v0.8+)

工作范围数据路径:

```tsx
import {
  normalizePath,
  isAbsolutePath,
  joinPaths,
  resolvePath,
} from '@a2ui-sdk/utils/0.8'

// Normalize path format
normalizePath('user/name') // '/user/name'
normalizePath('/items/') // '/items'

// Check if path is absolute
isAbsolutePath('/user/name') // true
isAbsolutePath('name') // false

// Join base path with relative path
joinPaths('/items/0', 'name') // '/items/0/name'
joinPaths('/items', '../users') // '/users'

// Resolve path with scope
resolvePath('/user/name', '/items/0') // '/user/name' (absolute, ignores basePath)
resolvePath('name', '/items/0') // '/items/0/name' (relative, uses basePath)
resolvePath('name', null) // '/name' (treats relative as absolute when no basePath)
```

### 字符串内插( v0. 9)

有嵌入式表达式的处理字符串 :

```tsx
import { hasInterpolation, interpolate } from '@a2ui-sdk/utils/0.9'

// Check if string contains interpolation
hasInterpolation('Hello {{name}}') // true
hasInterpolation('Hello world') // false

// Interpolate string with data
const data = { name: 'Alice', count: 5 }
interpolate('Hello {{name}}, you have {{count}} items', data)
// => 'Hello Alice, you have 5 items'
```

### 数据绑定

从数据模型中解析动态值 :

```tsx
import { resolveValue, isPathBinding } from '@a2ui-sdk/utils/0.9'

const dataModel = { user: { name: 'Alice' } }

// Check if value is a path binding
isPathBinding({ path: '/user/name' }) // true
isPathBinding('static value') // false

// Resolve value
resolveValue({ path: '/user/name' }, dataModel) // 'Alice'
resolveValue('static value', dataModel) // 'static value'
```

`resolveValue` 也支持范围路径解析 :

```tsx
import { resolveValue } from '@a2ui-sdk/utils/0.9'

const dataModel = { items: [{ name: 'Item 1' }, { name: 'Item 2' }] }

// Resolve with basePath for scoped data access
resolveValue({ path: 'name' }, dataModel, '/items/0') // 'Item 1'
resolveValue({ path: '/items/1/name' }, dataModel, '/items/0') // 'Item 2' (absolute path ignores basePath)
```

### 路径工具

与 JSON 指针路径合作( RFC 6901):

```tsx
import {
  parsePath,
  joinPath,
  getValueAtPath,
  setValueAtPath,
} from '@a2ui-sdk/utils/0.9'

// Parse path into segments
parsePath('/user/profile/name') // ['user', 'profile', 'name']

// Join segments into path
joinPath(['user', 'profile', 'name']) // '/user/profile/name'

// Get value at path
const data = { user: { profile: { name: 'Alice' } } }
getValueAtPath(data, '/user/profile/name') // 'Alice'

// Set value at path (immutable)
const newData = setValueAtPath(data, '/user/profile/name', 'Bob')
// data is unchanged, newData has the update
```

### 审定(v0.9)

评价验证规则 :

```tsx
import { evaluateCheckRule, validateChecks } from '@a2ui-sdk/utils/0.9'

const checks = [
  {
    message: 'Name is required',
    call: 'isNotEmpty',
    args: { value: { path: '/form/name' } },
  },
]

const dataModel = { form: { name: '' } }
const result = validateChecks(checks, dataModel)
// { valid: false, errors: ['Name is required'] }
```

## 许可证

阿帕奇 - 2.0

## 常见问题

### @a2ui-sdk/utils 是什么？

A2UI公用事业

### 如何安装 @a2ui-sdk/utils？

在项目目录运行 npm install @a2ui-sdk/utils，或使用 pnpm add / yarn add / bun add。

### @a2ui-sdk/utils 支持 TypeScript 吗？

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

### @a2ui-sdk/utils 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @a2ui-sdk/utils 可以商用吗？

@a2ui-sdk/utils 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @a2ui-sdk/utils 的下载量有多少？

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

### @a2ui-sdk/utils 还在维护吗？

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