mgacn-commonsdk 1.0.1 → 1.0.3

package/README.md

@@ -28,14 +28,14 @@ npm install mgacn-commonsdk
 ## 使用
 
 ```js
-import MgacnCommonSdk from 'mgacn-commonsdk'
-import 'mgacn-commonsdk/style.css'
+import MgacnCommonSdk from 'mgacn-commonsdk';
+import 'mgacn-commonsdk/style.css';
 
 app.use(MgacnCommonSdk, {
   tokenKey: 'your_token_key',
   baseURL: import.meta.env.VITE_API_BASE_URL,
   systemIdKey: 'mgacn_systemid', // 可选，有的系统需要
-})
+});
 ```
 
 ### 网络请求（宿主使用 .GET / .POST）
@@ -44,36 +44,206 @@ app.use(MgacnCommonSdk, {
 
 ```js
 // Options API
-this.$request.GET('/yhAdmin/user/queryUserById', { params: { id: 1 } })
-this.$request.POST('/yhAdmin/user/edit', { name: '张三' })
-this.$request.DELETE(`/yhAdmin/portal/deleteManager/${userId}`)
+this.$request.GET('/yhAdmin/user/queryUserById', { params: { id: 1 } });
+this.$request.POST('/yhAdmin/user/edit', { name: '张三' });
+this.$request.DELETE(`/yhAdmin/portal/deleteManager/${userId}`);
 
 // Composition API / <script setup>
-import { getRequest } from 'mgacn-commonsdk'
+import { getRequest } from 'mgacn-commonsdk';
 
-const request = getRequest()
-await request.GET('/path', { params: { page: 1 } })
-await request.POST('/path', { foo: 1 })
+const request = getRequest();
+await request.GET('/path', { params: { page: 1 } });
+await request.POST('/path', { foo: 1 });
 ```
 
 也可继续用封装好的 api：
 
 ```js
-import { getApi } from 'mgacn-commonsdk'
-await getApi().getUserInfo(userId)
+import { getApi } from 'mgacn-commonsdk';
+await getApi().getUserInfo(userId);
+await getApi().logout(username);
+await getApi().getOssSts(dir);
 ```
 
+### 工具方法
+
+统一通过 `utils` 调用，不单独导出各方法：
+
+```js
+import { utils } from 'mgacn-commonsdk';
+
+utils.formatDate(new Date(), 'YYYY-MM-DD HH:mm:ss');
+utils.formatNum(134343432); // '134,343,432'
+utils.debounce(fn, 300);
+utils.throttle(fn, 300);
+utils.uniqueId('row');
+```
+
+#### `utils.formatDate(date, format?)` 日期格式化
+
+第二个参数是格式模板，连接符可自定义（`-` / `.` / 中文「年月日」等）：
+
+| 占位符     | 含义                |
+| ---------- | ------------------- |
+| `YYYY`     | 年                  |
+| `MM` / `M` | 月（补零 / 不补零） |
+| `DD` / `D` | 日（补零 / 不补零） |
+| `HH` / `H` | 时                  |
+| `mm` / `m` | 分                  |
+| `ss` / `s` | 秒                  |
+
+```js
+utils.formatDate(date); // 2026-08-07 14:30:00（默认）
+utils.formatDate(date, 'YYYY-MM-DD'); // 2026-08-07
+utils.formatDate(date, 'YYYY.MM.DD'); // 2026.08.07
+utils.formatDate(date, 'YYYY/MM/DD'); // 2026/08/07
+utils.formatDate(date, 'YYYY年MM月DD日'); // 2026年08月07日
+utils.formatDate(date, 'YYYY年M月D日'); // 2026年8月7日
+utils.formatDate(date, 'YYYY年MM月DD日 HH:mm'); // 2026年08月07日 14:30
+```
+
+非法日期返回空字符串 `''`。
+
+**Safari 兼容：** 不要依赖 `new Date('2026-08-07 14:30:00')`（Safari 会 Invalid）。`formatDate` / `parseDate` 已对常见字符串做手动拆解，以下均可：
+
+```js
+utils.formatDate('2026-08-07 14:30:00');
+utils.formatDate('2026/08/07 14:30:00');
+utils.formatDate('2026年08月07日');
+utils.parseDate('2026-08-07'); // 返回 Date，失败为 null
+```
+
+#### `utils.getRecentMonthRange()` 最近一个月起止时间
+
+返回最近 30 天区间，开始为 `00:00:00`，结束为当天 `23:59:59`：
+
+```js
+const { start, end } = utils.getRecentMonthRange();
+// start: '2026-07-08 00:00:00'
+// end:   '2026-08-07 23:59:59'
+```
+
+#### `utils.cleanParams(params)` 清理请求参数
+
+去掉 `undefined` / `null` / `''` / 空数组，避免空条件传给后端：
+
+```js
+utils.cleanParams({
+  name: '张三',
+  projectIds: [],
+  type: undefined,
+});
+// => { name: '张三' }
+```
+
+#### `utils.formatNum(val, digits?)` 数字千分位
+
+用于 PV / UV、统计数量等展示。最多保留 `digits` 位小数（默认 2），并去掉小数末尾多余的 `0`。空值保持原值，不转成 0。
+
+```js
+utils.formatNum(134343432); // '134,343,432'
+utils.formatNum(1234.5); // '1,234.5'
+utils.formatNum(1234.56); // '1,234.56'
+utils.formatNum(1000, 0); // '1,000'
+utils.formatNum(null); // null
+utils.formatNum('abc'); // 'abc'
+```
+
+#### `utils.debounce(fn, delay?)` 防抖
+
+连续触发时只执行最后一次，适合搜索输入、窗口 resize 等。`delay` 默认 `300`（毫秒）。
+
+```vue
+<script setup>
+// ✅ 在 setup 顶层创建一次，后续复用同一个函数
+const handleInput = utils.debounce(val => {
+  getRequest().POST('/xxx/search', { keyword: val });
+}, 400);
+</script>
+
+<template>
+  <el-input @input="handleInput" />
+</template>
+```
+
+Options API：
+
+```js
+export default {
+  created() {
+    this.handleInput = utils.debounce(val => {
+      // ...
+    }, 400);
+  },
+};
+```
+
+**注意事项：**
+
+- `debounce` 返回的是**新函数**，必须存下来复用（赋给常量 / `this.xxx`），不要在每次事件回调里再包一层 `utils.debounce(...)`，否则每次都是新实例，防抖会失效。
+- 错误示例：
+
+```js
+// ❌ 每次输入都新建 debounce，防不住
+function handleInput(val) {
+  utils.debounce(() => {
+    getRequest().POST('/xxx/search', { keyword: val });
+  }, 400)();
+}
+```
+
+- 组件卸载后若仍可能触发（少见），注意清理定时器；当前实现未暴露 `cancel`，一般页面内搜索场景无需额外处理。
+
+#### `utils.throttle(fn, delay?)` 节流
+
+在固定时间间隔内最多执行一次，适合滚动监听、频繁点击、拖拽等。`delay` 默认 `300`（毫秒）。
+
+和防抖的区别：
+
+|          | debounce 防抖    | throttle 节流        |
+| -------- | ---------------- | -------------------- |
+| 行为     | 停下来之后才执行 | 每隔一段时间执行一次 |
+| 典型场景 | 搜索框输入       | 页面滚动、按钮连点   |
+
+```vue
+<script setup>
+// ✅ 同样要在 setup 顶层创建一次并复用
+const onScroll = utils.throttle(() => {
+  console.log('滚动位置', window.scrollY);
+}, 200);
+
+onMounted(() => window.addEventListener('scroll', onScroll));
+onBeforeUnmount(() => window.removeEventListener('scroll', onScroll));
+</script>
+```
+
+按钮防连点：
+
+接入系统（如 portal_cms）若已有 `v-noMoreClick` 自定义指令，**按钮场景优先用指令**，不必再用 `utils.throttle`：
+
+```vue
+<el-button type="primary" v-noMoreClick @click="onSubmit">提交</el-button>
+```
+
+`utils.throttle` 更适合滚动、resize、拖拽等非点击场景。
+
+**注意事项：**
+
+- 与 `debounce` 一样，返回的是**新函数**，必须存下来复用，不要在事件回调里每次 `utils.throttle(...)`。
+- 当前实现是「时间戳版」：间隔内再次触发会直接忽略，**不会在间隔结束后补跑最后一次**。
+- 第一次调用会立刻执行（满足间隔条件时）。
+
 ### 手动创建
 
 ```js
-import { createRequest, createApi } from 'mgacn-commonsdk'
+import { createRequest, createApi } from 'mgacn-commonsdk';
 
 const request = createRequest({
   tokenKey: 'your_token_key',
   baseURL: '/api',
   systemIdKey: 'mgacn_systemid', // 可选
-})
-const api = createApi(request)
+});
+const api = createApi(request);
 ```
 
 ### 图片上传
@@ -96,25 +266,25 @@ export default {
     return {
       urls: [], // 统一为 string[]，无图时为 []
       uploading: false,
-    }
+    };
   },
   methods: {
     submit() {
       if (this.uploading) {
-        this.$message.warning('图片上传中，请稍候')
-        return
+        this.$message.warning('图片上传中，请稍候');
+        return;
       }
       // this.urls => ['https://...', 'https://...']
     },
   },
-}
+};
 </script>
 ```
 
 也可通过 ref 判断：
 
 ```js
-if (this.$refs.upload.isUploading()) return
+if (this.$refs.upload.isUploading()) return;
 ```
 
 先 `app.use(MgacnCommonSdk, { tokenKey, baseURL })` 后，组件内部通过项目 `api.getOssSts` 获取凭证。
@@ -123,15 +293,15 @@ if (this.$refs.upload.isUploading()) return
 
 配置驱动，支持字段类型：
 
-| type | 说明 |
-| --- | --- |
-| `input` / `text` | 文本输入 |
-| `select` | 下拉选择 |
-| `remoteSelect` / `remote` | 远程搜索下拉 |
-| `numberRange` | 数字最小～最大区间 |
-| `date` | 日期 |
-| `dateRange` | 日期区间 |
-| `slot` | 自定义插槽 |
+| type                      | 说明               |
+| ------------------------- | ------------------ |
+| `input` / `text`          | 文本输入           |
+| `select`                  | 下拉选择           |
+| `remoteSelect` / `remote` | 远程搜索下拉       |
+| `numberRange`             | 数字最小～最大区间 |
+| `date`                    | 日期               |
+| `dateRange`               | 日期区间           |
+| `slot`                    | 自定义插槽         |
 
 ```vue
 <MgSearchForm
@@ -142,7 +312,13 @@ if (this.$refs.upload.isUploading()) return
     { type: 'remoteSelect', prop: 'deptId', label: '部门', remoteMethod: searchDept },
     { type: 'numberRange', prop: 'age', label: '年龄', startProp: 'ageMin', endProp: 'ageMax' },
     { type: 'date', prop: 'birthday', label: '生日' },
-    { type: 'dateRange', prop: 'createTime', label: '创建时间', startProp: 'start', endProp: 'end' },
+    {
+      type: 'dateRange',
+      prop: 'createTime',
+      label: '创建时间',
+      startProp: 'start',
+      endProp: 'end',
+    },
   ]"
   @search="onSearch"
   @reset="onReset"