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 层级。

// 菜单常量对应关系 (全部位于 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. 环境搭建

# 1. 安装 .NET 6.0 SDK
# 2. 下载并安装希沃白板 5 (5.2.2.653 ~ 5.3.0.0)

2. 构建项目

dotnet build Better-EN5/Better-EN5.csproj -c Release

3. 安装插件

方式一：安装程序

# 以管理员权限运行，自动安装到希沃白板指定目录
.
\\install.ps1

方式二：手动部署

# 将以下目录复制到：
# %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 自动完成

示例 (备课模式·右键菜单)：

// 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. 多语言支持

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

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. 菜单注册机制

// 底层方法 (不推荐直接使用)
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 中使用即可。

构建与发布

构建命令

# 调试版本
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 的完整逆向工程成果生成。所有常量和继承关系均已验证。