264 lines
10 KiB
Markdown
264 lines
10 KiB
Markdown
# 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` 的完整逆向工程成果生成**。所有常量和继承关系均已验证。
|