NocoBase 导入操作Import完全指南Excel 模板导入、字段映射与自定义解析器【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase导读「导入操作」是 NocoBase 界面搭建器中一个开箱即用的数据导入动作用户下载由系统自动生成的 Excel 模板按模板填写数据并上传即可将 Excel 等文件中的数据批量写入数据表。本指南以 导入操作官方文档 为核心结合nocobase/plugin-action-import插件与nocobase/database的 ValueParser 体系源码完整讲解各类字段类型数字、布尔、日期、选择、关系、JSON、地图几何图形等的导入格式与转换规则、如何注册自定义字段解析器以及导入操作的配置方式。读完本文你将掌握 NocoBase 数据导入的底层转换机制并能在实际项目中自定义导入格式。功能定位从模板下载到数据落库NocoBase 的导入操作面向“批量录入已有表格数据”这一高频场景其核心设计是自动生成模板根据数据表字段自动生成 Excel 模板无需手工绘制表头可配置导入字段导入时可选择参与导入的字段未勾选的字段不进入模板与解析流程模板下载导入弹窗内置「下载模板」入口保证表头与字段定义严格一致字段映射Excel 单元格中的原始文本如是、25%、北京市/市辖区会在服务端被解析为数据库可存储的 JSON 值。从源码看导入能力由 plugin-action-import 插件提供核心服务端入口为 import-xlsx.ts前端上传文件后服务端通过xlsx库读取工作簿readImportWorkbook再交由XlsxImporter逐行执行字段值解析与写入。值得注意的实现细节是单次导入上限为IMPORT_LIMIT_COUNT 2000行import-xlsx.ts读取时会在该行数基础上加表头行导入全程使用Mutex互斥锁同一时刻只允许一个导入任务执行避免并发写库冲突解析 Excel 日期单元格时显式设置cellDates: false保留序列号以避免在非 UTC 时区如 Asia/Shanghai解析纯日期时发生偏移。模板生成与文件下载分别由 template-creator.ts 与 download-xlsx-template.ts 承担模板内容随「可导入字段」的配置动态变化。各类字段类型的导入格式与转换规则导入的核心环节是「文本 → JSON 值」的转换。NocoBase 为每种字段类型内置了对应的ValueParser注册关系见 value-parsers/index.tsnumber/integer/bigInt/float/double/real/decimal使用NumberValueParserboolean使用BooleanValueParserdate使用DateValueParserjson/jsonb使用JsonValueParserstring使用StringValueParser关联关系字段则按hasOne/belongsTo使用ToOneValueParser、按hasMany/belongsToMany使用ToManyValueParser。下面逐类说明。数字类型字段数字与百分比均受支持。字符串N/A或-不区分大小写会被过滤为null数字1百分比数字2数字312325%N/A-转 JSON 之后为{ 数字1: 123, 百分比: 0.25, 数字2: null, 数字3: null, }底层实现位于 number-value-parser.ts字符串会先去除千分位逗号value.replace(/,/g, )以%结尾的文本通过percent2float转为小数25%→0.25否则用value转为数值空字符串与n/a、-均得到null转换结果为NaN时则把错误信息写入errors数组。布尔类型字段输入文案支持以下写法英文不区分大小写真值Yes、Y、True、1、是假值No、N、False、0、否字段1字段2字段3字段4字段5否是Ytrue0转 JSON 之后为{ 字段1: false, 字段2: true, 字段3: true, 字段4: true, 字段5: false, }对应的 boolean-value-parser.ts 同时接受布尔值、数值0/1与上述字符串集合空字符串得到null无法识别的文本会进入errors。日期类型字段日期字段的解析结果与字段自身的时区配置有关。以下三种配置对同一原始文本2023-01-18 22:22:22的解析结果为DateOnlyLocal(08:00)GMT2023-01-18 22:22:222023-01-18 22:22:222023-01-18 22:22:22转 JSON 之后为{ DateOnly: 2023-01-18T00:00:00.000Z, Local(08:00): 2023-01-18T14:22:22.000Z, GMT: 2023-01-18T22:22:22.000Z, }即仅日期DateOnly按00:00:00存为 UTC 零点本地时区08:00按东八区换算为 UTCGMT 则原样存储。实现上 date-value-parser.ts 支持YYYY-MM-DD纯日期字符串、dayjs 对象、Date对象以及 Excel 序列号通过getJsDateFromExcel转换字段的时区/日期显示配置取自field.options.uiSchema[x-component-props]。选择类型字段选项值value和选项标签label都可作为导入文案多个选项之间以半角逗号,、全角逗号或顿号、分隔。例如字段优先级的可选项定义如下选项值选项标签low低medium中high高导入数据优先级高low转 JSON 之后为[{ 优先级: high }, { 优先级: low }];可以看到标签高被映射为选项值high而low本身即选项值二者都解析成功。多个值的分隔规则源自 base-value-parser.ts 中的toArr(value, splitter)方法默认按正则/,||、/切分并去除首尾空白、过滤空项。中国行政区字段行政区中国行政区划字段支持以「省/市」路径形式导入地区1地区2北京市/市辖区天津市/市辖区转 JSON 之后为{ 地区1: [11,1101], 地区2: [12,1201] }即按行政区划层级解析为对应的行政区代码数组省代码、市代码。附件字段附件字段可直接填入文件的完整 URL系统会自动提取文件名与扩展名附件https://www.nocobase.com/images/logo.png转 JSON 之后为{ 附件: [ { filename: logo.png, title: logo.png, extname: .png, url: https://www.nocobase.com/images/logo.png } ] }关系类型字段关系字段支持通过目标表的展示字段来定位关联记录多条数据以逗号,或顿号、区分部门/名称分类/标题开发组分类1、分类2转 JSON 之后为{ 部门: [1], // 1 为部门名称为「开发组」的记录 ID 分类: [1,2], // 1,2 为分类标题为「分类1」和「分类2」的记录 ID }其中部门/名称表示按「部门」表的「名称」字段匹配分类/标题表示按「分类」表的「标题」字段匹配解析结果为匹配到的目标记录 ID 数组。服务端在 transform.ts 中按数据索引dataIndex对目标 Repository 执行findOne/find查询完成映射o2m一对多还支持以分号;分隔多个值。若关系字段的列配置带有选项枚举enum则会优先用标签匹配选项值后再查询。JSON 类型字段JSON 字段直接填入 JSON 字符串即可JSON1{key:value}转 JSON 之后为{ JSON: {key:value} }地图几何图形类型地图几何图形字段由 map 插件提供支持以下文本格式坐标以半角逗号分隔PointLinePolygonCircle1,2(1,2),(3,4)(1,2),(3,4),(1,2)1,2,3转 JSON 之后为{ Point: [1,2], Line: [[1,2], [3,4]], Polygon: [[1,2], [3,4], [1,2]], Circle: [1,2,3] }自定义导入格式注册自己的 ValueParser当内置解析器无法满足需求时例如自定义的数据类型或特殊的单元格格式可以通过db.registerFieldValueParsers()注册自定义的ValueParser将其绑定到某个字段类型上。示例import { BaseValueParser } from nocobase/database; class PointValueParser extends BaseValueParser { async setValue(value) { if (Array.isArray(value)) { this.value value; } else if (typeof value string) { this.value value.split(,); } else { this.errors.push(Value invalid); } } } const db new Database(); // typepoint 的字段导入时将通过 PointValueParser 解析数据 db.registerFieldValueParsers({ point: PointValueParser, });导入示例Point1,2转 JSON 之后为{ Point: [1,2] }需要说明的是该示例是文档中演示 API 用法的示意代码。作为对照map 插件在 plugin.ts 中通过相同的db.registerFieldValueParsers()机制为point、lineString、polygon、circle等地图字段类型注册了真实的解析器这也是上文「地图几何图形类型」能够按(1,2),(3,4)格式导入的原因。理解 ValueParser 基类自定义解析器应继承 base-value-parser.ts 中的BaseValueParser该基类提供field与ctx当前字段定义与上下文构造时注入value解析结果默认nullerrors: string[]错误收集数组解析失败时push错误信息即可被上层捕获trim(value)字符串去首尾空白toArr(value, splitter?)按分隔符默认/,||、/拆分多值文本返回去空白、过滤空项后的数组async setValue(value)解析入口默认直接赋值子类需重写。通常只需重写setValue方法并在内部维护this.value与this.errors。解析失败的错误信息会体现在导入结果中帮助用户定位模板中的异常单元格。操作配置项在界面搭建器中添加「导入」按钮后可在操作配置面板中完成以下设置配置可导入字段勾选参与导入的字段集合模板将按所选字段自动生成未勾选字段不会出现在模板与解析流程中联动规则动态显示/隐藏按钮详见 联动规则编辑按钮编辑按钮的标题、类型、图标详见 编辑按钮。从客户端代码看字段选项的构建与校验集中在 buildImportFieldOptions.ts 与 getOptionFields.ts下载模板的请求由 useDownloadXlsxTemplateAction.ts 发起执行导入则走 useImportAction.ts。插件同样提供了配套的 ACL 与测试覆盖acl.test.ts、xlsx-importer.test.ts、download-template.test.ts可据此了解导入权限与边界行为的预期。总结NocoBase 的导入操作将「模板生成、文件解析、字段映射、批量写入」整合为一个开箱即用的界面动作数字、布尔、日期、选择、行政区、附件、关系、JSON、地图几何图形等字段类型均有明确的文本书写规范与解析结果当内置规则不够用时可通过db.registerFieldValueParsers()注册继承自BaseValueParser的自定义解析器实现任意格式的导入扩展。理解这些转换规则既能保证导入数据的正确性也能在团队协作时向业务人员提供准确的填表说明。【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考