8.2 KiB
pptopic 说明
将 PowerPoint 演示文稿导出为长图的工具。
功能
- 将 PPTX 文件的所有幻灯片垂直拼接为一张长图
- 支持 JPG 和 PNG 格式输出
- 支持自定义输出宽度和目录
- 内置图片优化功能，使用图片优化引擎进行无损压缩
系统要求
- Windows 系统（使用 win32com 调用 PowerPoint）
- Python >= 3.13
- Microsoft PowerPoint
新手使用说明
如果你是第一次使用命令行工具，请按以下步骤操作。我们提供了一键安装脚本，尽量让你少输入命令。
安装前准备
- PowerPoint：需要安装 Microsoft PowerPoint（Office 2016 或更新版本）
- 网络连接：安装过程中需要下载工具
- 解压项目：把下载的
pptopic.zip解压到任意位置，例如桌面
一键安装（推荐）
项目根目录下有一个 setup.bat，它会自动完成：
- 安装
uv（Python 包管理器） - 安装 Python 3.13
- 安装
pngquant（图片压缩工具，强烈推荐） - 安装
pptopic - 验证安装结果
方法 A：双击运行（最简单）
- 打开解压后的
pptopic文件夹 - 找到
setup.bat文件 - 双击
setup.bat - 等待安装完成，窗口会显示版本信息
如果 Windows 提示“Windows 已保护你的电脑”，请点击“更多信息” → “仍要运行”。
方法 B：右键在 PowerShell 中运行
如果双击运行被系统拦截，可以按以下步骤：
- 打开解压后的
pptopic文件夹 - 在文件夹空白处按住
Shift键，同时点击鼠标右键 - 选择“在此处打开 PowerShell 窗口”（Windows 11 可能显示为“在终端中打开”）
- 在弹出的蓝色窗口中输入以下命令，然后按回车：
.\setup.bat
等待安装完成即可。
安装完成后
如果看到类似下面的输出，说明安装成功：
--- uv 版本 ---
uv 0.11.20
--- pngquant 版本 ---
2.17.0
--- pptopic 版本 ---
pptopic 0.3.2
然后你可以直接在当前窗口使用 pptopic：
# 导出 PPTX 为长图
pptopic export presentation.pptx
# 工作中常用命令：导出 PPTX 为长图并优化图片
# 其中，29999 是微信接受的最大高度
pptopic export presentation.pptx --optimize --max-height 29999 -o result.png
一键安装脚本的参数（可选）
如果你不想安装 pngquant，可以使用以下方式运行：
# 在 PowerShell 中直接运行 setup.ps1，跳过 pngquant
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -SkipPngquant
其他可用参数：
-SkipPngquant：跳过 pngquant 安装-Force：强制重新安装 uv 和 pngquant-SkipPptopicInstall：只安装环境，不安装 pptopic
手动安装（备用）
如果一键安装脚本在你的电脑上无法运行，可以按以下步骤手动安装。
第一步：安装 uv
uv 是一个 Python 包管理器，用来安装 pptopic 及其依赖。
打开 PowerShell（在开始菜单搜索 "PowerShell"），进入本项目的目录：
cd "<你的解压目录>\pptopic"
赋予 PowerShell 执行权限：
Set-ExecutionPolicy Bypass -Scope CurrentUser
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
运行项目自带的安装脚本：
.\uv-installer.ps1
该脚本会自动下载最新版本的 uv 并添加到系统 PATH。如果你在中国大陆，脚本已内置 GitHub 加速镜像，无需额外配置。
安装完成后，关闭并重新打开 PowerShell，验证安装：
uv --version
- 如果你已安装 scoop，也可以直接
scoop install uv。- 如果想安装特定版本的 uv，可以在运行脚本前设置环境变量：
$env:UV_INSTALLER_VERSION = "0.11.20"
第二步：安装 Python
使用 uv 安装 Python 3.13 或更新版本：
uv python install 3.13
第三步（可选）：安装 pngquant 图片优化工具
虽然是可选安装，但我超级建议你安装，因为 ppt 导出后，图片通常较大，不进行图片无损压缩，会导致文件大小过大。
如果你需要对导出的图片进行压缩优化，运行：
.\install-pngquant.ps1
该脚本会：
- 如果你已安装 scoop → 通过 scoop 安装 pngquant
- 如果没有 scoop → 自动下载并安装到
%APPDATA%\pngquant，并添加到 PATH
安装完成后，重新打开 PowerShell，验证安装：
pngquant --version
- 自定义安装目录：
.\install-pngquant.ps1 -InstallDir "D:\Tools\pngquant"- 强制重新安装：
.\install-pngquant.ps1 -Force
第四步：安装 pptopic
uv tool install -e .
第五步：开始使用
# 导出 PPTX 为长图
pptopic export presentation.pptx
# 优化图片
pptopic optimize image.png
# 工作中常用命令：导出 PPTX 为长图并优化图片
# 其中，29999 是微信接受的最大高度
pptopic export presentation.pptx --optimize --max-height 29999 -o result.png
至此安装完成。
一般安装说明
安装 pptopic
git clone https://git.lyz.one/SidneyZhang/pptopic.git
cd pptopic
uv tool install -e .
安装 uv
项目使用 uv 进行安装和项目管理，如果你没有安装，这里提供一个简单的安装指引：
只是简单安装，可以使用项目自带的安装脚本（推荐）：
.\uv-installer.ps1
该脚本自动检测 uv 最新版本，支持国内 GitHub 加速镜像下载（mirror.ghproxy.com、ghproxy.net），并自动将 uv 添加到系统 PATH。
也可以通过 scoop 安装：
scoop install uv
或者使用官方提供的安装脚本：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
请注意，上述脚本都需要相关的脚本运行权限，否则无法正常运行，一般如下操作即可获取相关权限：
Set-ExecutionPolicy Bypass -Scope CurrentUser
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
使用
导出 PPTX 为长图
# 基本用法
pptopic export presentation.pptx
# 详细说明
pptopic export --help
单独优化图片
# 优化图片
pptopic optimize image.png
# 详细说明
pptopic optimize --help
图片优化
为了获得最佳的图片压缩效果，推荐使用 pngquant 进行图片压缩。
安装脚本
可以使用提供的 PowerShell 脚本安装 pngquant：
.\install-pngquant.ps1
该脚本支持两种安装方式：
- 已安装 scoop → 通过
scoop install pngquant安装 - 未安装 scoop → 从 pngquant 官网下载并安装到
%APPDATA%\pngquant，自动添加到 PATH
# 自定义安装目录
.\install-pngquant.ps1 -InstallDir "D:\Tools\pngquant"
# 强制重新安装
.\install-pngquant.ps1 -Force
# 不修改 PATH ，将无法全局使用这个工具
.\install-pngquant.ps1 -NoModifyPath
也可以直接使用 scoop 安装 pngquant，或者手动下载安装。
scoop install pngquant
或从 pngquant.org 下载 Windows 版本手动配置。
常见问题
运行 setup.bat 时提示“无法加载文件，因为在此系统上禁止运行脚本”
这说明当前电脑通过组策略严格限制了脚本执行。setup.bat 已经尝试用 -ExecutionPolicy Bypass 绕过，但仍可能被拦截。
解决方法：使用 方法 B，在 PowerShell 窗口中手动运行：
powershell -ExecutionPolicy Bypass -File .\setup.ps1
不需要以管理员身份运行，本安装脚本只修改当前用户的环境变量。
安装完成后关闭窗口，新窗口中找不到 pptopic 命令
请重新运行一次 setup.bat。如果问题依旧，请检查系统环境变量中的 PATH 是否包含以下目录：
%USERPROFILE%\.local\bin（uv 和 pptopic 的位置）%APPDATA%\pngquant（pngquant 的位置）
不想安装 pngquant 怎么办？
可以运行：
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -SkipPngquant
但强烈建议安装，否则导出的长图文件会比较大。
License
MIT License