mazey 1.4.39 → 2.2.0

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 Mazey
+Copyright (c) 2022 Mazey
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,3 +1,5 @@
+English | [简体中文](./README_CN.md)
+
 # Mazey
 
 [![NPM version][npm-image]][npm-url]
@@ -20,111 +22,197 @@ npm install mazey --save
 
 ## Usage
 
-### 加载资源
+### Load Resource
 
-加载 JavaScript
+#### Load JavaScript
 
 ```
 import { loadScript } from 'mazey';
 
 loadScript({
-  url: 'http://www.mazey.net/js/plugin/jquery/jquery-2.1.1.min.js',
-  id: 'iamid', // 可选，script 标签 ID，默认无 ID
-  timeout: 5000, // 可选，超时时间，默认 5000
-  isDefer: false, // 可选，defer，默认 false
+  url: 'http://example.com/js/plugin/jquery/jquery-2.1.1.min.js',
+  id: 'iamid', // Optional, script ID, default none
+  timeout: 5000, // Optional, timeout, default `5000`
+  isDefer: false, // Optional, defer, default `false`
 })
   .then(
     res => {
-      console.log(`加载 JavaScript 成功: ${res}`);
+      console.log(`Load JavaScript Success: ${res}`);
     }
   )
   .catch(
     err => {
-      console.error(`加载 JavaScript 失败: ${err}`)
+      console.error(`Load JavaScript Fail: ${err}`)
     }
   );
 ```
 
-加载 CSS
+#### Load CSS
 
 ```
 import { loadCSS } from 'mazey';
 
 loadCSS({
-  url: 'http://www.mazey.net/css/mazey-base.css',
-  id: 'iamid', // 可选，link 标签 ID，默认无 ID
+  url: 'http://example.com/css/mazey-base.css',
+  id: 'iamid', // Optional, link ID, default none
 })
   .then(
     res => {
-      console.log(`加载 CSS 成功: ${res}`);
+      console.log(`Load CSS Success: ${res}`);
     }
   )
   .catch(
     err => {
-      console.error(`加载 CSS 失败: ${err}`)
+      console.error(`Load CSS Fail: ${err}`)
     }
   );
 ```
 
-判断页面是否加载完成（兼容浏览器 `load` 事件已经触发过的情况）
+#### Check Load
+
+Check whether the page is loaded successfully (Keepe the compatibility in case that browser's `load` event has been triggered).
 
 ```
-import { loadCSS } from 'mazey';
+import { windowLoaded } from 'mazey';
 
-windowLoaded({ timeout: 30 })
+windowLoaded({ timeout: 30 }) // second
   .then(res => {
-    console.log(`加载完成：${res}`); // 加载完成：load
+    console.log(`Load Success: ${res}`); // Load Success: load
   })
   .catch(err => {
-    console.log(`加载超时或失败：${err}`);
+    console.log(`Load Timeout or Fail: ${err}`);
   });
 ```
+### Function
 
-### 存储数据
+#### Debounce
 
-Storage（兼容 JSON 格式，自行转换）
+```
+import { debounce } from 'mazey';
 
+const foo = debounce(() => {
+  console.log('The debounced function will only be invoked in 1000 milliseconds, the other invoking will disappear during the wait time.');
+}, 1000, { leading: true })
 ```
-import { setSessionStorage, getSessionStorage, setLocalStorage, getLocalStorage } from 'mazey';
 
-setSessionStorage('test', '123');
-getSessionStorage('test'); // 123
-setLocalStorage('test', '123');
-getLocalStorage('test'); // 123
+#### Throttle
+
 ```
+import { throttle } from 'mazey';
 
-Cookie
+const foo = throttle(() => {
+  console.log('The function will be invoked at most once per every wait 1000 milliseconds.');
+}, 1000, { leading: true })
+```
+
+#### Check Number
+
+Check whether it is a right number.
 
 ```
-import { setCookie, getCookie } from 'mazey';
+import { isNumber } from 'mazey';
+
+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
+```
+
+#### Camel Case
+
+Transfer CamelCase to KebabCase.
+
+```
+import { camelCaseToKebabCase } from 'mazey';
+
+camelCaseToKebabCase('ABC'); // a-b-c
+camelCaseToKebabCase('aBC'); // a-b-c
+```
+
+Transfer CamelCase to Underscore.
+
+```
+import { camelCase2Underscore } from 'mazey';
+
+camelCase2Underscore('ABC'); // a_b_c
+camelCase2Underscore('aBC'); // a_b_c
+```
+
+#### Trim
+
+Remove leading and trailing whitespace or specified characters from string.
+
+```
+import { mTrim } from 'mazey';
+
+mTrim(' 1 2 3 '); // '1 2 3'
+mTrim('abc '); // 'abc'
+```
+
+#### Deep Clone
+
+Clone Object deeply.
+
+```
+import { deepCopyObject } from 'mazey';
+
+deepCopyObject(['a', 'b', 'c']); // ['a', 'b', 'c']
+deepCopyObject('abc'); // 'abc'
+```
+
+#### JSON
+
+Check whether it is a valid JSON string.
+
+```
+import { isJsonString } from 'mazey';
+
+isJsonString(`['a', 'b', 'c']`); // false
+isJsonString(`["a", "b", "c"]`); // true
+```
+
+#### Random
+
+Produce a random string of number, `generateRndNum(7)` => '7658495'.
 
-setCookie('test', '123', 30, 'mazey.net'); // key value day domain
-getCookie('test'); // 123
 ```
+import { generateRndNum } from 'mazey';
+
+generateRndNum(4); // '9730'
+generateRndNum(7); // '2262490'
+```
+
+### DOM
 
-### 操作 DOM
+#### Class
 
-修改 `class`
+Modify `class`.
 
 ```
 import { hasClass, addClass, removeClass } from 'mazey';
 
 const dom = document.querySelector('#box');
 
-// 判断 class
+// Determine `class`
 hasClass(dom, 'test');
-// 增加 class
+// Add `class`
 addClass(dom, 'test');
-// 删除 class
+// Remove `class`
 removeClass(dom, 'test');
 ```
 
-添加内联样式
+#### Style
+
+Add inline-style.
+
+Case 1: Add the inline style with `id`, and repeated invoking will update the content instead of adding a new one.
 
 ```
 import { addInlineStyle } from 'mazey';
 
-// 添加有 id 的内联样式，重复添加会更新内联样式而不是新增
 addInlineStyle({
   inlineStyle: `
     body {
@@ -138,8 +226,13 @@ addInlineStyle({
 //     background-color: #333;
 //   }
 // </style>
+```
+
+Case 2: Add the inline style without `id`, and repeated invoking will adding a new one.
+
+```
+import { addInlineStyle } from 'mazey';
 
-// 添加无 id 的内联样式，重复添加会新增内联样式
 addInlineStyle({
   inlineStyle: `
     body {
@@ -154,100 +247,124 @@ addInlineStyle({
 // </style>
 ```
 
-添加自定义滚动条（适用于用 `transform` 移动的元素）
+#### Newline
+
+Make a newline of HTML.
 
 ```
-import { customScrollBarForTransformEle } from 'mazey';
+import { newLine } from 'mazey';
 
-// 使用类名
-customScrollBarForTransformEle({
-  containerClassName: 'i-am-container',
-  imgBoxClassName: 'i-am-img-father-i-can-transform',
-  imgClassName: 'i-am-img',
-});
+newLine('a\nb\nc'); // 'a<br />b<br />c'
+newLine('a\n\nbc'); // 'a<br /><br />bc'
+```
 
-// 使用 Dom 对象
-customScrollBarForTransformEle({
-  containerClassName: 'i-am-container',
-  imgBoxDom: document.querySelector('.i-am-img-father-i-can-transform'),
-  imgDom: document.querySelector('.i-am-img-father-i-can-transform'),
-});
+### URL
+
+#### Query Param
+
+Get the query param's value of the current Web URL(`location.search`).
 
-// 按需直接隐藏滚动条
-customScrollBarForTransformEle({
-  containerClassName: 'i-am-container',
-  action: 'hide',
-});
 ```
+import { getQueryParam } from 'mazey';
 
-计算适配容器宽度的图片的尺寸、距离顶部的距离
+// http://example.com/?t1=1&t2=2&t3=3&t4=4#2333
+// ?t1=1&t2=2&t3=3&t4=4
+getQueryParam('t3'); // 3
+getQueryParam('t4'); // 4
+```
+
+Get the query param's value of the input URL.
 
 ```
-import { calcContainImageSizeAndPosition } from 'mazey';
+import { getUrlParam } from 'mazey';
 
-// 如果高度不足以占满容器，使其垂直居中；如果高度比容器长，由上向下铺开
-calcContainImageSizeAndPosition({ oriImageWidth: 300, oriImageHeight: 300, viewportWidth: 375, viewportHeight: 812 });
-// {"targetImageWidth":375,"targetImageHeight":375,"top":218.5,"wPer":1.25}
+getUrlParam('http://example.com/?t1=1&t2=2&t3=3&t4=4', 't3'); // 3
+getUrlParam('http://example.com/?t1=1&t2=2&t3=3&t4=4', 't4'); // 4
 ```
 
-### 网站性能
+#### Update Param
 
-获取加载时间
+Update the query param's value of the input URL.
 
 ```
-import { getPerformance } from 'mazey';
+import { updateQueryParam } from 'mazey';
 
-// camelCase：true（默认） 以驼峰形式返回数据 / false 以下划线形式返回数据
-getPerformance({ camelCase: true })
- .then(res => {
-  console.log(JSON.stringify(res));
-  // {"deviceType":"pc","network":"3g","unloadTime":0,"redirectTime":0,"dnsTime":0,"tcpTime":0,"responseTime":65,"downloadTime":1,"domreadyTime":369,"onloadTime":441,"whiteTime":94,"renderTime":441,"decodedBodySize":210,"encodedBodySize":210}
- })
- .catch(console.error);
+updateQueryParam('http://example.com/?t1=1&t2=2&t3=3&t4=4', 't3', 'three'); // http://example.com/?t1=1&t2=2&t3=three&t4=4
+updateQueryParam('http://example.com/?t1=1&t2=2&t3=3&t4=4', 't4', 'four'); // http://example.com/?t1=1&t2=2&t3=3&t4=four
 ```
 
-| 指标 | 字段 | 计算⽅法 |
-| --- | --- | --- |
-| * DNS 查询时间 | dns_time | domainLookupEnd - domainLookupStart |
-| * 服务器连接时间 | tcp_time | connectEnd - connectStart |
-| * 服务器响应时间 | response_time | responseStart - requestStart |
-| * ⽩屏时间 | white_time | responseStart - navigationStart |
-| * DomReady 总时间 | domready_time  | domContentLoadedEventStart - navigationStart |
-| * 页面加载时间 | onload_time | loadEventStart - navigationStart |
-| * EventEnd 总时间 | render_time | loadEventEnd -navigationStart |
-| 上个⽂档卸载时间 | unload_time | unloadEventEnd - unloadEventStart |
-| 重定向时间 | redirect_time | redirectEnd - redirectStart |
-| 客户端⽩屏时间 | custom_white_time | renderTiming - navigationStart |
-| SSL连接时间 | ssl_time | connectEnd - secureConnectionStart |
-| ⽹⻚下载时间 | download_time | responseEnd - responseStart |
-| FCP | first_contentful_paint_time | firstPaintTime |
+#### Hash Param
 
-### 公式计算
+Get the hash query param's value of the current Web URL(`location.hash`).
 
-计算两个字符串的最长公共子串
+```
+import { getHashQueryParam } from 'mazey';
 
+// http://example.com/?#2333?t1=1&t2=2&t3=3&t4=4
+// #2333?t1=1&t2=2&t3=3&t4=4
+getHashQueryParam('t3'); // 3
+getHashQueryParam('t4'); // 4
 ```
-import { calLongestCommonSubstring } from 'mazey';
 
-calLongestCommonSubstring('fish', 'finish'); // 3
+#### Domain
+
+Get the domain of URL, and other params.
+
+```
+import { getDomain } from 'mazey';
+
+getDomain('http://example.com/?t1=1&t2=2&t3=3&t4=4'); // example.com
+getDomain('http://example.com/test/thanks?t1=1&t2=2&t3=3&t4=4', ['hostname', 'pathname']); // example.com/test/thanks
+```
+
+### Cache Data
+
+#### Storage
+
+Handle Storage (Keep fit for JSON, it can tansfer format automatically).
+
 ```
+import { setSessionStorage, getSessionStorage, setLocalStorage, getLocalStorage } from 'mazey';
+
+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}`);
+}
 ```
-import { calLongestCommonSubsequence } from 'mazey';
 
-calLongestCommonSubsequence('fish', 'finish'); // 4
+#### Cookie
+
+Handle Cookie.
+
 ```
+import { setCookie, getCookie } from 'mazey';
+
+setCookie('test', '123', 30, 'example.com'); // key value day domain
+getCookie('test'); // 123
+```
+
+### Calculate&Formula
+
+#### Rate
 
-命中概率（1% ~ 100%）
+Hit probability (1% ~ 100%).
 
 ```
 import { inRate } from 'mazey';
 
 inRate(0.5); // 0.01 ~ 1 true / false
 
-// 测试准确性
+// Test
 let trueCount = 0;
 let falseCount = 0;
 new Array(1000000).fill(0).forEach(() => {
@@ -260,54 +377,92 @@ new Array(1000000).fill(0).forEach(() => {
 console.log(trueCount, falseCount); // 499994 500006
 ```
 
-### 浏览器信息
+#### Algorithm
+
+Computes the longest common substring of two strings.
 
 ```
-import { getBrowserType } from 'mazey';
+import { calLongestCommonSubstring } from 'mazey';
 
-getBrowserType(); // {"engine":"webkit","engineVs":"537.36","platform":"desktop","supporter":"chrome","supporterVs":"85.0.4183.121","system":"windows","systemVs":"10"}
-// 外壳和外壳版本 { shell: 'wechat', shellVs: '20' } shell: wechat qq uc 360 2345 sougou liebao maxthon
+calLongestCommonSubstring('fish', 'finish'); // 3
 ```
 
-### 安全边际
+Computes the longest common subsequence of two strings.
 
-判断是否是安全的 PWA 运行环境
+```
+import { calLongestCommonSubsequence } from 'mazey';
 
+calLongestCommonSubsequence('fish', 'finish'); // 4
 ```
-import { isSafePWAEnv } from 'mazey';
 
-isSafePWAEnv(); // true
+### Browser Information
+
 ```
+import { getBrowserInfo } from 'mazey';
 
-### 函数
+getBrowserInfo(); // {"engine":"webkit","engineVs":"537.36","platform":"desktop","supporter":"chrome","supporterVs":"85.0.4183.121","system":"windows","systemVs":"10"}
+// Shell and shell version { shell: 'wechat', shellVs: '20' } shell: wechat qq uc 360 2345 sougou liebao maxthon
+```
 
-防抖
+| 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 | wechat, qq_browser, qq_app, uc, 360, 2345, sougou, liebao, maxthon, bilibili |
+| Shell version | shellVs | - |
+| Apple device type | appleType | iphone, ipad, ipod, iwatch |
+
+### Web Performance
+
+Get page load time(PerformanceTiming).
 
 ```
-import { debounce } from 'mazey';
+import { getPerformance } from 'mazey';
 
-const foo = debounce(() => {
-  console.log('执行 1 秒内再次执行无反应');
-}, 1000, { leading: true })
+// `camelCase：true`(Default) Return hump data.
+// `camelCase：false` Return underline data.
+getPerformance({ camelCase: true })
+ .then(res => {
+  console.log(JSON.stringify(res));
+  // {"deviceType":"pc","network":"3g","unloadTime":0,"redirectTime":0,"dnsTime":0,"tcpTime":0,"responseTime":65,"downloadTime":1,"domreadyTime":369,"onloadTime":441,"whiteTime":94,"renderTime":441,"decodedBodySize":210,"encodedBodySize":210}
+ })
+ .catch(console.error);
 ```
 
-判断是否是有效数字
+| Index | Field | Calculation |
+| --- | --- | --- |
+| * DNS lookup | dns_time | domainLookupEnd - domainLookupStart |
+| * Connection negotiation | tcp_time | connectEnd - connectStart |
+| * Requests and responses | response_time | responseStart - requestStart |
+| * White screen | white_time | responseStart - navigationStart |
+| * DomReady | domready_time  | domContentLoadedEventStart - navigationStart |
+| * Onload | onload_time | loadEventStart - navigationStart |
+| * EventEnd | render_time | loadEventEnd -navigationStart |
+| Unload | unload_time | unloadEventEnd - unloadEventStart |
+| Redirect | redirect_time | redirectEnd - redirectStart |
+| SSL | ssl_time | connectEnd - secureConnectionStart |
+| Download | download_time | responseEnd - responseStart |
+
+### Margin of Safety
+
+Determine if it is a secure PWA environment that it can run.
 
 ```
-import { isNumber } from 'mazey';
+import { isSafePWAEnv } from 'mazey';
 
-isNumber(123); // true
-isNumber('123'); // false
-// 默认情况下 NaN、Infinity 不算有效数字
-isNumber(Infinity); // false
-isNumber(Infinity, { isUnFiniteAsNumber: true }); true
-isNumber(NaN); // false
-isNumber(NaN, { isNaNAsNumber: true, isUnFiniteAsNumber: true }); // true
+isSafePWAEnv(); // true
 ```
 
-### 调试
+### Debug
 
-自定义控制台打印（`console`）
+#### Print
+
+Custom console printing (`console`).
 
 ```
 import { genCustomConsole } from 'mazey';
@@ -319,7 +474,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)
+[More API>>](https://mazey.cn/docs/mazey/modules/_index_.html)
 
 ## Develop
 
@@ -332,4 +487,4 @@ npm run build
 
 # documentation
 npm run docs
-```
+```