# @flatfile/blueprint 中文文档 规范地址：https://npmcn.com/package/%40flatfile/blueprint/ 版本：0\.0\.15 npm 元数据更新时间：2026-04-23T23:54:12.311Z 中文译文更新时间：2026-11-14T21:48:29.422Z 软件包许可：未声明 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40flatfile/blueprint 原文对照：https://npmcn.com/package/%40flatfile/blueprint/?lang=original ## 关键信息（来自 npm 元数据） - 包体积（解压后）：35.3 kB，3 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=16 \|\| \>=22 - 运行依赖：2 个 - 首次发布：2022-08-17T15:49:54.880Z - 最新版本发布：2025-06-30T03:35:32.865Z - 近 30 天下载量：22310（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：14（近 12 个月 0 个） ## 中文简介 用于定义Flatfile数据结构的通用DDL. ## 安装 ```sh npm install @flatfile/blueprint ``` 也可以使用：`pnpm add @flatfile/blueprint`、`yarn add @flatfile/blueprint`、`bun add @flatfile/blueprint` ## README # 蓝图 `@flatfile/blueprint` 是Flatfile中与客户定义的数据结构合作的参考点。 我们有很多不同的数据问题需要解决 跨不同的系统,例如DAL,管道,工作簿,转盘,和SDK. ## 目标 - [ ] 描述外部系统界定的任何合理数据结构 - [ ] 向数据库引擎通报如何最好地存储和检索数据 - [ ] 告知渲染引擎(如表格或表格)如何最好地渲染数据点 - [ ] 提供数据本体分类的匹配或AI系统 - [ ] 向最终用户提供数据结构特有的指导 - [ ] 为数据库驱动的验证提供配置 - [ ] 为分析或未来优化目的报告用户或系统定义的钩子运行情况 ## 任期考虑 - **财产** 描述实体的属性(如名称、电子邮件)及其应如何行事. ## 示例配置 ```json { "properties": [ { "key": "code", "label": "Product Code", "type": "string", "description": "Unique identifier defining an individual product.", "constraints": [ { "type": "unique", "config": { "caseSensitive": false } } ], "config": { "size": "tiny" } }, { "key": "description", "type": "string" }, { "key": "price", "type": "number", "config": { "decimalPlaces": 2 } }, { "key": "category", "label": "Product Category", "type": "enum", "multi": true, "config": { "allowCustom": false, "options": [ { "value": 9, "label": "Kitchenware", "icon": "pots-and-pans", "color": "#f00000", "meta": { "product_code_prefix": "KI-" } }, { "value": 9, "label": "Clothing", "meta": { "product_code_prefix": "CL-" } } ] } } ] } ``` # 核心属性 所有属性都有以下选项. 如果属性类型以 `[]` (例如: `string[]`它应作为无限大小的阵列来储存、检索和显示. | 选项 | 说明 | 默认 | 需要吗? | | --- | --- | --- | --- | | `key` | 此字段的系统名. 主要告知JSON和Egress结构. | | ✅ | | `type` | 一个 `string`, (中文(简体) ), `number`, (中文(简体) ), `boolean`, (中文(简体) ), `date`, (中文(简体) ), `enum`, (中文(简体) ), `reference`。定义该财产的处理. | | ✅ | | `label` | 一个面向用户的描述标签, 设计用于在UI中显示, 如表格头 . | `key` | | | `description` | 对拟显示给最终用户的属性的长式描述 . | | | | `constraints` | 一系列系统级验证规则,打算在钩子运行后应用. | `[]` | | | `config` | 与列类型相关的配置 。 见下文财产文件. | `{}` | 有时 | | `multi` | 如果设定的话, 将允许多个值并存储 / 提供数组中的值 。 并非所有字段类型都支持数组. | `false` | | | `meta` | 任意的价值观对象通过钩子和后退 | `{}` | | ## `string` 🧵 _(默认)_ 定义一个应当存储并读取为基本字符串的属性。 数据库引擎应该期待在此提供任何文本长度,除非在配置中明确定义. ### 配置选项 - `size: enum(tiny, normal, medium, long)` 这一领域应储存多少文本? - `tiny` = 最多255个字符 - ➡`normal` = 64克b(默认) - `medium` = 16立方米b - `long` = 4克/秒 ## `number` #️⃣ 定义一个应当存储并读取为整数或浮点数的属性。 数据库引擎应当查看配置以确定理想的存储格式. ### 配置选项 | 选项 | 说明 | 默认 | | --- | --- | --- | | `decimalPlaces` | 保留精确度的小数位数。 逾期的,应当自动四舍五入并发出警告. 钩子可以预格式来完成地平线或地平线. | `0` | ## `reference` 🔗 > **3⁄4 ̄ ̧漯B** > > 这与外国钥匙不相上下。 不应具体指明哪一栏是多变量的。 用户在绘制图时可以建立类似 `company name`一旦储存在我们的系统中,我们将参考 我们的内部身份证, 并在入侵时,我们提供已知的 `system_id` 如果有的话. 定义另一个工作表的引用。 在对数据集之间独特或相近的列进行评价后,由匹配引擎自动建立或类似的链接. ### 配置选项 | 选项 | 说明 | 需要吗? | | --- | --- | --- | | `ref` | 其他工作表/表格配置的完整路径引用 。 一定是在同一个工作簿里. | ✅ | | `relationship` | 这定义的关系类型. 可以成为其中之一 `has-many` 或者说 `has-one` | ✅ | ## `enum` 定义供用户选择的选项列表。 匹配用于解决数据输入的尝试与有效选项。 此列表的最大选项数为 `100`对于较大的列表,用户应当使用 `reference` 或未来 `lookup` 类型. ### 配置选项 | 选项 | | 说明 | 默认 | 需要吗? | | --- | --- | --- | --- | --- | | `allowCustom` | | 允许用户为这个特定字段创建新选项 . | `false` | | | `options[]` | | 用户可以从中选择的有效选项列表 | | ✅ | | | `value` | 此选项的值或ID 。 此值将逐一发送 | | ✅ | | | `label` | 此选项的可视标签, 如果不提供则默认值 | | | | | `color` | 指定此选项的可选颜色 | | | | | `icon` | 以前注册的图标的参考指针 | | | | | `meta` | 任意的 JSON 对象与此选项相关联, 并可供钩子使用 | | | ## `boolean` A 类 `true` 或者说 `false` 值类型。 匹配引擎应该尝试解决所有常见的表达这个值的方法,并且它通常应该被显示为一个复选框. | 选项 | 说明 | 默认 | | --- | --- | --- | | `allowIndeterminate` | 允许不确定( E)`null`)既未选定,也未选定. | `true` | ## `date` 存储一个字段作为 GMT 日期 。 数据勾钩必须转换为 `YYYY-MM-DD` 格式,使其被视为有效的值。 时间应当是一个单独的、未来得到支持的价值,因为它必须考虑时区. # 未来类型 1. 链接属性 – 从被引用的表格中以一个或多个值填充此属性 - 数据钩可以被进一步转换. 应支持过滤器 . - 示例1:在 a 上显示只读值 `contact` 基于 `country` 链接 `company` 2. 滚动 — 使用一个数据hook来汇总或计算所有引用的值. 应支持过滤 . - 实例1: `sum()` 总计 `items.price * items.quty` 链接到 `invoice` - 实例2: `deals` 与 `status: lost` 链接到 a `salesperson` 3. 组/组- 任意取名的一组记录,这些记录可以只按命名空间分组,也可以重复使用类似于关系集的记录. - 实例1: `contact_methods` 带有 `type`, (中文(简体) ), `value`,以及 `priority`。 。 。 . - 实例2: `address` 组为 `street`, (中文(简体) ), `city`,, , , , , , , , . 4. 远程查询(Remote Lookup)——一种依靠数据hook返回有效选项而不是enum列表或参考表格的字段. - 例1:这个字段必须是所提供飞行的有效编号 `city` 财务报告和审定财务报表 `date`。用户在与单元格互动时应当能够从有效飞行列表中选择. - 示例2:全球自动完成 `address` 输入。 在您输入时, 一组建议出现在下拉中 . ## 常见问题 ### @flatfile/blueprint 是什么？ 用于定义Flatfile数据结构的通用DDL\. ### 如何安装 @flatfile/blueprint？ 在项目目录运行 npm install @flatfile/blueprint，或使用 pnpm add / yarn add / bun add。 ### @flatfile/blueprint 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @flatfile/blueprint 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @flatfile/blueprint 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=16 \|\| \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @flatfile/blueprint 可以商用吗？ @flatfile/blueprint 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @flatfile/blueprint 的下载量有多少？ 根据 npm 官方下载统计，@flatfile/blueprint 在 2026/10/15 – 2026/11/13 这 30 天内被下载 22,310 次，日均约 744 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @flatfile/blueprint 还在维护吗？ 最新版本 0\.0\.15 发布于 2025/06/30（1\.4 年前）；至今共发布 14 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/08/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。