PDF 生成与本地文件操作：浏览器原生文件系统 API 实战

在传统的 Web 应用中，生成并下载 PDF 通常需要后端服务的支持------前端发送 HTML 内容，后端使用 Puppeteer 或wkhtmltopdf 渲染后返回文件流。但在现代浏览器中，我们可以借助 html2pdf.js 与 File System Access API 构建一个纯前端、零服务端的 PDF 生成与保存方案，甚至可以让用户通过原生对话框自主选择保存路径。

本文将详细介绍如何：

在浏览器中将包含图片的 DOM 元素转换为高质量 PDF
使用 showSaveFilePicker 弹出"另存为"对话框，让用户自定义保存位置
顺带掌握 showOpenFilePicker，实现浏览器端的本地文件读取

技术架构概览

核心优势：

零服务端成本：无需后端渲染服务，减轻服务器压力
隐私安全：敏感数据在本地处理，不上传云端
原生体验：使用操作系统级文件对话框，符合用户直觉
高清输出 ：通过 html2canvas 的 scale 参数实现 2x/3x 高清渲染

第一部分：生成图文 PDF

1.1 基础环境搭建

我们使用 html2pdf.js，它集成了 html2canvas（DOM 转 Canvas）和 jsPDF（Canvas 转 PDF）：

html 复制代码

<script src="https://cdnjs.cloudflare.com/ajax/libs/html2pdf.js/0.10.1/html2pdf.bundle.min.js"></script>

1.2 处理图片跨域与高清渲染

这是最容易踩坑的部分。现代浏览器对 Canvas 的污染策略（Taint Policy） 非常严格，如果图片跨域且未设置 CORS，Canvas 会被标记为污染，无法调用 toDataURL() 导出。

解决方案：

Base64 内联图片：彻底规避跨域问题（推荐用于 Logo、图标等固定资源）
配置 html2canvas 参数 ：allowTaint: true 配合 useCORS: true

javascript 复制代码

const opt = {
    margin: 10,
    filename: 'document.pdf',
    image: { type: 'jpeg', quality: 0.98 },
    html2canvas: { 
        scale: 2,                // 高清关键：2倍像素比
        useCORS: true,           // 尝试跨域加载图片
        allowTaint: true,        // 允许污染 Canvas（对 Base64 必需）
        backgroundColor: '#fff'  // 避免透明背景变黑
    },
    jsPDF: { unit: 'mm', format: 'a4', orientation: 'portrait' }
};

1.3 生成 PDF Blob

不同于直接调用 .save()（自动下载到默认路径），我们需要先获取 Blob 对象，以便后续传给文件系统 API：

javascript 复制代码

const element = document.getElementById('content');
const worker = html2pdf().set(opt).from(element);

// 关键：使用 output('blob') 获取二进制数据，而非直接下载
const pdfBlob = await worker.output('blob');

第二部分：弹出保存对话框（核心）

这是本文的核心价值所在。传统的 anchor.download 或 jsPDF.save() 只能触发浏览器默认下载行为，用户无法选择保存路径（除非修改浏览器全局设置）。File System Access API 提供了 showSaveFilePicker，允许 Web 应用调用原生"另存为"对话框。

2.1 基本使用流程

javascript 复制代码

async function savePDFWithDialog(pdfBlob) {
    try {
        // 1. 弹出系统级"另存为"对话框
        const handle = await window.showSaveFilePicker({
            suggestedName: '煤矿选型报告.pdf',      // 默认文件名
            types: [{
                description: 'PDF 文档',
                accept: { 'application/pdf': ['.pdf'] }
            }],
            excludeAcceptAllOption: true             // 隐藏"所有文件"选项
        });

        // 2. 创建可写流（WritableStream）
        const writable = await handle.createWritable();
        
        // 3. 将 PDF Blob 写入文件
        await writable.write(pdfBlob);
        
        // 4. 关闭流（必须！否则文件句柄不释放）
        await writable.close();

        console.log('文件已保存至：', handle.name);
        
    } catch (err) {
        // 处理用户取消（AbortError）或其他错误
        if (err.name === 'AbortError') {
            console.log('用户取消了保存');
        } else {
            console.error('保存失败:', err);
        }
    }
}

2.2 安全限制与开发环境配置

⚠️ 重要 ：showSaveFilePicker 属于安全上下文受限 API，必须在以下环境运行：

https:// 生产环境
http://localhost / http://127.0.0.1 开发环境
禁止：直接双击打开 .html 文件（file:// 协议）

快速启动本地服务器测试：

复制代码

# Python 3
python -m http.server 8000

# Node.js
npx serve .

# VS Code 用户
# 安装 "Live Server" 插件，点击 "Go Live"

访问 http://localhost:8000 即可正常调用文件对话框。

第三部分：打开本地文件（额外技能）

既然已经引入了 File System Access API，不妨顺带掌握文件读取能力。使用 showOpenFilePicker 可以替代传统的 <input type="file">，提供更原生的文件选择体验，且支持持久化权限（用户授权后，下次打开可自动读取，无需重复选择）。

3.1 基础文件读取

javascript 复制代码

async function openLocalFile() {
    try {
        // 弹出"打开文件"对话框
        const [handle] = await window.showOpenFilePicker({
            multiple: false,                        // 单选
            types: [
                {
                    description: 'PDF 文档',
                    accept: { 'application/pdf': ['.pdf'] }
                },
                {
                    description: '图片',
                    accept: { 'image/*': ['.png', '.jpg', '.jpeg'] }
                }
            ]
        });

        // 获取文件对象
        const file = await handle.getFile();
        const content = await file.text();           // 文本读取
        // 或 const arrayBuffer = await file.arrayBuffer(); // 二进制读取
        
        console.log('文件名:', file.name);
        console.log('文件大小:', file.size);
        console.log('内容:', content.substring(0, 100));
        
    } catch (err) {
        if (err.name === 'AbortError') return;
        console.error('读取失败:', err);
    }
}

3.2 持久化句柄（高级应用）

File System Access API 的强大之处在于可以保存文件句柄到 IndexedDB，实现"最近打开的文件"或"工作区"功能：

javascript 复制代码

// 保存句柄到 IndexedDB
const db = await openDB('FileDB', 1);
await db.put('handles', fileHandle, 'lastOpened');

// 下次启动时恢复权限并直接读取
const savedHandle = await db.get('handles', 'lastOpened');
if (savedHandle) {
    const permission = await savedHandle.queryPermission({ mode: 'read' });
    if (permission === 'granted') {
        const file = await savedHandle.getFile();
        // 直接读取，无需再次弹窗！
    }
}

完整可运行代码

将以下代码保存为 index.html，通过本地服务器访问：

html 复制代码

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>浏览器原生 PDF 生成与文件操作</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/html2pdf.js/0.10.1/html2pdf.bundle.min.js"></script>
    <style>
        body { 
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; 
            max-width: 800px; 
            margin: 0 auto; 
            padding: 20px;
            background: #f5f5f5;
        }
        .container { background: white; padding: 30px; border-radius: 12px; box-shadow: 0 2px 8px rgba(0,0,0,0.1); }
        button { 
            padding: 12px 24px; 
            margin: 8px 8px 8px 0;
            font-size: 14px; 
            border: none; 
            border-radius: 6px; 
            cursor: pointer;
            transition: all 0.3s;
            font-weight: 500;
        }
        .btn-primary { background: #007bff; color: white; }
        .btn-primary:hover { background: #0056b3; transform: translateY(-1px); }
        .btn-secondary { background: #6c757d; color: white; }
        .btn-secondary:hover { background: #545b62; }
        
        #pdfContent { 
            margin: 20px 0; 
            padding: 30px; 
            border: 2px dashed #dee2e6; 
            background: #f8f9fa;
            border-radius: 8px;
        }
        .file-info { margin-top: 15px; padding: 15px; background: #e9ecef; border-radius: 6px; font-family: monospace; font-size: 13px; }
        .warning { background: #fff3cd; border-left: 4px solid #ffc107; padding: 12px; margin-bottom: 20px; border-radius: 4px; font-size: 14px; }
    </style>
</head>
<body>

<div class="container">
    <div class="warning">
        ⚠️ <strong>环境要求：</strong>请通过 <code>http://localhost</code> 或 <code>https://</code> 访问本页面，直接双击文件打开会导致文件对话框 API 被浏览器阻止。
    </div>

    <h2>📄 PDF 生成与本地保存演示</h2>
    
    <div>
        <button class="btn-primary" onclick="generateAndSavePDF()">
            💾 生成 PDF 并选择保存位置
        </button>
        <button class="btn-secondary" onclick="openLocalFile()">
            📂 打开本地文件
        </button>
    </div>

    <!-- 将要转换为 PDF 的内容区域 -->
    <div id="pdfContent">
        <h1 style="color: #2c3e50; border-bottom: 3px solid #3498db; padding-bottom: 10px;">
            煤矿综采工作面设计报告
        </h1>
        <p style="color: #7f8c8d; font-size: 14px;">生成时间：<span id="genTime"></span> | 报告编号：2024-WS-001</p>
        
        <!-- 使用 Base64 SVG 确保无跨域问题 -->
        <img src="data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iNDAwIiBoZWlnaHQ9IjIwMCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cmVjdCB3aWR0aD0iNDAwIiBoZWlnaHQ9IjIwMCIgZmlsbD0iIzAwN2JmZiIgb3BhY2l0eT0iMC4xIi8+PHRleHQgeD0iNTAlIiB5PSI1MCUiIGZvbnQtc2l6ZT0iMjQiIGZpbGw9IiMwMDdiZmYiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGR5PSIuM2VtIj7nrqHnkIbnlKjlk6HniYjvvIjljJbnlYznqbrpl7TnmoTlhoXlrrnvvIk8L3RleHQ+PC9zdmc+" 
             style="width: 100%; height: auto; margin: 20px 0; border-radius: 4px;">
        
        <h3>1. 设备选型概况</h3>
        <table border="1" cellpadding="8" cellspacing="0" style="border-collapse: collapse; width: 100%; font-size: 14px;">
            <tr style="background: #34495e; color: white;">
                <th>设备名称</th>
                <th>型号规格</th>
                <th>主要参数</th>
            </tr>
            <tr>
                <td>采煤机</td>
                <td>MG750/1860-WD</td>
                <td>采高范围：2.8~5.5m | 截深：0.865m</td>
            </tr>
            <tr>
                <td>液压支架</td>
                <td>ZY15000/28/58</td>
                <td>工作阻力：15000kN | 支护强度：1.35MPa</td>
            </tr>
            <tr>
                <td>刮板输送机</td>
                <td>SGZ1000/3×1000</td>
                <td>输送量：3500t/h | 链速：1.31m/s</td>
            </tr>
        </table>
        
        <h3>2. 三机配套说明</h3>
        <p style="line-height: 1.6; color: #2c3e50;">
            本工作面采用大采高综采工艺，采煤机与支架、输送机之间严格按"三机配套"原则选型。
            通过 html2pdf.js 生成的此 PDF 文档完全在浏览器端完成，未经过任何服务器渲染。
        </p>
    </div>

    <div id="fileInfo" class="file-info" style="display: none;"></div>
</div>

<script>
    // 初始化时间
    document.getElementById('genTime').innerText = new Date().toLocaleString('zh-CN');

    /**
     * 生成 PDF 并通过对话框保存到本地
     */
    async function generateAndSavePDF() {
        const btn = event.target;
        const originalText = btn.innerText;
        btn.innerText = '⏳ 生成中...';
        btn.disabled = true;

        try {
            const element = document.getElementById('pdfContent');
            
            // 配置 html2pdf
            const opt = {
                margin: [15, 15],
                image: { type: 'jpeg', quality: 0.98 },
                html2canvas: { 
                    scale: 2,                // 2倍高清
                    useCORS: true,
                    allowTaint: true,
                    backgroundColor: '#ffffff'
                },
                jsPDF: { unit: 'mm', format: 'a4', orientation: 'portrait' }
            };

            // 生成 Blob 而非直接下载
            const worker = html2pdf().set(opt).from(element);
            const pdfBlob = await worker.output('blob');

            // 检查 API 可用性
            if (!window.showSaveFilePicker) {
                // 降级方案：传统下载
                const url = URL.createObjectURL(pdfBlob);
                const a = document.createElement('a');
                a.href = url;
                a.download = '煤矿选型报告.pdf';
                a.click();
                URL.revokeObjectURL(url);
                alert('当前浏览器不支持文件选择对话框，已使用默认下载方式');
                return;
            }

            // 弹出系统"另存为"对话框
            const handle = await window.showSaveFilePicker({
                suggestedName: `煤矿选型报告_${new Date().getTime()}.pdf`,
                types: [{
                    description: 'PDF 文档',
                    accept: { 'application/pdf': ['.pdf'] }
                }]
            });

            // 写入文件
            const writable = await handle.createWritable();
            await writable.write(pdfBlob);
            await writable.close();

            showInfo(`✅ 保存成功！\n文件名：${handle.name}\n大小：${(pdfBlob.size/1024).toFixed(1)} KB`);
            
        } catch (err) {
            if (err.name === 'AbortError') {
                showInfo('ℹ️ 用户取消了保存');
            } else if (err.name === 'SecurityError') {
                alert('❌ 安全错误：请使用 localhost 或 HTTPS 访问');
            } else {
                alert('❌ 错误：' + err.message);
                console.error(err);
            }
        } finally {
            btn.innerText = originalText;
            btn.disabled = false;
        }
    }

    /**
     * 打开本地文件（演示 File System Access API 的读取功能）
     */
    async function openLocalFile() {
        try {
            const [handle] = await window.showOpenFilePicker({
                multiple: false,
                types: [
                    { description: '文本文件', accept: { 'text/plain': ['.txt'] } },
                    { description: 'PDF 文件', accept: { 'application/pdf': ['.pdf'] } },
                    { description: '图片', accept: { 'image/*': ['.png', '.jpg', '.jpeg'] } }
                ]
            });

            const file = await handle.getFile();
            
            // 根据文件类型处理
            let content = '';
            if (file.type.startsWith('image/')) {
                content = `图片文件，尺寸：${(file.size/1024).toFixed(1)} KB`;
                // 可以在这里创建 URL.createObjectURL(file) 来预览图片
            } else if (file.type === 'application/pdf') {
                content = `PDF 文件，页数信息需额外解析库，文件大小：${(file.size/1024).toFixed(1)} KB`;
            } else {
                content = await file.text();
                if (content.length > 500) content = content.substring(0, 500) + '...';
            }

            showInfo(`📄 已打开：${file.name}\n类型：${file.type || '未知'}\n大小：${(file.size/1024).toFixed(2)} KB\n\n内容预览：\n${content}`);

        } catch (err) {
            if (err.name !== 'AbortError') {
                console.error('打开文件失败:', err);
            }
        }
    }

    function showInfo(text) {
        const info = document.getElementById('fileInfo');
        info.style.display = 'block';
        info.innerText = text;
    }
</script>

</body>
</html>

兼容性说明与降级策略

功能	支持情况	降级方案
html2pdf.js	所有现代浏览器	无需降级，广泛兼容
showSaveFilePicker	Chrome 86+, Edge 86+, Opera 72+	使用传统 `a.download` 自动下载到默认路径
showOpenFilePicker	同上	回退到 `<input type="file">`

检测与降级代码示例：

javascript 复制代码

if (window.showSaveFilePicker) {
    // 使用原生对话框
    await saveWithDialog();
} else {
    // 降级：创建临时链接下载
    const url = URL.createObjectURL(pdfBlob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'default.pdf';
    document.body.appendChild(a);
    a.click();
    document.body.removeChild(a);
    URL.revokeObjectURL(url);
}

总结

通过组合 html2pdf.js 与 File System Access API，我们构建了一个既现代又实用的浏览器端文档处理方案：

零服务端架构：PDF 生成完全在客户端完成，适合处理敏感数据或离线环境
原生体验：使用操作系统级文件对话框，用户无需学习新的交互模式
高清输出 ：通过 scale: 2 配置，生成的 PDF 文字清晰、图片锐利，媲美后端渲染效果
双向文件操作：既可以将生成的内容保存到任意本地路径，也可以读取本地文件进行分析

这一技术组合特别适用于离线优先（Offline-First） 的 PWA 应用、数据隐私敏感 的企业内网系统，或需要即开即用的轻量级工具页面。随着 File System Access API 在 Firefox 和 Safari 的逐步落地，纯前端的文件操作能力将成为 Web 应用的标配特性。