mirror of
https://github.com/wwiinnddyy/LanMountainDesktop.git
synced 2026-06-24 02:14:26 +08:00
237 lines
5.4 KiB
Markdown
237 lines
5.4 KiB
Markdown
# 02-三分钟创建第一个插件
|
||
|
||
本指南将帮助你在三分钟内创建并运行你的第一个阑山桌面插件。让我们开始吧！
|
||
|
||
---
|
||
|
||
## 🎯 目标
|
||
|
||
完成本指南后，你将：
|
||
- ✅ 创建一个可运行的插件项目
|
||
- ✅ 在宿主中成功加载插件
|
||
- ✅ 在插件列表中看到你的插件
|
||
|
||
---
|
||
|
||
## ⚡ 步骤一：创建项目（30秒）
|
||
|
||
打开终端，运行以下命令：
|
||
|
||
```powershell
|
||
# 创建插件项目
|
||
dotnet new lmd-plugin -n MyFirstPlugin
|
||
|
||
# 进入项目目录
|
||
cd MyFirstPlugin
|
||
```
|
||
|
||
✅ **成功标志：** 命令执行后没有报错，且生成了 `MyFirstPlugin` 文件夹。
|
||
|
||
---
|
||
|
||
## 📝 步骤二：配置插件信息（30秒）
|
||
|
||
打开 `plugin.json` 文件，修改以下字段：
|
||
|
||
```json
|
||
{
|
||
"id": "com.yourname.myfirstplugin",
|
||
"name": "我的第一个插件",
|
||
"description": "这是一个测试插件",
|
||
"author": "你的名字",
|
||
"version": "1.0.0",
|
||
"apiVersion": "4.0.1",
|
||
"entranceAssembly": "MyFirstPlugin.dll",
|
||
"sharedContracts": []
|
||
}
|
||
```
|
||
|
||
⚠️ **重要提示：**
|
||
- `id` 必须是唯一的，建议使用反向域名格式（如 `com.yourname.pluginname`）
|
||
- `apiVersion` 必须与 SDK 版本匹配
|
||
- 保存文件时使用 **UTF-8** 编码
|
||
|
||
---
|
||
|
||
## 🔨 步骤三：构建项目（30秒）
|
||
|
||
在终端中运行：
|
||
|
||
```powershell
|
||
# 构建项目
|
||
dotnet build
|
||
```
|
||
|
||
✅ **成功标志：** 看到类似以下的输出：
|
||
```
|
||
生成成功。
|
||
0 个警告
|
||
0 个错误
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 步骤四：找到插件包（15秒）
|
||
|
||
构建完成后，插件包位于：
|
||
|
||
```
|
||
MyFirstPlugin/
|
||
└── bin/
|
||
└── Debug/
|
||
└── net10.0/
|
||
└── MyFirstPlugin.laapp <-- 这就是插件包！
|
||
```
|
||
|
||
⚠️ **什么是 .laapp 文件？**
|
||
- `.laapp` 是阑山桌面的插件包格式
|
||
- 本质上是一个 ZIP 压缩包，包含插件 DLL 和资源文件
|
||
- 不要解压，直接安装即可
|
||
|
||
---
|
||
|
||
## 🚀 步骤五：安装到宿主（30秒）
|
||
|
||
1. **启动阑山桌面**（如果尚未运行）
|
||
|
||
2. **打开设置**：
|
||
- 右键点击桌面上的阑山桌面图标
|
||
- 选择「设置」
|
||
|
||
3. **进入插件管理**：
|
||
- 在设置窗口左侧选择「插件」
|
||
|
||
4. **安装本地插件**：
|
||
- 点击「安装本地插件」按钮
|
||
- 选择刚才生成的 `.laapp` 文件
|
||
- 点击「打开」
|
||
|
||
5. **重启宿主**：
|
||
- 安装完成后，点击「重启」按钮
|
||
- 阑山桌面将重新启动
|
||
|
||
---
|
||
|
||
## ✅ 步骤六：验证安装（15秒）
|
||
|
||
重启后，再次打开设置 → 插件：
|
||
|
||
🎉 **成功标志：**
|
||
- 在插件列表中看到「我的第一个插件」
|
||
- 状态显示为「已启用」
|
||
- 作者显示为你设置的名字
|
||
|
||
|
||
|
||
---
|
||
|
||
## 📂 生成的项目结构
|
||
|
||
你的项目现在包含以下文件：
|
||
|
||
```
|
||
MyFirstPlugin/
|
||
├── plugin.json # 插件清单文件
|
||
├── MyFirstPlugin.csproj # 项目文件
|
||
├── Plugin.cs # 插件入口类
|
||
├── README.md # 项目说明
|
||
└── Localization/ # 本地化文件夹
|
||
├── zh-CN.json # 中文资源
|
||
└── en-US.json # 英文资源
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 查看插件代码
|
||
|
||
打开 `Plugin.cs`，你会看到：
|
||
|
||
```csharp
|
||
using LanMountainDesktop.PluginSdk;
|
||
using Microsoft.Extensions.DependencyInjection;
|
||
using Microsoft.Extensions.Hosting;
|
||
|
||
namespace MyFirstPlugin;
|
||
|
||
[PluginEntrance]
|
||
public sealed class Plugin : PluginBase
|
||
{
|
||
public override void Initialize(HostBuilderContext context, IServiceCollection services)
|
||
{
|
||
// 插件初始化代码
|
||
// 在这里注册组件、设置页面等
|
||
}
|
||
}
|
||
```
|
||
|
||
**关键点：**
|
||
- `[PluginEntrance]` 特性标记入口类
|
||
- 继承 `PluginBase` 基类
|
||
- `Initialize` 方法是插件的初始化入口
|
||
|
||
---
|
||
|
||
## 🎉 恭喜！
|
||
|
||
你已经成功创建并安装了第一个阑山桌面插件！
|
||
|
||
虽然这个插件目前还没有任何功能，但你已经掌握了：
|
||
- ✅ 使用模板创建项目
|
||
- ✅ 配置插件信息
|
||
- ✅ 构建插件包
|
||
- ✅ 安装到宿主
|
||
|
||
---
|
||
|
||
## 🚦 常见问题
|
||
|
||
### 问题 1：构建失败，提示找不到 SDK
|
||
|
||
**现象：** 错误信息包含 "SDK not found"
|
||
|
||
**解决：**
|
||
1. 确认已安装 .NET 10 SDK：`dotnet --version`
|
||
2. 检查 `global.json` 中的版本要求
|
||
|
||
### 问题 2：宿主提示插件安装失败
|
||
|
||
**现象：** 安装时弹出错误对话框
|
||
|
||
**排查步骤：**
|
||
1. 检查 `plugin.json` 是否为有效的 JSON 格式
|
||
2. 确认 `id` 字段唯一且合法（只能包含字母、数字、点号）
|
||
3. 确认 `apiVersion` 与 SDK 版本匹配
|
||
|
||
### 问题 3：插件列表中不显示
|
||
|
||
**现象：** 安装后重启，但列表中没有
|
||
|
||
**排查步骤：**
|
||
1. 确认已点击「重启」按钮
|
||
2. 检查日志文件：`%LOCALAPPDATA%\LanMountainDesktop\logs\`
|
||
3. 确认 `.laapp` 文件完整未损坏
|
||
|
||
---
|
||
|
||
## 🎯 下一步
|
||
|
||
现在你的插件已经能运行了，接下来学习：
|
||
|
||
👉 **[03-插件项目结构详解](03-插件项目结构详解.md)** - 深入理解每个文件的作用
|
||
|
||
或者直接进入实战：
|
||
|
||
👉 **[02-桌面组件系统](../02-核心概念与原理/02-桌面组件系统.md)** - 创建你的第一个桌面组件！
|
||
|
||
---
|
||
|
||
## 💡 小贴士
|
||
|
||
- **快速重建**：修改代码后，只需运行 `dotnet build` 即可重新生成 `.laapp`
|
||
- **自动安装**：可以在 IDE 中配置构建后自动复制到宿主插件目录
|
||
- **日志调试**：使用 `ILogger` 记录日志，在 `%LOCALAPPDATA%\LanMountainDesktop\logs\` 查看
|
||
|
||
---
|
||
|
||
*最后更新：2026年4月*
|