EG/build_scripts/ICON_GUIDE.md

# EG 图标准备指南

构建安装程序需要准备应用程序图标，本指南说明如何创建和放置图标文件。

---

## 📋 所需图标

| 平台 | 文件名 | 格式 | 推荐尺寸 | 用途 |
|------|--------|------|---------|------|
| Windows | `icons/app.ico` | ICO | 256x256 (多尺寸) | 可执行文件和安装程序图标 |
| Linux | `icons/app.png` | PNG | 256x256 | AppImage 和桌面图标 |

---

## 🎨 图标要求

### Windows ICO 文件

ICO 文件可以包含多个尺寸的图标：
- **必须包含**: 256x256 (32位)
- **推荐包含**: 48x48, 32x32, 16x16
- **可选**: 128x128, 64x64

**格式要求**:
- 支持透明背景 (32位，带 Alpha 通道)
- 大图标使用 PNG 压缩
- 小图标使用 BMP 格式

### Linux PNG 文件

- **尺寸**: 256x256 像素
- **格式**: PNG，带透明通道
- **色彩**: RGBA (32位)

---

## 🔧 创建图标的方法

### 方法 1: 使用现有图片转换

如果你有 PNG/JPG 格式的 logo：

**Windows (ICO)**:
```bash
# 使用 ImageMagick
convert logo.png -define icon:auto-resize=256,128,64,48,32,16 icons/app.ico

# 或在线工具
# https://convertio.co/png-ico/
# https://icoconvert.com/
```

**Linux (PNG)**:
```bash
# 直接复制或调整大小
cp logo.png icons/app.png

# 或使用 ImageMagick 调整
convert logo.png -resize 256x256 icons/app.png
```

### 方法 2: 使用专业工具设计

| 工具 | 平台 | 类型 | 链接 |
|------|------|------|------|
| Adobe Illustrator | Win/Mac | 专业矢量 | - |
| Figma | Web | 免费在线 | figma.com |
| Canva | Web | 免费在线 | canva.com |
| GIMP | Win/Mac/Linux | 免费开源 | gimp.org |
| Inkscape | Win/Mac/Linux | 免费矢量 | inkscape.org |

### 方法 3: 使用 Python 脚本生成

如果你有源图片，可以使用 Python 生成：

```python
#!/usr/bin/env python3
"""图标生成脚本"""

from PIL import Image
import os

# 源图片路径
source_image = "source_logo.png"  # 你的源图片
output_dir = "icons"

# 确保输出目录存在
os.makedirs(output_dir, exist_ok=True)

# 打开源图片
img = Image.open(source_image)

# 转换为 RGBA 模式 (确保透明通道)
if img.mode != 'RGBA':
    img = img.convert('RGBA')

# 生成 Windows ICO (多尺寸)
icon_sizes = [(16, 16), (32, 32), (48, 48), (64, 64), (128, 128), (256, 256)]
ico_images = []

for size in icon_sizes:
    resized = img.resize(size, Image.Resampling.LANCZOS)
    ico_images.append(resized)

# 保存 ICO (第一个图像作为根，其余作为子图标)
ico_images[0].save(
    os.path.join(output_dir, "app.ico"),
    format='ICO',
    sizes=[(i.width, i.height) for i in ico_images],
    append_images=ico_images[1:]
)

print(f"✓ 生成: {output_dir}/app.ico")

# 生成 Linux PNG (256x256)
png_size = (256, 256)
png_img = img.resize(png_size, Image.Resampling.LANCZOS)
png_img.save(os.path.join(output_dir, "app.png"), format='PNG')

print(f"✓ 生成: {output_dir}/app.png")

print("\n图标生成完成！")
```

**使用方法**:
```bash
# 安装依赖
pip install Pillow

# 运行脚本
python generate_icons.py
```

### 方法 4: 从项目中提取

如果项目中有现有图标资源：

```bash
# 查找项目中的图标文件
find . -name "*.ico" -o -name "*.png" | grep -i icon

# 复制到正确位置
cp 找到的图标文件 icons/app.ico
cp 找到的图标文件 icons/app.png
```

---

## 📁 目录结构

放置图标后，项目结构应为：

```
EG/
├── icons/
│   ├── app.ico          # Windows 图标 (必需)
│   ├── app.png          # Linux 图标 (必需)
│   └── ...              # 其他图标资源
├── build_scripts/
├── ...
```

---

## ✅ 验证图标

### Windows

```powershell
# 检查文件存在
Test-Path icons/app.ico

# 查看 ICO 内容 (需要工具)
# 使用 Resource Hacker: http://www.angusj.com/resourcehacker/
```

### Linux

```bash
# 检查文件存在
ls -la icons/app.png

# 查看图片信息
file icons/app.png
identify icons/app.png  # 需要 ImageMagick

# 预览
xdg-open icons/app.png
```

---

## 🚀 测试图标

构建完成后，验证图标是否正确显示：

### Windows

1. **可执行文件图标**:
   ```powershell
   # 检查 dist/EG_1.0.0/EG.exe 的图标
   # 在资源管理器中查看，应该显示你的图标
   ```

2. **安装程序图标**:
   ```powershell
   # 检查 dist/EG_Setup_v1.0.0_x64.exe 的图标
   ```

### Linux

```bash
# 检查 AppImage 图标
./dist/EG-1.0.0-x86_64.AppImage --appimage-mount
ls squashfs-root/EG.png
```

---

## 🐛 常见问题

### 问题 1: ICO 文件无法识别

**症状**: Windows 显示默认图标

**解决**:
- 确保 ICO 包含 256x256 尺寸
- 使用专业工具重新生成
- 检查文件是否损坏

### 问题 2: Linux 图标不显示

**症状**: AppImage 使用默认图标

**解决**:
- 确认 `icons/app.png` 存在
- 检查文件权限: `chmod 644 icons/app.png`
- 确认 PNG 格式正确: `file icons/app.png`

### 问题 3: 图标模糊

**症状**: 图标显示模糊或锯齿

**解决**:
- 使用矢量源文件生成
- 确保包含多个尺寸
- 使用高质量缩放算法 (LANCZOS)

---

## 📦 快速开始

如果你没有现成的图标，可以先使用占位图标：

```bash
# Windows: 创建一个简单的 ICO
# 使用在线工具生成，或先跳过 (Nuitka 会使用默认图标)

# Linux: 创建一个简单的 PNG
python3 -c "
from PIL import Image
import os
os.makedirs('icons', exist_ok=True)
img = Image.new('RGBA', (256, 256), (100, 150, 255, 255))
img.save('icons/app.png')
print('Created placeholder icon')
"
```

**注意**: 发布前务必替换为正式图标！

---

## 🎨 设计建议

1. **简洁明了**: 小尺寸下依然可识别
2. **品牌一致性**: 与应用风格一致
3. **透明背景**: 适应不同主题
4. **测试多尺寸**: 确保 16x16 到 256x256 都清晰
5. **考虑暗色主题**: 在深色背景下也可见

---

**文档版本**: 1.0