mazey 3.5.3 → 3.6.0

package/src/index.ts

@@ -22,6 +22,7 @@
  * @param {string} aStr String
  * @param {string} bStr String
  * @returns {number} Length
+ * @category Calculate and Formula
  */
 export function calLongestCommonSubstring(aStr: string, bStr: string): number {
   const aLen = aStr.length;
@@ -66,6 +67,7 @@ export function calLongestCommonSubstring(aStr: string, bStr: string): number {
  * @param {string} aStr 字符串
  * @param {string} bStr 字符串
  * @returns {number} 长度
+ * @category Calculate and Formula
  */
 export function calLongestCommonSubsequence(
   aStr: string,
@@ -114,6 +116,7 @@ export function calLongestCommonSubsequence(
  *
  * @param {string} param Query param.
  * @returns {string} value
+ * @category URL
  */
 export function getQueryParam(param: string): string {
   const reg = new RegExp('(^|&)' + param + '=([^&]*)(&|$)');
@@ -136,6 +139,7 @@ export function getQueryParam(param: string): string {
  * @param {string} url URL string.
  * @param {string} param Query param.
  * @returns {string} value
+ * @category URL
  */
 export function getUrlParam(url: string, param: string): string | string[] {
   const result: {
@@ -179,6 +183,7 @@ export function getUrlParam(url: string, param: string): string | string[] {
  * @param {string} param Query param.
  * @param {string} value Param's value.
  * @returns {string} URL.
+ * @category URL
  */
 export function updateQueryParam(
   url: string,
@@ -215,6 +220,7 @@ export function updateQueryParam(
  *
  * @param {string} param Query param.
  * @returns {string} value
+ * @category URL
  */
 export function getHashQueryParam(param: string): string {
   const hashs = location.hash.split('?');
@@ -245,6 +251,7 @@ export function getHashQueryParam(param: string): string {
  *
  * @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'
+ * @category URL
  */
 export function getDomain(url: string, rules = ['hostname']): string {
   const aEl: any = document.createElement('a');
@@ -265,6 +272,7 @@ export function getDomain(url: string, rules = ['hostname']): string {
  *
  * @param {string} camelCase 'aBC' or 'ABC'
  * @returns {string} 'a-b-c'
+ * @category Util
  */
 export function camelCaseToKebabCase(camelCase: string): string {
   const kebabCase = camelCase.replace(/([A-Z])/g, '-$1').toLowerCase();
@@ -281,6 +289,7 @@ export function camelCaseToKebabCase(camelCase: string): string {
  *
  * @param {string} camelCase 'aBC' or 'ABC'
  * @returns {string} 'a_b_c'
+ * @category Util
  */
 export function camelCase2Underscore(camelCase: string): string {
   const kebabCase = camelCase.replace(/([A-Z])/g, '_$1').toLowerCase();
@@ -297,6 +306,7 @@ export function camelCase2Underscore(camelCase: string): string {
  *
  * @param {string} str The string to trim.
  * @returns {string} Trimmed string.
+ * @category Util
  */
 export function mTrim(str: string): string {
   str = str.replace(/^\s+/, ''); // 去除头部空格
@@ -309,10 +319,16 @@ export function mTrim(str: string): string {
 }
 
 /**
- * @method newLine
- * @description Make a newline of HTML.
+ * Make a newline of HTML.
+ *
+ * ```
+ * 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
  */
 export function newLine(str: string): string {
   if (!str) {
@@ -341,6 +357,7 @@ export function newLine(str: string): string {
  *
  * @param {object} obj The value to clone.
  * @returns {object} Returns the deep cloned value.
+ * @category Util
  */
 export function deepCopyObject(obj: any): any {
   return JSON.parse(JSON.stringify(obj));
@@ -362,6 +379,10 @@ export function deepCopyObject(obj: any): any {
  * false
  * true
  * ```
+ *
+ * @param {string} str The string to check.
+ * @returns {boolean} Return the result of checking.
+ * @category Util
  */
 export function isJsonString(str: string): boolean {
   try {
@@ -375,10 +396,16 @@ export function isJsonString(str: string): boolean {
 }
 
 /**
- * @method generateRndNum
- * @description Produce a random string of number, `generateRndNum(7)` => '7658495'.
+ * 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
  */
 export function generateRndNum(n = 5): string {
   let ret = '';
@@ -438,7 +465,20 @@ export function cancelBubble(e: any): void {
 }
 
 /**
- * @method hasClass
+ * Modify `class`.
+ *
+ * ```
+ * const dom = document.querySelector('#box');
+ *
+ * // Determine `class`
+ * hasClass(dom, 'test');
+ * // Add `class`
+ * addClass(dom, 'test');
+ * // Remove `class`
+ * removeClass(dom, 'test');
+ * ```
+ *
+ * @category DOM
  */
 export function hasClass(obj: any, cls: string): boolean {
   const oriCls = obj.className; // 获取对象的class值
@@ -452,7 +492,20 @@ export function hasClass(obj: any, cls: string): boolean {
 }
 
 /**
- * @method addClass
+ * Modify `class`.
+ *
+ * ```
+ * const dom = document.querySelector('#box');
+ *
+ * // Determine `class`
+ * hasClass(dom, 'test');
+ * // Add `class`
+ * addClass(dom, 'test');
+ * // Remove `class`
+ * removeClass(dom, 'test');
+ * ```
+ *
+ * @category DOM
  */
 export function addClass(obj: any, cls: string): void {
   const oriCls = obj.className;
@@ -466,7 +519,20 @@ export function addClass(obj: any, cls: string): void {
 }
 
 /**
- * @method removeClass
+ * Modify `class`.
+ *
+ * ```
+ * const dom = document.querySelector('#box');
+ *
+ * // Determine `class`
+ * hasClass(dom, 'test');
+ * // Add `class`
+ * addClass(dom, 'test');
+ * // Remove `class`
+ * removeClass(dom, 'test');
+ * ```
+ *
+ * @category DOM
  */
 export function removeClass(obj: any, cls: string): void {
   const oriCls = obj.className;
@@ -490,6 +556,8 @@ export function removeClass(obj: any, cls: string): void {
  * ```
  *
  * Reference: [Lodash](https://lodash.com/docs/4.17.15#throttle)
+ *
+ * @category Util
  */
 export function throttle(
   func: any,
@@ -503,9 +571,6 @@ export function throttle(
   let args: any = null;
   let timeout: any = null;
   let [result, previous] = [null, 0];
-  // if (!options) {
-  //   options = {};
-  // }
   const later = function() {
     previous = options.leading === false ? 0 : mNow();
     timeout = null;
@@ -549,6 +614,8 @@ export function throttle(
  *   console.log('The debounced function will only be invoked in 1000 milliseconds, the other invoking will disappear during the wait time.');
  * }, 1000, true);
  * ```
+ *
+ * @category Util
  */
 export function debounce(func: any, wait: number, immediate?: any): any {
   let context: any = null;
@@ -647,6 +714,7 @@ export function friendlyInterval(
  * @param {boolean} options.isNaNAsNumber 是否 NaN 算数字（默认不算）
  * @param {boolean} options.isUnFiniteAsNumber 是否 无限 算数字（默认不算）
  * @returns {boolean} true 是数字
+ * @category Util
  */
 export function isNumber(
   num: any,
@@ -691,10 +759,30 @@ export function doFn(fn: any, ...params: any[]): any {
 }
 
 /**
- * @method setSessionStorage
- * @description 存储数据到 sessionStorage
+ * EN: Handle Storage (Keep fit for JSON, it can tansfer format automatically).
+ *
+ * ZH: 存储/获取数据到 sessionStorage/localStorage
+ *
+ * ```
+ * setSessionStorage('test', '123');
+ * getSessionStorage('test'); // 123
+ * setLocalStorage('test', '123');
+ * getLocalStorage('test'); // 123
+ *
+ * // or package in usage
+ * const projectName = 'mazey';
+ * function mSetLocalStorage (key, value) {
+ *   return setLocalStorage(`${projectName}_${key}`, value);
+ * }
+ *
+ * function mGetLocalStorage (key) {
+ *   return getLocalStorage(`${projectName}_${key}`);
+ * }
+ * ```
+ *
  * @param {string} key 键
- * @param {string} value 值
+ * @returns {any} 返回值
+ * @category Cache Data
  */
 export function setSessionStorage(key: string, value: any = null): void {
   if (key) {
@@ -703,10 +791,30 @@ export function setSessionStorage(key: string, value: any = null): void {
 }
 
 /**
- * @method getSessionStorage
- * @description 存储数据到 sessionStorage
+ * EN: Handle Storage (Keep fit for JSON, it can tansfer format automatically).
+ *
+ * ZH: 存储/获取数据到 sessionStorage/localStorage
+ *
+ * ```
+ * setSessionStorage('test', '123');
+ * getSessionStorage('test'); // 123
+ * setLocalStorage('test', '123');
+ * getLocalStorage('test'); // 123
+ *
+ * // or package in usage
+ * const projectName = 'mazey';
+ * function mSetLocalStorage (key, value) {
+ *   return setLocalStorage(`${projectName}_${key}`, value);
+ * }
+ *
+ * function mGetLocalStorage (key) {
+ *   return getLocalStorage(`${projectName}_${key}`);
+ * }
+ * ```
+ *
  * @param {string} key 键
- * @returns {*} 返回值
+ * @returns {any} 返回值
+ * @category Cache Data
  */
 export function getSessionStorage(key: string): any {
   let ret = null;
@@ -720,10 +828,30 @@ export function getSessionStorage(key: string): any {
 }
 
 /**
- * @method setLocalStorage
- * @description 存储数据到 localStorage
+ * EN: Handle Storage (Keep fit for JSON, it can tansfer format automatically).
+ *
+ * ZH: 存储/获取数据到 sessionStorage/localStorage
+ *
+ * ```
+ * setSessionStorage('test', '123');
+ * getSessionStorage('test'); // 123
+ * setLocalStorage('test', '123');
+ * getLocalStorage('test'); // 123
+ *
+ * // or package in usage
+ * const projectName = 'mazey';
+ * function mSetLocalStorage (key, value) {
+ *   return setLocalStorage(`${projectName}_${key}`, value);
+ * }
+ *
+ * function mGetLocalStorage (key) {
+ *   return getLocalStorage(`${projectName}_${key}`);
+ * }
+ * ```
+ *
  * @param {string} key 键
- * @param {string} value 值
+ * @returns {any} 返回值
+ * @category Cache Data
  */
 export function setLocalStorage(key: string, value: any = null): void {
   if (key) {
@@ -732,10 +860,30 @@ export function setLocalStorage(key: string, value: any = null): void {
 }
 
 /**
- * @method getLocalStorage
- * @description 存储数据到 localStorage
+ * EN: Handle Storage (Keep fit for JSON, it can tansfer format automatically).
+ *
+ * ZH: 存储/获取数据到 sessionStorage/localStorage
+ *
+ * ```
+ * setSessionStorage('test', '123');
+ * getSessionStorage('test'); // 123
+ * setLocalStorage('test', '123');
+ * getLocalStorage('test'); // 123
+ *
+ * // or package in usage
+ * const projectName = 'mazey';
+ * function mSetLocalStorage (key, value) {
+ *   return setLocalStorage(`${projectName}_${key}`, value);
+ * }
+ *
+ * function mGetLocalStorage (key) {
+ *   return getLocalStorage(`${projectName}_${key}`);
+ * }
+ * ```
+ *
  * @param {string} key 键
- * @returns {*} 返回值
+ * @returns {any} 返回值
+ * @category Cache Data
  */
 export function getLocalStorage(key: string): any {
   let ret = null;
@@ -775,6 +923,7 @@ export function getLocalStorage(key: string): any {
  * @param {string} url -- css资源路径
  * @param {string} options.id -- link标签id
  * @returns {Promise<boolean>} true -- 加载成功
+ * @category Load Resource
  */
 export function loadCSS(
   url: string,
@@ -931,6 +1080,7 @@ export function loadCSS(
  * @param {number} options.timeout -- 超时时长
  * @param {boolean} options.isDefer -- 是否添加 defer 标签
  * @returns {Promise<boolean>} -- true 成功
+ * @category Load Resource
  */
 export function loadScript(
   url: string,
@@ -1012,8 +1162,16 @@ export function mNow(): number {
 }
 
 /**
- * @method setCookie
- * @description 设置 Cookie
+ * EN: Handle Cookie.
+ *
+ * ZH: 设置/获取 Cookie
+ *
+ * ```
+ * setCookie('test', '123', 30, 'example.com'); // key value day domain
+ * getCookie('test'); // 123
+ * ```
+ *
+ * @category Cache Data
  */
 export function setCookie(
   name: string,
@@ -1061,8 +1219,16 @@ export function setCookie(
 }
 
 /**
- * @method getCookie
- * @description 获取 Cookie
+ * EN: Handle Cookie.
+ *
+ * ZH: 设置/获取 Cookie
+ *
+ * ```
+ * setCookie('test', '123', 30, 'example.com'); // key value day domain
+ * getCookie('test'); // 123
+ * ```
+ *
+ * @category Cache Data
  */
 export function getCookie(name: string): string {
   const nameEQ = name + '=';
@@ -1077,6 +1243,9 @@ export function getCookie(name: string): string {
   return '';
 }
 
+/**
+ * @hidden
+ */
 interface WebPerformance {
   [key: string]: string | number;
 }
@@ -1122,6 +1291,7 @@ interface WebPerformance {
  *
  * @param {boolean} camelCase -- false（默认） 以下划线形式返回数据 true 以驼峰形式返回数据
  * @returns {Promise<object>} 加载数据
+ * @category Web Performance
  */
 export function getPerformance(
   camelCase = false
@@ -1408,6 +1578,7 @@ export function getPerformance(
  *
  * @param {number} rate -- 0.1 ~ 1 => 1% ~ 100%
  * @returns {boolean} true 命中
+ * @category Calculate and Formula
  */
 export function inRate(rate: number): boolean {
   if (Math.random() < rate) {
@@ -1417,7 +1588,7 @@ export function inRate(rate: number): boolean {
 }
 
 /**
- * EN: Determine if it is a secure PWA environment that it can run.
+ * EN: Detect the margin of Safety. Determine if it is a secure PWA environment that it can run.
  *
  * ZH: 判断是否是安全的 PWA 环境
  *
@@ -1434,6 +1605,7 @@ export function inRate(rate: number): boolean {
  * ```
  *
  * @returns {boolean} true 是
+ * @category Browser Information
  */
 export function isSafePWAEnv(): boolean {
   // 判断是否支持 async await
@@ -1497,18 +1669,18 @@ export function isSafePWAEnv(): boolean {
  *
  * 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.
  *
@@ -1518,6 +1690,7 @@ export function isSafePWAEnv(): boolean {
  * ```
  *
  * @returns 浏览器信息
+ * @category Browser Information
  */
 export function getBrowserInfo(): {
   engine: string; // webkit gecko presto trident
@@ -1560,10 +1733,10 @@ export function getBrowserInfo(): {
       system = 'android'; // android系统
     } else if (testUa(/ios|iphone|ipad|ipod|iwatch/g)) {
       system = 'ios'; // ios系统
-      if (testUa(/iphone/g)) {
-        appleType = 'iphone';
-      } else if (testUa(/ipad/g)) {
+      if (testUa(/ipad/g)) {
         appleType = 'ipad';
+      } else if (testUa(/iphone/g)) {
+        appleType = 'iphone';
       } else if (testUa(/iwatch/g)) {
         appleType = 'iwatch';
       } else if (testUa(/ipod/g)) {
@@ -1778,6 +1951,7 @@ export function cutCHSString(str: string, len: number, hasDot = false): string {
  *
  * @param {number} timeout 超时时间 / 单位：秒
  * @returns {Promise<string>} document is loaded? 'complete' 'load' / 'timeout'
+ * @category Load Resource
  */
 export function windowLoaded(timeout = 90): Promise<string | Error> {
   let loaded: (value: string) => void = () => undefined;
@@ -1801,7 +1975,7 @@ export function windowLoaded(timeout = 90): Promise<string | Error> {
 /**
  * EN: Add `<style>` in `<head>`.
  *
- * ZH: 添加样式标签; style: 样式标签内的字符串; id: `<style>` 标签的 `id`; 返回: 添加成功/失败.
+ * 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.
  *
@@ -1829,20 +2003,18 @@ export function windowLoaded(timeout = 90): Promise<string | Error> {
  * addStyle(
  *   `
  *     body {
- *       background-color: #333;
+ *       background-color: #444;
  *     }
  *   `
  * );
  * // <style>
  * //   body {
- * //     background-color: #333;
+ * //     background-color: #444;
  * //   }
  * // </style>
  * ```
  *
- * @param style Style string.
- * @param options.id `id` in `<style>`
- * @returns Success/Fail
+ * @category DOM
  */
 export function addStyle(
   style: string,
@@ -1911,6 +2083,7 @@ export function addStyle(
  * @param {function} logFn The function with Log.
  * @param {function} errorFn The function with Error.
  * @returns {object} 新实例
+ * @category Debug
  */
 export function genCustomConsole(
   prefix = '',
@@ -2102,6 +2275,7 @@ export function isNonEmptyArray(arr: any[]): boolean {
  * @param {string[]} attributes Data Attributes
  * @param {any} validValue Given Value for verifying.
  * @returns {boolean} Return TRUE if the data is valid.
+ * @category Util
  */
 export function isValidData(
   data: any,
@@ -2208,6 +2382,7 @@ export function genHashCode(str: string): number {
  * @param {Date|number|string} dateIns Original Date
  * @param {string} format Format String
  * @returns {string} Return the formatted date string.
+ * @category Util
  */
 export function formatDate(
   dateIns?: Date | number | string,
@@ -2246,3 +2421,123 @@ export function formatDate(
   });
   return tempFormat;
 }
+
+/**
+ * Get event container.
+ *
+ * @category Event
+ * @hidden
+ */
+export function getDefineListeners(): DefineListeners {
+  let defineListeners = window.MAZEY_DEFINE_LISTENERS;
+  if (typeof defineListeners !== 'object') {
+    defineListeners = {};
+    window.MAZEY_DEFINE_LISTENERS = defineListeners;
+  }
+  return defineListeners;
+}
+
+/**
+ * Add event.
+ *
+ * @param type
+ * @param fn
+ * @category Event
+ */
+export function addEvent(type: string, fn: any): void {
+  const defineListeners = getDefineListeners();
+  if (typeof defineListeners[type] === 'undefined') {
+    defineListeners[type] = [];
+  }
+  if (typeof fn === 'function') {
+    defineListeners[type].push(fn);
+  }
+}
+
+/**
+ * Invoke event.
+ *
+ * @param type
+ * @category Event
+ */
+export function invokeEvent(type: string): void {
+  const defineListeners = getDefineListeners();
+  const arrayEvent = defineListeners[type];
+  if (arrayEvent instanceof Array) {
+    for (let i = 0, length = arrayEvent.length; i < length; i++) {
+      if (typeof arrayEvent[i] === 'function') {
+        arrayEvent[i]({
+          type: type
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Remove event.
+ *
+ * @param type
+ * @param fn
+ * @category Event
+ */
+export function removeEvent(type: string, fn: any): void {
+  const defineListeners = getDefineListeners();
+  const arrayEvent = defineListeners[type];
+  if (typeof type === 'string' && arrayEvent instanceof Array) {
+    if (typeof fn === 'function') {
+      for (let i = 0, length = arrayEvent.length; i < length; i++) {
+        if (arrayEvent[i] === fn) {
+          defineListeners[type].splice(i, 1);
+          break;
+        }
+      }
+    } else {
+      delete defineListeners[type];
+    }
+  }
+}
+
+/**
+ * Check if the given string is a valid url.
+ *
+ * @example
+ * ```js
+ * console.log(isUrl('https://www.google.com')); // true
+ * console.log(isUrl('https://www.google.com/')); // true
+ * console.log(isUrl('https://www.google.com/?q=hello')); // true
+ * console.log(isUrl('https://www.google.com/?q=hello#world')); // true
+ * console.log(isUrl('https://www.google.com/#world')); // true
+ * console.log(isUrl('https://www.google.com/#')); // true
+ * console.log(isUrl('https://www.google.com/#?q=hello')); // true
+ * console.log(isUrl('https://www.google.com/#?q=hello#world')); // true
+ * ```
+ *
+ * @param url
+ * @returns {boolean} Return true if the given url is a valid url.
+ * @category URL
+ */
+export function isValidUrl(url: string): boolean {
+  const reg = /[a-zA-Z0-9]+:\/\/[-a-zA-Z0-9@:%._+~#=]{1,256}\b([-a-zA-Z0-9\u4E00-\u9FA5()!@:%_+.~#?&//=]*)/gm;
+  return reg.test(url);
+}
+
+/**
+ * Check if the given string is a mobile phone number.
+ *
+ * @example
+ * ```js
+ * console.log(isMobile('13800138000')); // true
+ * console.log(isMobile('1380013800')); // false
+ * console.log(isMobile('138001380000')); // false
+ * console.log(isMobile('1380013800a')); // false
+ * ```
+ *
+ * @param mobile
+ * @returns {boolean} Return true if the given string is a mobile phone number.
+ * @category Util
+ */
+export function isValidPhoneNumber(mobile: string): boolean {
+  const reg = /^1[3456789]\d{9}$/;
+  return reg.test(mobile);
+}