# zdoc
**Repository Path**: zedo/zdoc
## Basic Information
- **Project Name**: zdoc
- **Description**: 基于 Vue 3 + TypeScript + Vite 构建的 WPS Word插件，核心功能是公文快速排版，并提供页面布局、图片处理、快捷样式、邮件合并等实用工具。通过自定义 CustomUI 选项卡集成到 WPS。
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-01
- **Last Updated**: 2026-10-22
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# zdoc · 公文排版工作台
**让 WPS 加载项开发回归现代前端工程化**
**让公文排版从手工反复调整变成一键可复现的操作**
[](#)
[](#)
[](#)
[](#)
[](#)
[功能手册](./FEATURES.md) · [架构设计](./ARCHITECTURE.md) · [问题反馈](https://github.com/your-repo/issues)
## 这是什么
**一套基础设施 + 一个开箱即用的应用：**
- 🧩 **`vite-plugin-wps-enhance`** —— Vite 插件，把 WPS 加载项从"手写 XML + 魔法数字 + 无法测试"升级到前端工程化水平
- 📝 **`zdoc`** —— 基于此插件构建的公文排版工作台：一键排版、批量处理、活文档对比、邮件合并增强、版头生成……
> 如果你只想要"又一个公文助手"，市面上有很多。
> 如果你想找**工程化程度、可测试性、二次排版速度**都到位的方案，继续往下读。
---
## 为什么不是又一个"公文助手"
### 与传统 WPS 加载项开发方式的对比
| 维度 | 传统方式（VBA / 手写 XML / 裸 JSA） | 本项目 |
| ---------------- | ----------------------------------------- | ---------------------------------------------------------- |
| **Ribbon 定义** | 手写数百行 XML，改按钮要同步改 XML + 绑定 | TypeScript 函数式 API，自动渲染 XML |
| **控件回调** | 控件 `id` 是裸字符串，拼错只能运行时崩 | 自动生成 `RibbonControlId` **联合类型**，编译期校验 |
| **枚举常量** | 必须 `wps.Enum.xxx` 或裸写魔法数字 | 源码里写 `wdAlignParagraphCenter` 就够，**构建时按需生成** |
| **图片图标** | 手写路径字符串，改名/删图即时崩 | 扫描目录生成 `ImageFileName` 类型，**路径由 TS 保证** |
| **排版逻辑测试** | 必须开 WPS 人工点按钮观察 | **纯文本输入 → vitest 断言**，CI 可跑 |
| **排版速度** | 全量重设每个属性，二次排版与首次一样慢 | **差异计算**：已排好的段落一条指令都不发，二次排版接近瞬时 |
| **新增段落样式** | 分散在 3~5 个函数里的 if/else | `ATTRS` 数组加一项，核心遍历代码零改动 |
| **dev 二次启动** | 每次重扫 `.d.ts` 枚举库 | 三级缓存（内存→落盘→实扫），**命中 <1ms** |
| **弹窗冷启动** | 拉起完整应用 | URL 分流：`?dialog=xxx` 只加载 Vue + 单组件，**≈500ms** |
### 一个具体例子
**传统方式**：给"落款日期"加一条左对齐规则，你要在排版函数、样式应用、差异检测三个地方同时改。
**本项目**：打开 `para-attributes.ts`，在 `ATTRS` 数组加一项：
```ts
{
key: "alignment",
desired(p) {
if (p.semanticKinds.has("signatureDate")) return wdAlignParagraphLeft;
return undefined;
},
readCom: (rng) => rng.ParagraphFormat.Alignment,
isEqual: (a, b) => a === b,
apply: (rng, v) => { rng.ParagraphFormat.Alignment = v; },
}
```
差异计算、应用修改、属性合并全部自动生效——**并且自带单测能力**。
---
## 功能速览
> 完整操作说明见 [功能手册](./FEATURES.md)
### 🚀 核心能力
| 模块 | 一句话 |
| ----------------- | ------------------------------------------------------------------------ |
| **一键排版** | 标题/正文/层级/抬头/附件/落款全自动识别 + 应用样式，**二次排版近似瞬时** |
| **活文档对比** | 在文档里标记一段文字，之后编辑这段文字，对比框**实时同步** |
| **批量排版** | 拖入多个 docx，进度条 + 时间戳日志，单个失败不影响其他 |
| **快捷样式弹窗** | 选中文本→点按钮，**弹窗秒开**（不加载主应用） |
| **邮件合并增强** | 域底纹三档、记录导航、可用域单击插入，**鼠标移入自动刷新** |
| **版头生成** | 红头文件版头：发文机关标志 / 发文字号 / 分隔线 |
| **页面设置** | 六项边距 + 页眉 + 页脚，全部支持鼠标滚轮调值 |
| **全半角 / 标点** | 英文标点转全角、字母数字转半角、引号配对更正 |
### 📋 页面设置面板
四个可折叠区（页面 / 字体 / 页眉 / 页脚），独立应用或一键「应用所有设置」。
- **页眉**带密级预设：内部★注意保管 / 秘密★1年 / 机密★5年 / 绝密★长期
- **页脚**页码 **5 种位置**（内侧/外侧/左/中/右）带位置示意图
- **字体**联动：改中文字体，西文字体若选「随中文」自动跟随
- **状态提示**：切换文档时页脚自动刷新「已设置 / 未检测到页码」
---
## 典型工作流
### 场景一：新收一份公文，一键排版
1. 打开文档
2. Ribbon → 快速排版 → 完成
3. 标题、正文、层级标题、抬头、附件、落款全部识别并套用样式
**再排一次几乎是瞬时的**——差异计算只对确实不一致的段落下发指令。
### 场景二：修改一稿，看看改了哪里
1. Ribbon → 文本对比 → 打开任务窗格
2. 在文档里**选中原始文字** → 点击「📌 标记选区段落」
3. 切到「旧文本」记为原稿，再切到「新文本」，随手编辑文档
4. 对比框**实时显示改动**——无需先保存两份文件
### 场景三：领导下发 20 个文件，统一格式
1. Ribbon → 批量排版
2. 选择 20 个 docx
3. 点「开始批量排版」，进度条 + 每条的日志（成功绿/失败红）
4. 单个文档打开失败不影响其他
### 场景四：编辑文档时右栏需要看到合并域
1. Ribbon → 邮件合并 → 插入合并域
2. **鼠标移入面板时自动拉取最新字段列表**（在文档里改了表头，回来立刻是新的）
3. 单击字段标签 → 插入到光标位置
4. 顶部可直接输入记录号跳转 + 切换「显示值 / 显示域」+ 调整域底纹
---
## 快速开始
```bash
# 1. 安装
pnpm install
# 2. 开发（Vite 热更新 + WPS 调试）
pnpm dev
# 3. 单元测试（无需 WPS 环境）
pnpm test
# 4. 打包
pnpm build
```
**环境要求**：WPS Office 2019+ / Node.js 18+ / pnpm 8+
---
## 架构一句话
```text
┌─────────────────────────────────────────────────┐
│ 纯逻辑层（可单测） │
│ para-analysis.ts → 语义识别（14 种段落类型） │
├─────────────────────────────────────────────────┤
│ 属性注册表 + 差异计算 │
│ para-attributes.ts → 声明式扩展，新增属性=加一行│
├─────────────────────────────────────────────────┤
│ COM 编排（唯一触碰 Wps.* 的排版模块） │
│ para-pipeline.ts → 批量读段 / 缓存 / 差异应用 │
└─────────────────────────────────────────────────┘
```
**完整架构设计**（三层分离、vite-plugin-wps-enhance 原理、测试策略、扩展指南）见 [ARCHITECTURE.md](./ARCHITECTURE.md)。
---
## 目录结构
```text
plugins/vite-plugin-wps-enhance/ 工程化插件
├── enum/ 枚举扫描 + 按需生成
├── ribbon/ TS 配置 → ribbon.xml
└── image/ 图片目录 → 文件名类型
src/
├── jsa/commands/ 20+ WPS 命令模块
├── jsa/ribbon/ Ribbon 声明式配置
├── utils/para-*.ts 排版引擎
├── components/ 设置区组件
├── composables/ WPS 交互封装
├── views/ 任务窗格页面
└── tests/ 60+ 单测 / 集成测试
```
---
## 技术栈
Vue 3 · TypeScript · Vite · WPS JSA · Vitest · Valibot · VueUse · Tailwind CSS · Element Plus
---
## 路线图
- [ ] `vite-plugin-wps-enhance` 独立发布到 npm
- [ ] 排版配置云端同步
- [ ] 更多公文子文体模板（函 / 请示 / 批复 / 纪要）
- [ ] VS Code 插件：`.d.ts` 就地跳转 + 枚举补全
- [ ] 排版规则可视化编辑器
**如果这个项目对你有所帮助，欢迎 ⭐ Star**