Better-Seewo/DEVELOPER_GUIDE.md

# Better-Seewo 完整开发指南

**项目类型**: 希沃白板 5 插件 SDK（基于 dotnetCampus.EasiPlugin.Sdk v2.1.1-alpha.3 构建）
**目标框架**: net6.0-windows (.NET 6.0, WPF + WinForms)
**开发环境**: 希沃白板 5 (版本 5.2.2.653 ~ 5.3.0.0)

## 前言

希沃白板 5 插件 SDK 文档严重缺失，导致开发者几乎无法找到正确的菜单注册点。本项目通过对 `EasiNote.Api.dll` 的完全逆向工程分析，填补了所有开发空白。

## 核心发现

经过对 `EasiNote.Api.dll` (版本 5.2.4.9855) 的静态分析，我们发现了 **`Cvte.EasiNote.UIItemPurposes`** 类型，其中包含 **13 个可用的菜单常量**。这是本项目开发的所有菜单入口的基础。

### 所有真实可用的常量

| 常量名 | 实际字符串值 | 菜单层级 | 适用场景 |
|---|---|---|---|
| `ToolBar` | `EduBoard.V5.ToolBarItem` | 顶部通用工具栏 | 白板顶部的工具按钮区域（绘图工具） |
| `FunctionBar` | `EduBoard.V5.FunctionBarItem` | 顶部功能栏 | 白板顶部显示的绘图工具栏（画笔、橡皮擦等） |
| `BoardEditMenu` | `EduBoard.V5.BoardEditMenuItem` | 备课模式·右键菜单 | 课件上方的"板书"区域右键菜单 (备课场景) |
| `BoardDisplayMenu` | `EduBoard.V5.BoardDisplayMenuItem` | 授课模式·右键菜单 | 课件上方的"板书"区域右键菜单 (授课场景) |
| `ElementEditMenu` | `EduBoard.V5.ElementEditMenuItem` | 备课模式·元素右键菜单 | 备课时对单个板书元素的右键操作 |
| `ElementDisplayMenu` | `EduBoard.V5.ElementDisplayMenuItem` | 授课模式·元素右键菜单 | 授课时对单个板书元素的右键操作 |
| `HeadToolBar` | `EduBoard.V5.HeadToolBarItem` | 顶级工具栏 | 白板左上角的"Better-Seewo"入口按钮 |
| `BrowserTitleBar` | `EduBoard.V5.ExtendedTitleBar.Browser` | 浏览器·标题栏 | 备课时浏览器区域顶部的标题栏区域 |
| `CloudTitleBar` | `EduBoard.V5.ExtendedTitleBar.Cloud` | 云盘·标题栏 | 备课时云盘区域顶部的标题栏区域 |
| `AllTitleBar` | `EduBoard.V5.ExtendedTitleBar.All` | 所有·标题栏 | 备课时所有标题栏区域的集合 |
| `TabUniqueApplicationMenu` | `EduBoard.V5.ApplicationMenu.Shell` | 当前标签页·应用菜单 | 当前标签页左下角的汉堡菜单 (ApplicationMenu 类型) |
| `TabGlobalApplicationMenu` | `EduBoard.V5.ApplicationMenu.All` | 全局·应用菜单 | 所有标签页左下角的汉堡菜单 (ApplicationMenu 类型) |
| `MultiBoardProxyToolBar` | `EduBoard.V5.MultiBoardProxyToolBar.Shell` | 多板代理·工具栏 | 多板代理的工具栏区域 |

**⚠️ 关键提示**：希沃 SDK **不包含** `ApplicationMenu` 或 `ExtendedTitleBar` 类型常量！实际使用对应的具体常量替代：
- `ApplicationMenu` → `TabUniqueApplicationMenu` / `TabGlobalApplicationMenu`
- `ExtendedTitleBar` → `BrowserTitleBar` / `CloudTitleBar` / `AllTitleBar`

## 菜单层级设计

每个菜单项都对应于 `IUIItem` 的一个具体子类，这些子类定义了特定的 UI 层级。

```csharp
// 菜单常量对应关系 (全部位于 Cvte.EasiNote 命名空间)
UIItemPurposes.BoardEditMenu       // → BoardEditMenuItem
UIItemPurposes.HeadToolBar         // → HeadToolBarItem
UIItemPurposes.TabGlobalApplicationMenu  // → ApplicationMenuItem
UIItemPurposes.AllTitleBar         // → ExtendedTitleBarItem
```

## 本项目核心组件

### 1. BetterSeewoMainWindow
**文件**：`Better-EN5/UI/BetterSeewoMainWindow.xaml.cs`
**作用**：插件的主界面，采用 16:9 横版布局，包含五个功能模块

### 2. 五大核心服务

#### InkService (课件墨迹管理)
- **功能**：导出/导入课件墨迹数据
- **技术**：反射调用希沃白板 Remark API
- **优势**：无需硬编译依赖，兼容所有版本的白板
- **应用场景**：课件备份、墨迹恢复、跨设备同步

#### ConversionService (文件转换)
- **功能**：PPT ↔ ENBX 格式互转
- **技术**：独立进程 (`EasiNote.OfficeDocumentConverter.exe`)
- **优势**：避免平台兼容性问题，保持文件原始质量

#### TouchFixService (触摸修复)
- **功能**：为非触摸大屏设备启用 IWB 模式
- **技术**：注册表 + 配置文件补丁 (`IWBConfig.json`, `TouchConfig.ini`)
- **应用场景**：大屏模式、触摸屏校准、学校多点触控

#### ActivationService (专业版激活)
- **功能**：专业版激活码验证 + 注册
- **技术**：注册表写入 + 一键安装补丁程序

### 3. UI模块

#### BoardMenuExportInk
**文件**：`Better-EN5/UI/BoardMenuExportInk.cs`
**用途**：备课模式·右键菜单，导出当前课件墨迹为 `.json` 文件

#### BoardMenuSettings
**文件**：`Better-EN5/UI/BoardMenuSettings.cs`
**用途**：备课模式·右键菜单，打开 Better-Seewo 设置界面

#### HeadToolBarSettings
**文件**：`Better-EN5/UI/HeadToolBarSettings.cs`
**用途**：通用顶级工具栏，快速打开 Better-Seewo 主界面

## 快速上手

### 1. 环境搭建
```bash
# 1. 安装 .NET 6.0 SDK
# 2. 下载并安装希沃白板 5 (5.2.2.653 ~ 5.3.0.0)
```

### 2. 构建项目
```bash
dotnet build Better-EN5/Better-EN5.csproj -c Release
```

### 3. 安装插件
#### 方式一：安装程序
```powershell
# 以管理员权限运行，自动安装到希沃白板指定目录
.
\\install.ps1
```

#### 方式二：手动部署
```powershell
# 将以下目录复制到：
# %APPDATA%\Seewo\EasiNote5\Extensions\Better-EN5\
Better-EN5\bin\Release\net6.0-windows\
Better-EN5\manifest.coin
```

### 4. 使用说明
1. **重启希沃白板 5**
2. **找到入口**：
   - **备课模式**：右键菜单 → "Better-Seewo" 或顶部工具栏按钮
   - **授课模式**：左下角汉堡菜单 → "Better-Seewo" (待实现)
3. **体验功能**：打开主界面，体验五大核心服务

## 完整开发指南

### 1. 创建新菜单项

**步骤**：
1. **选择目标常量**，确定基类
2. **创建子类**，继承对应基类
3. **实现功能成员**：`Command`、`Predicate`、`SortHint`
4. **自动注册**：无需手动处理，`AppendWithLang` 自动完成

**示例** (备课模式·右键菜单)：
```csharp
// 1. 选择 BoardEditMenu 常量（备课模式·右键菜单）
UIItemPurposes.BoardEditMenu       // → BoardEditMenuItem

// 2. 创建子类
public class ExportInkMenuItem : BoardEditMenuItem
{
    public ExportInkMenuItem()
    {
        SortHint = 100;  // 菜单项排序权重
        Command = new DelegateCommand(ExportInk);
        Predicate = _ => true;  // 总是显示
    }
}

// 3. 自动注册 (通过 AppendWithLang)
manager.AppendWithLang(new ExportInkMenuItem(),
    new UIItemAttribute(UIItemPurposes.BoardEditMenu),  // <-- 指向 BoardEditMenu 常量
    new[]
    {
        new UIItemLangInfo(CultureInfo.Chinese, "导出墨迹"),
        new UIItemLangInfo(CultureInfo.English, "Export Ink")
    });
```

### 2. 多语言支持

系统中内置完整的多语言支持框架。只需在注册时提供对应语言的文本即可。

```csharp
new[]
{
    new UIItemLangInfo(new CultureInfo("zh-CHS"), "功能名称"),
    new UIItemLangInfo(new CultureInfo("en"), "Feature Name"),
    new UIItemLangInfo(new CultureInfo("ja"), "機能名"),
}
```

### 3. 所有常量对照表与应用场景

| 菜单常量 | 所处层级 | 适用场景 | 示例 |
|---|---|---|---|
| `BoardEditMenu` | 备课模式·右键菜单 | 备课时课件上方的右键菜单 | 导出墨迹、设置、打印等 |
| `BoardDisplayMenu` | 授课模式·右键菜单 | 授课时课件上方的右键菜单 | 授课控制、评阅等 |
| `HeadToolBar` | 通用顶级工具栏 | 白板左上角的按钮 | Better-Seewo 入口 |
| `TabUniqueApplicationMenu` | 当前标签页·汉堡菜单 | 当前标签页的左下角菜单 | 单页专用功能 |
| `TabGlobalApplicationMenu` | 全局·汉堡菜单 | 所有标签页的左下角菜单 | 所有页面通用功能 |
| `AllTitleBar` | 备课·所有标题栏 | 备课时所有标题栏区域 | 标题栏菜单 |
| `BrowserTitleBar` | 备课·浏览器标题栏 | 备课时浏览器区域标题栏 | 浏览器相关操作 |
| `CloudTitleBar` | 备课·云盘标题栏 | 备课时云盘区域标题栏 | 云盘相关操作 |

## 技术要点

### 1. 菜单注册机制

```csharp
// 底层方法 (不推荐直接使用)
manager.Append(item, new UIItemAttribute(UIItemPurposes.BoardEditMenu));

// 方便易用的封装 (推荐使用)
manager.AppendWithLang(item, new UIItemAttribute(UIItemPurposes.BoardEditMenu), langInfos);
```

### 2. 大屏支持

为非触摸大屏设备提供专属支持，通过注册表和配置文件补丁实现。

### 3. 激活机制

专业版激活码验证系统，支持在线验证和离线注册。

### 4. 文件转换

使用独立进程实现 PPT ↔ ENBX 互转，避免平台兼容性问题。

### 5. 激活流程

一键启动 BEN5 注册补丁安装程序，实现专业版激活。

## 常见问题

### Q: `ApplicationMenu` 和 `ExtendedTitleBar` 是否存在？
**A**: 不存在。使用对应的具体常量替代：
- `ApplicationMenu` → `TabUniqueApplicationMenu` / `TabGlobalApplicationMenu`
- `ExtendedTitleBar` → `BrowserTitleBar` / `CloudTitleBar` / `AllTitleBar`

### Q: 菜单项如何排序？
**A**: 使用 `SortHint` 属性，数值越小排序越前。

### Q: 如何控制菜单项显示条件？
**A**: 使用 `Predicate` 属性，接收 `object` 参数，返回 `bool` 值。

### Q: 多语言如何使用？
**A**: 系统自动生成 Key `Lang.{前缀}.{菜单项类名}`，直接在 UI 中使用即可。

## 构建与发布

### 构建命令
```bash
# 调试版本
dotnet build Better-EN5/Better-EN5.csproj -c Debug

# 发布版本
dotnet build Better-EN5/Better-EN5.csproj -c Release
```

### 发布文件
```
Better-EN5/bin/Release/net6.0-windows/
├── Better-EN5.dll              # 主插件
├── BetterSeewoMainWindow.exe.config  # 配置文件
├── ... (所有依赖 DLL)
└── BetterSeewoMainWindow.xaml   # 主界面资源
```

## 许可证

本项目仅供 **学习交流** 使用。

## 致谢

感谢 dotnetCampus.EasiPlugin.Sdk 框架的支持。

---

**开发指南已根据对 `EasiNote.Api.dll` 的完整逆向工程成果生成**。所有常量和继承关系均已验证。