OneMore社区贡献指南：如何参与开源项目开发

OneMore社区贡献指南：如何参与开源项目开发

【免费下载链接】OneMoreA OneNote add-in with simple, yet powerful and useful features项目地址: https://gitcode.com/gh_mirrors/on/OneMore

OneMore是一款为OneNote设计的功能强大的插件，通过简单而实用的功能增强OneNote的使用体验。本文将为你提供一份完整的社区贡献指南，帮助你轻松参与到这个开源项目的开发中，无论是新手还是有经验的开发者，都能在这里找到适合自己的贡献方式。

一、开发环境搭建：快速开始你的贡献之旅 🚀

要参与OneMore的开发，首先需要搭建合适的开发环境。以下是详细的步骤：

1.1 必备条件

在开始之前，请确保你的系统满足以下要求：

• Windows 10 或更高版本
• Microsoft Visual Studio 2022（社区版即可）
• .NET Framework 4.8 SDK 和目标包
• Microsoft OneNote 2016 或更高版本（32位或64位）

1.2 安装Visual Studio组件

OneMore基于C# 9和.NET Framework开发，需要安装以下Visual Studio组件：

.NET Framework 4.8

确保安装.NET Framework 4.8的SDK和目标包，这是项目开发的基础框架。

Visual Studio Tools for Office (VSTO)

这是开发Office插件的关键组件，它会安装必要的Office互操作程序集。安装后，这些程序集通常位于C:\Program Files (x86)\Microsoft Visual Studio\Shared\Visual Studio Tools for Office\PIA\Office15目录下。

图：Visual Studio中需要安装的VSTO组件

Windows SDK

安装最新版本的Windows SDK，OneMore需要引用其中的Windows.winmd文件来支持PDF处理等功能。安装后，可以通过项目根目录下的update-sdk.ps1脚本自动更新项目引用。

1.3 安装Visual Studio Installer Projects扩展

为了能够构建OneMore的安装程序，需要安装Visual Studio 2022 Installer Projects扩展。你可以通过项目根目录下的install-vsix.ps1脚本自动安装：

PS C:\Github\OneMore> .\install-vsix.ps1

1.4 配置NuGet选项

确保在Visual Studio的NuGet包源中包含nuget.org（https://api.nuget.org/v3/index.json），以便能够获取项目所需的依赖包。

图：Visual Studio中的NuGet包源配置

二、获取项目代码：开始你的贡献之旅

2.1 克隆代码仓库

首先，将OneMore项目的代码克隆到本地：

git clone https://gitcode.com/gh_mirrors/on/OneMore

2.2 更新项目引用

Windows SDK版本可能会频繁更新，因此需要确保项目引用的SDK版本与你安装的版本一致。可以通过以下命令自动更新：

PS C:\Github\OneMore> .\update-sdk.ps1

2.3 配置注册表

OneNote COM插件需要在Windows注册表中进行配置。在首次构建解决方案后，可以使用setregistry.ps1脚本创建必要的注册表项：

PS C:\Github\OneMore> .\setregistry.ps1

你还可以运行iq.ps1脚本来验证设置是否正确：

PS C:\Github\OneMore> .\iq.ps1

三、贡献代码：从添加新命令开始

OneMore的核心功能是通过各种命令实现的。添加新命令是参与贡献的好方式，以下是详细步骤：

3.1 命令的组织结构

命令按照功能域进行分类，例如Clean、Edit、File、Images等，对应的代码位于Commands目录下的相应子目录中。如果你的新命令不适合现有分类，可以考虑添加到Extras或Tools目录，或者创建新的功能域目录。

3.2 创建命令类

1. 在合适的功能域目录下创建一个新的类文件，类名应遵循NameCommand的命名规范，例如TrimCommand.cs。

2. 确保类位于River.OneMoreAddIn.Commands命名空间下，继承自Command基类，并声明为internal。

3. 添加一个公共构造函数，并覆盖Execute方法。

示例代码：

namespace River.OneMoreAddIn.Commands { internal class TrimCommand : Command { public TrimCommand() { } public override async Task Execute(params object[] args) { // 命令实现代码 } } }

3.3 在AddinCommands.cs中添加命令调用方法

在AddinCommands.cs文件中添加一个新的方法，方法名应遵循NameCmd的命名规范，例如TrimCmd。该方法必须声明为async，接受IRibbonControl参数，并通过factory.Run调用命令。

示例代码：

[Command("ribTrimButton_Label", Keys.None, "ribCleanMenu")] public async Task TrimCmd(IRibbonControl control) => await factory.Run<TrimCommand>(false);

Command属性的参数说明：

• 第一个参数：资源ID，用于命令名称的本地化
• 第二个参数：默认快捷键，设置为Keys.None表示无快捷键
• 第三个参数：功能域（供将来使用）

3.4 在Ribbon.xml中添加按钮或菜单项

在Ribbon\Ribbon.xml文件中添加一个按钮或菜单项，指定唯一的id、imageMso（图标）和onAction（命令方法）。

示例代码：

<button id="ribTrimButton" imageMso="AutoTextGallery" getLabel="GetRibbonLabel" onAction="TrimCmd"/>

你可以从imageMso List中选择合适的图标。

四、测试你的贡献：确保代码质量

4.1 运行和调试

在Visual Studio中设置OneNote为启动项目，然后按F5开始调试。这将启动OneNote，并加载你的开发版本的OneMore插件。

4.2 单元测试

项目提供了一些烟雾测试（Smoke Tests），位于OneMoreSmokeTests目录下。你可以运行这些测试来验证基本功能是否正常工作。

4.3 代码审查

在提交Pull Request之前，请确保你的代码符合项目的编码规范，并通过了所有测试。项目维护者会对你的代码进行审查，提供反馈并帮助你改进。

五、提交贡献：成为OneMore社区的一员

5.1 创建Pull Request

当你的代码准备就绪后，提交一个Pull Request到项目仓库。在PR中请清晰描述你的改动内容、实现的功能以及测试情况。

5.2 参与讨论

积极参与项目的Issue讨论，帮助解决其他用户的问题，或者提出新的功能建议。你的参与将有助于项目的不断改进和发展。

六、其他贡献方式：不止于代码

除了编写代码，你还可以通过以下方式为OneMore贡献力量：

6.1 文档改进

项目的文档位于docs目录下，如果你发现文档中有错误或可以改进的地方，欢迎提交修改。

6.2 翻译

帮助将OneMore的界面和文档翻译成其他语言，让更多地区的用户能够使用这个优秀的插件。相关资源文件位于Properties目录下，如Resources.de-DE.resx等。

6.3 测试和反馈

使用OneMore并报告发现的bug，提供使用反馈和功能建议，这对于项目的改进同样重要。

结语

OneMore的成长离不开每一位社区成员的贡献。无论你是经验丰富的开发者还是刚刚入门的新手，都能在这里找到适合自己的贡献方式。希望这份指南能帮助你顺利参与到项目中，让我们一起让OneMore变得更加完善！ 🎉

如果你在贡献过程中遇到任何问题，可以查阅项目的开发者文档或在社区中寻求帮助。期待你的加入！

【免费下载链接】OneMoreA OneNote add-in with simple, yet powerful and useful features项目地址: https://gitcode.com/gh_mirrors/on/OneMore