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