ColorDesktop.Api 4.0.0

组件开发指南

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

• C# 12
• axaml
• avalonia ui

还需要安装.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"
        }
    ],
    //支持的操作系统
    "Os": [
        "windows_x86_64",
        "windows_arm64",
        "linux_x86_64",
        "linux_arm64",
        "macos_x86_64",
        "macos_arm64"
    ],
    //是否不需要请求权限就能让其他组件控制
    "Permission": true,
    //是否支持重载
    "Reload": true,
    //组件版本号
    "Version": "1.0.0",
    //API版本号
    "ApiVersion": "4"
}

然后设置编译后复制

<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即可

组件公共API

在类ColorDesktop.Api.LauncherApi里面可以获取一些用于操作的API

///
/// <summary>
/// 公共数据获取，只能存基础类型
/// </summary>
/// <param name="key">键</param>
/// <param name="obj">值</param>
/// <returns>是否有数据</returns>
public static bool GetData(string key, out object? obj);
/// <summary>
/// 公共数据设置，只能存基础类型
/// </summary>
/// <param name="key">键</param>
/// <param name="obj">值</param>
public static void SetData(string key, object? obj);
/// <summary>
/// 公共数据删除
/// </summary>
/// <param name="key">键</param>
/// <returns>是否成功删除</returns>
public static bool RemoveData(string key);
/// <summary>
/// 监听事件
/// </summary>
public static void AddListener(IPlugin plugin, Action<BaseEvent> action);
/// <summary>
/// 取消所有监听
/// </summary>
/// <param name="id"></param>
public static void RemoveListener(string id);
/// <summary>
/// 触发组件事件
/// </summary>
/// <param name="pluginEvent"></param>
public static void CallEvent(BaseEvent pluginEvent);

CoreLib

这个是ColorDesktop.CoreLib组件
主要是用于将重复代码抽出来弄成一个组件方便其他组件调用

使用前需要将其以共享的方式作为依赖

{
    "Dependents": [
        {
            "Type": "Share",
            "ID": "coloryr.corelib"
        }
    ]
}