@gravity-ui/unipika

中文文档
5.6.5发布于 2026/09/23MITCommonJS零依赖近 30 天下载 9536

常见的 YT/YQL 数据格式库

中文使用文档
文档目录6 节
  1. 格式(数据[,设置[,转换器]]])
  2. 支持类型列表 :
  3. 格式设置 :
  4. 格式来自YSON(数据[,设置])
  5. 格式来自YQL( 数据[, 设置])
  6. 与日期合作的特点 :

乌尼皮卡

常见的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缩进模式、按键值分隔符中的空格和字符串二进制代表符中的空格不破(   页: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 共发布 27 个版本,首次发布于 2023/02/22;过去 12 个月发布了 4 个版本。

版本发布日期距今
5.6.5latest2026/09/231 个月前
5.6.42026/09/102 个月前
5.6.32026/06/304 个月前
5.6.22025/12/2310 个月前
5.6.12025/11/061 年前
5.6.02025/07/301.3 年前

关于 @gravity-ui/unipika 的常见问题

@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 和提交记录判断。