From 22117d8d9734d1ae73abbaf13e1761cb06163896 Mon Sep 17 00:00:00 2001
From: Shigma <1700011071@pku.edu.cn>
Date: Tue, 15 Feb 2022 11:59:20 +0800
Subject: [PATCH] docs: add console data docs

---
 docs/.vuepress/markdown/highlight.js |   4 +-
 docs/guide/console/data.md           | 136 +++++++++++++++++++++++++++
 docs/guide/console/extension.md      |   4 +-
 3 files changed, 140 insertions(+), 4 deletions(-)

diff --git a/docs/.vuepress/markdown/highlight.js b/docs/.vuepress/markdown/highlight.js
index 604e23e3a6..996271ce06 100644
--- a/docs/.vuepress/markdown/highlight.js
+++ b/docs/.vuepress/markdown/highlight.js
@@ -26,10 +26,10 @@ module.exports = {
 
     md.options.highlight = (code, lang) => {
       if (!lang) {
-        return `<pre><code>${escapeHtml(code)}</code></pre>`
+        return `<pre v-pre><code>${escapeHtml(code)}</code></pre>`
       }
       const h = lang === 'cli' || cliAliases.includes(lang) ? highlighter2 : highlighter1
-      return h.codeToHtml(code, lang)
+      return h.codeToHtml(code, lang).replace('<pre', '<pre v-pre')
     }
 
     const fence = md.renderer.rules.fence
diff --git a/docs/guide/console/data.md b/docs/guide/console/data.md
index 2321735a21..c0796f8abd 100644
--- a/docs/guide/console/data.md
+++ b/docs/guide/console/data.md
@@ -3,3 +3,139 @@ sidebarDepth: 2
 ---
 
 # 数据交互
+
+前后端的数据交互基本是通过 WebSocket 实现的。为了适应不同的场景，我们提供了多种数据交互的形式。
+
+## 被动推送
+
+后端代码：
+
+```ts src/index.ts
+import { Context } from 'koishi'
+import { DataService } from '@koishijs/plugin-console'
+
+declare module '@koishijs/plugin-console' {
+  namespace Console {
+    interface Services {
+      custom: CustomProvider
+    }
+  }
+}
+
+class CustomProvider extends DataSource<string[]> {
+  constructor(ctx: Context) {
+    super(ctx, 'custom')
+  }
+
+  get() {
+    return ['Hello', 'World']
+  }
+}
+
+export const name = 'my-plugin'
+export const using = ['console'] as const
+
+export function apply(ctx: Context) {
+  ctx.plugin(CustomProvider)
+
+  ctx.console.addEntry({
+    dev: resolve(__dirname, 'client/index.ts'),
+    prod: resolve(__dirname, 'dist'),
+  })
+}
+```
+
+前端代码：
+
+```ts client/index.ts
+import { Context } from '@koishijs/client'
+import Page from './custom-page.vue'
+
+export default (ctx: Context) => {
+  ctx.addPage({
+    name: '页面标题',
+    path: '/custom-page',
+    // 只有当获得了 custom 数据，才可以访问页面
+    fields: ['custom'],
+    component: Page,
+  })
+}
+```
+
+```vue client/custom-page.vue
+<template>
+  <!-- 这里应该有类型支持，并且支持数据响应式变化 -->
+  <k-card>{{ store.custom }}</k-card>
+</template>
+
+<script>
+import { store } from '@koishijs/client'
+</script>
+```
+
+## 主动获取
+
+后端代码：
+
+```ts src/index.ts
+import { Context } from 'koishi'
+import { DataService } from '@koishijs/plugin-console'
+
+declare module '@koishijs/plugin-console' {
+  interface Events {
+    'get-greeting'(): string[]
+  }
+}
+
+export const name = 'my-plugin'
+export const using = ['console'] as const
+
+export function apply(ctx: Context) {
+  ctx.console.addListener('get-greeting', () => {
+    return ['Hello', 'World']
+  })
+
+  ctx.console.addEntry({
+    dev: resolve(__dirname, 'client/index.ts'),
+    prod: resolve(__dirname, 'dist'),
+  })
+}
+```
+
+```vue client/custom-page.vue
+<template>
+  <k-card>{{ greeting }}</k-card>
+</template>
+
+<script>
+import { send } from '@koishijs/client'
+import { ref } from 'vue'
+
+const greeting = ref<string[]>()
+
+send('get-greeting').then(data => {
+  greeting.value = data
+})
+</script>
+```
+
+## 权限管理
+
+当你引入了 @koishijs/plugin-auth 插件之后，你可以为你的页面访问和数据交互引入鉴权机制：
+
+```ts
+// 只有已登录并且权限等级不低于 3 的用户才能访问此接口
+ctx.console.addListener('get-greeting', () => {
+  return ['Hello', 'World']
+}, { authority: 3 })
+```
+
+```ts client/index.ts
+ctx.addPage({
+  name: '页面标题',
+  path: '/custom-page',
+  // 只有已登录并且权限等级不低于 3 的用户才能访问此界面
+  authority: 3,
+  component: Page,
+})
+```
diff --git a/docs/guide/console/extension.md b/docs/guide/console/extension.md
index 94d0069817..a1896fb589 100644
--- a/docs/guide/console/extension.md
+++ b/docs/guide/console/extension.md
@@ -44,13 +44,13 @@ export default (ctx: Context) => {
 }
 ```
 
-```vue custom-page.vue
+```vue client/custom-page.vue
 <template>
   <k-card>扩展内容</k-card>
 </template>
 ```
 
-```json tsconfig.json
+```json client/tsconfig.json
 {
   "compilerOptions": {
     "rootDir": ".",