mazey 3.5.3 → 3.6.0

package/README.md

@@ -61,28 +61,28 @@ There ara some examples maintained by hand below. For more information, please c
   * [loadScript](#loadscript)
   * [loadCSS](#loadcss)
   * [windowLoaded](#windowloaded)
-- [Function](#function)
+- [Util](#util)
+  * [isNumber](#isnumber)
+  * [generateRndNum](#generaterndnum)
+  * [isJsonString](#isjsonstring)
+  * [formatDate](#formatdate)
   * [debounce](#debounce)
   * [throttle](#throttle)
-  * [isNumber](#isnumber)
   * [camelCaseToKebabCase](#camelcasetokebabcase)
   * [camelCase2Underscore](#camelcase2underscore)
   * [mTrim](#mtrim)
   * [deepCopyObject](#deepcopyobject)
-  * [isJsonString](#isjsonstring)
-  * [generateRndNum](#generaterndnum)
-  * [formatDate](#formatdate)
   * [isValidData](#isvaliddata)
 - [DOM](#dom)
-  * [Class](#class)
   * [addStyle](#addstyle)
   * [newLine](#newline)
+  * [Class](#class)
 - [URL](#url)
   * [getQueryParam](#getqueryparam)
   * [getUrlParam](#geturlparam)
-  * [updateQueryParam](#updatequeryparam)
   * [getHashQueryParam](#gethashqueryparam)
   * [getDomain](#getdomain)
+  * [updateQueryParam](#updatequeryparam)
 - [Cache Data](#cache-data)
   * [Storage](#storage)
   * [Cookie](#cookie)
@@ -92,10 +92,9 @@ There ara some examples maintained by hand below. For more information, please c
   * [calLongestCommonSubsequence](#callongestcommonsubsequence)
 - [Browser Information](#browser-information)
   * [getBrowserInfo](#getbrowserinfo)
+  * [isSafePWAEnv](#issafepwaenv)
 - [Web Performance](#web-performance)
   * [getPerformance](#getperformance)
-- [Margin of Safety](#margin-of-safety)
-  * [isSafePWAEnv](#issafepwaenv)
 - [Debug](#debug)
   * [genCustomConsole](#gencustomconsole)
 <!-- toc - end -->
@@ -134,7 +133,8 @@ loadScript(
 @param {function} options.callback -- 加载后回调函数
 @param {number} options.timeout -- 超时时长
 @param {boolean} options.isDefer -- 是否添加 defer 标签
-@returns {Promise<boolean>} -- true 成功 -->
+@returns {Promise<boolean>} -- true 成功
+@category Load Resource -->
 
 #### loadCSS
 
@@ -163,7 +163,8 @@ loadCSS(
 
 <!-- @param {string} url -- css资源路径
 @param {string} options.id -- link标签id
-@returns {Promise<boolean>} true -- 加载成功 -->
+@returns {Promise<boolean>} true -- 加载成功
+@category Load Resource -->
 
 #### windowLoaded
 
@@ -182,9 +183,94 @@ windowLoaded(30) // second
 ```
 
 <!-- @param {number} timeout 超时时间 / 单位：秒
-@returns {Promise<string>} document is loaded? 'complete' 'load' / 'timeout' -->
+@returns {Promise<string>} document is loaded? 'complete' 'load' / 'timeout'
+@category Load Resource -->
+
+### Util
+
+#### isNumber
+
+Check whether it is a right number.
+
+<!-- ZH: 判断是否有效数字 -->
+
+```
+isNumber(123); // true
+isNumber('123'); // false
+// Default: NaN, Infinity is not Number
+isNumber(Infinity); // false
+isNumber(Infinity, { isUnFiniteAsNumber: true }); // true
+isNumber(NaN); // false
+isNumber(NaN, { isNaNAsNumber: true, isUnFiniteAsNumber: true }); // true
+```
+
+<!-- @param {*} num 被判断的值
+@param {boolean} options.isNaNAsNumber 是否 NaN 算数字（默认不算）
+@param {boolean} options.isUnFiniteAsNumber 是否 无限 算数字（默认不算）
+@returns {boolean} true 是数字
+@category Util -->
+
+#### generateRndNum
+
+Produce a random string of number, `generateRndNum(7)` => '7658495'.
+
+```
+generateRndNum(4); // '9730'
+generateRndNum(7); // '2262490'
+```
+
+<!-- @param {number} n Length
+@returns {string} Return the random string.
+@category Util -->
+
+#### isJsonString
+
+Check whether it is a valid JSON string.
+
+Usage:
+
+```
+isJsonString(`['a', 'b', 'c']`);
+isJsonString(`["a", "b", "c"]`);
+```
+
+Output:
+
+```
+false
+true
+```
+
+<!-- @param {string} str The string to check.
+@returns {boolean} Return the result of checking.
+@category Util -->
+
+#### formatDate
+
+Return the formatted date string in the given format.
+
+Usage:
 
-### Function
+```
+console.log('Default formatDate value:', formatDate());
+console.log('String formatDate value:', formatDate('Tue Jan 11 2022 14:12:26 GMT+0800 (China Standard Time)', 'yyyy-MM-dd hh:mm:ss'));
+console.log('Number formatDate value:', formatDate(1641881235000, 'yyyy-MM-dd hh:mm:ss'));
+console.log('Date formatDate value:', formatDate(new Date(2014, 1, 11), 'MM/dd/yyyy'));
+```
+
+Output:
+
+```
+Default formatDate value: 2023-01-11
+String formatDate value: 2022-01-11 14:12:26
+Number formatDate value: 2022-01-11 14:07:15
+Date formatDate value: 02/11/2014
+```
+
+<!-- @param {Date|number|string} dateIns Original Date
+@param {string} format Format String
+@returns {string} Return the formatted date string.
+@category Util -->
 
 #### debounce
 
@@ -198,6 +284,8 @@ const foo = debounce(() => {
 }, 1000, true);
 ```
 
+<!-- @category Util -->
+
 #### throttle
 
 Throttle
@@ -212,26 +300,7 @@ const foo = throttle(() => {
 
 Reference: [Lodash](https://lodash.com/docs/4.17.15#throttle)
 
-#### isNumber
-
-Check whether it is a right number.
-
-<!-- ZH: 判断是否有效数字 -->
-
-```
-isNumber(123); // true
-isNumber('123'); // false
-// Default: NaN, Infinity is not Number
-isNumber(Infinity); // false
-isNumber(Infinity, { isUnFiniteAsNumber: true }); // true
-isNumber(NaN); // false
-isNumber(NaN, { isNaNAsNumber: true, isUnFiniteAsNumber: true }); // true
-```
-
-<!-- @param {*} num 被判断的值
-@param {boolean} options.isNaNAsNumber 是否 NaN 算数字（默认不算）
-@param {boolean} options.isUnFiniteAsNumber 是否 无限 算数字（默认不算）
-@returns {boolean} true 是数字 -->
+<!-- @category Util -->
 
 #### camelCaseToKebabCase
 
@@ -243,7 +312,8 @@ camelCaseToKebabCase('aBC'); // a-b-c
 ```
 
 <!-- @param {string} camelCase 'aBC' or 'ABC'
-@returns {string} 'a-b-c' -->
+@returns {string} 'a-b-c'
+@category Util -->
 
 #### camelCase2Underscore
 
@@ -255,7 +325,8 @@ camelCase2Underscore('aBC'); // a_b_c
 ```
 
 <!-- @param {string} camelCase 'aBC' or 'ABC'
-@returns {string} 'a_b_c' -->
+@returns {string} 'a_b_c'
+@category Util -->
 
 #### mTrim
 
@@ -267,7 +338,8 @@ mTrim('abc '); // 'abc'
 ```
 
 <!-- @param {string} str The string to trim.
-@returns {string} Trimmed string. -->
+@returns {string} Trimmed string.
+@category Util -->
 
 #### deepCopyObject
 
@@ -288,63 +360,8 @@ Output:
 ```
 
 <!-- @param {object} obj The value to clone.
-@returns {object} Returns the deep cloned value. -->
-
-#### isJsonString
-
-Check whether it is a valid JSON string.
-
-Usage:
-
-```
-isJsonString(`['a', 'b', 'c']`);
-isJsonString(`["a", "b", "c"]`);
-```
-
-Output:
-
-```
-false
-true
-```
-
-<!-- @param {string} str The string to check.
-@returns {boolean} Return the result of checking. -->
-
-#### generateRndNum
-
-Produce a random string of number, `generateRndNum(7)` => '7658495'.
-
-```
-generateRndNum(4); // '9730'
-generateRndNum(7); // '2262490'
-```
-
-#### formatDate
-
-Return the formatted date string in the given format.
-
-Usage:
-
-```
-console.log('Default formatDate value:', formatDate());
-console.log('String formatDate value:', formatDate('Tue Jan 11 2022 14:12:26 GMT+0800 (China Standard Time)', 'yyyy-MM-dd hh:mm:ss'));
-console.log('Number formatDate value:', formatDate(1641881235000, 'yyyy-MM-dd hh:mm:ss'));
-console.log('Date formatDate value:', formatDate(new Date(2014, 1, 11), 'MM/dd/yyyy'));
-```
-
-Output:
-
-```
-Default formatDate value: 2023-01-11
-String formatDate value: 2022-01-11 14:12:26
-Number formatDate value: 2022-01-11 14:07:15
-Date formatDate value: 02/11/2014
-```
-
-<!-- @param {Date|number|string} dateIns Original Date
-@param {string} format Format String
-@returns {string} Return the formatted date string. -->
+@returns {object} Returns the deep cloned value.
+@category Util -->
 
 #### isValidData
 
@@ -381,30 +398,18 @@ isValidDataResC: false
 <!-- @param {any} data Original Data
 @param {string[]} attributes Data Attributes
 @param {any} validValue Given Value for verifying.
-@returns {boolean} Return TRUE if the data is valid. -->
+@returns {boolean} Return TRUE if the data is valid.
+@category Util -->
 
 ### DOM
 
-#### Class
-
-Modify `class`.
-
-```
-const dom = document.querySelector('#box');
-
-// Determine `class`
-hasClass(dom, 'test');
-// Add `class`
-addClass(dom, 'test');
-// Remove `class`
-removeClass(dom, 'test');
-```
-
 #### addStyle
 
 Add `<style>` in `<head>`.
 
-Case 1: Add the `<style>` with `id`, and repeated invoking will update the content instead of adding a new one.
+<!-- ZH: 添加样式标签; style: 样式标签内的字符串; id: `<style>` 标签的 `id`; 返回: 添加成功/失败 -->
+
+Example 1: Add the `<style>` with `id`, and repeated invoking will update the content instead of adding a new one.
 
 ```
 addStyle(
@@ -424,7 +429,7 @@ addStyle(
 // </style>
 ```
 
-Case 2: Add the `<style>` without `id`, and repeated invoking will adding a new one.
+Example 2: Add the `<style>` without `id`, and repeated invoking will adding a new one.
 
 ```
 addStyle(
@@ -441,6 +446,8 @@ addStyle(
 // </style>
 ```
 
+<!-- @category DOM -->
+
 #### newLine
 
 Make a newline of HTML.
@@ -450,6 +457,27 @@ newLine('a\nb\nc'); // 'a<br />b<br />c'
 newLine('a\n\nbc'); // 'a<br /><br />bc'
 ```
 
+<!-- @param {string} str The string to make a newline.
+@returns {string} A newline with `br`.
+@category DOM -->
+
+#### Class
+
+Modify `class`.
+
+```
+const dom = document.querySelector('#box');
+
+// Determine `class`
+hasClass(dom, 'test');
+// Add `class`
+addClass(dom, 'test');
+// Remove `class`
+removeClass(dom, 'test');
+```
+
+<!-- @category DOM -->
+
 ### URL
 
 #### getQueryParam
@@ -464,7 +492,8 @@ getQueryParam('t4'); // 4
 ```
 
 <!-- @param {string} param Query param.
-@returns {string} value -->
+@returns {string} value
+@category URL -->
 
 #### getUrlParam
 
@@ -477,30 +506,8 @@ getUrlParam('http://example.com/?t1=1&t2=2&t3=3&t4=4', 't4'); // 4
 
 <!-- @param {string} url URL string.
 @param {string} param Query param.
-@returns {string} value -->
-
-#### updateQueryParam
-
-Update the query param's value of the input URL.
-
-Usage:
-
-```
-updateQueryParam('http://example.com/?t1=1&t2=2&t3=3&t4=4', 't3', 'three');
-updateQueryParam('http://example.com/?t1=1&t2=2&t3=3&t4=4', 't4', 'four');
-```
-
-Output:
-
-```
-http://example.com/?t1=1&t2=2&t3=three&t4=4
-http://example.com/?t1=1&t2=2&t3=3&t4=four
-```
-
-<!-- @param {string} url URL string.
-@param {string} param Query param.
-@param {string} value Param's value.
-@returns {string} URL. -->
+@returns {string} value
+@category URL -->
 
 #### getHashQueryParam
 
@@ -523,7 +530,8 @@ Output:
 ```
 
 <!-- @param {string} param Query param.
-@returns {string} value -->
+@returns {string} value
+@category URL -->
 
 #### getDomain
 
@@ -544,7 +552,32 @@ example.com/test/thanks
 ```
 
 <!-- @param {string} url
-@param {array} rules Object.keys(location), ['href', 'protocol', 'host', 'hostname', 'port', 'pathname', 'search', 'hash'], ['hostname', 'pathname'] = 'km.mazey.net/plugins/servlet/mobile' -->
+@param {array} rules Object.keys(location), ['href', 'protocol', 'host', 'hostname', 'port', 'pathname', 'search', 'hash'], ['hostname', 'pathname'] = 'km.mazey.net/plugins/servlet/mobile'
+@category URL -->
+
+#### updateQueryParam
+
+Update the query param's value of the input URL.
+
+Usage:
+
+```
+updateQueryParam('http://example.com/?t1=1&t2=2&t3=3&t4=4', 't3', 'three');
+updateQueryParam('http://example.com/?t1=1&t2=2&t3=3&t4=4', 't4', 'four');
+```
+
+Output:
+
+```
+http://example.com/?t1=1&t2=2&t3=three&t4=4
+http://example.com/?t1=1&t2=2&t3=3&t4=four
+```
+
+<!-- @param {string} url URL string.
+@param {string} param Query param.
+@param {string} value Param's value.
+@returns {string} URL.
+@category URL -->
 
 ### Cache Data
 
@@ -552,6 +585,8 @@ example.com/test/thanks
 
 Handle Storage (Keep fit for JSON, it can tansfer format automatically).
 
+<!-- ZH: 存储/获取数据到 sessionStorage/localStorage -->
+
 ```
 setSessionStorage('test', '123');
 getSessionStorage('test'); // 123
@@ -569,15 +604,23 @@ function mGetLocalStorage (key) {
 }
 ```
 
+<!-- @param {string} key 键
+@returns {any} 返回值
+@category Cache Data -->
+
 #### Cookie
 
 Handle Cookie.
 
+<!-- ZH: 设置/获取 Cookie -->
+
 ```
 setCookie('test', '123', 30, 'example.com'); // key value day domain
 getCookie('test'); // 123
 ```
 
+<!-- @category Cache Data -->
+
 ### Calculate and Formula
 
 #### inRate
@@ -615,7 +658,8 @@ console.log(trueCount, falseCount); // 499994 500006
 ```
 
 <!-- @param {number} rate -- 0.1 ~ 1 => 1% ~ 100%
-@returns {boolean} true 命中 -->
+@returns {boolean} true 命中
+@category Calculate and Formula -->
 
 #### calLongestCommonSubstring
 
@@ -637,7 +681,8 @@ Output:
 
 <!-- @param {string} aStr String
 @param {string} bStr String
-@returns {number} Length -->
+@returns {number} Length
+@category Calculate and Formula -->
 
 #### calLongestCommonSubsequence
 
@@ -659,7 +704,8 @@ Output:
 
 <!-- @param {string} aStr 字符串
 @param {string} bStr 字符串
-@returns {number} 长度 -->
+@returns {number} 长度
+@category Calculate and Formula -->
 
 ### Browser Information
 
@@ -683,18 +729,18 @@ Output:
 
 Results:
 
-| Index | Field | Description |
-| --- | --- | --- |
-| System | system | android, ios, windows, macos, linux |
-| System version | systemVs | windows: 2000, xp, 2003, vista, 7, 8, 8.1, 10 <br />macos: ... |
-| Platform | platform | desktop, mobile |
-| Engine | engine | webkit, gecko, presto, trident |
-| Engine version | engineVs | - |
-| Supporter | supporter | edge, opera, chrome, safari, firefox, iexplore |
-| Supporter version | supporterVs | - |
-| Shell | shell | (Optional) wechat, qq_browser, qq_app, uc, 360, 2345, sougou, liebao, maxthon, bilibili |
-| Shell version | shellVs | (Optional) 20/... |
-| Apple device type | appleType | (Optional) iphone, ipad, ipod, iwatch |
+| Attribute | Description | Type | Values |
+| --- | --- | --- | --- |
+| **system** | System | string | android, ios, windows, macos, linux |
+| systemVs | System version | string | windows: 2000, xp, 2003, vista, 7, 8, 8.1, 10 <br />macos: ... |
+| platform | Platform | string | desktop, mobile |
+| engine | Engine | string | webkit, gecko, presto, trident |
+| engineVs | Engine version | string | - |
+| supporter | Supporter | string | edge, opera, chrome, safari, firefox, iexplore |
+| supporterVs | Supporter version | string | - |
+| shell | Shell | string | (Optional) wechat, qq_browser, qq_app, uc, 360, 2345, sougou, liebao, maxthon, bilibili |
+| shellVs | Shell version | string | (Optional) 20/... |
+| appleType | Apple device type | string | (Optional) ipad, iphone, ipod, iwatch |
 
 Example: Determine the environment of the mobile QQ.
 
@@ -703,7 +749,29 @@ const { system, shell } = getBrowserInfo();
 const isMobileQQ = ['android', 'ios'].includes(system) && ['qq_browser', 'qq_app'].includes(shell);
 ```
 
-<!-- @returns 浏览器信息 -->
+<!-- @returns 浏览器信息
+@category Browser Information -->
+
+#### isSafePWAEnv
+
+Detect the margin of Safety. Determine if it is a secure PWA environment that it can run.
+
+<!-- ZH: 判断是否是安全的 PWA 环境 -->
+
+Usage:
+
+```
+isSafePWAEnv();
+```
+
+Output:
+
+```
+true
+```
+
+<!-- @returns {boolean} true 是
+@category Browser Information -->
 
 ### Web Performance
 
@@ -748,29 +816,8 @@ Results:
 | Download | download_time | (Optional) responseEnd - responseStart |
 
 <!-- @param {boolean} camelCase -- false（默认） 以下划线形式返回数据 true 以驼峰形式返回数据
-@returns {Promise<object>} 加载数据 -->
-
-### Margin of Safety
-
-#### isSafePWAEnv
-
-Determine if it is a secure PWA environment that it can run.
-
-<!-- ZH: 判断是否是安全的 PWA 环境 -->
-
-Usage:
-
-```
-isSafePWAEnv();
-```
-
-Output:
-
-```
-true
-```
-
-<!-- @returns {boolean} true 是 -->
+@returns {Promise<object>} 加载数据
+@category Web Performance -->
 
 ### Debug
 
@@ -803,7 +850,8 @@ MazeyLog: I am object. {a: 123, b: 456}
 @param {string} locales A locale string.
 @param {function} logFn The function with Log.
 @param {function} errorFn The function with Error.
-@returns {object} 新实例 -->
+@returns {object} 新实例
+@category Debug -->
 
 ## Contributing
 

package/README_CN.md

@@ -1,5 +1,7 @@
 ⚠️ Note: The document has expired, please check the latest [README.md](./README.md).
 
+⚠️ 注意: 此文档只适用于 v1.4.39 版本，[查看 v3.x 版本的文档](./README.md)
+
 # mazey
 
 [![NPM version][npm-image]][npm-url]
@@ -10,7 +12,7 @@
 [l-image]: https://img.shields.io/npm/l/mazey
 [l-url]: https://github.com/mazeyqian/mazey
 
-后除的 JavaScript 函数库，所有的方法都在线上项目中使用过。
+后除的 JavaScript 函数库，所有的方法都在线上项目中使用过
 
 **目录**
 
@@ -338,7 +340,7 @@ myConsole.info('I am number.', 123, 456); // MazeyLog: I am number. 123 456
 myConsole.info('I am object.', { a: 123, b: 456}); // MazeyLog: I am object. {a: 123, b: 456}
 ```
 
-[更多接口>>](https://mazey.cn/docs/mazey/modules/_index_.html)
+[更多接口>>](https://mazey.cn/t/m)
 
 ## 开发