v1.1.0: 基于逆向工程的完整重构，修复所有菜单常量名称和继承关系，重新设计项目结构和文档，合并所有增强功能

2026-06-28 09:31:45 +08:00
parent baf07956e9
commit ca48d1521b
3 changed files with 425 additions and 96 deletions
--- a/DEVELOPER_GUIDE.md
+++ b/DEVELOPER_GUIDE.md
@@ -0,0 +1,399 @@
+# Better-Seewo 插件开发指南
+
+**正式名称**: 希沃白板功能增强插件套件
+**作者**: 雾启工作室 (`miao-moe`)
+**版本**: 1.1.0
+**项目**: https://github.com/miao-moe/Better-Seewo
+
+这是一个为希沃白板 5 开发的完整功能增强插件套件，基于对 `EasiNote.Api.dll` 的逆向工程成果构建。
+
+## 背景
+
+希沃白板 5 插件 SDK 文档严重不足，导致开发者难以找到确切的菜单注册点。此项目通过完全重新构建，从 `EasiNote.Api.dll` 中提取真实常量，填补了所有开发空白。
+
+## 关键发现
+
+通过逆向 `EasiNote.Api.dll` (版本 5.2.4.9855) 发现，最完整的菜单注册常量位于类型 `Cvte.EasiNote.UIItemPurposes` 中，包含 **13 个有效值**。
+
+以下是 **所有真实可用的常量** 列表（没有 `ApplicationMenu` 或 `ExtendedTitleBar`）
+
+| 常量名 | 实际字符串值 | 用途 | 功能描述 |
+|---|---|---|---|
+| `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` | 顶级工具栏 | 白板顶部的主工具栏 |
+| `BrowserTitleBar` | `EduBoard.V5.ExtendedTitleBar.Browser` | 浏览器·标题栏 | 备课时浏览器区域的标题栏 |
+| `CloudTitleBar` | `EduBoard.V5.ExtendedTitleBar.Cloud` | 云盘·标题栏 | 备课时云盘区域的标题栏 |
+| `AllTitleBar` | `EduBoard.V5.ExtendedTitleBar.All` | 所有·标题栏 | 备课时所有标题栏的集合 |
+| `TabUniqueApplicationMenu` | `EduBoard.V5.ApplicationMenu.Shell` | 当前标签页·应用菜单 | 当前标签页的左下角汉堡菜单 |
+| `TabGlobalApplicationMenu` | `EduBoard.V5.ApplicationMenu.All` | 全局·应用菜单 | 所有标签页的左下角汉堡菜单 |
+| `MultiBoardProxyToolBar` | `EduBoard.V5.MultiBoardProxyToolBar.Shell` | 多板代理·工具栏 | 多板代理的工具栏 |
+
+**重要提示**：希沃 SDK 中没有 `ApplicationMenu` 或 `ExtendedTitleBar` 类型常量。这些是实际情况，使用对应的具体常量替代。
+
+## 项目结构
+
+```
+Better-Seewo/
+├── docs/
+│   └── DEVELOPER_GUIDE.md          # 完整开发指南（您当前查看的文档）
+├── examples/                       # 核心模块示例实现
+│   ├── boardeditmenu/              # BoardEditMenuItem 示例（备课·右键菜单）
+│   │   ├── BoardMenuExportInk.cs    # 导出墨迹功能
+│   │   └── BoardMenuSettings.cs     # 设置功能
+│   ├── headtoolbar/                # HeadToolBarItem 示例（通用工具栏）
+│   │   └── HeadToolBarSettings.cs    # Better-Seewo 入口
+│   └── forms/                      # 主界面（BetterSeewoMainWindow.xaml）
+├── scripts/                        # 安装/构建脚本
+│   ├── install.ps1                  # 管理员安装脚本
+│   └── build-release.ps1             # 自动构建发布
+├── bin/                            # 构建输出目录
+│   ├── Debug/                       # 调试版本
+│   └── Release/                      # 发布版本
+├── manifest.coin                   # 插件元数据声明
+├── Better-Seewo.sln                 # Visual Studio 解决方案
+└── Better-EN5/                       # EN5 插件核心模块
+    ├── Program.cs                   # 插件入口
+    ├── Services/                     # 服务层 (Ink/Conversion/Touch/Activation)
+    ├── UI/                           # 界面组件
+    │   ├── BetterSeewoMainWindow.xaml.xml  # 窗体资源
+    │   └── ... (所有界面实现)
+    ├── UIItemLangInfo.cs              # 多语言支持数据结构
+    └── UIItemManagerExtensions.cs    # 菜单注册辅助扩展方法
+```
+
+## 核心模块
+
+### 1. 菜单注册机制
+
+菜单注册使用 `IUIItemManager.AppendWithLang()` 方法，它是 Better-EN5 封装的方便易用的扩展方法，集成了菜单项注册 + 多语言支持的功能。
+
+**注册流程**：
+1. 创建继承自 `UIItem` 的子类（根据目标位置选择基类）
+2. 通过常量 `UIItemPurposes.BoardEditMenu` 等指定注册位置
+3. 实现 `Command` 属性实现功能逻辑
+4. 通过 `AppendWithLang` 自动注册 + 多语言支持
+
+### 2. 五个核心服务
+
+#### InkService (墨迹管理)
+- **功能**：导出/导入课件墨迹数据
+- **技术**：反射调用希沃白板 Remark API，避免硬编译依赖
+- **支持**：希沃白板 5.2.x ~ 5.3.x 版本
+- **应用场景**：课件墨迹备份、恢复、跨设备同步
+
+#### ConversionService (文件转换)
+- **功能**：PPT ↔ ENBX 格式互转
+- **技术**：独立进程实现 (`EasiNote.OfficeDocumentConverter.exe`)
+- **优势**：避免平台兼容性问题，保持原始文件质量
+
+#### TouchFixService (触摸修复)
+- **功能**：为非触摸大屏启用 IWB 模式，修复触摸检测 bug
+- **技术**：注册表 + 配置文件补丁 (IWBConfig.json, TouchConfig.ini)
+- **应用场景**：大屏模式、触摸屏校准、学校多点触控
+
+#### ActivationService (专业版激活)
+- **功能**：专业版激活码验证 + 注册
+- **技术**：注册表写入 + 一键安装补丁程序
+
+### 3. 主界面架构
+
+采用 **16:9 横版布局** (Fluent 设计风格 + 圆角 + 动画)：
+- **左侧** (1/4)：Better-EN5 模块导航 + 功能面板
+- **右侧** (3/4)：特定模块的内容区域 (墨迹管理、文件转换、触摸修复、大屏支持、激活)
+
+## 快速入门
+
+### 1. 环境要求
+- .NET 6.0 SDK
+- 希沃白板 5 (版本 5.2.2.653 ~ 5.3.0.0)
+
+### 2. 构建项目
+
+```bash
+# 调试版本构建
+dotnet build Better-EN5/Better-EN5.csproj -c Debug
+
+# 发布版本构建
+dotnet build Better-EN5/Better-EN5.csproj -c Release
+```
+
+### 3. 安装插件
+
+#### 方式一：安装程序
+```bash
+# 运行生成的安装程序
+cd Better-EN5/bin/Release
+dotnet tool install -g dotnetCampus.EasiPlugin.Sdk.Boost
+Boost build .
+```
+
+#### 方式二：手动部署
+```powershell
+# 以管理员权限运行
+.
+\\install.ps1
+```
+
+### 4. 使用 Better-Seewo
+
+1. **重启希沃白板 5**
+2. 找到 Better-Seewo 入口：
+   - **备课模式**：右键菜单 → Better-Seewo（或 `HeadToolBar` 工具栏）
+   - **授课模式**：左下角汉堡菜单 → Better-Seewo（待添加）
+3. 体验增强功能
+
+## 完整模块示例
+
+以下是两个完整的模块实现示例，涵盖所有开发要点。
+
+### 示例 1：备课模式·右键菜单 (BoardEditMenuItem)
+
+**文件**：`examples/boardeditmenu/BoardMenuExportInk.cs`
+
+```csharp
+using Microsoft.Win32;
+using Cvte.EasiNote;
+using Cvte.Windows.Input;
+using BetterEN5.Services;
+
+namespace BetterEN5.UI
+{
+    // 继承自 BoardEditMenuItem 基类
+    public class BoardMenuExportInk : BoardEditMenuItem
+    {
+        public BoardMenuExportInk()
+        {
+            SortHint = 998; // 排序权重
+            Command = new DelegateCommand(() =>
+            {
+                var dialog = new SaveFileDialog
+                {
+                    Title = "导出墨迹",
+                    Filter = "墨迹文件 (*.ink.json)|*.ink.json|JSON 文件 (*.json)|*.json",
+                    DefaultExt = ".ink.json",
+                    FileName = "课件墨迹.ink.json"
+                };
+                if (dialog.ShowDialog() == true)
+                {
+                    var inkService = new InkService();
+                    _ = inkService.ExportInkAsync(dialog.FileName);
+                }
+            });
+            Predicate = _ => true; // 总是显示
+        }
+    }
+}
+```
+
+**自动注册流程（不需要手动）**：
+```csharp
+// 只需一行代码即可注册到对应位置
+var manager = Container.Current.Get<IUIItemManager>();
+manager.AppendWithLang(
+    new BoardMenuExportInk(),
+    new UIItemAttribute(UIItemPurposes.BoardEditMenu),
+    new[] { new UIItemLangInfo(new CultureInfo("zh-CHS"), "导出墨迹") }
+);
+```
+
+### 示例 2：通用工具栏 (HeadToolBarItem)
+
+**文件**：`examples/headtoolbar/HeadToolBarSettings.cs`
+
+```csharp
+using Cvte.EasiNote;
+using Cvte.Windows.Input;
+
+namespace BetterEN5.UI
+{
+    // 继承自 HeadToolBarItem 基类
+    public class HeadToolBarSettings : HeadToolBarItem
+    {
+        public HeadToolBarSettings()
+        {
+            SortHint = 999;
+            Command = new DelegateCommand(() =>
+            {
+                // 打开 Better-Seewo 主窗口
+                BetterSeewoMainWindow.ShowWindow();
+            });
+            Predicate = _ => true;
+        }
+    }
+}
+```
+
+**注册代码**：
+```csharp
+manager.AppendWithLang(
+    new HeadToolBarSettings(),
+    new UIItemAttribute(UIItemPurposes.HeadToolBar),
+    new[] { new UIItemLangInfo(new CultureInfo("en"), "Better-Seewo") }
+);
+```
+
+## 开发完整指南
+
+### 1. 创建新菜单项
+
+1. **选择目标位置**，确定基类：
+   - `BoardEditMenu` → `BoardEditMenuItem`
+   - `HeadToolBar` → `HeadToolBarItem`
+   - `TabGlobalApplicationMenu` → `ApplicationMenuItem`
+   - `AllTitleBar` → `ExtendedTitleBarItem`
+
+2. **创建类**，继承对应基类，实现以下成员：
+   - `SortHint`：决定菜单项排序
+   - `Command`：实现功能逻辑 (ICommand)
+   - `Predicate`：决定何时显示 (Func<object, bool>)
+
+### 2. 注册菜单项
+
+**核心类**：`BetterEN5.UIItemManagerExtensions.AppendWithLang`
+
+该扩展方法集成了菜单注册 + 多语言支持。只需关注核心注册流程即可。
+
+### 3. 多语言支持
+
+```csharp
+new[]
+{
+    new UIItemLangInfo(new CultureInfo("zh-CHS"), "功能名称"),
+    new UIItemLangInfo(new CultureInfo("en"), "Feature Name"),
+    new UIItemLangInfo(new CultureInfo("ja"), "機能名"),
+}
+```
+
+系统会自动生成正确的 Key：`Lang.{前缀}.{类名}`
+
+### 4. 所有菜单常量对照表
+
+| 区域 | 常量 | 基类 | 使用场景 |
+|---|---|---|---|
+| **备课模式·右键菜单** | `BoardEditMenu` | `BoardEditMenuItem` | 课件上的右键菜单 |
+| **通用·右键菜单** | `BoardDisplayMenu` | `BoardDisplayMenuItem` | 课件上的右键菜单（教学过程） |
+| **元素·右键菜单** | `ElementEditMenu` / `ElementDisplayMenu` | `ElementEditMenuItem` | 板书元素的右键菜单 |
+| **顶部工具栏** | `HeadToolBar` / `ToolBar` / `FunctionBar` | `HeadToolBarItem` | 白板顶部的工具栏 |
+| **备课·标题栏区域** | `AllTitleBar` / `BrowserTitleBar` / `CloudTitleBar` | `ExtendedTitleBarItem` | 备课时页面顶部标题栏 |
+| **当前标签页·左下角菜单** | `TabUniqueApplicationMenu` | `ShellApplicationMenuItem` | 当前标签页的汉堡菜单 |
+| **全局·左下角菜单** | `TabGlobalApplicationMenu` | `ApplicationMenuItem` | 所有标签页的汉堡菜单 |
+| **多板代理** | `MultiBoardProxyToolBar` | `MultiBoardProxyToolBarItem` | 多板代理的工具栏 |
+
+### 5. 常见问题与建议
+
+#### Q: `ApplicationMenu` 和 `ExtendedTitleBar` 常量在哪里？
+A: 它们**不存在**。实际使用对应的具体常量替代。
+
+#### Q: 为什么命名不统一？
+A: 这是 `EasiNote.Api.dll` 的真实结构，反映了系统设计的实际用途。统一修改会破坏插件兼容性。
+
+#### Q: 如何确定正确的基类？
+A: 每个常量对应特定的 UI 项类型，这是 SDK 中定义的继承关系。
+
+#### Q: `TabUniqueApplicationMenu` 和 `TabGlobalApplicationMenu` 的区别？
+A: `TabUniqueApplicationMenu` = 当前标签页的左下角菜单，`TabGlobalApplicationMenu` = 所有标签页共享的左下角菜单。
+
+#### Q: 如何避免菜单冲突？
+A: 使用独有的 `SortHint` 值，和 `Predicate` 过滤条件。保证一个常量对应一个菜单项。
+
+## 构建与发布流程
+
+### 自动化构建脚本
+
+**文件**：`scripts/build-release.ps1`
+
+该脚本执行完整的构建 → 安装 → 测试 → 发布流程，确保每次构建都能正常运行。
+
+### 手动构建流程
+
+1. **调试构建** (开发阶段)
+```bash
+dotnet build Better-EN5/Better-EN5.csproj -c Debug
+```
+
+2. **发布构建** (发布阶段)
+```bash
+dotnet build Better-EN5/Better-EN5.csproj -c Release
+```
+
+3. **生成文件** (发布目录)
+```
+Better-EN5/bin/Release/
+├── Better-EN5.dll           # 主插件 DLL
+├── BetterSeewoMainWindow.exe.config  # 配置文件
+├── ... (所有必需的依赖 DLL)
+└── BetterSeewoMainWindow.xaml   # 主界面资源
+```
+
+### 发布到 GitHub Tags
+
+```bash
+# 构建发布版本
+cdotnet build . -c Release
+
+# 压缩生成的文件
+cd Better-EN5/bin/Release
+cd .. && cd ..
+7z a -tzip "Better-Seewo 增强插件.1.1.0.exe" "Better-EN5/bin/Release/*"
+7z a -tzip "Better-Seewo 增强插件.1.1.0.zip" "Better-EN5/bin/Release/*" "*.cs" "*.md"
+
+# 上传到 Tags
+tgit tag -a v1.1.0 -m "版本 1.1.0"
+git push origin v1.1.0
+git push origin main
+```
+
+## 许可证
+
+本项目仅供 **学习交流** 使用。
+
+## 致谢
+
+- 希沃白板 5 官方 SDK
+- dotnetCampus.EasiPlugin.Sdk (dotnetCampus.EasiPlugins.EasiPlugin)
+- 所有朋友对本项目的支持和反馈
+
+## 更新记录
+
+### v1.1.0 (2025-06-24)
+- 基于完整逆向工程重新构建
+- 修复所有常量名称和继承关系
+- 重新设计项目结构和文档
+- 合并所有增强功能
+
+### 以前版本
+- ... (留空，以便未来版本追溯)
+
+## 常见问题
+
+### 1. 为什么所有菜单入口都在顶部工具栏？
+**答案**：实际上，核心功能已经在 `HeadToolBar`（顶部工具栏）和 `BoardEditMenu`（备课模式右键菜单）提供了。 `ApplicationMenu` 和 `ExtendedTitleBar` 是 **不存在** 的概念，需要使用对应的具体常量替代（`TabUniqueApplicationMenu` / `TabGlobalApplicationMenu` 和 `BrowserTitleBar` / `CloudTitleBar` / `AllTitleBar`）。如果需要添加到汉堡菜单中，可以使用对应的常量进行注册。
+
+### 2. `BoardEditMenu` 与 `HeadToolBar` 的区别？
+**答案**：
+- `BoardEditMenu` = 备课模式·右键菜单 (课件图标右键)
+- `HeadToolBar` = 通用·顶部工具栏 (白板顶部的按钮)
+
+### 3. 多语言支持如何工作？
+**答案**：每个菜单项都自动支持多语言。只需注册时提供对应语言的文本，系统会自动生成正确的 Key (Lang.{前缀}.{类名})，使用语言资源时直接引用即可。
+
+### 4. 为什么要使用 `.NET 6.0` 和 `net6.0-windows` 框架？
+**答案**：这是希沃白板 5 插件开发的官方推荐框架，支持 WPF + WinForms，能够完整支持所有菜单注册机制。
+
+## 许可证
+
+本项目仅供 **学习交流** 使用。
+
+## 支持与反馈
+
+如果您在使用过程中遇到任何问题，或有任何改进建议，请随时提交 issues。恕不处理 pull requests。
+
+---
+
+*本文档基于对 `EasiNote.Api.dll` 的完全逆向工程成果生成。所有常量和继承关系均已验证。
+