Skip to content

Commit

Permalink
Merge remote-tracking branch 'upstream/main' into shangjianan2
Browse files Browse the repository at this point in the history
  • Loading branch information
shangjianan2 committed Oct 27, 2023
2 parents 1fc1648 + 147952f commit 110b47c
Show file tree
Hide file tree
Showing 32 changed files with 640 additions and 560 deletions.
8 changes: 4 additions & 4 deletions docs/developer-guide/plugin/api-reference/extension.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,10 +74,10 @@ gender: male
- @GVK:此注解标识该类为一个自定义模型,同时必须继承 `AbstractExtension`。
- kind:表示自定义模型所表示的 REST 资源。
- group:表示一组公开的资源,通常采用域名形式,Halo 项目保留使用空组和任何以*.halo.run结尾的组名供其单独使用。
选择群组名称时,我们建议选择你的群组或组织拥有的子域,例如widget.mycompany.com
- version:API 的版本,它与 group 组合使用为 apiVersion=GROUP/VERSION,例如api.halo.run/v1alpha1
- singular: 资源的单数名称,这允许客户端不透明地处理复数和单数,必须全部小写通常为小写的kind
- group:表示一组公开的资源,通常采用域名形式,Halo 项目保留使用空组和任何以 `*.halo.run` 结尾的组名供其单独使用。
选择群组名称时,我们建议选择你的群组或组织拥有的子域,例如 `widget.mycompany.com`
- version:API 的版本,它与 group 组合使用为 `apiVersion=GROUP/VERSION`,例如`api.halo.run/v1alpha1`
- singular: 资源的单数名称,这允许客户端不透明地处理复数和单数,必须全部小写通常为小写的 `kind`
- plural: 资源的复数名称,自定义资源在 `/apis/<group>/<version>/.../<plural>` 下提供,必须为全部小写。
- @Schema:属性校验注解,会在创建/修改资源前对资源校验,参考 [schema-validator](https://www.openapi4j.org/schema-validator.html)。
:::
Expand Down
28 changes: 14 additions & 14 deletions docs/developer-guide/plugin/api-reference/reverseproxy.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,21 @@ description: 了解如果使用静态资源代理来访问插件中的静态资
例如 `src/main/resources` 下的 `static` 目录下有一张 `halo.jpg`:

1. 首先需要在 `src/main/resources/extensions` 下创建一个 `yaml`,文件名可以任意。
2. 示例配置如下
2. 示例配置如下

```yaml
apiVersion: plugin.halo.run/v1alpha1
kind: ReverseProxy
metadata:
# name 为此资源的唯一标识名称,不允许重复,为了避免与其他插件冲突,推荐带上插件名称前缀
name: my-plugin-fake-reverse-proxy
rules:
- path: /res/**
file:
directory: static
# 如果想代理 static 下所有静态资源则省略 filename 配置
filename: halo.jpg
```
```yaml
apiVersion: plugin.halo.run/v1alpha1
kind: ReverseProxy
metadata:
# name 为此资源的唯一标识名称,不允许重复,为了避免与其他插件冲突,推荐带上插件名称前缀
name: my-plugin-fake-reverse-proxy
rules:
- path: /res/**
file:
directory: static
# 如果想代理 static 下所有静态资源则省略 filename 配置
filename: halo.jpg
```
插件启动后会根据 `/plugins/{plugin-name}/assets/**` 规则生成 API。
因此该 `ReverseProxy` 的访问路径为: `/plugins/my-plugin/assets/res/halo.jpg`
Expand Down
34 changes: 17 additions & 17 deletions docs/developer-guide/plugin/api-reference/role-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,15 +58,15 @@ rules:
- `resources` 对应 API 中的 resource 部分,`my-plugin` 表示插件名称。
- `verbs` 表示请求动词,可选值为 "create", "delete", "deletecollection", "get", "list", "patch", "update"。对应的 HTTP 请求方式如下表所示:

| HTTP verb | request verb |
| --------- | ------------------------------------------------------------ |
| POST | create |
| GET, HEAD | get (for individual resources), list (for collections, including full object content), watch (for watching an individual resource or collection of resources) |
| PUT | update |
| PATCH | patch |
| DELETE | delete (for individual resources), deletecollection (for collections) |
| HTTP verb | request verb |
| --------- | ------------------------------------------------------------ |
| POST | create |
| GET, HEAD | get (for individual resources), list (for collections, including full object content), watch (for watching an individual resource or collection of resources) |
| PUT | update |
| PATCH | patch |
| DELETE | delete (for individual resources), deletecollection (for collections) |

`metadata.labels` 中必须包含 `halo.run/role-template: "true"` 以表示它此资源要作为角色模板。
`metadata.labels` 中必须包含 `halo.run/role-template: "true"` 以表示它此资源要作为角色模板。
`metadata.annotations` 中:

Expand All @@ -75,16 +75,16 @@ rules:
- `rbac.authorization.halo.run/display-name`:模板角色的显示名称,用于展示为用户可读的名称信息。
- `rbac.authorization.halo.run/ui-permissions`:用于控制 UI 权限,规则为 `plugin:{your-plugin-name}:scope-name`,使用示例为在插件前端部分入口文件 `index.ts` 中用于控制菜单是否显示或者控制页面按钮是否展示:

```javascript
{
path: "",
name: "HelloWorld",
component: DefaultView,
meta: {
permissions: ["plugin:my-plugin:person:view"]
```javascript
{
path: "",
name: "HelloWorld",
component: DefaultView,
meta: {
permissions: ["plugin:my-plugin:person:view"]
}
}
}
```
```

以上定义角色模板的方式适合资源型请求,即需要符合以下规则

Expand Down
177 changes: 50 additions & 127 deletions docs/developer-guide/plugin/examples/todolist.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,51 +55,52 @@ description: 这个例子展示了如何开发 Todo List 插件
1. 在 `src/main/java` 下创建包,如 `run.halo.tutorial`,在创建一个类 `TodoListPlugin`,它继承自 `BasePlugin` 类内容如下:

```java
package run.halo.tutorial;
import org.pf4j.PluginWrapper;
import org.springframework.stereotype.Component;
import run.halo.app.plugin.BasePlugin;
@Component
public class TodoListPlugin extends BasePlugin {
public TodoListPlugin(PluginWrapper wrapper) {
super(wrapper);
}
}
```

`src/main/java` 下的文件结构如下:

```text
.
└── run
└── halo
└── tutorial
└── TodoListPlugin.java
```

然后在项目目录执行命令
```java
package run.halo.tutorial;
import org.pf4j.PluginWrapper;
import org.springframework.stereotype.Component;
import run.halo.app.plugin.BasePlugin;
@Component
public class TodoListPlugin extends BasePlugin {
public TodoListPlugin(PluginWrapper wrapper) {
super(wrapper);
}
}
```

`src/main/java` 下的文件结构如下:

```text
.
└── run
└── halo
└── tutorial
└── TodoListPlugin.java
```

2. 然后在项目目录执行命令

```shell
./gradlew build
```

```shell
./gradlew build
```
3. 使用 `IntelliJ IDEA` 打开 Halo,参考 [Halo 开发环境运行](../../core/run.md) 及 [插件入门](../hello-world.md) 配置插件的运行模式和路径:

使用 `IntelliJ IDEA` 打开 Halo,参考 [Halo 开发环境运行](../../core/run.md) 及 [插件入门](../hello-world.md) 配置插件的运行模式和路径:
```yaml
halo:
plugin:
runtime-mode: development
fixed-plugin-path:
# 配置为插件绝对路径
- /Users/guqing/halo-plugin-todolist
```

```yaml
halo:
plugin:
runtime-mode: development
fixed-plugin-path:
# 配置为插件绝对路径
- /Users/guqing/halo-plugin-todolist
```
4. 启动 Halo,然后访问 `http://localhost:8090/console`

启动 Halo,然后访问 `http://localhost:8090/console`
在插件列表将能看到插件已经被正确启用:

在插件列表将能看到插件已经被正确启用
![plugin-todolist-in-list-view](/img/todolist-in-list.png)

## 创建一个自定义模型
Expand Down Expand Up @@ -283,13 +284,13 @@ export default definePlugin({
2. ` pnpm install todomvc-app-css `。
3. 修改 `console/src/views/DefaultView.vue` 最底部的 `style` 标签。

```diff
- <style>
+ <style scoped>
- @import "https://unpkg.com/[email protected]/index.css";
+ @import "todomvc-app-css/index.css";
</style>
```
```diff
- <style>
+ <style scoped>
- @import "https://unpkg.com/[email protected]/index.css";
+ @import "todomvc-app-css/index.css";
</style>
```

4. 重新 Build 后刷新页面,便能看到目标图所示效果。

Expand All @@ -307,7 +308,7 @@ pnpm install axios

为了符合最佳实践,将用 TypeScript 改造之前的 todomvc 示例:

1. 创建 types 文件 `console/src/types/index.ts`
创建 types 文件 `console/src/types/index.ts`

```typescript
export interface Metadata {
Expand Down Expand Up @@ -575,87 +576,9 @@ const handleDelete = (todo: Todo) => {

至此我们就完成了与插件后端 APIs 实现 Todo List 数据交互的部分。

### 使用 Icon

目前 Todo 的菜单还是默认的网格样式 Icon,在 `console/src/index.ts` 文件中配置有一个 `icon: markRaw(IconGrid)`。以此为例说明该如何使用其他 `Icon`

1. 安装 [unplugin-icons](https://github.com/antfu/unplugin-icons)

```shell
pnpm install -D unplugin-icons
pnpm install -D @iconify/json
pnpm install -D @vue/compiler-sfc
```

2. 编辑 `console/vite.config.ts`,在 `defineConfig``plugins` 中添加配置,修改如下。

```diff
+ import Icons from "unplugin-icons/vite";

// https://vitejs.dev/config/
export default defineConfig({
- plugins: [vue(), vueJsx()],
+ plugins: [vue(), vueJsx(), Icons({ compiler: "vue3" })],
```

3.`console/tsconfig.app.json` 中加入 `unplugni-icons``types` 配置。

```diff
{
// ...
"compilerOptions": {
// ...
"paths": {
"@/*": ["./src/*"]
- }
+ },
+ "types": ["unplugin-icons/types/vue"]
}
}
```

4.[icones](https://icones.js.org/) 搜索你想要使用的图标,并点击它,然后选择 `Unplugin Icons`,会复制到剪贴板。

![unplugin icons selector](/img/unplugin-icons-example.png)

5. 编辑 `console/src/index.ts``import` 区域粘贴,并 `icon` 属性。

```diff
- import { IconGrid } from "@halo-dev/components";
+ import VscodeIconsFileTypeLightTodo from "~icons/vscode-icons/file-type-light-todo";

export default definePlugin({
routes: [
{
// ...
route: {
path: "/todos",
children: [
{
// ...
meta: {
// ...
menu: {
// ...
- icon: markRaw(IconGrid),
+ icon: markRaw(VscodeIconsFileTypeLightTodo),
priority: 0,
},
},
},
],
},
},
],
// ...
});
```

### 用户界面使用静态资源

如果你想在用户界面中使用图片,你可以放到 `console/src/assets` 中,例如 `logo.png`,并将其作为 Todo 的 Logo 放到标题旁边

![todo logo example](/img/todo-logo-check-48.png)
如果你想在用户界面中使用图片,你可以放到 `console/src/assets` 中,例如 `logo.png`,并将其作为 Todo 的 Logo 放到标题旁边。

需要修改 `console/src/views/DefaultView.vue` 示例如下:

Expand Down
23 changes: 13 additions & 10 deletions docs/developer-guide/plugin/hello-world.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,20 @@ title: 入门
description: 了解如何构建你的第一个插件并在 Halo 中使用它。
---

Halo 提供了一个模板仓库用于创建插件:
此文档将帮助你了解如何构建你的第一个插件并在 Halo 中安装和启用。

## 创建插件项目

1. 打开 [halo-dev/plugin-starter](https://github.com/halo-dev/plugin-starter)

> 这是一个插件的初始模板,你可以基于它来开发自己的插件。
1. 打开 [plugin-starter](https://github.com/halo-dev/plugin-starter)
2. 点击 `Use this template` -> `Create a new repository`
3. 如图所示填写仓库名后点击 `Create repository from template`
![create-repository-for-hello-world-plugin](/img/create-repository-for-hello-world-plugin.png)

你现在已经基于 Halo 插件模板创建了自己的存储库。接下来,你需要将它 `git clone` 到你的计算机上并使用 `IntelliJ IDEA` 打开它。
![create-repository-for-hello-world-plugin](/img/create-repository-for-hello-world-plugin.png)

你现在已经基于 Halo 插件模板创建了自己的存储库。接下来,你需要将它克隆到你的计算机上并使用 `IntelliJ IDEA` 打开它。

## 运行插件

Expand All @@ -24,10 +30,7 @@ Halo 提供了一个模板仓库用于创建插件:

或者使用 `IntelliJ IDEA` 提供的 `Gradle build` 即可完成插件项目的构建。

第二步就是使用它。

使用 `IntelliJ IDEA` 打开 Halo,参考 [Halo 开发环境运行](../core/run.md)
然后在 `src/main/resources` 下创建一个 `application-local.yaml` 文件并做如下配置:
然后使用 `IntelliJ IDEA` 打开 Halo,参考 [Halo 开发环境运行](../core/run.md),在 `src/main/resources` 下创建一个 `application-local.yaml` 文件并做如下配置:

```yaml
# macOS / Linux
Expand All @@ -36,15 +39,15 @@ halo:
runtime-mode: development
fixed-plugin-path:
# 配置为插件绝对路径
- /Users/guqing/halo-plugin-hello-world
- /path/to/halo-plugin-hello-world

# Windows
halo:
plugin:
runtime-mode: development
fixed-plugin-path:
# 配置为插件绝对路径
- C:\Users\guqing\halo-plugin-hello-world
- C:\path\to\halo-plugin-hello-world
```
使用此 local profile 启动 Halo:
Expand Down
3 changes: 2 additions & 1 deletion docs/developer-guide/plugin/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@
title: 介绍
description: 插件开发的准备工作
---
插件是由社区创建的程序或应用程序,用于扩展 Halo 的功能。插件在 Halo 中运行并执行一项或多项用户操作。它们允许用户根据自己的喜好扩展或修改 Halo。

Halo 采用可插拔架构,功能模块之间耦合度低、灵活性提高,支持用户按需安装、卸载插件,操作便捷。同时提供插件开发接口以确保较高扩展性和可维护性,这个系列的文档将帮助你了解如何开发 Halo 插件。

## 插件管理

Expand Down
Loading

0 comments on commit 110b47c

Please sign in to comment.