DOCX Live Preview

中文介绍

DOCX Live Preview 是一个面向 VS Code 的轻量 DOCX 预览插件。它通过本机 WPS Office 渲染 DOCX 页面，再在 VS Code Webview 中展示结果，让论文、报告、公式、表格、图片和中英文混排尽量接近 WPS 真实打开时的版式。

项目目标很简单：不做复杂编辑，不堆冗余功能，只把 DOCX 预览做得稳定、清晰、接近真实排版。

文档：

• CHANGELOG.md：面向用户的版本更新记录。
• DEVELOPMENT.md：维护说明、测试流程、发布流程和设计决策。

功能

• 默认用 WPS DOCX Preview 打开 .docx 文件。
• 通过 WPS Office COM 渲染 DOCX，减少与真实 WPS 版式的偏差。
• 在 VS Code 只读自定义编辑器中显示渲染后的页面。
• 支持翻页、手动缩放、适合宽度、刷新和自动刷新。
• 缩放状态会在翻页后延续；点击恢复后，也会延续恢复后的状态。
• 刷新和自动刷新会清理旧页面缓存，避免翻页时看到过期渲染。
• 当 DOCX 内包含 _src_L{line} 书签时，支持源码到预览、预览到源码的双向跳转。
• 找不到 build 脚本或源码映射时，只在状态栏短暂提示，不遮挡阅读页面。
• 支持多个 DOCX 同时预览，已按至少 3 个并行预览面板设计，适合对比文本、模版和最终版本。
• 通过 WPS 只读打开文档，并在关闭时不保存。
• 自动忽略 WPS 临时锁文件，例如 ~$example.docx。

环境要求

• Windows。WPS COM 自动化仅支持 Windows。
• 已安装 WPS Office。
• Python 3.8+，并安装 pywin32 和 PyMuPDF：

pip install pywin32 PyMuPDF

安装

• VS Code 商店：在扩展面板搜索 DOCX Live Preview。
• 手动安装：从 Releases 下载 .vsix，然后执行 Extensions: Install from VSIX...。

使用

1. 在 VS Code 中打开任意 .docx 文件。
2. 文件会自动使用 WPS DOCX Preview 打开。
3. 如果被其他编辑器打开，执行 Reopen Editor With...，选择 WPS DOCX Preview。

多文档预览与 WPS 同时打开

当前插件会为每个 DOCX 预览面板创建独立的 Python/WPS 渲染会话。你可以用 VS Code 原生分栏同时打开文本、模版、最终版本等至少 3 个 DOCX；它们的翻页、缩放、刷新和自动刷新互不影响。关闭某个预览面板时，插件会释放对应的渲染进程。

如果同一个 DOCX 已经在 WPS 中打开，插件会尽量通过自己的 WPS COM 实例以只读方式打开，并在关闭时不保存。预览渲染的是磁盘上最后保存的文件；WPS 里的未保存修改，需要保存后才会进入预览。如果 WPS 无法只读打开该文件，插件会报错，而不会抢占文档的编辑权。

命令

控件

源码同步

双向同步依赖 DOCX 内的 _src_L{line} 书签，例如 _src_L42。插件会读取这些书签，并把它们作为源码映射锚点。

• 正向同步：在源码文件中放置光标，执行 DOCX: Go to Preview。
• 反向同步：在预览中执行 DOCX: Go to Source，或按住 Ctrl 点击预览文字。
• 构建脚本发现：优先使用 docx.sourceScript 配置；未配置时，会在 DOCX 同目录查找 build_generated.py、*_generated.py 或 build_*.py。
• 如果匹配到多个 build 脚本，需要显式设置 docx.sourceScript，插件不会自动猜测。

如果没有 build 脚本或没有书签映射，预览功能仍然可用。插件只会显示一条短暂的状态栏提示，阅读页面不会被遮挡。

配置

工作原理

WPS Office COM 打开 DOCX 并导出为 PDF。PyMuPDF 将 PDF 页面渲染成 PNG 图片。VS Code Webview 显示这些图片，并且只有在显式执行源码到预览跳转后，才短暂显示源码位置光标。

English

WPS-native DOCX preview for VS Code. It renders DOCX pages through WPS Office, then displays the rendered pages in a VS Code webview so academic layout, OMML equations, CJK fonts, images, and tables stay close to real WPS output.

Features

• Opens .docx files with WPS DOCX Preview by default.
• Uses WPS Office COM automation for faithful document rendering.
• Displays rendered pages in a VS Code custom readonly editor.
• Supports page navigation, manual zoom, fit-width zoom, refresh, and auto-refresh.
• Keeps the selected zoom mode across page navigation; reset also persists until changed again.
• Refresh and auto-refresh invalidate cached preview pages before showing new renders.
• Supports source-to-preview and preview-to-source sync when the DOCX contains _src_L{line} bookmarks.
• Uses transient status bar messages for missing source mappings so the preview surface is not blocked.
• Supports multiple simultaneous DOCX previews, designed for at least 3 side-by-side preview panels.
• Opens documents in WPS read-only mode and closes without saving.
• Ignores WPS lock files such as ~$example.docx.

Requirements

• Windows. WPS COM automation is Windows-only.
• WPS Office installed.
• Python 3.8+ with pywin32 and PyMuPDF:

pip install pywin32 PyMuPDF

Installation

• Marketplace: search DOCX Live Preview in the VS Code Extensions panel.
• Manual install: download a .vsix from Releases, then run Extensions: Install from VSIX....

Usage

1. Open any .docx file in VS Code.
2. The file should open automatically with WPS DOCX Preview.
3. If another editor opens it, run Reopen Editor With... and select WPS DOCX Preview.

Multiple Previews And WPS

The extension creates an independent Python/WPS render session for each DOCX preview panel. You can use native VS Code editor splits to open at least 3 DOCX files side by side, such as source text, template, and final output. Page navigation, zoom, refresh, and auto-refresh stay isolated per preview. Closing a preview panel releases its renderer process.

If the same DOCX is already open in WPS, the extension opens it read-only through its own WPS COM instance where possible and closes it without saving. The preview renders the last saved file on disk, so unsaved edits in WPS are not visible until you save them. If WPS cannot open the file read-only, the preview fails instead of taking edit ownership of the document.

Commands

Controls

Source Sync

Bidirectional sync works when the DOCX includes bookmarks named _src_L{line}, for example _src_L42. The extension reads those bookmarks and uses them as source mapping anchors.

• Forward sync: place the cursor in a source file and run DOCX: Go to Preview.
• Reverse sync: run DOCX: Go to Source from the preview, or Ctrl + click text in the preview.
• Build script discovery: the extension uses docx.sourceScript when configured. Otherwise, it looks beside the DOCX for build_generated.py, *_generated.py, or build_*.py.
• If multiple build scripts match, set docx.sourceScript explicitly so the extension does not guess.

If there is no build script or no bookmark mapping, preview still works. The extension shows a short status bar message and keeps the reading surface unobstructed.

Configuration

How It Works

WPS Office COM opens the DOCX and exports it to PDF. PyMuPDF renders PDF pages to PNG images. The VS Code webview displays those images and briefly shows a source-position cursor only after an explicit source-to-preview jump.

License

MIT