Plugins

插件开发-api参考-Server&UI

halo 基础组件库

编辑器和文章渲染提供 KaTeX

在 plugin.yaml 中配置 settingName 和 configMapName 字段：
对应到extensions/setting.yaml

在 Halo 通知系统中，ReasonType 和 Reason 是两个核心自定义模型，用于定义通知事件的类别和具体的事件实例。 
理解它们的字段对于开发者扩展通知功能至关重要。

主题模板中使用自定义模型时, 创建一个自定义的 finder 来实现

为插件创建一个模板,要提供一个路由用于渲染这个模板

从 Halo 2.15.0 版本开始，核心提供了 WebSocketEndpoint 接口，其主要目的是为了方便插件实现 WebSocket 功能。

登录增强器
Halo 提供了一个 LoginHandlerEnhancer 的 Bean，插件可以通过依赖注入的方式在合适的位置调用该 Bean 的方法，以便 Halo 可以在登录成功或失败后执行逻辑切入。

插件中外部静态资源如图片,
首先需要在 src/main/resources/extensions 下创建一个 yaml，文件名可以任意。
声明 ReverseProxy 对象如下：
apiVersion: plugin.halo.run/v1alpha1
kind: ReverseProxy
metadata:
  # 为了避免与其他插件冲突，推荐带上插件名称前缀
  name: my-plugin-fake-reverse-proxy
rules:
  - path: /res/**
    file:
      directory: static
      # 如果想代理 static 下所有静态资源则省略 filename 配置
      filename: halo.jpg
      
该 ReverseProxy 的访问路径为：/plugins/my-plugin/assets/res/halo.jpg。

自定义模型

自定义模型 API

定义并注册自定义模型后，Halo 会根据 GVK 注解自动生成一组 CRUD APIs。

PhotoVo 类型定义
{
  "metadata": {
    "name": "string",                                   // 唯一标识
    "labels": {
      "additionalProp1": "string"
    },
    "annotations": {
      "additionalProp1": "string"
    },
    "creationTimestamp": "2022-11-20T13:06:38.512Z",    // 创建时间
  },
  "spec": {
    "displayName": "string",                            // 图片名称
    "description": "string",                            // 图片描述
    "url": "string",                                    // 图片链接
    "cover": "string",                                  // 封面链接
    "priority": 0,                                      // 优先级
    "groupName": "string",                              // 分组名称，对应分组 metadata.name
  },
}

路由信息
* 模板路径：/templates/photos.html
* 访问路径：/photos | /photos/page/{page}

/photos?group=photo-group-UEcvi | /photos/page/1?group=photo-group-UEcvi

生成 APIs 的规则为：/apis/<group>/<version>/<extension>/{extensionname}/<subextension>

例如，Person 自定义模型将有以下 APIs：

GET /apis/my-plugin.halo.run/v1alpha1/persons：列出所有对象。
GET /apis/my-plugin.halo.run/v1alpha1/persons/{name}：根据名称查询对象。
POST /apis/my-plugin.halo.run/v1alpha1/persons：创建对象。
PUT /apis/my-plugin.halo.run/v1alpha1/persons/{name}：更新对象。
DELETE /apis/my-plugin.halo.run/v1alpha1/persons/{name}：删除对象。

其中，列出所有对象的 API 支持以下参数：

page：页码，从 1 开始。
size：每页的数据量。
sort：排序字段，格式为 字段名,排序方式，例如 name,desc，可传递多个排序字段，排序使用的字段必须是注册为索引的字段。
labelSelector：标签选择器，用于筛选特定标签的对象。详见 标签选择器参数规则。
fieldSelector：字段选择器，用于筛选注册为索引的字段。详见 字段选择器参数规则。

示例：
GET /apis/my-plugin.halo.run/v1alpha1/persons?
    page=1&
    size=10&
    sort=name,desc&
    labelSelector=name=halo&
    fieldSelector=spec.slug=halo
    
表示查询 metadata.labels 中 name 的值等于 halo 且 spec.slug 的值等于 halo 的自定义模型对象，
并按照 name 字段降序排序，查询第 1 页，每页 10 条数据。


annotations
annotations 是一个字符串键值对集合，用于存放扩展信息，命名规则与 labels 相同。
可以使用 metadata.annotations 存放一些额外的信息，如 JSON 数据、配置信息等。

Annotations 元数据适配
根据 Halo 的元数据表单定义文档和模型元数据文档，Halo 支持为部分模型的表单添加元数据表单，此插件同样适配了此功能，如果你作为主题开发者，需要为链接或者链接分组添加额外的字段，可以参考上述文档并结合下面的 TargetRef 列表进行适配。

对应模型	group	        kind
图库	    core.halo.run	Photo
图库分组	core.halo.run	PhotoGroup

API 文档可以通过访问 /swagger-ui.html 查看，例如：http://localhost:8090/swagger-ui.html。

快速创建halo插件模板

git clone https://github.com/halo-dev/create-halo-plugin.git halo-plugins
cd halo-plugins
pnpm create halo-plugin myplugin
cd myplugin
./gradlew haloServer
#In another terminal, start UI dev
cd ui
pnpm dev

git clone https://github.com/halo-dev/plugin-feed.git feed
git clone https://github.com/halo-dev/plugin-s3.git s3
git clone https://github.com/halo-dev/plugin-comment-widget.git comment

git clone https://github.com/halo-sigs/plugin-photos.git photos
(图库管理插件)
git clone https://github.com/chengzhongxue/plugin-vote.git vote
(投票插件, 创建管理投票)
git clone https://github.com/chengzhongxue/plugin-mail-template.git mailtpl
(邮件模板管理，查看、编辑邮件模板)
git clone https://github.com/monyuan/notify-me.git noticeme
(当有新评论、待审核评论、发布文章、投稿时将通知推送到微信、企业微信、钉钉、飞书、微信测试号等应用上。)
git clone https://github.com/acanyo/plugin-announcement.git announce
(一个功能强大的 Halo 博客系统公告通知插件，支持自定义弹窗内容、按钮行为、动画效果和智能弹出控制)
git clone https://github.com/halo-sigs/plugin-page-cache.git pagecache
(提供页面的静态缓存功能，提高页面访问速度)