miao-moe/LanMountainDesktop
1
0
Fork 0
mirror of https://github.com/wwiinnddyy/LanMountainDesktop.git synced 2026-06-24 18:44:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat.文档更新

Browse Source
This commit is contained in:
lincube
2026-06-08 03:54:33 +08:00
parent 7db72fbcd0
commit 49af6601aa
247 changed files with 2939 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

345
docs/01-插件开发/01-快速开始/01-环境准备.md Normal file
View File

@@ -0,0 +1,345 @@
# 插件开发 - 环境准备
## 前置要求
在开始开发插件之前，请确保你已经：
- ✅ 安装了 .NET 10 SDK
- ✅ 安装了支持 C# 的 IDE（Visual Studio 2022 / Rider / VS Code）
- ✅ 了解 C# 基础语法
- ✅ 了解 Avalonia UI 基础（或 WPF，两者相似）
> 如果还没有配置开发环境，请先阅读 [开发环境配置](../../00-快速开始/03-开发环境配置.md)
## 安装插件模板
### 安装官方模板
阑山桌面提供了官方的插件项目模板，可以快速创建插件项目骨架。
```powershell
# 安装插件模板包
dotnet new install LanMountainDesktop.PluginTemplate
# 验证安装成功
dotnet new list | Select-String "lmd"
```
你应该看到类似输出：
```
lmd-plugin LanMountainDesktop Plugin C# LanMountainDesktop/Plugin
```
### 模板版本管理
```powershell
# 查看已安装的模板
dotnet new list lmd
# 更新到最新版本
dotnet new install LanMountainDesktop.PluginTemplate --force
# 卸载模板
dotnet new uninstall LanMountainDesktop.PluginTemplate
```
## 创建第一个插件项目
### 使用模板创建项目
```powershell
# 创建新插件项目
dotnet new lmd-plugin -n MyFirstPlugin
# 进入项目目录
cd MyFirstPlugin
```
### 项目结构
创建后的项目结构如下：
```
MyFirstPlugin/
├── MyFirstPlugin.csproj # 项目文件
├── Plugin.cs # 插件入口类
├── plugin.json # 插件清单
├── Components/ # 组件目录
│ └── SampleComponent.cs # 示例组件
├── Views/ # 视图目录
│ └── SampleComponentView.axaml # 组件视图
│ └── SampleComponentView.axaml.cs # 视图代码后台
├── ViewModels/ # 视图模型
│ └── SampleComponentViewModel.cs # 组件视图模型
├── Settings/ # 设置页目录
│ └── PluginSettingsPage.axaml # 设置页视图
│ └── PluginSettingsPage.axaml.cs # 设置页代码
├── Assets/ # 资源目录
│ └── icon.png # 插件图标
└── Localization/ # 本地化目录
└── Strings.resx # 字符串资源
```
## 理解插件清单
### plugin.json 文件
`plugin.json` 是插件的元数据文件，定义了插件的基本信息。
```json
{
"Id": "com.example.myfirstplugin",
"Name": "My First Plugin",
"Version": "1.0.0",
"Author": "Your Name",
"Description": "My first LanMountainDesktop plugin",
"MinHostVersion": "1.0.0",
"SdkVersion": "5.0.0",
"Dependencies": [],
"Permissions": [
"Network.Access"
],
"Icon": "Assets/icon.png",
"Homepage": "https://github.com/yourusername/myfirstplugin",
"Repository": "https://github.com/yourusername/myfirstplugin.git"
}
```
### 字段说明
| 字段 | 必需 | 说明 |
|------|------|------|
| `Id` | ✅ | 插件唯一标识符，建议使用反向域名格式 |
| `Name` | ✅ | 插件显示名称 |
| `Version` | ✅ | 插件版本号，遵循语义化版本 |
| `Author` | ✅ | 插件作者 |
| `Description` | ✅ | 插件简介 |
| `MinHostVersion` | ✅ | 最低宿主版本要求 |
| `SdkVersion` | ✅ | 使用的 SDK 版本 |
| `Dependencies` | ❌ | 依赖的其他插件 ID 列表 |
| `Permissions` | ❌ | 插件所需权限列表 |
| `Icon` | ❌ | 插件图标路径 |
| `Homepage` | ❌ | 插件主页 URL |
| `Repository` | ❌ | 源码仓库 URL |
### 版本号规范
插件版本号遵循 [语义化版本 2.0.0](https://semver.org/lang/zh-CN/)：
```
主版本号.次版本号.修订号
例如: 1.2.3
```
- **主版本号**: 不兼容的 API 修改
- **次版本号**: 向下兼容的功能性新增
- **修订号**: 向下兼容的问题修正
## 理解项目文件
### MyFirstPlugin.csproj
```xml
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
<!-- 插件元数据 -->
<PluginId>com.example.myfirstplugin</PluginId>
<PluginName>My First Plugin</PluginName>
<PluginVersion>1.0.0</PluginVersion>
<!-- 禁用可执行文件生成，插件是类库 -->
<OutputType>Library</OutputType>
</PropertyGroup>
<ItemGroup>
<!-- Plugin SDK -->
<PackageReference Include="LanMountainDesktop.PluginSdk" Version="5.0.0" />
<PackageReference Include="LanMountainDesktop.Shared.Contracts" Version="5.0.0" />
<!-- Avalonia UI -->
<PackageReference Include="Avalonia" Version="12.0.1" />
<PackageReference Include="Avalonia.Themes.Fluent" Version="12.0.1" />
<!-- MVVM Toolkit -->
<PackageReference Include="CommunityToolkit.Mvvm" Version="8.2.2" />
</ItemGroup>
<!-- 复制 plugin.json 到输出目录 -->
<ItemGroup>
<None Update="plugin.json">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</None>
<None Update="Assets\**">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</None>
</ItemGroup>
<!-- Avalonia 编译支持 -->
<ItemGroup>
<AvaloniaResource Include="**\*.axaml" />
</ItemGroup>
</Project>
```
### 关键配置项
- **TargetFramework**: 必须是 `net10.0`
- **OutputType**: 必须是 `Library`（插件是类库，不是可执行文件）
- **Nullable**: 建议启用，提高代码质量
- **PluginId/PluginName/PluginVersion**: 应与 `plugin.json` 保持一致
## 构建插件
### 还原依赖
```powershell
dotnet restore
```
### 构建项目
```powershell
# Debug 模式
dotnet build
# Release 模式
dotnet build -c Release
```
### 查看输出
构建成功后，输出目录结构：
```
bin/Debug/net10.0/
├── MyFirstPlugin.dll # 主程序集
├── MyFirstPlugin.pdb # 调试符号
├── plugin.json # 插件清单
├── Assets/ # 资源文件
│ └── icon.png
└── *.dll # 依赖程序集
```
## 调试插件
### 方法一：复制到插件目录（推荐）
```powershell
# 构建插件
dotnet build
# 复制到宿主的插件目录
$pluginDir = "$env:LOCALAPPDATA\LanMountainDesktop\plugins\MyFirstPlugin"
New-Item -ItemType Directory -Path $pluginDir -Force
Copy-Item -Path "bin\Debug\net10.0\*" -Destination $pluginDir -Recurse -Force
# 启动宿主应用
# （确保宿主在 Debug 模式下构建，这样可以附加调试器）
```
### 方法二：使用符号链接
在开发模式下，可以创建符号链接避免每次复制：
```powershell
# 创建符号链接（需要管理员权限）
$pluginDir = "$env:LOCALAPPDATA\LanMountainDesktop\plugins\MyFirstPlugin"
$buildDir = "$(pwd)\bin\Debug\net10.0"
New-Item -ItemType SymbolicLink -Path $pluginDir -Target $buildDir -Force
```
### 方法三：配置宿主调试路径
如果你有宿主源码，可以修改宿主的插件搜索路径指向你的插件构建目录。
在宿主项目的 `appsettings.Development.json` 中：
```json
{
"PluginPaths": [
"C:\\Dev\\MyFirstPlugin\\bin\\Debug\\net10.0"
]
}
```
### 附加调试器
1. 启动宿主应用（LanMountainDesktop）
2. 在 Visual Studio 中，选择"调试" → "附加到进程"
3. 找到 `LanMountainDesktop.exe` 进程
4. 点击"附加"
5. 在插件代码中设置断点
## 查看日志
### 日志位置
```
%LOCALAPPDATA%\LanMountainDesktop\logs\latest.log
```
### 实时查看日志
```powershell
# PowerShell
Get-Content "$env:LOCALAPPDATA\LanMountainDesktop\logs\latest.log" -Wait -Tail 50
```
### 日志级别
- **Trace**: 最详细的信息，用于诊断
- **Debug**: 调试信息
- **Information**: 一般信息
- **Warning**: 警告信息
- **Error**: 错误信息
- **Critical**: 严重错误
## 常见问题
### 插件没有被加载
**检查清单**:
1. 确认 `plugin.json` 存在且格式正确
2. 确认插件 DLL 文件存在
3. 查看日志文件中的错误信息
4. 确认插件 ID 唯一，没有与其他插件冲突
5. 确认 SDK 版本匹配
### 编译错误：找不到类型
**问题**: `error CS0246: The type or namespace name 'IPlugin' could not be found`
**解决方案**:
```powershell
# 确认引用了 PluginSdk
dotnet add package LanMountainDesktop.PluginSdk --version 5.0.0
# 清理并重新构建
dotnet clean
dotnet build
```
### Avalonia 视图无法编译
**问题**: AXAML 文件编译错误
**解决方案**:
1. 确认安装了 Avalonia NuGet 包
2. 检查 AXAML 语法是否正确
3. 确认 `AvaloniaResource` 项已配置在 csproj 中
4. 清理并重新构建项目
## 下一步
现在你已经完成了环境准备，可以继续：
- [创建第一个插件](02-创建第一个插件.md) - 实现插件功能
- [插件生命周期](../02-核心概念/01-插件生命周期.md) - 理解插件运行机制
- [组件系统](../02-核心概念/02-组件系统.md) - 创建桌面组件

266
docs/01-插件开发/README.md Normal file
View File

@@ -0,0 +1,266 @@
# 插件开发完整指南
欢迎来到阑山桌面插件开发指南！本章节将带你从零开始，掌握插件开发的完整流程。
## 📚 学习路径
### 初学者路径
如果你是第一次开发阑山桌面插件，请按以下顺序学习：
1. **[环境准备](01-快速开始/01-环境准备.md)** - 配置开发环境和工具
2. **[创建第一个插件](01-快速开始/02-创建第一个插件.md)** - 快速上手
3. **[插件生命周期](02-核心概念/01-插件生命周期.md)** - 理解插件运行机制
4. **[组件系统](02-核心概念/02-组件系统.md)** - 创建桌面组件
### 进阶路径
已经了解基础，想要深入学习？
1. **[设置系统](02-核心概念/03-设置系统.md)** - 管理插件配置
2. **[主题与外观](02-核心概念/04-主题外观.md)** - 适配暗色/亮色模式
3. **[插件通信](02-核心概念/05-插件通信.md)** - 插件间数据交互
4. **[IPC 公共服务](03-API参考/05-IPC公共服务.md)** - 对外提供服务
### 实战路径
通过完整案例学习：
1. **[天气组件插件](04-实战案例/01-天气组件.md)** - 完整的组件开发
2. **[待办事项插件](04-实战案例/02-待办事项.md)** - 数据持久化
3. **[RSS 阅读器](04-实战案例/03-RSS阅读器.md)** - 网络请求和列表展示
4. **[系统监控插件](04-实战案例/04-系统监控.md)** - 系统信息获取
## 🎯 核心概念
### 什么是插件？
插件是扩展阑山桌面功能的独立模块，可以：
- ✅ 添加新的桌面组件（Widget）
- ✅ 注册设置页面
- ✅ 提供后台服务
- ✅ 与其他插件通信
- ✅ 对外提供 IPC 服务
### 插件架构
```
┌─────────────────────────────────────┐
│ LanMountainDesktop Host │
│ (桌面宿主 - 主程序) │
├─────────────────────────────────────┤
│ Plugin Runtime (插件运行时) │
│ ┌────────────┐ ┌────────────┐ │
│ │ Plugin A │ │ Plugin B │ │
│ ├────────────┤ ├────────────┤ │
│ │ Components │ │ Components │ │
│ │ Settings │ │ Settings │ │
│ │ Services │ │ Services │ │
│ └────────────┘ └────────────┘ │
└─────────────────────────────────────┘
```
### 插件 SDK 版本
| SDK 版本 | 发布时间 | 主要特性 |
|---------|---------|---------|
| **5.0.0** | 2025.05 | 当前版本 - 进程隔离准备、IPC 公共服务 |
| 4.0.0 | 2025.03 | 组件系统重构、设置域管理 |
| 3.0.0 | 2025.01 | Avalonia 12 升级 |
| 2.0.0 | 2024.11 | 稳定 API，插件市场支持 |
| 1.0.0 | 2024.09 | 初始版本 |
## 📖 文档结构
### [01-快速开始](01-快速开始/)
快速上手，从零到一创建插件
- [环境准备](01-快速开始/01-环境准备.md) - 安装工具和模板
- [创建第一个插件](01-快速开始/02-创建第一个插件.md) - 实现基本功能
- [调试与测试](01-快速开始/03-调试测试.md) - 调试技巧
- [打包插件](01-快速开始/04-打包插件.md) - 生成 .laapp 文件
### [02-核心概念](02-核心概念/)
深入理解插件系统的工作原理
- [插件生命周期](02-核心概念/01-插件生命周期.md) - 加载、初始化、卸载
- [组件系统](02-核心概念/02-组件系统.md) - 桌面组件的创建和管理
- [设置系统](02-核心概念/03-设置系统.md) - 配置持久化
- [主题与外观](02-核心概念/04-主题外观.md) - 适配主题和圆角系统
- [插件通信](02-核心概念/05-插件通信.md) - 插件间协作
### [03-API参考](03-API参考/)
完整的 API 文档和使用示例
- [IPlugin 接口](03-API参考/01-IPlugin接口.md) - 插件入口
- [IPluginContext](03-API参考/02-IPluginContext.md) - 插件上下文
- [组件 API](03-API参考/03-组件API.md) - 组件开发接口
- [设置 API](03-API参考/04-设置API.md) - 设置管理接口
- [IPC 公共服务](03-API参考/05-IPC公共服务.md) - 对外服务接口
- [日志 API](03-API参考/06-日志API.md) - 日志记录
### [04-实战案例](04-实战案例/)
通过完整示例学习插件开发
- [天气组件](04-实战案例/01-天气组件.md) - API 调用、数据展示
- [待办事项](04-实战案例/02-待办事项.md) - 数据持久化、CRUD
- [RSS 阅读器](04-实战案例/03-RSS阅读器.md) - 网络请求、列表
- [系统监控](04-实战案例/04-系统监控.md) - 系统信息、实时更新
### [05-发布维护](05-发布维护/)
插件的发布、更新和维护
- [版本管理](05-发布维护/01-版本管理.md) - 语义化版本
- [CI/CD 配置](05-发布维护/02-CICD配置.md) - 自动构建
- [发布到市场](05-发布维护/03-发布市场.md) - 插件市场发布
- [用户反馈](05-发布维护/04-用户反馈.md) - 收集和处理反馈
- [迁移指南](05-发布维护/05-迁移指南.md) - SDK 版本升级
## 🚀 快速参考
### 创建插件
```powershell
# 安装模板
dotnet new install LanMountainDesktop.PluginTemplate
# 创建项目
dotnet new lmd-plugin -n MyPlugin
# 构建
dotnet build
```
### 插件入口
```csharp
public class Plugin : IPlugin
{
public string Id => "com.example.myplugin";
public string Name => "My Plugin";
public string Version => "1.0.0";
public async Task InitializeAsync(IPluginContext context)
{
// 注册组件
var registry = context.Services.GetService<IComponentRegistry>();
registry?.RegisterComponent<MyComponent>();
}
public Task ShutdownAsync() => Task.CompletedTask;
}
```
### 创建组件
```csharp
[Component(
Id = "com.example.myplugin.mycomponent",
Name = "我的组件",
Category = "工具"
)]
public class MyComponent : ComponentBase
{
public override string Id => "com.example.myplugin.mycomponent";
public override string Name => "我的组件";
}
```
## 💡 最佳实践
### 代码规范
- ✅ 使用异步编程（`async/await`）
- ✅ 启用可空引用类型（`nullable enable`）
- ✅ 编写 XML 文档注释
- ✅ 遵循 C# 命名约定
- ✅ 使用依赖注入模式
### 性能优化
- ✅ 避免阻塞 UI 线程
- ✅ 使用延迟加载
- ✅ 缓存数据避免重复计算
- ✅ 及时释放资源（实现 `IDisposable`）
- ✅ 使用弱事件模式避免内存泄漏
### 用户体验
- ✅ 适配亮色/暗色主题
- ✅ 支持多语言本地化
- ✅ 提供友好的错误提示
- ✅ 响应式设计适配不同分辨率
- ✅ 提供设置页让用户自定义
## 🔗 相关资源
### 官方资源
- [GitHub 仓库](https://github.com/HelloWRC/LanMountainDesktop)
- [插件示例](https://github.com/HelloWRC/LanMountainDesktop.SamplePlugin)
- [SDK 源码](https://github.com/HelloWRC/LanMountainDesktop/tree/main/LanMountainDesktop.PluginSdk)
- [问题反馈](https://github.com/HelloWRC/LanMountainDesktop/issues)
### 技术文档
- [Avalonia UI 文档](https://docs.avaloniaui.net/)
- [FluentAvalonia 文档](https://github.com/amwx/FluentAvalonia/wiki)
- [CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/)
- [.NET API 浏览器](https://learn.microsoft.com/dotnet/api/)
### 社区
- [GitHub Discussions](https://github.com/HelloWRC/LanMountainDesktop/discussions) - 技术讨论
- [插件市场](https://github.com/HelloWRC/LanMountainDesktop/wiki/Plugins) - 浏览现有插件
## ❓ 常见问题
### 我需要什么基础？
- **必需**: C# 基础语法、面向对象编程
- **推荐**: XAML/Avalonia UI 基础、MVVM 模式
- **加分**: 异步编程、依赖注入
### 插件可以做什么？
插件可以：
- ✅ 添加桌面组件（显示天气、时钟、待办等）
- ✅ 添加设置页面
- ✅ 提供后台服务（定时任务、数据同步等）
- ✅ 与其他插件通信
- ✅ 通过 IPC 对外提供服务
插件不能：
- ❌ 修改宿主核心代码
- ❌ 直接访问其他插件的私有数据
- ❌ 绕过权限系统访问敏感资源
### 如何调试插件？
1. 将插件构建到宿主的插件目录
2. 启动宿主应用
3. 使用 IDE 附加到宿主进程
4. 在插件代码中设置断点
详见 [调试与测试](01-快速开始/03-调试测试.md)
### 插件会被隔离运行吗？
当前插件运行在宿主进程内（in-process 模式），未来将支持进程隔离模式：
- **当前**: 进程内插件，共享内存空间
- **未来**: 进程隔离插件，独立进程运行（计划中）
## 🎯 下一步
准备开始了吗？
- [环境准备](01-快速开始/01-环境准备.md) - 配置开发环境
- [创建第一个插件](01-快速开始/02-创建第一个插件.md) - 动手实践
- [插件生命周期](02-核心概念/01-插件生命周期.md) - 理解原理