seismic-doc-parser

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
预览
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
预览
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
预览
is-admin="true"
accept="[txt]"
default-format="CustomTXT"
formats='[{"id":"CustomTXT","name":"TXT 通用格式","isStandard":false}]'
>
场景 2 非管理员权限（仅可调整列范围，不可编辑字段）
html
预览
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 同类型（标准 / 自定义）下格式名称不可重复，重复时保存会覆盖原有格式配置。