# @gravity-ui/unipika 中文文档

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

版本：5\.6\.5
npm 元数据更新时间：2026-09-23T10:46:00.054Z
中文译文更新时间：2026-11-17T02:27:42.611Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：240 kB，60 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2023-02-22T15:00:33.645Z
- 最新版本发布：2026-09-23T10:45:59.918Z
- 近 30 天下载量：9536（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：27（近 12 个月 4 个）

## 中文简介

常见的 YT/YQL 数据格式库

## 安装

```sh
npm install @gravity-ui/unipika
```

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

## README

# 乌尼皮卡

常见的YT/YQL/QC数据格式库.

## 格式(数据\[,设置\[,转换器\]\]\])

函数接受Unipika-YSON格式的数据(以下简称-Unipika格式),或者,如果显示转换器,则按照类型以任何其他格式和格式的数据. 目前介绍两个内置转换器:

-   YSON 到 Unipikan
-   YQL 到 Unipika

### 支持类型列表 :

| 源格式 | 类型 |
| --- | --- |
| 亚森 | `string`, (中文(简体) ), `number`, (中文(简体) ), `int64`, (中文(简体) ), `uint64`, (中文(简体) ), `double`, (中文(简体) ), `map`, (中文(简体) ), `list`, (中文(简体) ), `null` |
| YQL 语言 | `yql.string`, (中文(简体) ), `yql.int64`, (中文(简体) ), `yql.uint64`, (中文(简体) ), `yql.double`, (中文(简体) ), `yql.struct`, (中文(简体) ), `yql.dict`, (中文(简体) ), `yql.list`, (中文(简体) ), `yql.tuple`, (中文(简体) ), `yql.null`, (中文(简体) ), `yql.yson`, (中文(简体) ), `yql.pg.*` - YQL 中的 PostgreSQL 数据类型正在被格式化为字符串 |

在含义类型上相似的显示类似 。 譬如说, `int64` 财务报告和审定财务报表 `yql.int64`, (中文(简体) ), `map` 财务报告和审定财务报表 `yql.struct`等 (中文(简体) ).

假设类型不能任意混合,例如, `list` 不能有类型元素 `yql.string`尽管如此,图书馆并没有试图修复在这种情况下无效的数据. 当使用内置转换器时,这种情况不应该发生. 还有,例如,只有YSON类型可以拥有属性,对于其他类型特殊领域来说 `$attributes` 毫无意义.

### 格式设置 :

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| 恢复正常Url | `(url: string) => string` | `(url) => new URL(url).toString()` | 可选参数可以覆盖默认行为 `utils.normalizeUrl`默认执行用途 `encodeURI(url)` 如果调用例外,则返回空字符串。 电话的结果 `settings.normalizeUrl(url)` 向 DOM 树“ as is” 注入值为 `href`\-属性,所以你必须消毒返回的值以防止XSS. |
| 校验SrcUrl | `(url: string) => boolean` | `() => false` | 函数,接受源 URL for `TaggedType` 键入并返回是否允许下载。 如果设置未定义, `TaggedType` 类型(图像、音频、视频)将格式化为 `StructType` |
| 格式 | 字符串 | `'json'` | `[YSON-specific]` 影响显示 YSON 类型。 文本序列化 `yson` 或者说 `json` 支持。 YT文件中描述了这些代表方式. |
| 解码UTF8 | 布尔 | `true` | `[YSON-Converter][YSON-specific]` 设置传递给转换器( YSON 到 Unipik ) 。 表示是否尝试解码数据 。 从 YT 收到的设定为 { encode utf8 = false } 的数据不应该被解码(也意味着所有的字符串都是有效的 UTF-8 序列,即它们不是二进制) 。 默认从 YT 接收的数据是设置 { encode utf8 = true} 并且应该被解码;不能解码的字符串被标记为 二进制 . |
| 显示已解密 | 布尔 | `true` | `[NCP][YSON-specific]` 说明应显示解码数据还是从YT收到数据的形式. |
| 二进制AsHex | 布尔 | `true` | `[NCP][YSON-specific]` 指示二进制字符串是否应当显示为HEX数字的序列. |
| 作为HTML | 布尔 | `true` | 返回序列数据 `plain text` 或者说 `html`。 。 。 . |
| 换行 | 布尔 | `true` | 将连字符和缩入或还一切作一行. |
| 缩进 | 数目 | `4` | 缩入大小. |
| 紧凑 | 布尔 | `false` | 复杂类型喜欢的模式 `map`, (中文(简体) ), `list`, (中文(简体) ), `yql.struct` 如果只包含一个元素,则显示更为紧凑的元素. |
| 突出显示控制 | 布尔 | `false` | 允许在 html 字符串中突出显示特殊控制字符. |
| 逃出白空间 | 布尔 | `true` | `[NCP]`连字符和分页字符没有被逃脱的模式 。 使用此选项可以查看堆栈跟踪等格式化数据 . |
| 逃出 YQLST 环 | 布尔 | `true` | `[NCP][YQL-Converter]`没有符号被逃脱的模式,这样用户就可以得到"raw"数据. |
| 非断裂 缩进 | 布尔 | `true` | 缩进模式、按键值分隔符中的空格和字符串二进制代表符中的空格不破( `&nbsp;` 页:1. |
| 省略StructNull 语句 | 布尔 | `false` | `[YQL-Converter]` 指示是否跳过密钥 `null` 数值在 `yql.struct` 类型. |
| 最大列表大小 | 数目 | `undefined` | `[YQL-Converter]` 列表节点的最大允许大小( N)`yql.list`, (中文(简体) ), `yql.dict`, (中文(简体) ), `yql.struct`, (中文(简体) ), `yql.tuple`, (中文(简体) ), `yql.stream`) (中文(简体) ). 如果值 > 0 被设定, 节点将被切换到此值 . |
| 最大 | 数目 | `undefined` | `[YQL-Converter]` 最大允许字符串大小( E)`yql.string`, (中文(简体) ), `yql.utf8`) (中文(简体) ). 如果值 > 0 被设定,字符串将被切换到这个值 . |
| 限制MapLength | 数目 | `undefined` | 所有地图节点的最大允许大小 。 如果设定值 > 0,则节点会切入到此值( 值 - 1) . |
| 限制列表ListLength | 数目 | `undefined` | 所有列表节点的最大允许大小 。 如果设定值 > 0,则节点会切入到此值( 值 - 1) . |
| 治疗ValAsData | 布尔 | `false` | 若为 `val` 在数据字段中,它可被作为普通对象键(如果 `treatValAsData` 未设置或设置为 `false`)或数值将设定为美元总价值(如果 `treatValAsData` 设置为 `true`) (中文(简体) ). 在大多数情况下,不应设置这种设置. |

`[YQL-Converter]` - 选项只影响YQL格式的数据转换. `[YSON-Converter]` - 选项只影响YSON格式的数据转换. `[YSON-Specific]` - 选项只影响YSON类型的代表,不应影响其他类型的代表. `[NCP]` - (不可复制-可复制)这种表示法用于提高可读性,但无效;复制和使用这些数据可能造成错误.

## 格式来自YSON(数据\[,设置\])

格式函数包,数据以YSON格式传递,使用YSON到Unipika转换器.

## 格式来自YQL( 数据\[, 设置\])

格式函数包,数据以 YQL 格式传递( 在列表中) `[data, dataType]`),使用YQL到Unipika转换器.

## 与日期合作的特点 :

1.  所有日期都转换为格雷高历.
2.  根据Gregorian日历,AD的第一年表示为:01-01-01T00:00:00.000Z. 如果从这个日期减去1微秒,则得到日期为-01-12-31T23:59:999999Z(公元前1年).
3.  为了确定负年是否是格里高利历上的一个跳跃年,首先将一年加一,再适用通常的跳跃年规则. 因此,年份-1是一个跃迁年份(自-1+1=0起,而0%为4=0起,所以是一个跃迁年份).
4.  第1年是继第2年之后,但与此同时,-1-01-21-20在-01-21之前(类似地,-1-01-01在-1-02-01之前). 因此,减号仅适用于当年的价值.
5.  格里高利历上没有0年,但这并不妨碍我们把1年视为一跃而起.
6.  必须明白,作为输入,插件yql-date,yql-datetime,和yql-time-timestamp接收了与Unix epoch(1970-01-01T00:00:00.000Z)相对的时间. 因此,1-01-02的日期是719161天前相较于Unix时代,但比时代开始早了一天(1-01-01).

## 常见问题

### @gravity-ui/unipika 是什么？

常见的 YT/YQL 数据格式库

### 如何安装 @gravity-ui/unipika？

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

### @gravity-ui/unipika 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/gravity-ui\_\_unipika 是否存在。

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

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

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

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

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

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

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

