feat: ma-form文档-1

mineadmin · Oct 30, 2024 · f1d9b9a · f1d9b9a
1 parent ede58ad
commit f1d9b9a
Show file tree

Hide file tree

Showing 10 changed files with 129 additions and 31 deletions.
diff --git a/.vitepress/components/preview.vue → .vitepress/components/demo-preview.vue b/.vitepress/components/preview.vue → .vitepress/components/demo-preview.vue
@@ -42,7 +42,7 @@ const isOpen = ref<boolean>(false)
         >
           {{ isOpen ? '隐藏' : '显示' }}代码
         </el-button>
-        <div class="px-4 max-h-[500px] overflow-y-auto">
+        <div class="px-4">
           <code-group v-if="codeFiles.length > 0 && isOpen" :files="codeFiles">
             <template v-for="file in codeFiles" #[file]>
               <slot :name="file"></slot>

diff --git a/.vitepress/config.mts b/.vitepress/config.mts
@@ -7,7 +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 { demoPreviewPlugin } from './plugins/previewPlugin'
 import UnoCSS from 'unocss/vite'
 import vueJsx from '@vitejs/plugin-vue-jsx'
 
@@ -125,7 +125,7 @@ export default defineConfigWithTheme ({
   srcDir: 'docs',
   markdown:{
     config:(md:MarkdownRenderer)=>{
-      md.use(previewPlugin)
+      md.use(demoPreviewPlugin)
       md.use(plantuml,{
         type:"fence",
         fence:"plantuml",

diff --git a/.vitepress/plugins/previewPlugin.ts b/.vitepress/plugins/previewPlugin.ts
@@ -1,10 +1,12 @@
-import type { MarkdownEnv, MarkdownRenderer } from 'vitepress'
+import type { MarkdownEnv, MarkdownRenderer } from 'vitepress';
 
-import crypto from 'node:crypto'
-import { readdirSync } from 'node:fs'
-import { join } from 'node:path'
+import crypto from 'node:crypto';
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
 
-export const rawPathRegexp = /^(.+?(?:\.([\da-z]+))?)(#[\w-]+)?(?: ?{(\d+(?:[,-]\d+)*)? ?(\S+)?})? ?(?:\[(.+)])?$/;
+export const rawPathRegexp =
+  // eslint-disable-next-line regexp/no-super-linear-backtracking, regexp/strict
+  /^(.+?(?:\.([\da-z]+))?)(#[\w-]+)?(?: ?{(\d+(?:[,-]\d+)*)? ?(\S+)?})? ?(?:\[(.+)])?$/;
 
 function rawPathToToken(rawPath: string) {
   const [
@@ -21,15 +23,15 @@ function rawPathToToken(rawPath: string) {
   return { extension, filepath, lang, lines, region, title };
 }
 
-export const previewPlugin = (md: MarkdownRenderer) => {
-  md.core.ruler.after('inline', 'preview', (state) => {
+export const demoPreviewPlugin = (md: MarkdownRenderer) => {
+  md.core.ruler.after('inline', 'demo-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`;
+        importComponent.content = `<script setup>\n${importString}\n</script>\n`;
         state.tokens.splice(0, 0, importComponent);
       } else {
         if (state.tokens[index]) {
@@ -42,7 +44,7 @@ export const previewPlugin = (md: MarkdownRenderer) => {
       }
     };
     // Define the regular expression to match the desired pattern
-    const regex = /<Preview[^>]*\sdir="([^"]*)"/g;
+    const regex = /<DemoPreview[^>]*\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(
@@ -88,7 +90,7 @@ export const previewPlugin = (md: MarkdownRenderer) => {
         return a.localeCompare(b, 'en', { sensitivity: 'base' });
       });
       state.tokens[index].content =
-        `<Preview files="${encodeURIComponent(JSON.stringify(childFiles))}" ><${ComponentName}/>
+        `<DemoPreview files="${encodeURIComponent(JSON.stringify(childFiles))}" ><${ComponentName}/>
         `;
 
       const _dummyToken = new state.Token('', '', 0);
@@ -119,7 +121,7 @@ export const previewPlugin = (md: MarkdownRenderer) => {
         tokenArray.push(templateEnd);
       });
       const endTag = new state.Token('html_inline', '', 0);
-      endTag.content = '</Preview>';
+      endTag.content = '</DemoPreview>';
       tokenArray.push(endTag);
 
       state.tokens.splice(index + 1, 0, ...tokenArray);

diff --git a/.vitepress/theme/components/layout.vue b/.vitepress/theme/components/layout.vue
@@ -28,7 +28,7 @@ giscusTalk({
 </script>
 
 <template>
-  <ElConfigProvider :locale="zhCn">
+  <ElConfigProvider :locale="{ zhCn }">
     <Layout />
   </ElConfigProvider>
 </template>
diff --git a/.vitepress/theme/index.ts b/.vitepress/theme/index.ts
@@ -39,7 +39,7 @@ import { baiduPlugin } from "./plugin/baidu";
 
 import "virtual:uno.css";
 
-import Preview from '../components/preview.vue';
+import DemoPreview from '../components/demo-preview.vue';
 import 'element-plus/dist/index.css'
 import 'element-plus/theme-chalk/dark/css-vars.css'
 
@@ -61,7 +61,7 @@ export default {
       app,
     })
 
-    app.component('Preview', Preview)
+    app.component('DemoPreview', DemoPreview)
 
     baiduPlugin()
   },

diff --git a/docs/demos/ma-form/index.vue → docs/demos/ma-form/config/index.vue b/docs/demos/ma-form/index.vue → docs/demos/ma-form/config/index.vue
diff --git a/docs/demos/ma-table/base/index.vue → docs/demos/ma-table/index.vue b/docs/demos/ma-table/base/index.vue → docs/demos/ma-table/index.vue
@@ -1,6 +1,11 @@
 <script setup lang="tsx">
 import { ref } from 'vue'
-import type { MaTableColumns, MaTableExpose, MaTableOptions } from "@mineadmin/table"
+import type {
+  MaTableColumns,
+  MaTableExpose,
+  MaTableOptions
+} from "@mineadmin/table"
+import { ElMessage } from 'element-plus'
 
 const tableRef = ref<MaTableExpose>()
 const columns = ref<MaTableColumns[]>([
@@ -23,6 +28,13 @@ const options = ref<MaTableOptions>({
   defaultSort: { prop: 'xinshui', order: 'descending' },
   showSummary: true,
   sumText: '合计薪资',
+  // 分页配置
+  pagination: {
+    total: 30,
+    onChange: (currentPage: number, pageSize: number) => {
+      ElMessage.success('当前页：' + currentPage + ', 每页显示：' + pageSize)
+    }
+  }
 })
 
 const data: any[] = [
@@ -35,12 +47,14 @@ const data: any[] = [
   { name: '陈平安', dept: '运营部', xinshui: 8750, date: '2022-08-05' },
   { name: '王林', dept: '研发部', xinshui: 11369, date: '2022-09-05' },
 ]
+
 </script>
 
 <template>
-  <ma-table ref="tableRef" :columns="columns" :data="data" :options="options" />
-</template>
-
-<style scoped>
-
-</style>
+  <ma-table
+    ref="tableRef"
+    :columns="columns"
+    :data="data"
+    :options="options"
+  />
+</template>
diff --git a/docs/zh/front/component/ma-form.md b/docs/zh/front/component/ma-form.md
@@ -1,3 +1,85 @@
 # MaForm
 
-与 `2.0` 相比，`3.0` 的更加自由高效，几乎接近原生写法，同时配合 `tsx` 或 `jsx` 语法，事半功倍。
+基于 `Element plus` 的表单二次封装的 `Form` 组件，支持所有原生表单的参数、事件、插槽、写法，还支持通过配置方式来实现。
+另外还支持了基于 `el-row` 和 `el-space` 的布局来规划表单
+
+::: tip 说明
+由于全部兼容及支持原生 `el-from` 的所有参数、事件、插槽，所以只讲扩展参数。
+
+官方表单参数请参考 [Element plus](https://element-plus.org/zh-CN/component/form.html) 官方文档。
+:::
+
+## 配置方式使用
+
+## 模板方式使用
+
+## 获取`组件`和`el-form-item`的`Ref`
+
+## Props
+
+| 参数        | 说明                             | 类型         | Ele-官网文档                                                                   | 版本    |
+|-----------|--------------------------------|-------------------|----------------------------------------------------------------------------|-------|
+| `v-model` | `ma-form`数据，双向绑定               | `MaModel`   | -                                                                          | 1.0.0 |
+| `options` | `el-form` 参数及[扩展参数](#extraprops) | `MaFormOptions`   | [表单属性](https://element-plus.org/zh-CN/component/form.html#form-attributes) | 1.0.0 |
+| `items`   | [ma-form-item参数](#maformitem)  | `MaFormItem[]` | -                                                                          | 1.0.0 |
+
+## ExtraProps
+::: tip 说明
+此为 `ma-form` 对 `el-form` 的扩展参数
+:::
+| 参数        | 说明                                                                    | 类型                                                                                              | 默认值      | 版本    |
+|-----------|-----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|----------|-------|
+| `containerClass` | 表单容器类名                                                                  | `string`                                                                                        | -        | 1.0.0 |
+| `loading` | 是否开启加载动画                                                              | `boolean`                                                                                       | `false`  | 1.0.0 |
+| `loadingConfig` | 加载动画的相关配置                                                             | [LoadingConfig](#loadingconfig说明)                                                               | -        | 1.0.0 |
+| `layout` | <el-tooltip content="布局方式，在使用`flex`时，可在 `item` 的 `itemProps` 配置项里设置 `cols` 参数 ，默认值：`flex`">`鼠标放上查看`</el-tooltip>  | `flex, grid` | `flex` | 1.0.0 |
+| `grid` | <el-tooltip content=" `grid` 布局，在 `layout` 为 `grid` 时生效。实际是用的 `el-space`，配置可参考 `element-plus` 的 `el-space` 文档">`鼠标放上查看`</el-tooltip> | [el-space文档](https://element-plus.org/zh-CN/component/space.html#attributes)     | -        | 1.0.0 |
+| `flex` | <el-tooltip content=" `flex` 布局，在 `layout` 为 `flex` 时生效。实际是用的 `el-row`，配置可参考 `element-plus` 的 `el-row` 文档">`鼠标放上查看`</el-tooltip> | [el-row文档](https://element-plus.org/zh-CN/component/layout.html#row-attributes)     | -        | 1.0.0 |
+| `footerSlot` | <el-tooltip content="配置型插槽，在 `template` 写法为 #footer">`鼠标放上查看`</el-tooltip>       | `() => {}`  | -  | 1.0.0 |
+
+### LoadingConfig说明
+| 参数        | 说明      | 类型   | 默认值 | 版本    |
+|-----------|----------|------|-----|-------|
+| `text` | 显示在加载图标下方的加载文案   | `string`  | -   | 1.0.0 |
+| `spinner` | 自定义加载图标   | `string` | -   | 1.0.0 |
+| `svg` | 自定义 `svg` 加载图标   | `string` | -   | 1.0.0 |
+| `viewBox` | 加载图标的大小   | `string` | -   | 1.0.0 |
+| `background` | 背景遮罩的颜色   | `string` | -   | 1.0.0 |
+| `customClass` | 自定义 class 类名   | `string` | -   | 1.0.0 |
+
+## MaFormItem
+
+| 参数             | 说明                                                                                                                                                                              | 类型                                                                                                 | 默认值     | 版本    |
+|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|---------|-------|
+| `label`        | 增强原生参数，添加支持函数类型                                                                                                                                                                 | `string, () => string`                                                                             | -       | 1.0.0 |
+| `prop`         | 增强原生参数，添加支持函数类型                                                                                                                                                                 | `string, () => string`                                                                             | -       | 1.0.0 |
+| `hide`   | <el-tooltip content="是否隐藏该项，隐藏后还是有数据的，默认: `false`，自定义组件下可能无效">`鼠标放上查看`</el-tooltip>                                                                                             | <el-tooltip content="boolean, (item: MaFormItem, model: MaModel) => boolean">`鼠标放上查看`</el-tooltip> | `false` | 1.0.0 |
+| `show` | <el-tooltip content="是否显示该项，不显示后实际不渲染，也没有数据，默认: `true`，自定义组件下可能无效">`鼠标放上查看`</el-tooltip>                                                                                        | <el-tooltip content="boolean, (item: MaFormItem, model: MaModel) => boolean">`鼠标放上查看`</el-tooltip> | `true`  | 1.0.0 |
+| `cols` | 在 `options.layout 为 flex` 下生效                                                                                                                                                   | [el-col文档](https://element-plus.org/zh-CN/component/layout.html#col-attributes)                    | -       | 1.0.0 |
+| `itemProps` | `el-form-item` 原生属性                                                                                                                                                             | [表单项属性](https://element-plus.org/zh-CN/component/form.html#formitem-attributes)                    | -       | 1.0.0 |
+| `itemSlots` | `el-form-item` 原生插槽                                                                                                                                                             | [表单项插槽](https://element-plus.org/zh-CN/component/form.html#formitem-slots)                         | -       | 1.0.0 |
+| `render` | 渲染单元格：<el-tooltip content="设置要渲染的组件，可设置 `element plus` 的所有 `form` 组件，例如：`input`, `datePicker`，也可以传入 `tsx`, `jsx` 语法的虚拟dom，也可以传入一个组件，函数式，例如：() => ElInput">`鼠标放上查看`</el-tooltip> | `string, () => any`                                                                                | -       | 1.0.0 |
+| `renderProps` | 被渲染组件的 `props` 属性                                                                                                                                                               | `Record<string, any>`                                                                              | -       | 1.0.0 |
+| `renderSlots` | 被渲染组件的插槽  | `Record<string, (...args) => {}>`                                                                  | -       | 1.0.0 |
+
+## Slot
+
+| 名称              | 说明                                    | 参数 |
+|-----------------|---------------------------------------|----|
+| `default`       | 默认插槽，可写原生标签 `<el-form-item>`，配置方式自动失效 | -  |
+| `footer`        | 表单底部插槽                                | -  |
+
+
+## Expose
+| 名称                  | 说明                | 参数                | 返回值             |
+|---------------------|-------------------|-------------------|-----------------|
+| `setLoadingState()` | 设置表单 `loading` 状态 | `(boolean)`       | -               |
+| `setOptions()`      | 设置 `ma-form` 配置   | `(MaFormOptions)` | -               |
+| `getOptions()`      | 获取 `ma-form` 配置   | -                 | `MaFormOptions` |
+| `setItems()`        | 设置表单项             | `(MaFormItem[])`  | -               |
+| `getItems()`        | 获取表单项             | -                 | `MaFormItem[]`  |
+| `appendItem()`      | 追加表单项             | `(MaFormItem)`    | -               |
+| `removeItem()`      | 移除表单项             | `(prop: string)`  | -              |
+| `getItemByProp()`   | 按`prop`获取表单项      | `(prop: string)`  | `MaFormItem`    |
+| `isMobileState()`   | 检查是否为移动端模式        | -                 | `boolean`    |
+| `getElFormRef()`    | 获取 `el-form` Ref  | -                 | `El-Form`       |
diff --git a/docs/zh/front/component/ma-table.md b/docs/zh/front/component/ma-table.md
@@ -6,11 +6,12 @@
 由于全部兼容及支持原生 `el-table` 的所有参数、事件、插槽，表格只讲扩展参数。
 
 官方参数请参考 [Element plus](https://element-plus.org/zh-CN/component/table.html) 官方文档。
+
+**注意：演示组件显示语言包不对很正常，项目里不会存在此问题。**
 :::
 
 ## 使用
-<Preview dir="demos/ma-table/base/" />
-
+<DemoPreview dir="demos/ma-table" />
 
 ## Props
 
@@ -64,14 +65,13 @@
 
 | 名称              | 说明                                     | 参数 |
 |-----------------|----------------------------------------|----|
-| `default`       | 原生插槽，自定义默认内容，必须为 `el-table-columns` 标签 | -  |
 | `empty`         | 原生插槽，空数据时显示                            | -  |
 | `append`        | 原生插槽，表格最后一行                            | -  |
 | `pageLeft`      | 分页那行左边区域插槽                             |    |
 | `column-[prop]` | 表格列插槽，`prop` 为字段名                      |  scope  |
 | `header-[prop]` | 表格头插槽，`prop` 为字段名                      |  scope  |
 
-## Emit
+## Event
 | 名称              | 说明         | 参数          |
 |-----------------|------------|-------------|
 | `set-data-callback`  | 设置表格数据后的回调 | `data: any[]` |
@@ -87,6 +87,6 @@
 | `setColumns()`      | 设置表格列             | `(MaTableColumns[])` | -                  |
 | `getColumns()`      | 获取表格列             | -                    | `MaTableColumns[]` |
 | `appendColumn()`    | 追加表格列             | `(MaTableColumns)`   | -                  |
-| `removeColumn()`    | 移除表格列             | `(prop: string)`     | `MaTableColumns`   |
+| `removeColumn()`    | 移除表格列             | `(prop: string)`     | -                  |
 | `getColumnByProp()`    | 按`prop`获取表格列      | `(prop: string)`     | `MaTableColumns`   |
 | `getElTableRef()`    | 获取 `el-table` Ref | -                    | `El-Table`         |
diff --git a/docs/zh/guide/start/fast-install.md b/docs/zh/guide/start/fast-install.md
@@ -78,7 +78,7 @@ docker run -d --name mineadmin -p 9501:9501 -v .:/opt/www mineadmin
 ::: code-group
 
 ```shell[重新安装 Vendor]
-composer instsll -vvv
+composer install -vvv
 ```
 
 ```shell [数据表迁移]