← 返回学习路线

SYSTEM

D26 前端:按文体默认格式导出 + 二进制保存通道

QuillAgent文档5. D26 前端:按文体默认格式导出 + 二进制保存通道growth
src/content/notes/growth/D26-前端:按文体默认格式导出-二进制保存通道.md

5. D26 前端:按文体默认格式导出 + 二进制保存通道

5.1 任务

  • 导出菜单:按文体默认格式(网文 NOVEL→txt / 自媒体 MEDIA→md / 公文 OFFICIAL→word),用户可覆盖;文件名 = 标题 + 扩展名。
  • 新增主进程「二进制保存」IPC(现有 save-file 只支持文本),走保存对话框;导出内容本地流转,不上传第三方。
  • 数据边界:正文快照以文本存 SQLite;只有二进制导出文件走 saveBinaryFile IPC,二者不混存。

5.2 代码

electron/electron/preload.ts 追加:

    /** 二进制导出保存:dialog 选路径后写 Buffer(word 导出用;txt/md 也可走此通道统一) */
    saveBinaryFile: (data: Uint8Array, name: string): Promise<string | null> =>
        ipcRenderer.invoke('save-binary-file', data, name),

electron/electron/main.ts 追加 IPC(放在 save-file handler 旁;强制文件名白名单,禁止任何路径传递):

/** 渲染进程只提供纯文件名:拒绝路径分隔符、盘符、`..`、控制字符,长度上限 120 */
function safeExportName(name: unknown): string | null {
    if (typeof name !== 'string') return null;
    const trimmed = name.trim();
    if (!trimmed || trimmed.length > 120) return null;
    if (/[\\/:*?"<>|\u0000-\u001f]/.test(trimmed)) return null;   // 含 / 或 \ 即视为路径注入
    if (trimmed.includes('..')) return null;
    return trimmed;
}

const MAX_EXPORT_BYTES = 50 * 1024 * 1024;   // 50MB 上限:普通文档导出远低于此

ipcMain.handle('save-binary-file', async (_e, data: Uint8Array, defaultName: string) => {
    const name = safeExportName(defaultName);            // 路径穿越在此被拒绝
    if (!name) return null;
    if (!(data instanceof Uint8Array) || data.byteLength > MAX_EXPORT_BYTES) return null;

    // 默认目录固定为应用数据目录下的 exports;最终写入位置由用户在系统保存对话框中确认
    const exportDir = path.join(dataDir, 'exports');
    fs.mkdirSync(exportDir, { recursive: true });
    const r = await dialog.showSaveDialog({ defaultPath: path.join(exportDir, name) });
    if (r.canceled || !r.filePath) return null;
    fs.writeFileSync(r.filePath, Buffer.from(data));
    return r.filePath;
});

安全边界说明(评审项落地):

  1. 渲染进程永远不能传绝对路径,只传 basename;/、\、盘符、.. 一律拒绝 → 路径穿越面为零。
  2. 最终路径来自用户本人在系统对话框中的选择,这是产品功能而非攻击面;默认目录限定在 userData/data/exports。
  3. 数据边界:文档正文快照存 SQLite(文本),二进制导出文件才走本 IPC 通道,二者不混存。

electron/src/api/export.ts(新建)

import http from './http';

/** 非法文件名字符清洗(与后端 ExportService.sanitizeFileName 同规则,双端一致) */
function sanitize(title: string): string {
    const t = (title || 'document').replace(/[\\/:*?"<>|\u0000-\u001f]/g, '_').trim();
    return t.length > 60 ? t.slice(0, 60) : t;
}

const EXT: Record<'md' | 'txt' | 'word', string> = { md: 'md', txt: 'txt', word: 'docx' };

export const exportApi = {
    download: async (docId: number, format: 'md' | 'txt' | 'word', title: string): Promise<string | null> => {
        const r = await http.get(`/api/documents/${docId}/export`, {
            params: { format },
            responseType: 'arraybuffer',
        });
        const type = String(r.headers['content-type'] || '');
        if (type.includes('application/json')) {
            // 二进制流被错误 JSON 替换(ERR-DOC-001 等)→ 解出 message 提示
            const err = JSON.parse(new TextDecoder().decode(r.data));
            throw new Error(err.message || '导出失败');
        }
        const defaultName = `${sanitize(title)}.${EXT[format]}`;
        return (await window.quill?.saveBinaryFile(new Uint8Array(r.data), defaultName)) ?? null;
    },
};

electron/src/views/WritingView.vue 集成(工具栏加两个入口,<script setup> 补对应逻辑):

<!-- 工具栏追加 -->
<el-button icon="Clock" @click="versionOpen = true">历史版本</el-button>
<el-dropdown @command="onExport">
  <el-button>
    导出<el-icon style="margin-left: 4px"><ArrowDown /></el-icon>
  </el-button>
  <template #dropdown>
    <el-dropdown-menu>
      <el-dropdown-item command="txt">纯文本 .txt(网文默认)</el-dropdown-item>
      <el-dropdown-item command="md">Markdown .md(自媒体默认)</el-dropdown-item>
      <el-dropdown-item command="word">Word .docx(公文默认)</el-dropdown-item>
    </el-dropdown-menu>
  </template>
</el-dropdown>
<!-- 抽屉放模板末尾 -->
<VersionPanel v-model="versionOpen" :doc-id="store.current?.id ?? 0" :editor="editor" />
import { ref } from 'vue';
import { ElMessage } from 'element-plus';
import { ArrowDown } from '@element-plus/icons-vue';
import VersionPanel from '../components/VersionPanel.vue';
import { exportApi } from '../api/export';
import { useDocumentStore } from '../stores/document';

const store = useDocumentStore();
const versionOpen = ref(false);
// ...existing editor 定义不变

/** 文体 → 默认导出格式(02-接口文档 §2.4) */
function defaultFormat(genre: string): 'txt' | 'md' | 'word' {
    return genre === 'MEDIA' ? 'md' : genre === 'OFFICIAL' ? 'word' : 'txt';
}

async function onExport(format?: 'txt' | 'md' | 'word') {
    const doc = store.current;
    if (!doc) return;
    const f = format ?? defaultFormat(doc.genre);
    try {
        const path = await exportApi.download(doc.id, f, doc.title);
        if (path) ElMessage.success(`已导出:${path}`);
    } catch (e) {
        ElMessage.error(e instanceof Error ? e.message : '导出失败');
    }
}