feat: 完善前端文档

.vitepress/components/preview.vue

@@ -0,0 +1,41 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+
+interface Props {
+  files?: string;
+}
+
+const props = withDefaults(defineProps<Props>(), { files: '() => []' });
+
+const parsedFiles = computed(() => {
+  try {
+    return JSON.parse(decodeURIComponent(props.files ?? ''));
+  } catch {
+    return [];
+  }
+});
+</script>
+
+<template>
+  <div class="border-border shadow-float relative rounded-xl border">
+    {{ parsedFiles }}
+    <div
+      class="not-prose relative w-full overflow-x-auto rounded-t-lg px-4 py-6"
+    >
+      <div class="flex w-full max-w-[700px] px-2">
+        <ClientOnly>
+          <slot v-if="parsedFiles.length > 0"></slot>
+          <div v-else class="text-destructive text-sm">
+            <span class="bg-destructive text-foreground rounded-sm px-1 py-1">
+              找不到演示文件路径
+            </span>
+          </div>
+        </ClientOnly>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+
+</style>

.vitepress/config.mts

@@ -7,6 +7,7 @@ import zhGetSidebar from "./src/zh/sidebars";
 import enGetSidebar from "./src/en/sidebars";
 import { AnnouncementPlugin } from 'vitepress-plugin-announcement'
 import { plantuml } from "@mdit/plugin-plantuml";
+import { previewPlugin } from './plugins/previewPlugin'
 import UnoCSS from 'unocss/vite'
 
 // https://vitepress.dev/reference/site-config
@@ -122,6 +123,7 @@ export default defineConfigWithTheme ({
   srcDir: 'docs',
   markdown:{
     config:(md:MarkdownRenderer)=>{
+      md.use(previewPlugin)
       md.use(plantuml,{
         type:"fence",
         fence:"plantuml",

.vitepress/plugins/previewPlugin.ts

@@ -0,0 +1,141 @@
+import type { MarkdownEnv, MarkdownRenderer } from 'vitepress'
+
+import crypto from 'node:crypto'
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const rawPathRegexp = /^(.+?(?:\.([\da-z]+))?)(#[\w-]+)?(?: ?{(\d+(?:[,-]\d+)*)? ?(\S+)?})? ?(?:\[(.+)])?$/;
+
+function rawPathToToken(rawPath: string) {
+  const [
+    filepath = '',
+    extension = '',
+    region = '',
+    lines = '',
+    lang = '',
+    rawTitle = '',
+  ] = (rawPathRegexp.exec(rawPath) || []).slice(1);
+
+  const title = rawTitle || filepath.split('/').pop() || '';
+
+  return { extension, filepath, lang, lines, region, title };
+}
+
+export const previewPlugin = (md: MarkdownRenderer) => {
+  md.core.ruler.after('inline', 'preview', (state) => {
+    const insertComponentImport = (importString: string) => {
+      const index = state.tokens.findIndex(
+        (i) => i.type === 'html_block' && i.content.match(/<script setup>/g),
+      );
+      if (index === -1) {
+        const importComponent = new state.Token('html_block', '', 0);
+        importComponent.content = `<script setup lang="ts">\n${importString}\n</script>\n`;
+        state.tokens.splice(0, 0, importComponent);
+      } else {
+        if (state.tokens[index]) {
+          const content = state.tokens[index].content;
+          state.tokens[index].content = content.replace(
+            '</script>',
+            `${importString}\n</script>`,
+          );
+        }
+      }
+    };
+    // Define the regular expression to match the desired pattern
+    const regex = /<Preview[^>]*\sdir="([^"]*)"/g;
+    // Iterate through the Markdown content and replace the pattern
+    state.src = state.src.replaceAll(regex, (_match, dir) => {
+      const componentDir = join(process.cwd(), 'docs', dir).replaceAll(
+        '\\',
+        '/',
+      );
+
+      let childFiles: string[] = [];
+      let dirExists = true;
+
+      try {
+        childFiles =
+          readdirSync(componentDir, {
+            encoding: 'utf8',
+            recursive: false,
+            withFileTypes: false,
+          }) || [];
+      } catch {
+        dirExists = false;
+      }
+
+      if (!dirExists) {
+        return '';
+      }
+
+      const uniqueWord = generateContentHash(componentDir);
+
+      const ComponentName = `DemoComponent_${uniqueWord}`;
+      insertComponentImport(
+        `import ${ComponentName} from '${componentDir}/index.vue'`,
+      );
+      const { path: _path } = state.env as MarkdownEnv;
+
+      const index = state.tokens.findIndex((i) => i.content.match(regex));
+
+      if (!state.tokens[index]) {
+        return '';
+      }
+      const firstString = 'index.vue';
+      childFiles = childFiles.sort((a, b) => {
+        if (a === firstString) return -1;
+        if (b === firstString) return 1;
+        return a.localeCompare(b, 'en', { sensitivity: 'base' });
+      });
+      state.tokens[index].content =
+        `<Preview files="${encodeURIComponent(JSON.stringify(childFiles))}" ><${ComponentName}/>
+        `;
+
+      const _dummyToken = new state.Token('', '', 0);
+      const tokenArray: Array<typeof _dummyToken> = [];
+      childFiles.forEach((filename) => {
+        // const slotName = filename.replace(extname(filename), '');
+
+        const templateStart = new state.Token('html_inline', '', 0);
+        templateStart.content = `<template #${filename}>`;
+        tokenArray.push(templateStart);
+
+        const resolvedPath = join(componentDir, filename);
+
+        const { extension, filepath, lang, lines, title } =
+          rawPathToToken(resolvedPath);
+        // Add code tokens for each line
+        const token = new state.Token('fence', 'code', 0);
+        token.info = `${lang || extension}${lines ? `{${lines}}` : ''}${
+          title ? `[${title}]` : ''
+        }`;
+
+        token.content = `<<< ${filepath}`;
+        (token as any).src = [resolvedPath];
+        tokenArray.push(token);
+
+        const templateEnd = new state.Token('html_inline', '', 0);
+        templateEnd.content = '</template>';
+        tokenArray.push(templateEnd);
+      });
+      const endTag = new state.Token('html_inline', '', 0);
+      endTag.content = '</Preview>';
+      tokenArray.push(endTag);
+
+      state.tokens.splice(index + 1, 0, ...tokenArray);
+
+      // console.log(
+      //   state.md.renderer.render(state.tokens, state?.options ?? [], state.env),
+      // );
+      return '';
+    });
+  });
+};
+
+function generateContentHash(input: string, length: number = 10): string {
+  // 使用 SHA-256 生成哈希值
+  const hash = crypto.createHash('sha256').update(input).digest('hex');
+
+  // 将哈希值转换为 Base36 编码，并取指定长度的字符作为结果
+  return Number.parseInt(hash, 16).toString(36).slice(0, length);
+}

.vitepress/src/zh/sidebars.ts

@@ -161,14 +161,14 @@ const sidebar:DefaultTheme.Sidebar = {
           text: 'MaTable',
           link: '/zh/front/component/ma-table'
         },
-        {
-          text: 'MaProTable',
-          link: '/zh/front/component/ma-pro-table'
-        },
         {
           text: 'MaSearch',
           link: '/zh/front/component/ma-search'
         },
+        {
+          text: 'MaProTable',
+          link: '/zh/front/component/ma-pro-table'
+        },
         {
           text: 'MaEcharts',
           link: '/zh/front/component/ma-echarts'

.vitepress/theme/index.ts

@@ -40,6 +40,8 @@ import { baiduPlugin } from "./plugin/baidu";
 
 import "virtual:uno.css";
 
+import Preview from '../components/preview.vue';
+
 export default {
   enhanceApp(ctx: EnhanceAppContext) {
 
@@ -57,6 +59,9 @@ export default {
       },
       app,
     })
+
+    app.component('Preview', Preview)
+
     baiduPlugin()
   },
   extends: DefaultTheme,

docs/demos/ma-dialog/index.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+
+</script>
+
+<template>
+
+</template>
+
+<style scoped>
+
+</style>

docs/demos/ma-echarts/index.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+
+</script>
+
+<template>
+
+</template>
+
+<style scoped>
+
+</style>

docs/demos/ma-form/index.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+
+</script>
+
+<template>
+
+</template>
+
+<style scoped>
+
+</style>

docs/demos/ma-pro-table/index.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+
+</script>
+
+<template>
+
+</template>
+
+<style scoped>
+
+</style>

docs/demos/ma-search/index.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+
+</script>
+
+<template>
+
+</template>
+
+<style scoped>
+
+</style>

docs/demos/ma-table/index.vue

@@ -0,0 +1,11 @@
+<script setup lang="ts">
+
+</script>
+
+<template>
+
+</template>
+
+<style scoped>
+
+</style>

docs/zh/front/component/ma-dialog.md

@@ -0,0 +1 @@
+# MaDialog

docs/zh/front/component/ma-echarts.md

@@ -0,0 +1 @@
+# MaEcharts

docs/zh/front/component/ma-pro-table.md

@@ -0,0 +1 @@
+# MaProTable

docs/zh/front/component/ma-search.md

@@ -0,0 +1 @@
+# MaSearch

docs/zh/front/component/ma-table.md

@@ -0,0 +1,6 @@
+# MaTable
+
+二次封装的 `Table` 组件，非常好用。
+
+<Preview dir="demos/ma-form" />
+

package.json

@@ -9,9 +9,9 @@
     "@imengyu/vue3-context-menu": "^1.4.2",
     "@mineadmin/echarts": "^1.0.1",
     "@mineadmin/form": "^1.0.20",
-    "@mineadmin/pro-table": "^1.0.19",
+    "@mineadmin/pro-table": "^1.0.22",
     "@mineadmin/search": "^1.0.19",
-    "@mineadmin/table": "^1.0.22",
+    "@mineadmin/table": "^1.0.23",
     "@vueuse/core": "^11.1.0",
     "@vueuse/integrations": "^11.1.0",
     "echarts": "^5.5.1",