插件使用
本指南详细介绍 CodeSign 切图助手插件的使用方法。
基本使用
方式一：自动下载（推荐）
这是最便捷的使用方式，完全自动化。
步骤：
- 启动 QT Tool 服务器
bash
qt --run- 打开 CodeSign 平台
- 下载切图
在 CodeSign 平台上点击下载切图按钮，插件会自动：
- 拦截下载请求
- 下载 ZIP 文件
- 调用本地 QT Tool 处理
- 显示处理结果通知
流程图：
CodeSign 平台
↓
用户点击下载
↓
Content Script 拦截
↓
Background Script 处理
↓
下载 ZIP 文件
↓
调用 QT Tool API
↓
显示结果通知方式二：手动处理
如果自动下载不工作，可以使用手动处理方式。
步骤：
- 点击插件图标
打开插件弹窗。
- 选择功能
弹窗显示两个主要功能：
- 历史记录
- 通用设置
- 手动上传文件
（此功能将在未来版本中提供）
功能详解
1. 历史记录
查看所有处理历史记录。
查看历史：
- 点击插件图标
- 点击「历史记录」按钮
- 查看处理列表
历史记录包含：
- 处理时间
- 文件名称
- 处理状态（✅ 成功 / ❌ 失败）
- 使用的配置索引
历史记录操作：
- 点击记录可查看详细信息
- 支持重新处理失败的文件
2. 通用设置
配置插件的基本参数。
设置项：
| 设置项 | 说明 | 默认值 |
|---|---|---|
| 服务地址 | QT Tool 服务器地址 | http://localhost:9999 |
| 弹窗宽度 | 插件弹窗宽度 | 400px |
| 弹窗高度 | 插件弹窗高度 | 240px |
配置步骤：
- 点击插件图标
- 点击「通用设置」按钮
- 修改配置项
- 点击「测试连接」验证
- 点击「保存配置」
测试连接：
- 成功：显示「连接成功」通知
- 失败：显示「连接失败」通知，请检查服务器是否启动
3. 文件检查
插件在处理前会自动检查文件是否已存在。
检查流程：
用户请求处理
↓
调用 /check API
↓
文件是否存在？
├─ 是 → 提示用户确认是否覆盖
└─ 否 → 直接处理检查 API：
http
POST /process/check
Content-Type: application/json
{
"name": "icon.png",
"config_index": 0
}使用场景
场景 1：Android 应用开发
需求：
- 从 CodeSign 下载 Android 应用图标
- 自动生成 mdpi/hdpi/xhdpi/xxhdpi 四种尺寸
配置：
toml
[[output]]
name = "Android 应用图标"
description = "Android 应用图标"
base_path = "./android/app/src/main/res"
format = ["mipmap-mdpi", "mipmap-hdpi", "mipmap-xhdpi", "mipmap-xxhdpi"]
zip_format = [
"mipmap-mdpi/",
"mipmap-hdpi/",
"mipmap-xhdpi/",
"mipmap-xxhdpi/"
]
format_limit = [".png"]使用：
- 在 CodeSign 平台下载 Android 图标
- 插件自动处理并输出到对应目录
- 直接在 Android 项目中使用
场景 2：iOS 应用开发
需求：
- 从 CodeSign 下载 iOS 应用图标
- 自动生成 @1x/@2x/@3x 三种尺寸
配置：
toml
[[output]]
name = "iOS 应用图标"
description = "iOS 应用图标"
base_path = "./ios/Assets.xcassets/AppIcon.appiconset"
format = ["", "@2x", "@3x"]
zip_format = ["./**.png", "./**@2x.png", "./**@3x.png"]
format_limit = [".png"]使用：
- 在 CodeSign 平台下载 iOS 图标
- 插件自动处理并输出到对应目录
- 直接在 iOS 项目中使用
场景 3：Web 前端开发
需求：
- 从 CodeSign 下载 Web 图片
- 自动生成响应式图片（1x/2x/3x/4x）
配置：
toml
[[output]]
name = "Web 响应式图片"
description = "Web 不同尺寸的图片"
base_path = "./assets/images"
format = ["1x", "2x", "3x", "4x"]
zip_format = [
"./**.png",
"./**@2x.png",
"./**@3x.png",
"./**@4x.png"
]
format_limit = [".png", ".jpg", ".webp"]使用：
- 在 CodeSign 平台下载 Web 图片
- 插件自动处理并输出到对应目录
- 在 HTML/CSS 中使用响应式图片
场景 4：Flutter 开发
需求：
- 从 CodeSign 下载 Flutter 资源
- 自动生成 1.0x/2.0x/3.0x 三种尺寸
配置：
toml
[[output]]
name = "Flutter 资源"
description = "Flutter 项目资源"
base_path = "./assets/images"
format = ["1.0x", "2.0x", "3.0x"]
zip_format = [
"./**.png",
"./**@2x.png",
"./**@3x.png"
]
format_limit = [".png", ".svg"]使用：
- 在 CodeSign 平台下载 Flutter 资源
- 插件自动处理并输出到对应目录
- 在 Flutter 项目中引用资源
高级功能
配置选择
如果配置了多个输出规则，插件会：
- 显示配置列表供用户选择
- 记住用户的选择
- 下次使用相同的配置
键盘快捷键
（此功能将在未来版本中提供）
最佳实践
1. 启动顺序
推荐启动顺序：
- 启动 QT Tool 服务器
- 打开浏览器
- 访问 CodeSign 平台
- 开始下载切图
2. 配置管理
- 为不同平台创建不同的配置
- 使用清晰的命名和描述
- 遵循配置索引规则（不要随意调整顺序）
3. 文件命名
- 使用有意义的文件名
- 遵循平台命名规范
- 避免使用特殊字符
故障排除
1. 自动下载不工作
问题： 在 CodeSign 下载切图时没有自动处理
排查步骤：
- 确认插件已正确安装
- 检查插件权限是否已授予
- 刷新 CodeSign 页面后重试
- 查看浏览器控制台错误信息
2. 处理失败
问题： 文件处理失败
排查步骤：
- 查看 QT Tool 日志：
~/.config/qt-tool/record.log - 检查配置文件是否正确
- 确认 ZIP 文件格式是否符合配置
- 检查输出目录是否有写入权限
3. 连接超时
问题： 连接 QT Tool 服务器超时
排查步骤：
- 确认服务器已启动：
qt --run - 检查服务器地址是否正确
- 测试服务器连接：
http://localhost:9999/process/test - 检查防火墙设置
4. 文件已存在
问题： 提示文件已存在，无法覆盖
解决方法：
- 删除已存在的文件
- 或使用不同的文件名
- 或在配置中允许覆盖（未来版本）