Miao-moe/Better-Seewo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity
Files
ca48d1521be87b9b82f25eff60c5c86e45b3cb56
Better-Seewo/DEVELOPER_GUIDE.md

15 KiB
Raw Blame History

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. 构建项目

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

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

3. 安装插件

方式一：安装程序

# 运行生成的安装程序
cd Better-EN5/bin/Release
dotnet tool install -g dotnetCampus.EasiPlugin.Sdk.Boost
Boost build .

方式二：手动部署

# 以管理员权限运行
.
\\install.ps1

4. 使用 Better-Seewo

  1. 重启希沃白板 5
  2. 找到 Better-Seewo 入口：
    • 备课模式：右键菜单 → Better-Seewo（或 HeadToolBar 工具栏）
    • 授课模式：左下角汉堡菜单 → Better-Seewo（待添加）
  3. 体验增强功能

完整模块示例

以下是两个完整的模块实现示例，涵盖所有开发要点。

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

文件：examples/boardeditmenu/BoardMenuExportInk.cs

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; // 总是显示
        }
    }
}

自动注册流程（不需要手动）：

// 只需一行代码即可注册到对应位置
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

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;
        }
    }
}

注册代码：

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

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. 调试构建 (开发阶段)
dotnet build Better-EN5/Better-EN5.csproj -c Debug
  1. 发布构建 (发布阶段)
dotnet build Better-EN5/Better-EN5.csproj -c Release
  1. 生成文件 (发布目录)
Better-EN5/bin/Release/
├── Better-EN5.dll           # 主插件 DLL
├── BetterSeewoMainWindow.exe.config  # 配置文件
├── ... (所有必需的依赖 DLL)
└── BetterSeewoMainWindow.xaml   # 主界面资源

发布到 GitHub Tags

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

Reference in New Issue View Git Blame Copy Permalink