插件开发入门

在开发插件之前，建议先了解一下 CCXC 插件概述和 CCXC 插件 API 参考。

后端 API 扩展：为 CCXC Engine 后端提供额外的 API 接口和业务逻辑
前端管理面板扩展：为 CCXC Admin 后台管理系统添加新的管理页面和功能模块

技术栈

后端：C# (.NET 8.0)
前端：Vue 3 + Ant Design Vue
构建工具：Vite + Node.js

准备开发环境

CCXC Engine 插件使用 Vite 作为构建工具。你需要安装 Node.js 和 npm。

同时，后端使用 .NET 8.0 开发。你需要安装 .NET 8.0 SDK。

使用 npm create 创建插件项目

可以使用 npm create 命令来创建一个新的插件项目。打开终端，执行以下命令：

bash

npm create ccxc-admin-template my-plugin

这个命令执行时会：

交互式地询问你插件的名称、描述等信息。
创建一个新的目录 my-plugin，并在其中创建一个基本的插件项目
配置后端项目的命名空间和入口类
生成前端组件模板（如果需要）

在创建结束后，你需要：

bash

# 进入新创建的插件目录
cd my-plugin

# 安装依赖
npm install

插件目录结构

my-plugin/
├── manifest.json                     # 插件配置文件
├── package.json                      # Node.js 项目配置
├── [您的后端项目名]/                   # 后端项目目录
│   ├── [项目名].csproj                # C# 项目文件
│   ├── [入口类名].cs                  # 插件入口类
│   └── Controllers/                  # API 控制器
└── src/views/                        # 前端组件（可选）
    └── [组件名].vue                   # Vue 组件

开发后端

使用 C# 来编写你的后端逻辑。

在项目建立后，默认应该已经引用了 Ccxc.Core.Plugins 包，可以通过这个包调用 CCXC Engine 的插件 API。

同时，也会引用 Ccxc.Core.DbOrm 包，提供 ORM 功能来操作数据库。

系统已经为你创建了一个入口类。使用 Visual Studio 或 VS Code 打开后端项目目录，编辑入口类。

你必须通过 Name 返回你的插件名称。

csharp

using Ccxc.Core.Plugins;

namespace MyPluginNamespace;

public class MyPlugin : IPlugin
{
    public string Name => "yt.ikp.ccxc-engine.ExamplePlugin"; // 插件名称，必须唯一。建议使用反写域名的方式命名。

    public MyPlugin(IPluginAPI api, IConfig config)
    {
        // 插件的构造函数提供了自动注入的 API 和配置对象。
        // api 提供了访问 CCXC Engine 的 API
        // config 提供了插件的配置
    }

    public Task Initialize()
    {
        // 插件初始化方法，在插件加载时调用
    }

    public Task<IEnumerable<HttpController>> RegisterControllers()
    {
        // 在这里初始化所有的HttpController，然后返回它们。
        var controllers = new List<HttpController>
        {
            new Controllers.BasicController(),
        };
        return Task.FromResult<IEnumerable<HttpController>>(controllers);
    }
}

添加 API

打开 Controllers 目录，创建一个新的 C# 类文件，例如 BasicController.cs。它必须继承 Ccxc.Core.HttpServer.HttpController 类。

csharp

using Ccxc.Core.HttpServer;
using Ccxc.Core.Plugins;
using Ccxc.Core.Plugins.DataModels;

namespace PluginBackend.Controllers;

public class BasicController : HttpController
{
    // 通过静态属性访问 IPluginAPI
    private IPluginAPI API => ExamplePlugin.API;

    // 注册一个POST请求，请注意所有请求注册的路径都不能相同。
    // 这个请求的方法签名始终为 public async Task ApiName(Request request, Response response)
    [HttpHandler("POST", "/admin/plguin/example-api")]
    public async Task ExampleApi(Request request, Response response)
    {
        // 对于任何一个请求，都可以通过先调用CheckAuth方法来确认调用者身份以及是否有权限
        var user = await API.CheckAuth(request, response, AuthLevel.Organizer);
        if (user == null) return; // 如果返回了null, 此时说明权限认证失败，相关内容在CheckAuth内部已经返回，此时只能直接return

        // 获取请求参数
        var requestJson = request.Json<ExampleRequest>();

        // 返回
        await response.JsonResponse(200, new
        {
            status = 1,
            test_req = requestJson,
            user_info = user
        });
    }
}

public class ExampleRequest
{
    public int type { get; set; }
    public string keyword { get; set; }
}

开发前端

在 src/views 目录下创建一个新的 Vue 组件文件，例如 ExampleComponent.vue。

你可以使用 Ant Design Vue 组件库来构建你的前端界面。

它们会被自然的加载到 CCXC Admin 后台管理面板中作为一个新的菜单项。

在前端组件中，有一些工具被注入到 Vue 实例中，可以通过 inject 来使用。

request - 用于发送 HTTP 请求到后端 API
MonacoEditor - Monaco 编辑器实例，用于代码编辑
ImageUploader - 图片上传组件，用于上传图片到服务器

构建

你可以使用

bash

npm run build

来构建完整的前端和后端。

也可以分别构建：

bash

# 构建前端
npm run build:f

# 构建后端
npm run build:b

提示

执行 npm run build:b 时，实际上执行了 dotnet build -C Release -o "../dist/backend/${projectName}" 命令。

构建完成后，输出文件将生成在 dist 目录下：

dist/frontend/ - 前端构建产物
dist/backend/ - 后端构建产物

配置说明

在插件根目录下有一个 manifest.json 文件。它是插件的配置文件，包含了插件的基本信息。

json

{
    "name": "com.cipherpuzzles.ccbc16.qian-plugin",
    "title": "CCBC16 四方谜/千字谜 特殊功能插件",
    "description": "实现千字谜的全局ID分配、图片上传、审核和自动发布功能",
    "version": "1.0.0",
    "author": "Ted Zyzsdy",
    "entry_assembly": "C16QianPlugin.dll",
    "entry": "C16QianPlugin.QianBackend",
    "icon": "InfoCircleOutlined",
    "frontendComponents": [
        {
            "name": "千字谜审核",
            "path": "qianReviews",
            "component": "qianReview",
            "icon": "BarChartOutlined"
        }
    ]
}

name: 插件唯一标识符（建议使用反向域名格式）
title: 插件显示名称
description: 插件描述
version: 插件版本号
author: 插件作者
entry_assembly: 后端程序集名称
entry: 插件入口类完整路径
icon: 插件图标（Ant Design 图标名称）
frontendComponents: 前端组件配置（如果有）

所有图标字段使用 Ant Design 图标名称，例如：

UserOutlined
SettingOutlined
DatabaseOutlined

完整图标列表：Ant Design Icons

插件开发入门 ​

技术栈 ​

准备开发环境 ​

使用 npm create 创建插件项目 ​

插件目录结构 ​

开发后端 ​

开发前端 ​

构建 ​

配置说明 ​

插件开发入门

技术栈

准备开发环境

使用 npm create 创建插件项目

插件目录结构

开发后端

开发前端

构建

配置说明