docs: revise and add more examples

BREAKING CHANGE: The following top-level functions exported by the 'artalk' npm package have been deprecated: `Artalk.update`, `Artalk.reload`, and `Artalk.destroy`. These methods now require invocation on an instance created by either `Artalk.init` or `new Artalk`. Please utilize instance-level methods instead, such as `artalkInstance.update`. For more information, refer to  [the documentation](https://artalk.js.org/guide/frontend/import-framework.html). The update was implemented to enable the concurrent creation of multiple instances, adapting to situations where Vue components are simultaneously referenced across various pages. Initially, only a singular instance was permitted to mitigate memory leak concerns. However, this proved limiting for scenarios involving the caching of multiple component instances through 'keep-alive.' To better suit intricate SPA application needs, the choice was made to permit the creation of multiple independent instances. It's crucial to remember to manually invoke the `artalk.destroy` method when releasing components to avoid memory leaks (Issue #660).

README.md

@@ -55,13 +55,19 @@
 - 支持 Latex：提供集成 Katex 插件
 - 使用 [Vite](https://github.com/vitejs/vite)：属于开发者的极致体验
 
-更多内容请查看：[“**介绍文档**”](https://artalk.js.org/guide/intro.html)
+更多内容请查看：[**介绍文档**](https://artalk.js.org/guide/intro.html)
 
-## 食用方针
+## 安装
 
-前往：[“**部署文档**”](https://artalk.js.org/guide/deploy.html)
+参考：[**部署文档**](https://artalk.js.org/guide/deploy.html)
+
+```bash
+npm install artalk
+```
 
 ```ts
+import Artalk from 'artalk'
+
 Artalk.init({
   el:     '#Comments',
   site:   'Artalk 的博客',
@@ -76,6 +82,7 @@ docker run -d \
   --name artalk \
   -p 8080:23366 \
   -v $(pwd)/data:/data \
+  --restart=always \
   artalk/artalk-go
 ```
 
@@ -91,6 +98,7 @@ services:
   artalk:
     container_name: artalk
     image: artalk/artalk-go
+    restart: always
     ports:
       - 8080:23366
     volumes:

docs/.vitepress/config.ts

@@ -50,7 +50,8 @@ export default defineConfig({
     en: {
       label: 'English',
       lang: 'en',
-      link: '/en/'
+      link: 'https://artalk-js-org.translate.goog/guide/intro?_x_tr_sl=auto&_x_tr_tl=en-US&_x_tr_hl=en-US&_x_tr_pto=wapp'
+      // link: '/en/'
     }
   },
 
@@ -94,6 +95,7 @@ export default defineConfig({
             { text: '精简版本', link: '/guide/frontend/artalk-lite.md' },
             { text: '置入博客', link: '/guide/frontend/import-blog.md' },
             { text: '置入框架', link: '/guide/frontend/import-framework.md' },
+            { text: '前端 API', link: '/develop/fe-api.md', },
             { text: '开发文档', link: '/develop/index.md', },
           ],
         },
@@ -109,11 +111,11 @@ export default defineConfig({
           text: "部署说明",
           collapsed: true,
           items: [
-            { text: 'Docker', link: '/guide/backend/docker.md' },
             { text: '守护进程', link: '/guide/backend/daemon.md' },
             { text: '反向代理', link: '/guide/backend/reverse-proxy.md' },
             { text: '编译构建', link: '/guide/backend/build.md' },
             { text: '程序升级', link: '/guide/backend/update.md' },
+            { text: 'Docker', link: '/guide/backend/docker.md' },
           ]
         },
         {

docs/.vitepress/theme/Artalk.vue

@@ -5,7 +5,7 @@
 </template>
 
 <script setup lang="ts">
-import { watch, nextTick, ref, onMounted, onBeforeUnmount } from 'vue'
+import { watch, nextTick, ref, onMounted, onUnmounted } from 'vue'
 import { useData, useRouter } from 'vitepress'
 import type Artalk from 'artalk'
 
@@ -27,7 +27,7 @@ watch(() => router.route.data.relativePath, () => {
   })
 })
 
-onBeforeUnmount(() => {
+onUnmounted(() => {
   artalk.destroy()
 })
 

docs/develop/event.md

@@ -4,23 +4,39 @@
 
 |事件名|描述|
 |-|-|
-| `list-load` | 评论加载事件 |
-| `list-loaded` | 评论加载完成事件 |
-| `list-inserted` | 新增评论插入事件 |
-| `editor-submit` | 编辑器提交事件 |
-| `editor-submitted` | 编辑器提交完成事件 |
-| `user-changed` | 本地用户数据变更事件 |
-| `conf-loaded` | 配置变更事件 |
-| `sidebar-show` | 侧边栏显示事件 |
-| `sidebar-hide` | 侧边栏隐藏事件 |
+| `inited` | 初始化后 |
+| `destroy` | 实例销毁时 |
+| `list-fetch` | 评论列表请求时 |
+| `list-fetched` | 评论列表请求后 |
+| `list-load` | 评论装载前 |
+| `list-loaded` | 评论装载后 |
+| `list-error` | 评论加载错误时 |
+| `list-goto-first` | 评论列表归位时 |
+| `list-reach-bottom` | 评论列表滚动到底部时 |
+| `list-reach-bottom` | 评论列表滚动到底部时 |
+| `comment-inserted`   | 评论插入后           |
+| `comment-updated`    | 评论更新后           |
+| `comment-deleted`    | 评论删除后           |
+| `comment-rendered`   | 评论节点渲染后       |
+| `unreads-updated`    | 未读消息变更时       |
+| `list-goto`          | 评论跳转时           |
+| `page-loaded`        | 页面数据更新后       |
+| `editor-submit`      | 编辑器提交时         |
+| `editor-submitted`   | 编辑器提交后         |
+| `user-changed`       | 本地用户数据变更时   |
+| `conf-loaded`        | 配置变更时           |
+| `dark-mode-changed`  | 深色模式变更时       |
+| `sidebar-show`       | 侧边栏显示          |
+| `sidebar-hide`       | 侧边栏隐藏          |
+
+
+事件声明代码：[@ArtalkJS/Artalk - types/event.ts](https://github.com/ArtalkJS/Artalk/blob/master/ui/packages/artalk/types/event.ts)
 
 ## 添加事件监听
 
 ```js
-Artalk.use(ctx => {
-  ctx.on('list-loaded', () => {
-    alert('评论已加载完毕')
-  })
+artalk.on('list-loaded', () => {
+  alert('评论已加载完毕')
 })
 ```
 
@@ -29,8 +45,6 @@ Artalk.use(ctx => {
 ```js
 let foo = function() { /* do something */ }
 
-Artalk.use(ctx => {
-  ctx.on('list-loaded', foo)
-  ctx.off('list-loaded', foo)
-})
+artalk.on('list-loaded', foo)
+artalk.off('list-loaded', foo)
 ```

docs/develop/fe-api.md

@@ -1,11 +1,23 @@
 # Frontend API
 
-## 初始化 `Artalk.init`
+## 安装依赖
 
-创建 Artalk 实例化对象。
+用你喜欢的包管理器安装 Artalk：
+
+```bash
+pnpm add artalk
+# 或者使用 npm
+npm install artalk
+```
+
+## 创建实例 `init`
+
+`Artalk.init` 函数和 `new Artalk` 等价，调用该函数将创建并得到一个 Artalk 的实例化对象，可用于后续操作。
 
 ```js
-Artalk.init({
+import Artalk from 'artalk'
+
+const artalk = Artalk.init({
   el:        '#Comments',
   pageKey:   '/post/1',
   pageTitle: '关于引入 Artalk 的这档子事',
@@ -14,93 +26,134 @@ Artalk.init({
 })
 ```
 
-## 更新配置 `Artalk.update`
+调用该函数会向后端发起请求：
 
-修改 Artalk 当前配置。
+1. 获取前端配置
+2. 获取评论列表
+
+配置和评论加载完毕后会分别触发 `conf-loaded` 和 `list-loaded` 事件。
+
+注：前端配置可能会被覆盖，详情见：[在后端控制前端](../guide/backend/fe-control.md)。
+
+## 释放资源 `destroy`
+
+销毁 Artalk 实例，用于资源释放。
 
 ```js
-Artalk.update({
-  // 新的配置...
-})
+const artalk = Artalk.init({ ... })
+
+artalk.destroy()
 ```
 
-该函数调用后，`conf-loaded` 事件将被触发。
+释放资源将执行 Artalk 挂载的 DOM 节点删除，以及解除 Artalk 事件监听等操作。
 
-更新配置不会自动刷新评论列表，可按需继续执行 `Artalk.reload()` 函数。
+在 Vue / React 等框架中，务必在组件销毁时调用该函数，否则会造成内存泄漏：
 
-注：前端的一些配置将会被后端的配置覆盖，详情见：[在后端控制前端](../guide/backend/fe-control.md)
+```ts
+import { onUnmounted } from 'vue'
 
-## 重新加载 `Artalk.reload`
+onUnmounted(() => {
+  artalk.destroy()
+})
+```
 
-刷新 Artalk 评论列表。
+## 更新配置 `update`
+
+修改 Artalk 当前配置。
 
 ```js
-Artalk.reload()
+const artalk = Artalk.init({ ... })
+
+artalk.update({
+  // 新的配置...
+})
 ```
 
-列表加载前将触发 `list-load` 事件，加载完毕后将触发 `list-loaded` 事件。
+调用该函数将触发 `conf-loaded` 事件。
 
-## 释放资源 `Artalk.destroy`
+更新配置不会自动刷新评论列表，可按需继续执行 `artalk.reload()` 函数。
 
-销毁 Artalk 实例，用于资源释放。
+请注意，该函数是一个实例化对象中的方法，并非全局函数。
+
+前端配置参考：[前端配置](../guide/frontend/config.md)
+
+## 重新加载 `reload`
+
+重新从后端加载 Artalk 评论列表数据。
 
 ```js
-Artalk.destroy()
+const artalk = Artalk.init({ ... })
+
+artalk.reload()
 ```
 
-## 事件监听 `Artalk.on`
+列表加载前将触发 `list-load` 事件，加载完毕后将触发 `list-loaded` 事件。
+
+## 监听事件 `on`
 
 添加 Artalk 事件监听。
 
 ```js
-Artalk.on('list-loaded', () => {
+const artalk = Artalk.init({ ... })
+
+artalk.on('list-loaded', () => {
   alert('评论列表加载完毕')
 })
 ```
 
-可监听事件类型见：[前端界面事件](./event.md)
+可参考：[前端 Event](./event.md)。
 
-## 解除监听 `Artalk.off`
+## 解除监听 `off`
 
 解除 Artalk 事件监听。
 
 ```js
+const artalk = Artalk.init({ ... })
+
 const handler = () => {
   alert('评论列表加载完毕')
 }
 
-Artalk.on('list-loaded', handler)
-Artalk.off('list-loaded', handler)
+artalk.on('list-loaded', handler)
+artalk.off('list-loaded', handler)
 ```
 
-## 触发事件 `Artalk.trigger`
+## 触发事件 `trigger`
 
 触发 Artalk 事件。
 
 ```js
-Artalk.trigger('list-loaded')
+const artalk = Artalk.init({ ... })
+
+artalk.trigger('list-loaded')
 ```
 
-## 扩展插件 `Artalk.use`
+## 加载插件 `use`
 
-该 API 用于扩展 Artalk。
+通过 `Artalk.use` 函数加载插件。请注意，该函数是一个全局函数，并非实例化对象中的方法。通过该函数加载的插件将对所有 Artalk 实例生效。
 
 ```js
+import Artalk from 'artalk'
+
 Artalk.use((ctx) => {
   ctx.editor.setContent("Hello World")
 })
+
+const artalk = Artalk.init({ ... })
 ```
 
 详情见：[插件开发](./plugs.md)
 
-## 夜间模式 `Artalk.setDarkMode`
+## 夜间模式 `setDarkMode`
 
 修改夜间模式，可以配合博客主题调用，例如当用户点击夜间模式切换按钮。
 
 ```js
-Artalk.setDarkMode(true)
+const artalk = Artalk.init({ ... })
+
+artalk.setDarkMode(true)
 ```
 
-## 浏览量组件 `Artalk.loadCountWidget`
+## 浏览量组件 `loadCountWidget`
 
 详情见：[浏览量统计](../guide/frontend/pv.md)

docs/develop/index.md

@@ -23,6 +23,6 @@
    * [@ArtalkJS/Artalk - server/server.go](https://github.com/ArtalkJS/Artalk/blob/master/server/server.go)
  - `UI` 及 `Event` 部分参考源码
    * [@ArtalkJS/Artalk - src/artalk.ts](https://github.com/ArtalkJS/Artalk/blob/master/ui/packages/artalk/src/artalk.ts)
-   * [@ArtalkJS/Artalk - types/event.d.ts](https://github.com/ArtalkJS/Artalk/blob/master/ui/packages/artalk/types/event.d.ts)
+   * [@ArtalkJS/Artalk - types/event.ts](https://github.com/ArtalkJS/Artalk/blob/master/ui/packages/artalk/types/event.ts)
 
 通过 Artalk 提供的 `API` 和 `Event`，你可以实现很多高级功能，比如编写评论管理机器人、评论提醒推送插件等。Artalk 并不为此提供技术指导，但鼓励你参考此处的文档自行定制。