Skip to content

Latest commit

 

History

History
152 lines (129 loc) · 6.11 KB

dev.md

File metadata and controls

152 lines (129 loc) · 6.11 KB
Raw

组件开发指南

在开发组件之前，你需要有以下知识

还需要安装.net8 sdk
git软件，与任意一个C#开发的IDE，本指南后面使用VS2022作为示例

开发前准备

克隆源码

git clone https://github.com/Coloryr/ColorDesktop.git

构建一次ColorDesktop.Launcher

cd ColorDesktop
cd src
dotnet build

此时，会构建到./src/build_out/Debug/net8.0，你可以在这里面找到ColorDesktop.Launcher.exe

组件与显示实例概念

组件是软件的附属，组件里面有用于操作与显示的内容
显示实例是组件实例化的窗口，部分操作与显示都在这上面
组件有主页面、组件设置页面与组件实例设置页面三种页面，主页面是必须要编写的，任何一个组件都必须包含一个主页面 例如我这个时钟组件（ColorDesktop.ClockPlugin）有三个页面

- 时钟页面ClockControl（主页面）
- 时钟设置页面ClockSettingControl（组件设置页面）
- 时钟实例设置页面ClockInstanceSettingControl（组件实例设置页面）

设置页面可以按需要编写
例如我这个模拟时钟组件（ColorDesktop.AnalogClockPlugin）有两个

- 时钟页面AnalogClockControl（主页面）
- 时钟实例设置页面AnalogClockSettingControl（组件实例设置页面）

每个组件程序空间隔离，但可以设置组件见共享或加载的依赖关系

可以看到，组件A B C都由ColorDeskop加载，并且可以进行操作
组件B可以共享使用组件A的程序集，但组件A不能共享使用组件B的程序集，这是共享依赖
组件C可以独立加载组件A的程序集，但组件A不加载组件C的程序集，这是加载依赖
任何未标注依赖的组件都无法相互访问
组件都可以使用ColorDesktop的程序集（但是不推荐）

创建项目

创建一个C#运行库项目，目标SDK为.net8
引用项目./src/ColorDesktop.Api/ColorDesktop.Api.csproj

为了方便调试，你可以在构建后自动讲插件复制到ColorDesktop的组件目录中去
例如

<PropertyGroup>
	<TargetFramework>net8.0</TargetFramework>
	<ImplicitUsings>enable</ImplicitUsings>
	<Nullable>enable</Nullable>
	<AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
	<BaseOutputPath>..\build_out\Debug\net8.0\plugins\AnalogClockPlugin</BaseOutputPath>
	<ProduceReferenceAssembly>False</ProduceReferenceAssembly>
</PropertyGroup>

然后启动调试ColorDesktop.Launcher，若组件编写正确会自动加载dll与pdb文件

创建一个组件信息plugin.json

{
  //冲突ID，不能和其他组件冲突
  "ID": "coloryr.analogclock",
  //组件名字
  "Name": "模拟时钟",
  //组件描述
  "Describe": "使用表盘方式显示系统时间，依赖与组件coloryr.clock",
  //组件作者
  "Auther": "Coloryr",
  //组件程序集，就是dll的名字，在这里可以添加你的依赖库等
  "Dlls": [ "ColorDesktop.AnalogClockPlugin" ],\
  //依赖的插件
  "Dependents": [
    {
      //依赖方式 Share共享 Load加载
      "Type": "Share",
      //依赖插件的ID
      "ID": "coloryr.clock"
    }
  ],
  //组件版本号
  "Version": "1.0.0",
  //API版本号
  "ApiVersion": "1"
}

然后设置编译后复制

<ItemGroup>
	<None Update="plugin.json">
		<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
	</None>
</ItemGroup>

编写组件主入口类，需要实现接口ColorDesktop.Api.IPlugin

编写显示实例，需要实现接口ColorDesktop.Api.IInstance

组件生命周期

组件相关的生命周期有四个函数

  • Init 只在组件初始化时调用，整个生命周期只会调用一次
  • Enable 组件启用时调用，会多次调用，在组件管理界面下的启用组件就会调用这个
  • Disable 组件卸载时调用，会多次调用，在组件管理界面下的禁用组件就会调用这个
  • Stop 组件关闭时调用，整个生命周期只会调用一次，调用后组件会被卸载

显示实例生命周期

显示实例相关的生命周期有五个函数

  • CreateView 只会调用一次，需要返回一个Avalonia的Control，及显示内容
  • Start 只会调用一次，调用时窗口已经创建完毕
  • Updatge 设置显示实例相关信息，例如UUID，插件ID等，这个函数在设置显示实例完成后都会调用一次
  • RenderTick 开始更新与渲染，每帧调用一次
  • Stop 只会调用一次，调用后窗口会被关闭

创建一个显示实例会调用CreateInstanceDefault()
此时需要返回一个默认的显示实例配置

return new InstanceDataObj()
{
    Nick = "模拟时钟",
    Plugin = "coloryr.analogclock",
    Pos = PosEnum.TopRight,
    Margin = new(5)
};

之后会保存这个配置文件，然后打开显示配置的设置页面，及调用OpenSetting(InstanceDataObj instance)，你需要返回一个控件，用于设置你自己独立的显示实例配置
如果你的HaveInstanceSetting = false则不会调用这个函数

开始进行显示实例创建会调用MakeInstances(InstanceDataObj obj)，此时你需要返回一个显示实例

更多具体内容可以参考示例插件和示例显示实例

预览

如果你使用了VS2022，并安装了Avalonia插件，但是无法预览页面
此时你需要将ColorDesktop.Debug引入到你的解决方案中，添加你的组件为依赖项目，然后编译，选择启动项为ColorDesktop.Debug即可