知识库文档，参数说明放弃表格改用列表

Tevin

2025-03-08 90b79a92b0bc878491d9d7d64ec732f0f50ba4a3

知识库文档，参数说明放弃表格改用列表

 @framework/201-请求层基类Fetcher.md

@@ -57,18 +57,14 @@
### `spellURL(devSuffix, serSuffix)`

**功能**  
根据开发环境和生产环境拼接 URL 地址。
根据开发环境和生产环境拼接 URL 地址

**参数**
| 参数名    | 类型   | 说明                      |
| --------- | ------ | ------------------------- |
| devSuffix | String | 开发环境 URL 后缀         |
| serSuffix | String | 生产环境 URL 后缀（可选） |
- `devSuffix` (String)：开发环境下的 URL 后缀
- `serSuffix` (String, 可选)：生产环境下的 URL 后缀。如果未提供，则使用 `devSuffix`

**返回值**
| 类型   | 说明                              |
| ------ | --------------------------------- |
| String | 拼接后的完整 URL 地址（不含域名） |
- (String)：处理后的完整 URL 地址

**示例**
```javascript
@@ -81,27 +77,23 @@
```

**注意事项**
- 如果启用了 Mock 模式（比如本地开发时），URL 会指向本地的 JSON 文件。
- 支持处理路径中的 `../` 和多余的 `/`。
- 如果启用了 Mock 模式（比如本地开发时），URL 会指向本地的 JSON 文件
- 自动处理路径中的 `../` 和多余的 `/`，确保路径正确

---

### `get(url, data, options)`

**功能**  
发起 GET 请求。
发起 GET 请求

**参数**  
| 参数名  | 类型   | 说明             |
| ------- | ------ | ---------------- |
| url     | String | 请求的 URL 地址  |
| data    | Object | 请求参数         |
| options | Object | 请求配置（可选） |
- `url` (String)：请求的 URL 地址
- `data` (Object)：请求参数
- `options` (Object，可选)：请求配置

**返回值**  
| 类型    | 说明                   |
| ------- | ---------------------- |
| Promise | 返回请求结果的 Promise |
- (Promise)：返回请求结果的 Promise

---

@@ -111,16 +103,12 @@
发起 POST 请求，query 方法的简写

**参数**  
| 参数名  | 类型   | 说明             |
| ------- | ------ | ---------------- |
| url     | String | 请求的 URL 地址  |
| data    | Object | 请求参数         |
| options | Object | 请求配置（可选） |
- `url` (String)：请求的 URL 地址
- `data` (Object)：请求参数
- `options` (Object，可选)：请求配置

**返回值**  
| 类型    | 说明                   |
| ------- | ---------------------- |
| Promise | 返回请求结果的 Promise |
- (Promise)：返回请求结果的 Promise

**示例**
```js
@@ -142,17 +130,13 @@
发起基础 AJAX 请求

**参数**  
| 参数名  | 类型   | 说明                             |
| ------- | ------ | -------------------------------- |
| type    | String | 请求类型（如 `'get'`、`'post'`） |
| url     | String | 请求的 URL 地址                  |
| data    | Object | 请求参数（可选）                 |
| options | Object | 请求配置（可选）                 |
- `type` (String)：请求类型（如 `'get'`、`'post'`）
- `url` (String)：请求的 URL 地址
- `data` (Object，可选)：请求参数
- `options` (Object，可选)：请求配置

**返回值**  
| 类型    | 说明                   |
| ------- | ---------------------- |
| Promise | 返回请求结果的 Promise |
- (Promise)：返回请求结果的 Promise

**注意事项**  
- 小程序环境下会自动处理 Cookie，无需手动设置
@@ -165,14 +149,10 @@
将下划线命名的字符串转换为小驼峰命名

**参数**  
| 参数名 | 类型   | 说明             |
| ------ | ------ | ---------------- |
| str    | String | 需要转换的字符串 |
- `str` (String)：需要转换的字符串  

**返回值**  
| 类型   | 说明                 |
| ------ | -------------------- |
| String | 转换后的小驼峰字符串 |
- (String)：转换后的小驼峰字符串

---

@@ -181,14 +161,10 @@
将小驼峰命名的字符串转换为下划线命名，如果没有大写字母，则返回原字符串

**参数**  
| 参数名 | 类型   | 说明             |
| ------ | ------ | ---------------- |
| str    | String | 需要转换的字符串 |
- `str` (String)：需要转换的字符串  

**返回值**  
| 类型   | 说明                 |
| ------ | -------------------- |
| String | 转换后的下划线字符串 |
- (String)：转换后的下划线字符串

---

@@ -197,15 +173,13 @@
将 JSON 对象的键名在驼峰与下划线命名模式之间转换

**参数**  
| 参数名 | 类型   | 说明                                 |
| ------ | ------ | ------------------------------------ |
| type   | String | 转换类型：`'camel'` 或 `'underline'` |
| json   | Object | 需要转换的 JSON 对象                 |
- `type` (String)：转换的目标类型，有两个值：
  - `'camel'`：下划线转小驼峰
  - `'underline'`：小驼峰转下划线
- `json` (Object)：需要转换的 JSON 对象

**返回值**  
| 类型   | 说明               |
| ------ | ------------------ |
| Object | 转换后的 JSON 对象 |
- (Object)：转换后的 JSON 对象

**示例**  
```js
@@ -224,16 +198,40 @@
## 请求的 options 配置

### `hostType` 主机类型
在混合 App 中，指定本次请求的主机类型（即域名）

- `base` 基础主机（预登陆用）
- `main` 默认主机，默认值，正常业务主机
在混合 App 中，指定本次请求的主机类型（即域名），有两个值：

- `base`：基础主机（预登陆用）
- `main`：默认主机，默认值，正常业务主机
  - 优先由 java 层在 webview 的 URL 上指定
  - 未指定时，按文件 project.config.json 的 host.buildHost 项值指定

**示例**  
```js
class FCommon extends Fetcher {

    loginPrepare() {
        const url = this.spellURL('loginPrepare', 'User/preLogin');
        const send = {};
        return this.post(url, send, { hostType: 'base' });
    }
}
```

### `silence` 静音请求
设为 true 时，如果请求失败，不显示提示

**示例**  
```js
class FCommon extends Fetcher {

    getUserInfo() {
        const url = this.spellURL('getUserInfo', 'User/info');
        const send = {};
        return this.post(url, send, { silence: true });
    }
}
```


## 响应处理
@@ -253,7 +251,7 @@

格式如下：

```
```js
{
    state: { // 状态
        code, // 状态码
@@ -283,13 +281,11 @@

### 前端统一响应状态码

| 状态码 | 意义                                                   |
| ------ | ------------------------------------------------------ |
| 2000   | 通用请求成功                                           |
| 2001   | 请求成功，但是没有数据，弹窗提示 msg（仅特殊情况使用） |
| 5000   | 通用请求失败，弹窗提示 msg                             |
| 9001   | 登录已过期，返回登录页                                 |
| 9002   | 已登录但没有操作权限，弹窗提示 msg                     |
- `2000`：通用请求成功  
- `2001`：请求成功，但是没有数据，弹窗提示 msg（仅特殊情况使用）  
- `5000`：通用请求失败，弹窗提示 msg  
- `9001`：登录已过期，返回登录页  
- `9002`：已登录但没有操作权限，弹窗提示 msg

## 请求调用


 @framework/202-数据控制层基类Pilot.md

@@ -38,14 +38,10 @@
创建页面合并对象，将实例的属性和方法映射到页面合并对象中

**参数**  
| 参数名  | 类型   | 说明                       |
| ------- | ------ | -------------------------- |
| dataAdd | Object | 需要添加到页面中的额外数据 |
- `dataAdd` (Object)：需要添加到页面中的额外数据  

**返回值**  
| 类型   | 说明         |
| ------ | ------------ |
| Object | 页面合并对象 |
- (Object)：页面合并对象


**注意事项**  
@@ -53,20 +49,17 @@
- `$` 开头的属性会被直接映射到合并对象中，同时去掉 `$` 前缀
- 非 `$` 开头的属性会被映射到合并对象的 `methods` 属性中

---

### `transAssets(assets)`
**功能**  
转换静态图片引用的路径，根据运行环境（H5 或小程序）生成图片实际发布的路径

**参数**  
| 参数名 | 类型   | 说明               |
| ------ | ------ | ------------------ |
| assets | Object | 包含图片路径的对象 |
- `assets` (Object)：包含图片路径的对象  

**返回值**  
| 类型   | 说明                 |
| ------ | -------------------- |
| Object | 转换后的图片路径对象 |
- (Object)：转换后的图片路径对象

#### 静态图片地址转换说明

@@ -107,12 +100,12 @@

## 页面合并流程

`createOptions` 是类 Pilot 的核心方法，此方法将独立申明的信息合并回原 Vue 对象
`createOptions` 是类 Pilot 的核心方法，此方法将独立申明的信息转换为合并对象，以方便原 Vue 对象进行合并

### 第一步：生成合并对象

* 扫描当前类，以 \$ 开头的属性或方法，去掉 \$ 符后，直接作为 Vue 的属性或方法准备合并
* 扫描当前类，非以 \$ 开头的方法，作为 Vue 对象申明中 methods 的子级方法准备合并
* 扫描当前类，以 `$` 开头的属性或方法，去掉 `$` 符后，直接作为 Vue 的属性或方法准备合并
* 扫描当前类，非以 `$` 开头的方法，作为 Vue 对象申明中 methods 的子级方法准备合并
* 生成合并对象，用以进行合并

```js
@@ -192,11 +185,12 @@
this.$poster(direction, action, data);
```

| 参数名    | 类型   | 必填 | 描述                                                     |
| --------- | ------ | ---- | -------------------------------------------------------- |
| direction | String | 是   | 发送去向，有两个值，下一页'nextPage'、上一页'prevPage'） |
| action    | String | 是   | 动作名称                                                 |
| data      | any    | 否   | 携带数据                                                 |
参数：  
- `direction` (String，必填)：发送去向，有两值：
  - `'nextPage'`：发生给下一页（如果正在创建，会等待创建成功后再传递）
  - `'prevPage'`：发送给上一页
- `action` (String，必填)：动作名称  
- `data` (any，可选)：携带数据

例如：


 @framework/210-公共工具箱Tools.md

@@ -5,6 +5,18 @@
  - [引用方法](#引用方法)
  - [使用方法](#使用方法)
  - [方法列表](#方法列表)
    - [`toast()`](#toast)
    - [`getUrlParam(name, search)`](#geturlparamname-search)
    - [`createGUID()`](#createguid)
    - [`getRandomString(long)`](#getrandomstringlong)
    - [`isNumber(data)`](#isnumberdata)
    - [`isString(data)`](#isstringdata)
    - [`isBoolean(data)`](#isbooleandata)
    - [`isObject(data)`](#isobjectdata)
    - [`isArray(data)`](#isarraydata)
    - [`isFunction(data)`](#isfunctiondata)
    - [`isUndefined(data)`](#isundefineddata)
    - [`isNull(data)`](#isnulldata)
  - [部分功能详解](#部分功能详解)
    - [momentFormat 时间格式化](#momentformat-时间格式化)
    - [debounce、throttle 防抖和节流](#debouncethrottle-防抖和节流)
@@ -31,269 +43,225 @@

## 方法列表

```JS
export class Tools {
    /**
     * 显示消息
     * @param {string} msg - 消息内容
     * @param {number} [duration=2000] - 显示时长，默认2000毫秒
     * @param {boolean} [mask=false] - 是否显示透明蒙层，防止触摸穿透，默认false
     */
    static toast(msg, duration = 2000, mask = false) {}
### `toast()`
**功能**  
显示消息提示。

    /**
     * URL参数解析
     * @param {string} name - 参数名
     * @param {string} [search] - URL查询字符串，默认当前页面URL
     * @return {string|null} 返回参数值或null
     */
    static getUrlParam(name, search) {}
**参数**  
- `msg` (String)：需要显示的消息内容。  
- `duration` (Number，可选，默认值 `2000`)：消息显示的时长，单位为毫秒。  
- `mask` (Boolean，可选，默认值 `false`)：是否显示遮罩层。

    /**
     * 生成 GUID
     * @return {string} 返回生成的GUID
     */
    static createGUID() {}
**返回值**  
无

    /**
     * 获取随机字符串
     * @param {number} [long] - 字符串长度，默认32
     * @return {string} 返回生成的随机字符串
     */
    static getRandomString(long = 32) {}

    /**
     * 判断是否是数字
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为数字
     */
    static isNumber(data) {}

    /**
     * 判断是否是字符串
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为字符串
     */
    static isString(data) {}

    /**
     * 判断是否为布尔值
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为布尔值
     */
    static isBoolean(data) {}

    /**
     * 判断是否是普通对象
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为普通对象
     */
    static isObject(data) {}

    /**
     * 判断是否是数组
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为数组
     */
    static isArray(data) {}

    /**
     * 判断是否是函数
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为函数
     */
    static isFunction(data) {}

    /**
     * 判断是否为未定义
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为未定义
     */
    static isUndefined(data) {}

    /**
     * 判断是否为 null
     * @param {*} data - 要判断的数据
     * @return {boolean} 返回是否为 null
     */
    static isNull(data) {}

    /**
     * 是否为空对象
     * @param {*} obj - 要判断的对象
     * @return {boolean} 返回是否为空对象
     */
    static isEmptyObject(obj) {}

    /**
     * 判断对象是否在属性上相等
     * @param {Object} a - 对象a
     * @param {Object} b - 对象b
     * @return {boolean} 返回对象是否相等
     */
    static isObjValEqual(a, b) {}

    /**
     * 统计字符串占位宽度（汉字占两位）
     * @param {string} string - 要统计的字符串
     * @return {number} 返回字符串占位宽度
     */
    static countStringLength(string) {}

    /**
     * 获取字符串基于字节长度的剪切点
     * @param {string} string - 要剪切的字符串
     * @param {number} byteLength - 字节长度
     * @return {number} 返回剪切点位置
     */
    static getStringCutIndex(string, byteLength) {}

    /**
     * 限制数值范围，超出边界返回边界值
     * @param {number|string} num - 数值
     * @param {[number, number]} range - 数值范围
     * @return {number} 返回限制后的数值
     */
    static limitNumberRange(num, range) {}

    /**
     * 深拷贝
     * @param {Object} source - 源对象
     * @return {Object|Array} 返回深拷贝后的对象或数组
     */
    static deepCopy(source) {}

    /**
     * 深合并
     * @param {Object|Array} target - 目标对象或数组
     * @param {Object|Array} source - 源对象或数组
     * @return {Object|Array} 返回合并后的对象或数组
     */
    static deepCombine(target, source) {}

    /**
     * 数组元素交换位置
     * @param {Array} arr - 数组
     * @param {number} fromIndex - 要交换项目的位置
     * @param {number} toIndex - 被交换项目的位置
     * @return {Array} 返回交换后的数组
     */
    static swapArray(arr, fromIndex, toIndex) {}

    /**
     * 使用 moment.js 格式化时间戳
     * @param {number|string} timestamp - 时间戳
     * @param {string} [type='date'] - 格式化类型
     * @return {string} 返回格式化后的时间字符串
     */
    static momentFormat(timestamp, type = 'date') {}

    /**
     * 数值转换为时长描述
     * @param {number} timestamp - 时间戳
     * @return {string} 返回时长描述
     */
    static durationFormat(timestamp) {}

    /**
     * 数值转换为金钱格式
     * @param {number|string} number - 数值
     * @param {string} [forRead=''] - 便于阅读财务金额模式
     * @return {string} 返回格式化后的金钱字符串
     */
    static moneyFormat(number, forRead = '') {}

    /**
     * 数值转换为千分位格式
     * @param {number|string} number - 数值
     * @param {string} decimalFormat - 处理小数的方式，有 notRetain、keepTwo、keepThree 三个值
     * @return {string} 返回格式化后的字符串
     */
    static thousandFormat(number, decimalFormat = 'keepTwo') {}

    /**
     * 加法函数，用来得到精确的加法结果
     * @param {number|string} num1 - 数值1
     * @param {number|string} num2 - 数值2
     * @return {number} 返回加法结果
     */
    static accAdd(num1, num2) {}

    /**
     * 减法函数，用来得到精确的减法结果
     * @param {number|string} num1 - 数值1
     * @param {number|string} num2 - 数值2
     * @return {number} 返回减法结果
     */
    static accSub(num1, num2) {}

    /**
     * 乘法函数，用来得到精确的乘法结果
     * @param {number|string} num1 - 数值1
     * @param {number|string} num2 - 数值2
     * @return {number} 返回乘法结果
     */
    static accMul(num1, num2) {}

    /**
     * 除法函数，用来得到精确的除法结果
     * @param {number|string} num1 - 数值1
     * @param {number|string} num2 - 数值2
     * @return {number} 返回除法结果
     */
    static accDiv(num1, num2) {}

    /**
     * 求小数点后的数据长度
     * @param {number|string} num - 数值
     * @return {number} 返回小数点后的数据长度
     */
    static getDecimalLength(num) {}

    /**
     * 判断是否为手机号码
     * @param {number|string} phone - 手机号码
     * @return {boolean} 返回是否为手机号码
     */
    static isPhone(phone) {}

    /**
     * 转换周数到日期
     * @param {number} year - 年份
     * @param {number} week - 周数
     * @param {number} weekDay - 需要输出星期几对应的日期 (1~7)
     * @return {string} 返回对应的日期
     */
    static transWeekIndexToDate(year, week, weekDay) {}

    /**
     * 防抖函数（一段时间周期内，仅执行最后一次回调）
     * @param {Function} fnc - 回调函数
     * @param {number} wait - 等待时间，默认200毫秒
     * @return {Function} 返回防抖函数
     * @tutorial Tools.debounce(<fnc>, <wait>)(<DebounceKey>)
     */
    static debounce(fnc, wait = 200) {}

    /**
     * 节流函数（本段时间内，仅执行第一次回调）
     * @param {Function} fnc - 回调函数
     * @param {number} wait - 等待时间，默认200毫秒
     * @return {Function} 返回节流函数
     * @tutorial Tools.throttle(<fnc>, <wait>)(<ThrottleKey>)
     */
    static throttle(fnc, wait = 200) {}

    /**
     * 精确保留小数点几位数，自动补零，修复 toFixed 四舍五入和后端不一致的问题
     * @param {number|string} num - 数值
     * @param {number} [digit=0] - 小数点后位数
     * @return {string|NaN} 返回保留小数点后的数值或NaN
     */
    static accFixed(num, digit = 0) {}
}
**示例**  
```javascript
Tools.toast('操作成功');
```

---

### `getUrlParam(name, search)`
**功能**  
解析 URL 参数。

**参数**  
- `name` (String)：需要解析的参数名。  
- `search` (String，可选)：自定义的查询字符串，默认为当前页面的 `window.location.search`。

**返回值**  
- `String`: 解析后的参数值。  
- `Null`: 如果参数不存在或在小程序环境中，返回 `null`。

**示例**  
```javascript
const userId = Tools.getUrlParam('userId');
```

**注意事项**  
- 该方法仅适用于浏览器环境，在小程序环境中，该方法直接返回 `null`  

---

### `createGUID()`
**功能**  
生成一个全局唯一标识符（GUID）。

**参数**  
无

**返回值**
- `String`：返回一个符合 GUID 格式的字符串。

**示例**
```javascript
const guid = Tools.createGUID();
console.log(guid); // 输出类似 "3b9f1a2c-4e5f-4d3a-8b2c-1a2b3c4d5e6f"
```

**注意事项**
- 生成的 GUID 是基于随机数的，虽然概率极低，但不能保证绝对唯一，因此不适于永久存储的业务。
  
---

### `getRandomString(long)`
**功能**  
生成一个指定长度的随机字符串。

**参数**
- `long` (Number，可选)：生成的字符串长度，默认为 32。

**返回值**：
- (String)：返回一个随机字符串。

**示例**
```javascript
const randomString = Tools.getRandomString(16);
console.log(randomString); // 输出类似 "aB3dEfGhIjKlMnOp"
```

**注意事项**：
- 生成的字符串仅包含指定的字符集，不包含容易混淆的字符（如 `1`, `l`, `0`, `O` 等）。

---

### `isNumber(data)`
**功能**：判断传入的数据是否为数值类型。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是数值类型，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isNumber(123)); // true
console.log(Tools.isNumber('123')); // false
```

---

### `isString(data)`
**功能**：判断传入的数据是否为字符串类型。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是字符串类型，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isString('hello')); // true
console.log(Tools.isString(123)); // false
```

---

### `isBoolean(data)`
**功能**：判断传入的数据是否为布尔类型。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是布尔类型，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isBoolean(true)); // true
console.log(Tools.isBoolean('true')); // false
```

---

### `isObject(data)`
**功能**：判断传入的数据是否为普通对象类型。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是普通对象类型，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isObject({})); // true
console.log(Tools.isObject([])); // false
```
---

### `isArray(data)`
**功能**：判断传入的数据是否为数组类型。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是数组类型，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isArray([])); // true
console.log(Tools.isArray({})); // false
```

---

### `isFunction(data)`
**功能**：判断传入的数据是否为函数类型。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是函数类型，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isFunction(() => {})); // true
console.log(Tools.isFunction({})); // false
```

---

### `isUndefined(data)`
**功能**：判断传入的数据是否为 `undefined`。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是 `undefined`，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isUndefined(undefined)); // true
console.log(Tools.isUndefined(null)); // false
```

---

### `isNull(data)`
**功能**：判断传入的数据是否为 `null`。

**参数**：
- `data` (*)：需要判断的数据。

**返回值**：
- (Boolean)：如果数据是 `null`，返回 `true`，否则返回 `false`。

**示例**：
```javascript
console.log(Tools.isNull(null)); // true
console.log(Tools.isNull(undefined)); // false
```

---


## 部分功能详解

### momentFormat 时间格式化