docs: add documentation for singlePage extension (#501)

Signed-off-by: Ryan Wang <i@ryanc.cc>

Author: ruibaby

docs/developer-guide/plugin/extension-points/ui/interface/ListedSinglePage.md

@@ -0,0 +1,70 @@
+```ts
+export interface ListedSinglePage {
+  contributors: Array<{                           // 页面的贡献者集合
+    avatar: string;                               // 贡献者头像
+    displayName: string;                          // 贡献者名称
+    name: string;                                 // 贡献者唯一标识
+  }>;
+  owner: {                                        // 页面的作者信息
+    avatar: string;                               // 作者头像
+    displayName: string;                          // 作者名称
+    name: string;                                 // 作者唯一标识
+  };
+  page: {                                         // 页面信息
+    apiVersion: "content.halo.run/v1alpha1";
+    kind: "SinglePage";
+    metadata: {
+      annotations: {};
+      creationTimestamp: string;
+      labels: {};
+      name: string;                               // 页面的唯一标识
+      version: number;
+    };
+    spec: {
+      allowComment: boolean;                      // 是否允许评论
+      baseSnapshot: string;                       // 内容基础快照
+      cover: string;                              // 页面封面图
+      deleted: boolean;                           // 是否已删除
+      excerpt: {                                  // 页面摘要
+        autoGenerate: boolean;                    // 是否自动生成
+        raw: string;                              // 摘要内容
+      };
+      headSnapshot: string;                       // 内容最新快照
+      htmlMetas: Array<{}>;
+      owner: string;                              // 页面作者的唯一标识
+      pinned: boolean;                            // 是否置顶
+      priority: number;                           // 页面优先级
+      publish: boolean;                           // 是否发布
+      publishTime: string;                        // 发布时间
+      releaseSnapshot: string;                    // 已发布的内容快照
+      slug: string;                               // 页面别名
+      template: string;                           // 页面渲染模板
+      title: string;                              // 页面标题
+      visible: string;                            // 页面可见性
+    };
+    status: {
+      commentsCount: number;                      // 页面评论总数
+      conditions: Array<{
+        lastTransitionTime: string;
+        message: string;
+        reason: string;
+        status: string;
+        type: string;
+      }>;
+      contributors: Array<string>;
+      excerpt: string;                            // 最终的页面摘要，根据是否自动生成计算
+      inProgress: boolean;                        // 是否有未发布的内容
+      lastModifyTime: string;                     // 页面最后修改时间
+      permalink: string;                          // 页面的永久链接
+      phase: string;
+    };
+  };
+  stats: {
+    approvedComment: number;                      // 已审核的评论数
+    totalComment: number;                         // 评论总数
+    upvote: number;                               // 点赞数
+    visit: number;                                // 访问数
+  };
+}
+
+```

docs/developer-guide/plugin/extension-points/ui/post-list-item-field-create.md

@@ -1,6 +1,6 @@
 ---
 title: 文章数据列表显示字段
-description: 扩展文章数据列表显示字段 - plugin:list-item:field:create
+description: 扩展文章数据列表显示字段 - post:list-item:field:create
 ---
 
 此扩展点用于扩展文章数据列表的显示字段。

docs/developer-guide/plugin/extension-points/ui/single-page-list-item-field-create.md

@@ -0,0 +1,80 @@
+---
+title: 页面数据列表显示字段
+description: 扩展页面数据列表显示字段 - single-page:list-item:field:create
+---
+
+此扩展点用于扩展页面数据列表的显示字段。
+
+![页面数据列表显示字段](/img/developer-guide/plugin/extension-points/ui/single-page-list-item-field-create.png)
+
+## 定义方式
+
+```ts
+export default definePlugin({
+  extensionPoints: {
+    "single-page:list-item:field:create": (singlePage: Ref<ListedSinglePage>): EntityFieldItem[] | Promise<EntityFieldItem[]> => {
+      return [
+        {
+          priority: 0,
+          position: "start",
+          component: markRaw(FooComponent),
+          props: {},
+          permissions: [],
+          hidden: false,
+        }
+      ];
+    },
+  },
+});
+```
+
+```ts title="EntityFieldItem"
+export interface EntityFieldItem {
+  priority: number;
+  position: "start" | "end";
+  component: Raw<Component>;
+  props?: Record\<string, unknown\>;
+  permissions?: string[];
+  hidden?: boolean;
+}
+```
+
+## 示例
+
+此示例将添加一个显示页面 slug（别名）的字段。
+
+```ts
+import { definePlugin } from "@halo-dev/console-shared";
+import { markRaw, type Ref } from "vue";
+import type { ListedSinglePage } from "@halo-dev/api-client";
+import { VEntityField } from "@halo-dev/components";
+
+export default definePlugin({
+  extensionPoints: {
+    "single-page:list-item:field:create": (singlePage: Ref<ListedSinglePage>) => {
+      return [
+        {
+          priority: 0,
+          position: "end",
+          component: markRaw(VEntityField),
+          props: {
+            description: singlePage.value.page.spec.slug,
+          },
+          permissions: [],
+          hidden: false,
+        },
+      ];
+    },
+  },
+});
+```
+
+## 类型定义
+
+### ListedSinglePage
+
+```mdx-code-block
+import ListedSinglePage from "./interface/ListedSinglePage.md";
+
+<ListedSinglePage />
+```

docs/developer-guide/plugin/extension-points/ui/single-page-list-item-operation-create.md

@@ -0,0 +1,92 @@
+---
+title: 页面数据列表操作菜单
+description: 扩展页面数据列表操作菜单 - single-page:list-item:operation:create
+---
+
+此扩展点用于扩展页面数据列表的操作菜单项。
+
+![页面数据列表操作菜单](/img/developer-guide/plugin/extension-points/ui/single-page-list-item-operation-create.png)
+
+## 定义方式
+
+```ts
+export default definePlugin({
+  extensionPoints: {
+    "single-page:list-item:operation:create": (
+      singlePage: Ref<ListedSinglePage>
+    ): OperationItem<ListedSinglePage>[] | Promise<OperationItem<ListedSinglePage>[]> => {
+      return [
+        {
+          priority: 10,
+          component: markRaw(VDropdownItem),
+          props: {},
+          action: (item?: ListedSinglePage) => {
+            // do something
+          },
+          label: "foo",
+          hidden: false,
+          permissions: [],
+          children: [],
+        },
+      ];
+    },
+  },
+});
+```
+
+```mdx-code-block
+import OperationItem from "./interface/OperationItem.md";
+
+<OperationItem />
+```
+
+## 示例
+
+此示例将实现一个操作菜单项，点击后会将页面内容作为文件下载到本地。
+
+```ts
+import type { ListedSinglePage } from "@halo-dev/api-client";
+import { VDropdownItem } from "@halo-dev/components";
+import { definePlugin } from "@halo-dev/console-shared";
+import axios from "axios";
+import { markRaw } from "vue";
+
+export default definePlugin({
+  extensionPoints: {
+    "single-page:list-item:operation:create": () => {
+      return [
+        {
+          priority: 21,
+          component: markRaw(VDropdownItem),
+          label: "下载到本地",
+          visible: true,
+          permissions: [],
+          action: async (singlePage: ListedSinglePage) => {
+            const { data } = await axios.get(
+              `/apis/api.console.halo.run/v1alpha1/single-pages/${singlePage.page.metadata.name}/head-content`
+            );
+            const blob = new Blob([data.raw], {
+              type: "text/plain;charset=utf-8",
+            });
+            const url = window.URL.createObjectURL(blob);
+            const link = document.createElement("a");
+            link.href = url;
+            link.download = `${singlePage.page.spec.title}.${data.rawType}`;
+            link.click();
+          },
+        },
+      ];
+    },
+  },
+});
+```
+
+## 类型定义
+
+### ListedSinglePage
+
+```mdx-code-block
+import ListedSinglePage from "./interface/ListedSinglePage.md";
+
+<ListedSinglePage />
+```

sidebars.js

@@ -287,6 +287,7 @@ module.exports = {
                 "developer-guide/plugin/extension-points/ui/plugin-installation-tabs-create",
                 "developer-guide/plugin/extension-points/ui/theme-list-tabs-create",
                 "developer-guide/plugin/extension-points/ui/post-list-item-operation-create",
+                "developer-guide/plugin/extension-points/ui/single-page-list-item-operation-create",
                 "developer-guide/plugin/extension-points/ui/comment-list-item-operation-create",
                 "developer-guide/plugin/extension-points/ui/reply-list-item-operation-create",
                 "developer-guide/plugin/extension-points/ui/plugin-list-item-operation-create",
@@ -295,6 +296,7 @@ module.exports = {
                 "developer-guide/plugin/extension-points/ui/theme-list-item-operation-create",
                 "developer-guide/plugin/extension-points/ui/plugin-list-item-field-create",
                 "developer-guide/plugin/extension-points/ui/post-list-item-field-create",
+                "developer-guide/plugin/extension-points/ui/single-page-list-item-field-create",
                 "developer-guide/plugin/extension-points/ui/user-detail-tabs-create",
                 "developer-guide/plugin/extension-points/ui/uc-user-profile-tabs-create",
                 "developer-guide/plugin/extension-points/ui/dashboard-widgets",

static/img/developer-guide/plugin/extension-points/ui/single-page-list-item-field-create.png

@@ -1,6 +1,6 @@
 ---
 title: 文章数据列表显示字段
-description: 扩展文章数据列表显示字段 - plugin:list-item:field:create
+description: 扩展文章数据列表显示字段 - post:list-item:field:create
 ---
 
 此扩展点用于扩展文章数据列表的显示字段。

static/img/developer-guide/plugin/extension-points/ui/single-page-list-item-operation-create.png

@@ -1,6 +1,6 @@
 ---
 title: 文章数据列表显示字段
-description: 扩展文章数据列表显示字段 - plugin:list-item:field:create
+description: 扩展文章数据列表显示字段 - post:list-item:field:create
 ---
 
 此扩展点用于扩展文章数据列表的显示字段。

versioned_docs/version-2.16/developer-guide/plugin/api-reference/ui/extension-points/post-list-item-field-create.md

@@ -1,6 +1,6 @@
 ---
 title: 文章数据列表显示字段
-description: 扩展文章数据列表显示字段 - plugin:list-item:field:create
+description: 扩展文章数据列表显示字段 - post:list-item:field:create
 ---
 
 此扩展点用于扩展文章数据列表的显示字段。