企业官网建设流程全解析

说个最近接到的实际需求：后台管理系统的附件列表功能，用户要求点一下就能直接预览，不想先把文件下载到本地再打开。附件类型也不复杂，主要就是txt、docx、xlsx、mp4这四种，格式看着常规，需求方却加了个硬性要求——纯前端实现，不能依赖后端转换服务。

接到这种需求，第一反应往往是“后端转一下不就行了”，但仔细想想，纯前端做其实完全可行，而且整条链路梳理清楚之后，对以后做类似功能非常有参考价值。这篇文章就围绕“vue中实现txt、docx、xlsx、mp4格式文件的纯前端预览”来展开。全文会从方案选型、核心代码、封装思路到踩坑经验逐步讲透，既适合正在找现成方案的朋友，也适合想理解底层实现原理、后续打算自己扩展更多格式的开发者。

1. 为什么能纯前端预览：四种格式背后的不同技术逻辑

先说结论：txt、docx、xlsx、mp4这四种格式虽然都叫“文件”，但它们的底层结构完全不同，预览方式也不能用同一套代码搞定。

txt的本质是一段纯文本字节流，核心工作是把二进制数据按正确的字符编码解码成字符串，然后渲染到页面上，技术上最轻量。

docx要复杂得多，它本质上是一个zip压缩包，内部包含一堆XML文件（word/document.xml、word/media/等），文档内容、样式、图片都分散在这些XML和资源文件里。要预览它，前端需要解压并解析XML，把Word的结构映射成HTML，这一步不是简单读字符串能解决的，必须借助专门的解析库。

xlsx同样是一个zip包，和工作簿结构打过交道的人都知道，它内部由多张工作表（sheet）组成，每个sheet包含行、列、单元格数据、合并单元格信息、列宽、日期格式等元数据。预览Excel的核心不是“渲染格式”，而是“解析数据模型”，然后把数据重新组织成表格来展示。

mp4是最特殊的一个，它属于媒体流格式，前端播放它依赖的就是video标签，浏览器内部已经实现了视频容器的解封装、解码、渲染全链路，开发者要处理的核心问题其实是“怎么把文件对象喂给video标签”，“大文件如何处理内存/性能问题”。

这四种格式的技术栈差异很大，所以方案选型上我一开始就决定分开处理，用一套统一的组件做入口，内部按文件类型做分支分发。下面这张表格是我最终选用的技术方案：

这套组合的优点是每个环节都选用了社区里最成熟或者最轻量的方案，不需要引一个庞大的“万能预览框架”。如果你愿意，后续还可以在同一个组件里继续扩展pdf、csv、图片等格式。

2. txt文件预览：FileReader只是起点，编码处理才是关键

txt是这四种文件中最容易让人掉以轻心的。很多教程只会给你一段“把文件读成字符串，塞进一个div”的代码，实际在真实业务环境里跑一遍就会发现：中文乱码了，或者几MB的日志文件把页面卡死了。

2.1 常规实现：FileReader读取文本内容

FileReader是浏览器提供的原生API，专门用来读取用户选择的File对象，也可以读取Blob。最简单的txt预览代码如下：

const reader = new FileReader(); reader.onload = function (e) { const text = e.target.result; document.getElementById('preview').innerText = text; }; reader.readAsText(file);

这段代码的问题在于，readAsText(file)默认按UTF-8编码解码。如果上传的txt文件是GBK、GB2312编码（国内很多老的业务系统、Windows记事本保存的文件都有这种情况），页面就会出现一堆乱码。

注意：真实项目里，txt文件的编码往往是不可控的。用户上传来的文件可能是UTF-8、GBK、GB18030，甚至BOM开头的UTF-8。直接按UTF-8读，遇到GBK文件就会展示乱码。

我当时就踩了这个坑，测试时用自己电脑上保存的UTF-8文件，一切正常，上线后运维部门上传了几个Windows下生成的GBK日志文件，反馈全是乱码，排查后才发现是编码问题。

2.2 加入编码检测：让文本内容稳定可读

解决乱码问题的核心方案是：先检测文件的编码，再按正确编码解码。前端做编码检测最常用的库是jschardet，它是Python中chardet库的JavaScript移植版本。

实现思路分两步：

• 第一步，用FileReader的readAsArrayBuffer把文件读成ArrayBuffer；
• 第二步，取ArrayBuffer前若干字节（通常取前几KB已经足够判断），交给jschardet检测编码；
• 第三步，用TextDecoder按检测到的编码来解码完整内容。

关键实现代码如下：

async function readTxt(file) { const buffer = await file .arrayBuffer() .then((res) => res); // 取前4000个字节判断编码 const sample = new Uint8Array(buffer.slice(0, 4000)); const detector = new jschardet.detect(sample); const encoding = detector.encoding || 'UTF-8'; const decoder = new TextDecoder(encoding); const content = decoder.decode(buffer); return content; }

TextDecoder是浏览器内置的编码解码器，支持的编码类型包括UTF-8、GBK、GB18030、Big5等。比自己去浏览器外手动实现一套解码逻辑要可靠得多。

提示：jschardet虽然检测准确率不错，但并不能保证100%识别正确。稳妥的做法是检测完成后，用解码结果再做一次合法性校验——如果解码出来的字符串中包含大量U+FFFD替换字符，说明编码判断可能有问题，可以回退到UTF-8或其他常见编码再试一次。

2.3 大文件处理和长文本渲染

日志类txt文件动辄几MB甚至几十MB，如果一次性读取全文再渲染，主线程会卡顿，页面就会出现“长时间白屏”或者“点击无响应”。我处理的方案是分片读取加分段渲染。

分片读取的核心是Blob的slice方法：

async function readTxtByChunk(file, chunkSize = 1024 * 1024) { const totalSize = file.size; let offset = 0; let result = ''; while (offset < totalSize) { const chunk = file.slice(offset, offset + chunkSize); const buffer = await chunk.arrayBuffer(); const decoder = new TextDecoder('utf-8'); result += decoder.decode(buffer, { stream: true }); offset += chunkSize; // 做一次渲染节流，避免一次性渲染过大内容 if (result.length > 1024 * 200) { renderPreview(result); result = ''; } } renderPreview(result || ''); }

这里有一个小细节：TextDecoder.decode(buffer, { stream: true })中的stream参数表示当前是流式解码，因为一个字符的字节可能横跨两个分片边界，传stream可以让解码器在内部保留未结束的字节序列，等下一段数据到来时再继续解码。

渲染长文本时也有讲究，直接使用innerHTML会有XSS风险，应该用innerText或textContent。同时建议给预览容器加样式white-space: pre-wrap，因为txt文本中的换行、连续空格都必须原样展示。

3. docx文件预览：用mammoth.js解析Word文档

docx的预览是最难实现的部分之一，如果没有现成库，自己解zip、解析XML、处理图片，工作量相当惊人。我在这里选用mammoth.js，主要看中它能把Word文档转换为干净的HTML，并且在转换英文文档时效果很好，同时探测文档结构层级的能力也比较稳定。

3.1 mammoth.js的基本使用

mammoth.js的使用方式也很简单，它接收一个ArrayBuffer，返回转换后的HTML字符串：

import mammoth from 'mammoth/mammoth.browser'; async function previewDocx(arrayBuffer) { const result = await mammoth.convertToHtml({ arrayBuffer }); const html = result.value; const messages = result.messages; // messages里可能包含警告信息，比如“文档包含无法转换的样式” document.getElementById('docx-preview').innerHTML = html; }

convertToHtml返回的对象有两个关键属性：value是转换后的HTML字符串，messages中存放的是转换过程中产生的警告或错误信息。实际开发中我建议把messages打印出来看一下，这样能很快定位文档中哪些部分没有转换成功。

mammoth内部做了什么？简单来说，它读取docx这个zip压缩包，找到word/document.xml，解析其中的段落、表格、图片、标题等节点，映射成对应的HTML标签。它不会把Word的完整样式细节100%还原出来（比如复杂的页眉页脚、带格式的编号列表），但在80%以上的普通办公文档场景下表现都不错。

3.2 样式自定义：在转换时控制输出

mammoth允许你通过styleMap参数自定义元素映射关系。比如我想让文档中的一级标题显示为蓝色、加16px字号，可以这样配置：

const customStyleMap = [ { element: 'h1', style: 'color: #1e88e5; font-size: 24px; font-weight: 600; line-height: 1.4;', }, { element: 'h2', style: 'color: #333; font-size: 20px; font-weight: 600;', }, { element: 'p', style: 'font-size: 14px; line-height: 1.8; color: #333;', }, ]; const result = await mammoth.convertToHtml( { arrayBuffer }, { styleMap: customStyleMap }, );

如果用默认转换结果觉得样式太朴素，也可以不传styleMap，直接给渲染的容器写一套CSS去覆盖。比如：

.docx-preview-container h1 { font-size: 24px; color: #2c3e50; border-bottom: 1px solid #eee; padding-bottom: 8px; } .docx-preview-container table { border-collapse: collapse; width: 100%; } .docx-preview-container table td, .docx-preview-container table th { border: 1px solid #ddd; padding: 6px 10px; }

用CSS覆盖的方式更灵活，不用再去维护styleMap配置，推荐优先用这种方式。

3.3 图片无法显示的问题

docx中如果插入了图片，mammoth默认会把图片转换为base64格式的data URL，直接嵌入HTML中。这样做好处是图片不会丢失，坏处是如果文档里图片体积很大（比如几MB的高清截图），生成的HTML字符串会极其膨胀，预览的时候内存占用会明显升高。

如果希望图片走单独的URL加载，可以通过convertImage选项自定义图片转换逻辑：

const options = { convertImage: (image) => { return image.read('base64').then((base64) => { return { src: `data:${image.contentType};base64,${base64}`, }; }); }, };

如果公司有自己的文件系统，也可以把图片提取出来，上传到OSS，然后返回外链。不过这块和后端有耦合，纯前端场景下直接用base64即可。

踩坑提示：如果docx里的图片太多，mammoth的转换性能会明显下降，建议在组件中加上Loading状态，并在大文件转换前给出提示，避免用户以为是页面卡死了。

4. xlsx文件预览：SheetJS解析数据模型，自己渲染表格

Excel的预览一开始我想得比较简单：解析出来数据，用elempi?24mpi?24一个table展示不就行了吗？实际做的时候才发现，日期显示不对、合并单元格错位、列宽乱掉、大数据量渲染卡顿，问题一个接一个。

4.1 SheetJS的基本解析流程

SheetJS又叫xlsx库，是目前前端处理Excel最主流的库。读取文件的流程如下：

import * as XLSX from 'xlsx'; async function previewXlsx(arrayBuffer) { const workbook = XLSX.read(arrayBuffer, { type: 'array' }); // 读取第一个工作表 const firstSheetName = workbook.SheetNames[0]; const worksheet = workbook.Sheets[firstSheetName]; // 直接转成JSON数组 const jsonData = XLSX.utils.sheet_to_json(worksheet, { header: 1, defval: '' }); renderTable(jsonData); }

XLSX.read的第一个参数是ArrayBuffer，type设为'array'，它会解析整个工作簿。workbook.Sheets中存储的是工作表对象，每个sheet包含单元格数据和元信息。sheet_to_json用于把sheet转换成二维数组，header: 1表示每一行作为数组返回，defval: ''表示空单元格填充空字符串。

拿到二维数组之后，遍历即可生成HTML表格：

function renderTable(rows) { let html = '<table>'; for (let i = 0; i < rows.length; i++) { html += '<tr>'; for (let j = 0; j < rows[i].length; j++) { html += `<td>${rows[i][j]}</td>`; } html += '</tr>'; } html += '</table>'; document.getElementById('excel-preview').innerHTML = html; }

不过直接用sheet_to_json拿到的数据有几个明显问题：单元格内部的富文本（rich text）只取到拼接后的字符串，日期会变成一长串数字，合并单元格信息完全丢失。所以生产环境不能用这种“一把梭”的转换方式。

4.2 合并单元格和列宽的处理

更可控的做法是遍历原始单元格对象，自己读取每个单元格的value、type、合并范围、列宽信息。

SheetJS中，每个sheet有一个!merges属性，存储了所有合并单元格的范围；!cols属性存储列宽信息。遍历方式如下：

function buildHtmlWithMeta(worksheet) { const range = XLSX.utils.decode_range(worksheet['!ref']); // 数据范围 const merges = worksheet['!merges'] || []; const cols = worksheet['!cols'] || []; // 构建合并映射表 const mergeMap = {}; merges.forEach((merge) => { for (let r = merge.s.r; r <= merge.e.r; r++) { for (let c = merge.s.c; c <= merge.e.c; c++) { if (!mergeMap[r]) mergeMap[r] = {}; mergeMap[r][c] = { isStart: r === merge.s.r && c === merge.s.c, rowspan: merge.e.r - merge.s.r + 1, colspan: merge.e.c - merge.s.c + 1, }; } } }); let html = '<table>'; for (let r = 0; r < range.e.r + 1; r++) { html += '<tr>'; for (let c = 0; c < range.e.c + 1; c++) { const mergeInfo = mergeMap[r]?.[c]; if (mergeInfo && !mergeInfo.isStart) { // 非合并起点，跳过 continue; } const cell = worksheet[XLSX.utils.encode_cell({ r, c })]; const value = cell ? cell.v : ''; const tdAttrs = []; if (mergeInfo) { if (mergeInfo.rowspan > 1) tdAttrs.push(`rowspan="${mergeInfo.rowspan}"`); if (mergeInfo.colspan > 1) tdAttrs.push(`colspan="${mergeInfo.colspan}"`); } html += `<td ${tdAttrs.join(' ')}>${escapeHtml(value)}</td>`; } html += '</tr>'; } html += '</table>'; return html; }

这段代码的核心逻辑是：先根据!merges构建合并关系映射表，遍历单元格时，如果当前单元格是合并区域的起点，就输出td并携带rowspan/colspan属性；如果不是起点就跳过，交给起点单元格占位。

列宽!cols可以转换成CSS样式：

const colStyles = cols .map((col, index) => { return `col:nth-child(${index + 1}) { width: ${col.wch ? col.wch * 7 + 'px' : 'auto'} }`; }) .join('\n');

4.3 日期类型数据的序列号转换

Excel中的日期在内部是以数字序列号存储的，比如2023-06-01真实存储的可能是45078（从1900年1月1日起计算的天数）。直接用单元格的v属性拿到的就是这种数字，必须做转换。

SheetJS提供了一个工具方法：

function formatCellValue(cell) { if (!cell) return ''; if (cell.t === 'd') { // 已经是Date类型 return formatDate(cell.v); } if (cell.t === 'n' && cell.z && /y|m|d|h|s/i.test(cell.z)) { // 数字类型，但格式是日期格式 const date = XLSX.SSF.parse_date_code(cell.v); return `${date.y}-${pad(date.m)}-${pad(date.d)}`; } return cell.v; }

检查单元格的z属性（格式字符串）可以判断它是不是日期格式，y、m、d、h、s分别对应年月日时分秒。如果z中出现了这些字母，说明单元格是日期格式，需要把序列号转成日期对象。

4.4 大数据量表格的性能处理

一个几百KB的小Excel渲染上万个单元格时，DOM节点数量会爆炸，页面明显卡顿。处理思路有几种：

• 虚拟滚动，只渲染可视区域内的行，但实现成本较高；
• 分页渲染，每页显示一二百行，用户手动翻页；
• 限制最大预览行数，超出部分提示用户“仅显示前1000行”。

个人项目里我采用了“分页渲染+最大行数限制”的组合方案，既保证了交互体验，又避免了引入虚拟滚动库带来的复杂度。用户真的要预览超大Excel的时候，通常也只是想看前几十行了解数据结构，很少真的去滚动上万行。

5. mp4文件预览：video标签背后的内存与兼容性问题

mp4在四种格式中是最“特殊”的，因为它不需要解析数据模型，浏览器原生video标签就能搞定，但处理不好内存和兼容性，体验会非常差。

5.1 用ObjectURL而不是DataURL

拿到mp4文件后，最常见的方式有两种：FileReader.readAsDataURL得到base64地址，或者URL.createObjectURL生成一个临时对象URL。

我个人强烈推荐后者。原因是base64字符串比原始二进制体积大33%，一个50MB的视频转成base64后大概67MB，而createObjectURL创建的URL本质上只是指向浏览器内部二进制数据的一个引用，不占额外的JS字符串内存。

function createVideoPreview(file) { const objectURL = URL.createObjectURL(file); const video = document.createElement('video'); video.src = objectURL; video.controls = true; video.autoplay = false; document.getElementById('video-preview').appendChild(video); // 用完后释放 video.onloadeddata = () => { // 此时已经可以播放，如果需要释放URL，等组件销毁时再调用revoke }; }

组件销毁时的清理很重要：

beforeUnmount() { if (this.objectURL) { URL.revokeObjectURL(this.objectURL); } }

如果不调revokeObjectURL，对象URL会一直占用内存，频繁预览不同视频会导致内存泄漏，页面最后越来越卡。这一点在长列表场景中尤其明显，很多人预览几个视频之后内存飙到几个GB，多半就是漏掉了这一步。

5.2 直接URL地址时的兼容性

如果mp4不是本地文件，而是服务器URL，直接给video标签赋值src即可。但有几个兼容性问题需要提前知道：

• mp4容器内编码一般是H.264，这种格式在绝大多数浏览器上都能直接播放；
• 如果mp4内部的视频编码是HEVC（H.265），Chrome默认不支持，Firefox也不支持，页面会黑屏或者提示“没有支持的视频格式”；
• 如果服务器返回的Content-Type不正确（如application/octet-stream），部分浏览器也可能拒绝播放。

处理思路是：在video标签的error事件中捕获错误，给用户一个明确的提示，而不是一直黑屏。

video.onerror = () => { showError('该视频编码格式当前浏览器不支持，请尝试下载后播放'); };

5.3 大视频播放的体验优化

大视频文件（比如超过1GB的MP4）如果直接给video标签赋值URL，用户等待时间会很长，因为浏览器需要先下载一部分数据才能开始播放。有两个优化体验的办法：设置preload="metadata"让浏览器只加载元数据，快速得到视频时长和首帧画面；或者在服务器端开启Range请求支持，让浏览器可以分段拉取数据，实现“边下边播”。

<video :src="videoUrl" controls preload="metadata" style="max-width: 100%; max-height: 80vh" ></video>

如果业务场景需要更高阶的播放体验，比如自定义进度条、弹幕、倍速菜单，建议直接集成成熟的播放器库如plyr、video.js，但纯预览场景下video原生控件够用了。

6. 封装一个统一的FilePreview组件

上面四种格式的预览逻辑各自独立，但落到业务中是同一个入口：用户点击附件名，弹窗预览。因此封装一个通用的FilePreview组件很有必要，对外暴露文件对象或文件URL，内部自动按类型分流。

6.1 组件结构设计

组件对外API尽可能简单，调用方只需要传文件信息即可。我用Vue 3的Composition API写的骨架如下：

<template> <div class="file-preview"> <div v-if="loading" class="file-preview__loading">文件加载中...</div> <div v-else-if="error" class="file-preview__error">{{ error }}</div> <div v-else class="file-preview__content"> <!-- 按类型渲染 --> <pre v-if="type === 'txt'" class="file-preview__txt">{{ txtContent }}</pre> <div v-else-if="type === 'docx'" class="file-preview__docx" v-html="docxHtml"></div> <div v-else-if="type === 'xlsx'" class="file-preview__xlsx" v-html="xlsxHtml"></div> <video v-else-if="type === 'mp4'" :src="videoUrl" controls preload="metadata" ></video> </div> </div> </template>

组件的props设计成这样：

const props = defineProps({ // 支持传File对象或者文件URL file: { type: File, default: null }, fileUrl: { type: String, default: '' }, fileType: { type: String, required: true }, // 'txt' | 'docx' | 'xlsx' | 'mp4' });

加载逻辑根据文件类型分发：

const loadFile = async () => { loading.value = true; error.value = ''; try { if (props.fileType === 'txt') { txtContent.value = await readTxt(props.file); } else if (props.fileType === 'docx') { const buffer = await props.file.arrayBuffer(); docxHtml.value = await convertDocx(buffer); } else if (props.fileType === 'xlsx') { const buffer = await props.file.arrayBuffer(); xlsxHtml.value = await convertXlsx(buffer); } else if (props.fileType === 'mp4') { videoUrl.value = URL.createObjectURL(props.file); } } catch (e) { error.value = '文件解析失败：' + e.message; } finally { loading.value = false; } };

6.2 大插件动态引入，优化首屏体积

mammoth.js和xlsx库的体积都不小。mammoth浏览器版大约几百KB，xlsx就更大了，如果这些库都在主包里，首屏加载时间会明显变长。建议通过动态import按需加载，只有真正点击预览对应格式文件时才拉取相关库：

const convertDocx = async (buffer) => { const mammoth = await import('mammoth/mammoth.browser'); const result = await mammoth.convertToHtml({ arrayBuffer: buffer }); return result.value; }; const convertXlsx = async (buffer) => { const XLSX = await import('xlsx'); return buildXlsxHtml(XLSX, buffer); };

jschardet同理，也只有预览txt文件时需要。动态import配合webpack或Vite的代码分割，能把预览组件对首屏的影响降到最低。

6.3 弹窗场景下的组件复用

实际业务中预览通常放在弹窗（dialog）组件里。这里有一个容易踩的坑：弹窗关闭时，子组件并没有销毁（取决于是否使用v-if），mp4的视频流、docx的HTML字符串这些数据仍然占用内存。建议在弹窗关闭事件里通过v-if销毁预览组件，或者暴露一个destroy方法清理资源。

<template> <el-dialog v-model="visible" title="文件预览" width="80%"> <FilePreview v-if="visible" :file="currentFile" :file-type="currentFileType" /> </el-dialog> </template>

用v-if绑定弹窗的可见状态，关闭即销毁，组件的beforeUnmount钩子会自动触发，再配合之前提到的revokeObjectURL清理，内存管理就闭环了。

7. 实际交付中踩过的坑和性能建议

功能交付给业务方使用之后，陆陆续续遇到一些在本地测试时完全没暴露的问题，这里挑几个处理过程比较典型的记录下来。

7.1 txt文件编码检测失败的兜底方案

jschardet虽然强大，但也会出错。遇到过一个情况：一个UTF-8编码的文件被误判为ISO-8859-1，解码后所有中文全部变成乱码。我的兜底策略是：解码后统计字符串中U+FFFD替换字符的数量，如果比例超过阈值（比如千分之一），就回退到UTF-8重新解码一次。

function decodeWithFallback(buffer, encoding) { const decoder = new TextDecoder(encoding); const result = decoder.decode(buffer); const badCount = result.split('\uFFFD').length - 1; if (badCount / result.length > 0.001 && encoding !== 'UTF-8') { return new TextDecoder('UTF-8').decode(buffer); } return result; }

实际效果不错，虽然不能覆盖所有边界情况，但比单一编码判断稳妥得多。

7.2 docx预览的表格宽度溢出

mammoth转换docx中的表格时，有时候会生成比较宽的表格，导致预览区域横向溢出，页面出现横向滚动条。处理方式是给预览容器加上overflow-x: auto，并对表格设置最大宽度：

.docx-preview-container { overflow-x: auto; } .docx-preview-container table { max-width: 100%; width: auto; }

7.3 xlsx预览时富文本单元格只显示一部分

SheetJS读取富文本单元格时，v字段默认只保留纯文本拼接结果。一开始我没注意，后来发现有的单元格明明显示为一段文字带一个换行，预览出来却丢了一半内容。检查后确认是换行符在解析中丢失了，需要手动处理单元格的r属性（富文本对象），把各段的t字段拼接起来。

function getCellDisplayValue(cell) { if (!cell) return ''; if (cell.w) return cell.w; // 优先使用格式化后的展示值 if (cell.r) { // 富文本，遍历run对象拼接 return cell.r.t .map((run) => run.t) .join(''); } return cell.v; }

cell.w是SheetJS计算好的格式化显示值，大部分时候比手动拼v更准确，优先使用它。

7.4 mp4视频编码兼容性的兜底提示

生产环境上传的视频五花八门，有手机录制的HEVC格式，有电脑录制的H.264，甚至还有带Alpha通道的MOV改名成mp4的。HEVC格式在Chrome上无法播放的问题没法在前端解决，只能在体验层做兜底：video的error事件触发时，显示“该视频编码当前浏览器不支持，建议下载后用本地播放器打开”。

7.5 性能层面的三个建议

从最终灰度到稳定运行，我总结出三条对性能最有帮助的建议：

• 资源按需加载，mammoth、xlsx、jschardet全部动态import，代码分割后主包体积明显下降；
• 大数据量预览做行数限制，Excel预览超过2000行就分页，txt渲染超过3000行就截断提示，避免DOM节点过多导致卡顿；
• 及时清理对象URL和事件监听，组件卸载时统一清理，防止内存泄漏。

我个人的体会是，纯前端预览这四种格式，难点其实不在于API调用本身，而在于“格式背后的数据模型完全不同”，以及“各种边界情况几乎不可穷尽”。只要把组件设计成可扩展的分发结构，后续再加csv、pdf、png等格式都会非常顺。组件内部加一个分支，对应写一个解析函数，这就够了。