native-class-ext/README.md

js原生对象增加常用方法

# js原生对象添加常用方法

所有的扩展方法都以$开头加到原型上

***

## Array
```javascript
let test = [2,3,5,6,7,9]
```
### 根据位置删除 $removeByIndex
- 语法
   ```javascript
   test.$removeByIndex(index)
   ```
	
- 参数   
   index {Numbar} 删除的位置0开始
   
- 返回值   
   {Array} 删除的值
   
- 例子
   ```javascript
   let test = [2,3,5,6,7,9]
   console.log(test.$removeByIndex(1)) // [3]
   console.log(test) // [ 2, 5, 6, 7, 9 ]
   ```
   
***

### 根据值删除 $remove
- 语法
   ```javascript
   test.$remove(val, [key])
   ```
	
- 参数   
   val {Object} 要删除的值   
   key {function|String} 如果数组元素是对象，key为对象比对的字段，或比较函数
   
- 返回值   
   {Array} 删除的值
   
- 例子
   ```javascript
   test = [2,3, {name: 3}]
   console.log(test.$remove(3)) // [ 3 ]
   console.log(test) // 输出 [ 2, { name: 3 } ]
   console.log(test.$remove(3, 'name')) // [ { name: 3 } ]
   console.log(test) // 输出 [ 2 ]
   ```

***

### 添加或删除 $addOrRemove
- 语法
   ```javascript
   test.$addOrRemove(val, padStart, [key])
   ```
	
- 参数   
   val {Object} 要添加或删除的值   
   padStart {Boolean} 是否添加到开头，默认false   
   key {function|String} 如果数组元素是对象，key为对象比对的字段，或比较函数   
   
- 返回值   
   {Boolean} 添加返回true
   
- 例子
   ```javascript
   test = [2,3, {name: 3}]
   console.log(test.$addOrRemove(8), test) // true [ 2, 3, 8 ]
   console.log(test.$addOrRemove(9, true), test) // true [ 9, 2, 3, 8 ]
   console.log(test.$addOrRemove(8), test) // false [ 9, 2, 3 ]
   console.log(test.$addOrRemove(3, 'name'), test) // false [ 9, 2, 3 ]
   ```

***


### 替换 $replace
- 语法
   ```javascript
   test.$replace(index, value)
   ```
	
- 参数   
   index {Number} 位置,0开始   
   value {Object} 值
   
- 返回值   
   {Array} 旧的值
   
- 例子
   ```javascript
   test = [2, 3, 9]
   console.log(test.$replace(1, 6), test) // [ 3 ] [ 2, 6, 9 ]
   ```

***


### 查找元素返回位置  $findIndex
- 语法
   ```javascript
   test.$findIndex(value, key)
   ```
	
- 参数   
   val {Object} 要找的值   
   key {function|String} 如果数组元素是对象，key为对象比对的字段，或比较函数
   
- 返回值   
   {Number} 位置，0开始
   
- 例子
   ```javascript
   test = [2, 3, {name: 3}]
   console.log(test.$findIndex(3)) // 1
   console.log(test.$findIndex(3, 'name')) // 2
   ```

***


### 查找元素返回值  $findEl
- 语法
   ```javascript
   test.$findEl(value, key)
   ```
	
- 参数   
   val {Object} 要找的值   
   key {function|String} 如果数组元素是对象，key为对象比对的字段，或比较函数
   
- 返回值   
   {Object} 值
   
- 例子
   ```javascript
   test = [2, 3, {name: 3}]
   console.log(test.$findEl(3)) // 3
   console.log(test.$findEl(3, 'name')) // { name: 3 }
   ```

***


### 最后一个值  $last
- 语法
   ```javascript
   test.$last()
   ```
	
- 参数
  
- 返回值   
   {Object} 值
   
- 例子
   ```javascript
   test = [2, 3]
   console.log(test.$last()) // 3
   ```

***


### 交换值  $swap
- 语法
   ```javascript
   [].$swap(0, 2)
   ```
	
- 参数
   index1 {Number} 位置
   index2 {Number} 位置   
   
- 例子
   ```javascript
   let test = [2, 3, 5]
   test.$swap(0, 2)
   console.log(test) // [5, 3, 2]
   ```

***

### 判断空数组  $isEmpty
- 语法
   ```javascript
   Array.$isEmpty(test)
   ```
	
- 参数   
  test {Array} 数组
  
- 返回值   
   {Boolean} 不是数组 或 长度 返回true
   
- 例子
   ```javascript
   test = [2, 3]
   console.log(Array.$isEmpty([])) // true
   console.log(Array.$isEmpty(test)) // false
   let test1;
   console.log(Array.$isEmpty(test1)) // true
   ```


## Date

### 日期格式化 $format
- 语法
   ```javascript
   new Date().$format([reg]);
   ```
	
- 参数   
   reg {String} 格式，默认yyyy-MM-dd HH:mm:ss   
   
      1. yy/yyyy 年
      3. M/MM 月
      5. d/dd 日
      6. H/HH 时
      7. m/mm 分
      8. s/ss 秒
      9. S 毫秒
     10. ww 星期
  
- 返回值   
   {String} 
   
- 例子
   ```javascript
   new Date().$format('yyyy-MM-dd HH:mm:ss ww');
   ```


### 格式秒 $formatSeconds
- 语法
   ```javascript
   Date.$formatSeconds(seconds)
   ```
	
- 参数   
  seconds {Number} 秒数
  
- 返回值   
   {String} 
   
- 例子
   ```javascript
   Date.$formatSeconds(61)// = "1分1秒"
   ```


### 本地时间与服务器时间的差异 $serverTimeOffset   
   有使用 $newServerDate、$nowServer需要初始化，服务器时间-本地时间，单位毫秒
- 语法
   ```javascript
   Date.$serverTimeOffset = {服务器时间}-Date.now()
   ```
   

### 服务器时间 $newServerDate
- 语法
   ```javascript
   Date.$newServerDate()
   ```
  
- 返回值   
   {Date} new Date(Date.$nowServer())
   

### 服务器时间戳 $nowServer / $now10
- 语法
   ```javascript
   Date.$nowServer()
   Date.$now10()
   ```
  
- 返回值   
   {Date} Date.now() + Date.$serverTimeOffset


### 时间单位转换 $UNIT

- 例子
   ```javascript
   Date.$UNIT.DAYS.toHours(1) // =24 天转小时
   Date.$UNIT.HOURS.toMinutes(1) // =60 小时转分钟
   Date.$UNIT.MINUTES.toSeconds(1) // =60 分钟转秒
   Date.$UNIT.SECONDS.toMillis(1) // =1000 秒转毫秒
   ```


### 解析Date对象 $parseDate
- 语法
   ```javascript
   Date.$parseDate(date)
   ```
	
- 参数   
  date {String|Number|Date} 需要转的值
  
- 返回值   
   {Date} 
   
- 例子
   ```javascript
   Date.$parseDate('2021-01-01')
   Date.$parseDate(1609430400000)
   Date.$parseDate(1609430400)
   ```


### 复制一份副本 $copy
   不同对象，值相同
- 返回值   
   {Date} 
   
- 例子
   ```javascript
   new Date().$copy())
   ```


### 获取月最后一天 $getMonthLastDay  
- 返回值   
   {Date} 
   
- 例子
   ```javascript
   new Date().$getMonthLastDay()
   ```


### 获取0点日期 $getZeroDate

- 返回值   
   {Date} 
   
- 例子
   ```javascript
   new Date().$getZeroDate()// = new Date(yyyy, MM, dd)
   ```


### 判断是否是今天 $isToday
- 返回值   
   {Boolean} 
   
- 例子
   ```javascript
   new Date().$isToday()// true
   ```


### 两个日期相差几天 $differDay
- 语法
   ```javascript
   $differDay(date)
   ```
	
- 参数   
  date {Date} 另一个日期
  
- 返回值   
   {Number} 相差天数
   
- 例子
   ```javascript
   new Date(2021, 01, 01).$differDay(new Date(2021, 01, 03)) // = -2
   ```


### 下一个半小时 $next30
   返回 yyyy-MM-dd HH:00:00 或 yyyy-MM-dd HH:30:00
- 语法
   ```javascript
   $next30([copy])
   ```
	
- 参数   
  copy {Boolean} 是否复制一份修改，默认false 修改原对象
  
- 返回值   
   {Date} 
   
- 例子
   ```javascript
   let d1 = Date.$parseDate('2021-02-01 10:01:01');
   let d2 = d1.$next30();
   console.log(d2==d1)// true
   console.log(d2.$format())// '2021-02-01 10:30:00'
   d2 = d1.$next30(true);
   console.log(d2==d1)// false
   console.log(d2.$format())// '2021-02-01 11:00:00'
   ```


### 添加月 $addMonth
- 语法
   ```javascript
   $addMonth(num[, copy])
   ```
	
- 参数   
  num {Number} 添加月数，可负   
  copy {Boolean} 是否在新的Date对象上添加，默认 false 修改当前对象
  
- 返回值   
   {Date} 
   
- 例子
   ```javascript
   let d1 = Date.$parseDate('2021-01-01 00:00:00');
   d1.$addMonth(1).$format()// 2021-02-01 00:00:00
   d1.$addMonth(-1, true).$format()// 不修改原对象=2021-01-01 00:00:00
   d1.$format()// 2021-02-01 00:00:00
   ```


### 添加年 $addYear
- 语法
   ```javascript
   $addYear(num[, copy])
   ```
	
- 参数   
  num {Number} 添加年数，可负   
  copy {Boolean} 是否在新的Date对象上添加，默认 false 修改当前对象
  
- 返回值   
   {Date} 
   
- 例子
   ```javascript
   let d1 = Date.$parseDate('2021-01-01 00:00:00');
   d1.$addYear(1).$format()// 2022-01-01 00:00:00
   d1.$addYear(-1, true).$format()// 不修改原对象=2021-01-01 00:00:00
   d1.$format()// 2022-01-01 00:00:00
   ```


### 添加天 $addDay
- 语法
   ```javascript
   $addDay(num[, copy])
   ```
	
- 参数   
  num {Number} 添加天数，可负
  copy {Boolean} 是否在新的Date对象上添加，默认 false 修改当前对象
  
- 返回值   
   {Date} 
   
- 例子
   ```javascript
   let d1 = Date.$parseDate('2021-01-01 00:00:00');
   d1.$addDay(1).$format()// 2021-01-02 00:00:00
   d1.$addDay(-1, true).$format()// 不修改原对象=2021-01-01 00:00:00
   d1.$format()// 2021-01-02 00:00:00
   ```


### 添加小时 $addHours
- 语法
   ```javascript
   $addHours(num[, copy])
   ```
	
- 参数   
  num {Number} 添加数，可负
  copy {Boolean} 是否在新的Date对象上添加，默认 false 修改当前对象
  
- 返回值   
   {Date} 
   
- 例子
   ```javascript
   let d1 = Date.$parseDate('2021-01-01 00:00:00');
   d1.$addHours(1).$format()// =2021-01-01 01:00:00
   d1.$addHours(-1, true).$format()// 不修改原对象=2021-01-01 00:00:00
   d1.$format()// =2021-01-01 01:00:00
   ```


### 添加分钟 $addMinutes
- 语法
   ```javascript
   $addMinutes(num[, copy])
   ```
	
- 参数   
  num {Number} 添加数，可负
  copy {Boolean} 是否在新的Date对象上添加，默认 false 修改当前对象
  
- 返回值   
   {Date} 
   
- 例子
   ```javascript
   let d1 = Date.$parseDate('2021-01-01 00:00:00');
   d1.$addMinutes(1).$format()// =2021-01-01 00:01:00
   d1.$addMinutes(-1, true).$format()// 不修改原对象=2021-01-01 00:00:00
   d1.$format()// =2021-01-01 00:01:00
   ```


### 测试此日期是否在指定日期之前 $before
- 语法
   ```javascript
   $before(when)
   ```
	
- 参数   
  when {Date} 另一个日期
  
- 返回值   
   {Boolean} this<when
   
- 例子
   ```javascript
   let d1 = new Date();
   let d2 = d1.$addHours(1, true);
   d1.$before(d2)// =true
   ```


### 测试此日期是否在指定日期之后 $after
- 语法
   ```javascript
   $after(when)
   ```
	
- 参数   
  when {Date} 另一个日期
  
- 返回值   
   {Boolean} this>when
   
- 例子
   ```javascript
   let d1 = new Date();
   let d2 = d1.$addHours(1, true);
   d1.$after(d2)// =false
   ```
   
## Number

### 加 $add
- 语法
   ```javascript
   $add(augend)
   ```
	
- 参数   
  augend {Number} 被加数
  
- 返回值   
   {Number} 
   
- 例子
   ```javascript
   0.1.$add(0.2) // =0.3
   ```
   
   
### 减 $subtract
- 语法
   ```javascript
   $subtract(subtrahend)
   ```
	
- 参数   
  subtrahend {Number} 被减数
  
- 返回值   
   {Number} 
   
- 例子
   ```javascript
   0.3.$subtract(0.2)// =0.1
   ```
   
   
### 乘 $multiply
- 语法
   ```javascript
   $multiply(multiplicand)
   ```
	
- 参数   
  multiplicand {Number} 乘数
  
- 返回值   
   {Number} 
   
- 例子
   ```javascript
   0.1.$multiply(3)// =0.3
   ```
   
   
### 除 $divide
- 语法
   ```javascript
   $divide(divisor[, scale[, roundingMode]])
   ```
	
- 参数   
  divisor {Number} 除数   
  scale {Number} 保留小数位数,默认2   
  roundingMode {Number} 舍入方式,默认Number.$ROUND_HALF_UP   
  
- 返回值   
   {Number} 
   
- 例子
   ```javascript
   2.4.$divide(0.8) // =3
   (153).$divide(1000, 1, Number.$ROUND_HALF_UP)// =0.2
   ```
   
   
### 设置精度 $setScale
- 语法
   ```javascript
   $setScale([scale[, roundingMode]])
   ```
	
- 参数   
  scale {Number} 保留小数位数,默认2   
  roundingMode {Number} 舍入方式,默认Number.$ROUND_HALF_UP   
     1. $ROUND\_UP 进位
     1. $ROUND\_DOWN 舍弃
     1. $ROUND\_HALF\_UP 四舍五入
  
- 返回值   
   {Number} 
   
- 例子
   ```javascript
   0.153.$setScale(1, Number.$ROUND_UP)// 0.2
   0.143.$setScale(1, Number.$ROUND_UP)// 0.2
   (-0.143).$setScale(1, Number.$ROUND_UP)// -0.2
   
   0.143.$setScale(1, Number.$ROUND_DOWN)// 0.1
   (-0.153).$setScale(1, Number.$ROUND_DOWN)// -0.1
   
   0.153.$setScale(1, Number.$ROUND_HALF_UP)// 0.2
   0.143.$setScale(1, Number.$ROUND_HALF_UP)// 0.1
   (-0.153).$setScale(1, Number.$ROUND_HALF_UP)// -0.2
   (-0.143).$setScale(1, Number.$ROUND_HALF_UP)// -0.1
   ```
   
   
## Promise
   
### 都完成后回调 allSettled
   部分浏览器本身就支持[文档](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled)
- 语法
   ```javascript
   Promise.allSettled(iterable);
   ```
	
- 参数   
  iterable {Array} 一个可迭代的对象，例如Array，其中每个成员都是Promise。
  
- 返回值   
   {Array} 一旦所指定的 promises 集合中每一个 promise 已经完成，无论是成功的达成或被拒绝，未决议的 Promise将被异步完成。
      那时，所返回的 promise 的处理器将传入一个数组作为输入，该数组包含原始 promises 集中每个 promise 的结果。   
      对于每个结果对象，都有一个 status 字符串。如果它的值为 fulfilled，则结果对象上存在一个 value 。如果值为 rejected，则存在一个 reason 。value（或 reason ）反映了每个 promise 决议（或拒绝）的值。
   
- 例子
   ```javascript
   let p = new Promise((r)=>r(1))
   let p1 = new Promise((res, rej)=>rej(1))
   Promise.allSettled([p, p1]).then(res=>{
	   // res = [{"status": "fulfilled","value": 1,},
		//{"reason": 1,"status": "rejected",}]
   })
   ```
   
### 最后执行 finally
   部分浏览器本身就支持[文档](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise/finally)
- 语法
   ```javascript
   new Promise().finally();
   ```

### 不抛异常的方式返回结果 $result
- 返回值   
   {Object} {status: true/false, data: 返回数据}
   
- 例子
   ```javascript
   new Promise((r)=>r(1)).$result().then(res=>{
	   // res= {status: true, data: 1}
   })
   new Promise((res, rej)=>rej(1)).$result().then(res=>{
	   // res= {status: false, data: 1}
   })
   ```

## String

### 判断空字符串 $isEmpty
- 语法
   ```javascript
   String.$isEmpty(str[, minLength])
   "".$isEmpty(minLength)
   ```
	
- 参数   
  str {String}   
  minLength {Number} 最小长度，默认1
   
- 例子
   ```javascript
   String.$isEmpty("") // true;
   String.$isEmpty("1"))// false;
   String.$isEmpty("1", 2))// true;
   
   "".$isEmpty()) // true;
   "1".$isEmpty()) // false;
   "1".$isEmpty(2)) //true;
   ```

### 指定位置插入字符串 $insertStr
- 语法
   ```javascript
   "".$insertStr(start, str)
   ```
	
- 参数   
  start {Number} 出入位置，0开始  
  str {String} 要插入的字符串
   
- 例子
   ```javascript
   "124".$insertStr(2, '3')// 1234
   ```
   
### 字符串填充浏览器兼容 padStart/padEnd
- 语法
   ```javascript
   "".padStart(maxLength, padStr)
   ```
	
- 参数   
  maxLength {Number} 字符串最大长度  
  str {String} 不够长度填充字符串
   
- 例子
   ```javascript
   "1".padStart(2, '0')// 01
   "1".padEnd(2, '0')// 10
   ```

## Object

### 获取对象值数组(兼容处理) values
- 例子
   ```javascript
   Object.values({a: 66})// [66]
   ```