# @didomi/consent-string-schema 中文文档 规范地址：https://npmcn.com/package/%40didomi/consent-string-schema/ 版本：1\.1\.0 npm 元数据更新时间：2026-04-09T08:24:22.995Z 中文译文更新时间：2026-11-12T07:35:17.934Z 软件包许可：未声明 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40didomi/consent-string-schema 原文对照：https://npmcn.com/package/%40didomi/consent-string-schema/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：271 kB，83 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - 首次发布：2026-04-09T08:24:22.458Z - 最新版本发布：2026-04-09T08:24:22.694Z - 近 30 天下载量：15846（2026-10-12 至 2026-11-10，npm 官方下载统计） - 已发布版本数：1（近 12 个月 1 个） ## 中文简介 \* \[同意弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦 ## 安装 ```sh npm install @didomi/consent-string-schema ``` 也可以使用：`pnpm add @didomi/consent-string-schema`、`yarn add @didomi/consent-string-schema`、`bun add @didomi/consent-string-schema` ## README # 协议字符串Schema - [协议字符串Schema](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-consent-string-schema) - [图表格式](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-schema-format) - [类型](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-type) - [外地](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-field) - [同意字符串类型](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-consent-string-type) - [规格版本](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-specification-version) - [测试](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-test) - [类型](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-types) - [领域和部分](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-fields-and-segments) - [Schema 验证](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-schema-validation) - [结构验证](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-structure-validation) - [类型验证](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-type-validation) - [密钥验证](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-key-validation) 同意字符串将用户同意状态存储为二进制数据,编码为base64. 将用户同意状态编码为二进制字符串,或从已存在的字符串中解码,都需要一个编码器/解码器库. Schema以人可读的方式定义同意字符串格式. 这样可以定义出新的格式,或者对现有格式进行更新,而不修改编码器/解码器库. ## 图表格式 计划的结构如下: - `consent_string_type` - `specification_version` - `tests` - `types` - `fields` 或者说 `segments` ### 类型 编码员和解码员需要知道他们合作的数据类型. 计划定义有特定类型的字段, 很像编程中的变量。 下列类型必须得到编码器/解码器库的支持: | {\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0} | 类型编号 | 说明 | | --- | --- | --- | | 1个 | `u1` | 1 比特大小( 0 或 1) 无符号整数 | | 2个 | `u2` | 未签名的2比特大小的整数 | | 3个 | `u3` | 3 比特大小的无符号整数 | | 页:1 | `u4` | 4 比特大小的无符号整数 | | 页:1 | `u6` | 6 比特大小的无符号整数 | | 6个 | `u12` | 12 比特大小的无符号整数 | | 第7条 | `u16` | 16位数大小的无符号整数 | | 第8条 | `u24` | 24位大小的无符号整数 | | 第9条 | `u32` | 32 位大小的无符号整数 | | 10个 | `date` | 日期 | | 第11个 | `uuid` | 用户名 - Base16 字符串 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx | | 第12条 | `fibonacci` | 数字 | | 第13条 | `fibonacci_range` | Fibonacci 编号的 Fibonacci ID 范围, 以 Fibonacci 编号为起始 id 和编号 id 编号 | | 页:1 | `u16_range` | 以 u16 个数字开头的 Ids 范围 | | 15个 | `bit_field` | 位数阵列 | | 16个 | `fixed_bit_field` | 固定大小比特字段阵列,大小属性必须在方案内指定 | | 页:1 | `bit_field_2_bits` | Bit 字段阵列( bool, bul) | | 第 18 条 | `ranges_u16` | Id 范围矩阵 - (起始 id: u16;结束 id: u16) | | 第 19 条 | `ranges_fibonacci` | Id 范围矩阵 - (起始 id: fibonacci,编号 ids: fibonacci) | | 20国 | `string` | 表示字符串的固定位数 。 该字符的ASCII整数ID被减去了65并被编码为一int(6). | | 21国 | `optimized_range` | 第一个数据类型总是布尔(u1),如果它是真实的,下一个是Fibonacci范围,如果是假的 - Bitfield . | | 22个 | `optimized_u16_range` | 以 u16 range - (最大 id: u12, range flag: u1, 类型: \[u16 range, 固定 bit field(大小: max id)\] 优化位域 | | 第23条 | `array_of_optimized_u16_ranges` | 优化- u16 排列( 数字 记录: u12, 键: u6, 类型: u2, ids: 优化- u16 排列) | | 24个 | `n_array_of_ranges_x_y` | 通用类型QQ,Y>(数字 记录:u12,密钥:u,类型:u,IDs:优化 范围) | | 第25条 | `optimized_array_of_u16_ranges` | (max id:u16,是:u1,类型:\[(数字 of indies:u12,是:a range:u1,类型:\[起 id:u16,端 id:u16\],起 id:u16\]),固定 bit field(大小:最大 id)\] | | 第 26 条 | `array_of_u16_ranges` | (编号: of records:u12,密钥:u6,类型:u2,号码:u12,是 a range:u1,类型:\[(从 id:u16起,端-id:u16起,起-id:u16起) | | 27个 | `segment_type` | 3bits 分区类型代码 | | 第28条 | `enabled_disabled_ids` | 启用和禁用以变体属性所列出的某些类型编码的 ID | | 29个 | `array_of_attributed_u16_ranges` | 用于出版商限制编码的指定范围的数组 | | 30个 | `version` | 以 6bits 编号编码的同意字符串版本 | ### 外地 计划的主要组成部分是 `field`编辑 `field` 是一个编程语言中的变量的模拟,每个归档必须有一个类型. 有一个实地定义的例子: ```json { "type": "version", "description": "The Didomi Consent String version 6bits number", "key": "dcs_version", "value": 2 } ``` 在这里,我们正在定义的领域与 `type` "版本"和 `key` 等于“ dcs version” 。 编码器将使用 `key` 属性访问用户状态对象中提供的字段值。 我们还可以定义领域 `value` 属性指示编码器不从用户状态对象读取值,而是从计划读取值. 另一个例子是 `field` 属性是 `optional`。每个字段都可以是可选的,这将指示 编码器,在字段值之前将1比特旗放入编码字符串中. 如果旗帜是 `1`,该值是存在的并解码的。 如果是这样 `0`,在解码时,该值缺失并跳出. 有可选字段定义的例子 ```json { "type": "date", "key": "sync", "optional": true } ``` 有些字段可以使用不同的编码算法进行编码来进行优化. 说明什么 算法(类型)可以通过编码器用于我们使用的值编码器 `variants` 字段属性 : ```json { "type": "enabled_disabled_ids", "description": "User Status for purposes opt-out", "key": "purposes_li", "variants": [ "bit_field_2_bits", "ranges_u16", "ranges_fibonacci" ] } ``` 这个例子说明了如何使用三种方法来编码用户状态: `bit_field_2_bits`, (中文(简体) ), `ranges_u16`,以及 `ranges_fibonacci`。 。 。 . 编码器选择产生最短结果的方法并包含 在编码值之前选择方法的代码,允许解码器 以正确解码字符串. 有些类型需要有大小信息才能正确编码/解码. ```json { "type": "string", "description": "Two-letter ISO 639-1 language code in which the CMP UI was presented", "key": "consent_language", "size": 12 } ``` 我们在这里定义了一个12位字符串类型字段. 所有字段属性都有摘要: | {\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0} | 字段属性 | 强制 | 说明 | | --- | --- | --- | --- | | 1个 | `type` | Y | 字段类型 | | 2个 | `key` | Y | 从模型中提取值的密钥 | | 3个 | `description` | Y | 字段说明 | | 页:1 | `size` | 无 | 类型大小位 | | 页:1 | `optional` | 无 | `true` 如果值可能缺失 | | 6个 | `value` | 无 | 字段常数值 | | 第7条 | `variants` | 无 | 类型编码方法变体 | ### 同意字符串类型 同意字符串计划支持以下类型: | {\\fn方正粗倩简体\\fs12\\an8\\1cHFFFF00\\b0} | 字符串类型 | 说明 | | --- | --- | --- | | 1个 | `didomi_consent_string` | Didomi 同意字符串 | | 2个 | `iab_tcf_string` | IAB TCF 协议字符串 | | 3个 | `gpp_string` | GPP 字符串 | ### 规格版本 对于每个字符串类型,可以定义几个规格版本,例如:, 给迪多米同意弦 `specification_version` 1和2,其中第1版 对编码器有一些限制. ### 测试 同意字符串计划定义了编码器和解码器的测试 `tests` 阵列。 编码器/解码器库应 运行这些测试,以确保库根据计划产生预期结果. ### 类型 这个 `types` 数组定义了由同意字符串计划支持的子集类型([类型](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-type)) (中文(简体) ). 每个 `type` 从 `types` 必须至少出现在字段定义中,来自字段定义的所有类型都应该是 列入清单 `types` 阵列. ### 领域和部分 同意字符串计划可以 `fields` 顶级数组或 `segments` 阵列。 这个 `fields` 阵列包含字段定义( r)[外地](https://npmcn.com/package/%40didomi/consent-string-schema/#readme-field)和 `segments` 能够 用于定义分块字符串结构,其中每个分块编码 单独连接,然后使用 `.` 字符键. 例如: ```json { "tests": { "encoded": "CQH-gkAQH-gkAAHABBENBOFgAPAAAELAAAAAF5wAQF5gXnABAXmAAAAA.YAAAAAAAAAAA" } } ``` 这里有一个 IAB TCF 字符串作为 `encoded` 值有两个部分:核心部分和出版部分. 在被定义为下列对象的图示中: ```json { "name": "Disclosed Vendors", "key": "disclosed_vendors", "optional": true, "fields": [ { "type": "segment_type", "description": "DisclosedVendors segment is 1 which is 001 in binary.", "key": "disclosed_vendors_segment_type", "value": 1 }, { "type": "optimized_array_of_u16_ranges", "description": "Vendors Disclosure", "key": "disclosed_vendors" } ] } ``` 每个 `segment` 已经 `name`, (中文(简体) ), `key`, (中文(简体) ), `optional` 财务报告和审定财务报表 `fields` 属性,除 `optional` 强制的. ## Schema 验证 同意字符串计划库提供 `validator` 函数,通过3个步骤验证计划: - 使用 `zod` 图书馆 - 验证计划类型 - 验证密钥 ### 结构验证 我们用 `zod` 以定义同意字符串结构以及控制类型。 比如说,有 `field` 使用定义 `zod`数字 : ```typescript import { z } from 'zod'; export const availableTypesSchema = z.nativeEnum(SchemaTypes); export const typesSchema = uniqueNotEmptyArray(availableTypesSchema); export const consentStringTypeSchema = z.enum([ 'didomi_consent_string', 'iab_tcf_string', 'gpp_string', ]); export const variantsTypes = z.enum([SchemaTypes.bit_field_2_bits, SchemaTypes.ranges_fibonacci, SchemaTypes.ranges_u16]); export const variantsSchema = uniqueNotEmptyArray(variantsTypes); export const fieldSchema = z.object({ type: availableTypesSchema, description: z.string(), key: z.string(), optional: z.boolean().optional(), size: z.number().or(z.string()).optional(), value: z.number().optional(), variants: variantsSchema.optional() }); ``` 这个计划确保了 `type` 属性只包含允许的类型 `variants` 属性包含三个允许的类型. ### 类型验证 虽然 `zod` 验证类型,计划还必须确保所有类型 `types` 阵列用于字段定义, 并且所有字段类型都列在 `types` 阵列。 此镜像编程语言, 其中类型被定义 使用前和未使用的定义可能触发警告或错误. 图书馆的 `typeValidator` 之后执行此约束 `zod` 审定. ### 密钥验证 最后的验证步骤需要确保域定义中的所有密钥都独一无二. 图书馆的 `keyValidator` 运行后 页:1 `typeValidator` 以强制执行这一限制. ## 常见问题 ### @didomi/consent-string-schema 是什么？ \* \[同意弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦-弦 ### 如何安装 @didomi/consent-string-schema？ 在项目目录运行 npm install @didomi/consent-string-schema，或使用 pnpm add / yarn add / bun add。 ### @didomi/consent-string-schema 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @didomi/consent-string-schema 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @didomi/consent-string-schema 可以商用吗？ @didomi/consent-string-schema 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @didomi/consent-string-schema 的下载量有多少？ 根据 npm 官方下载统计，@didomi/consent-string-schema 在 2026/10/12 – 2026/11/10 这 30 天内被下载 15,846 次，日均约 528 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @didomi/consent-string-schema 还在维护吗？ 最新版本 1\.1\.0 发布于 2026/04/09（7 个月前）；至今共发布 1 个版本，其中过去 12 个月发布了 1 个；首次发布于 2026/04/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。