FileParser 组件使用文档 组件介绍 file-parser 是基于 Web Component 开发的文件解析与自定义格式配置组件，支持 TXT/CSV/Excel（xlsx/xls）文件解析、字段列范围配置、数据类型定义、格式保存与复用等核心功能，适用于需要自定义文件解析规则的业务场景。 快速开始 2.1 引入方式 方式 1 直接引入脚本 引入组件脚本： html 预览

在页面中使用组件： html 预览 方式 2 模块化引入（ES Module） javascript 运行 import './path/to/file-parser.js' 2.2 基础使用 html 预览 <file-parser id="fileParser" formats='[{"id":"SP210.R","name":"SP210.R","isStandard":true,"doc_format":{"bConfig":[{"index":1,"name":"INDEX","startCell":18,"endCell":25,"type":"double"}]}}]' default-format="SP210.R" is-admin="true" accept="[txt,csv,excel]"

外部可配置参数（Properties） 参数名 类型 默认值 说明 formats Array [] 外部传入的格式列表，用于格式选择下拉框。每个格式项结构：{id: String, // 格式唯一标识 name: String, // 格式显示名称 isStandard: Boolean, // 是否为标准格式（区分标准 / 自定义分类） doc_format: Object // 可选，格式对应的字段配置，包含 bConfig} defaultFormat String 空字符串 默认选中的格式名称 / ID，组件初始化时会自动匹配 formats 中对应项（支持匹配 id 或 name） isAdmin Boolean false 是否开启管理员权限：true：可编辑字段名称、数据类型、经纬度类型，可新增 / 删除字段，可保存格式；false：仅可编辑起始列 / 终止列，其余编辑功能禁用 accept String "[txt,csv,excel]" 文件类型限制，格式为数组字符串，支持的取值：基础类型：txt、csv、excel（excel 包含 xlsx/xls）；示例：仅允许 TXT："[txt]"；允许 CSV 和 Excel："[csv,excel]" onSave Function undefined 保存按钮点击时的回调函数，参数为解析后的字段信息（同 saveAs 事件的 detail） 组件事件（Events） 组件会派发以下自定义事件，外部可通过 addEventListener 监听 4.1 saveAs 触发时机：点击组件 “确定” 按钮时 事件参数（e.detail）： javascript 运行 { fileType: String, // 文件类型（txt/csv/xlsx/xls） fileName: String, // 选中的文件名 fileContent: File, // 选中的文件对象 bConfig: Array, // 配置的字段列表 startRow: Number/String, // 起始行 endRow: Number/String, // 终止行 validChar: String, // 有效行标识符 invalidChar: String, // 无效行标识符 splitParams: Object, // 分割参数（仅 TXT 文件有效） format: String // 当前选中的格式 ID } 4.2 returnFormatData 触发时机：点击 “保存当前格式” 按钮并确认时 事件参数（e.detail）： javascript 运行 { formatName: String, // 保存的格式名称 isStandard: Boolean, // 格式类型（标准 / 自定义） bConfig: Array, // 字段配置列表 startRow: Number/String, // 起始行 endRow: Number/String, // 终止行 invalidChar: String, // 无效行标识 validChar: String, // 有效行标识 splitParams: Object // 分割参数 } 核心数据结构说明 5.1 bConfig（字段配置项） javascript 运行 { index: Number, // 序号（组件自动维护） name: String, // 字段名称 startCell: Number, // 起始列（TXT 为字符索引，表格为列号，均从 0/1 开始） endCell: Number, // 终止列 type: String, // 数据类型，可选值：int8/int16/int32/float/double/string/date/boolean isCoordinate: String // 经纬度类型，可选值：longitude/latitude/elve（为空则无） } 5.2 splitParams（分割参数） javascript 运行 { splitType: String, // 分割类型：fixed（固定列）/char（字符分隔） useTab: Boolean, // 是否使用 Tab 分隔 useSpace: Boolean, // 是否使用空格分隔 useSemicolon: Boolean, // 是否使用分号分隔 useComma: Boolean, // 是否使用逗号分隔 useContinuous: Boolean, // 连续分隔符当作一个 otherSeparator: String, // 其他自定义分隔符 startToEnd: Boolean // 是否解析起始行到最后一行 } 完整使用流程 步骤 1 引入组件 html 预览

步骤 2 配置组件参数 html 预览 <file-parser id="myFileParser" formats='[ {"id":"SP210.R","name":"SP210.R","isStandard":true,"doc_format":{"bConfig":[{"index":1,"name":"INDEX","startCell":18,"endCell":25,"type":"double"}]}}, {"id":"CustomFormat","name":"自定义格式","isStandard":false} ]' default-format="SP210.R" is-admin="true" accept="[txt,excel]"

步骤 3 监听组件事件 / 配置回调 javascript 运行 const parser = document.querySelector('#myFileParser'); // 方式 1 使用 onSave 回调 parser.onSave = (data) => { console.log('保存的解析配置：', data); // 业务逻辑：提交配置到后端 / 本地存储等 }; // 方式 2 监听 saveAs 事件 parser.addEventListener('saveAs', (e) => { console.log('解析结果详情：', e.detail); }); // 监听格式保存事件 parser.addEventListener('returnFormatData', (e) => { console.log('保存的格式数据：', e.detail); // 业务逻辑：保存格式到后端 }); 步骤 4 用户交互操作 点击组件的 “自定义格式” 按钮，打开解析弹框； 点击 “浏览选择文件”，选择 TXT/CSV/Excel 文件； 配置标题行（默认 1 行，可修改），组件自动解析生成字段配置； （管理员权限）编辑字段名称、数据类型、经纬度类型，或新增 / 删除字段； 拖动 A 区红色标记线，调整字段的起始 / 终止列（或手动输入）； （可选）点击 “分割参数设置”，配置 TXT 文件的分隔符规则； 选择格式类型（标准 / 自定义）和格式名称，点击 “保存当前格式” 可保存配置； 点击 “确定” 按钮，触发保存回调 / 事件，获取解析配置。 常见使用场景示例 场景 1 基础使用（管理员权限，仅解析 TXT 文件） html 预览 <file-parser is-admin="true" accept="[txt]" default-format="CustomTXT" formats='[{"id":"CustomTXT","name":"TXT 通用格式","isStandard":false}]'

场景 2 非管理员权限（仅可调整列范围，不可编辑字段） html 预览 <file-parser is-admin="false" accept="[excel]" default-format="ExcelStandard" formats='[{"id":"ExcelStandard","name":"Excel 标准格式","isStandard":true}]'

场景 3 自定义格式列表并监听保存事件 javascript 运行 // 初始化格式列表 const formatList = [ { id: "SP300.TXT", name: "SP300.TXT", isStandard: true, doc_format: { bConfig: [ {index: 1, name: 'ID', startCell: 0, endCell: 5, type: 'int'}, { index: 2, name: 'Name', startCell: 6, endCell: 20, type: 'string' } ] } } ]; // 设置组件格式列表 const parser = document.querySelector('#myFileParser'); parser.formats = formatList; // 监听保存事件 parser.addEventListener('saveAs', (e) => { // 提交到后端 fetch('/api/save-parser-config', { method: 'POST', body: JSON.stringify(e.detail), headers: { 'Content-Type': 'application/json' } }); }); 注意事项 文件类型限制：accept 参数仅限制文件选择框的可选类型，组件内部会二次校验文件扩展名，确保匹配； 管理员权限：isAdmin=false 时，字段名称、数据类型、经纬度类型、新增 / 删除字段、保存格式等功能会被禁用； 格式匹配规则：defaultFormat 会优先匹配格式列表中项的 id 或 name（不区分大小写），无匹配时选中第一个格式； 标题行与起始行：起始行默认等于 “标题行 + 1”，修改标题行时起始行会自动同步； TXT 文件列索引：TXT 文件的起始 / 终止列为字符索引（从 0 开始），表格文件（CSV/Excel）为列号（从 1 开始）； 事件冒泡：组件派发的事件开启了 bubbles: true 和 composed: true，可在父元素上监听； 兼容性：基于 Web Component 开发，需确保浏览器支持（现代浏览器均支持，IE 不支持）。 常见问题 Q1 默认格式无法自动选中？ A1 检查 defaultFormat 的值是否与 formats 中项的 id/name 完全匹配（去除首尾空格），或确认 formats 已正确传入（建议在组件挂载后再赋值）。 Q2 TXT 文件红色标记线无法拖动？ A2 确保已选中 B 区的字段序号（点击序号激活标记线），且文件类型为 TXT。 Q3 Excel 合并单元格不显示？ A3 组件已兼容 Excel 合并单元格解析，合并单元格会自动渲染为跨行 / 跨列样式，隐藏合并区域的子单元格。 Q4 保存格式时提示名称重复？ A4 同类型（标准 / 自定义）下格式名称不可重复，重复时保存会覆盖原有格式配置。