阅读 358

immutability-helper 插件的基本使用(附源码)

本文介绍了 immutability-helper 插件的基本使用,详细介绍了相关 API 的用法及注意事项。


概念

先理解一下 Immutable 的概念,Immutable数据就是一旦创建,就不能更改的数据。每当对Immutable对象进行修改的时候,就会返回一个新的Immutable对象,以此来保证数据的不可变。但是由于 Immutable 的 API 和用法学习起来比较困难,所以可以使用 immutability-helper 这个工具来对原生JS对象进行操作。本文主要是对 immutability-helper 的用法做一个讲解。

源码

源码位置

欢迎 Star!欢迎 Watch!

注意事项总结

  • immutability-helper 不会对原有对象进行修改,只是会返回一个新的对象

  • $push、$unshift、$splice 的使用目标必须是数组,否则会报错

  • $add、$remove 的使用目标必须是 Set 或 Map

  • 其余 API 的使用目标可以是任意数据

  • $splice 的参数是一个操作数组,可以对目标数组一次进行多次操作,但是参数 arrays 中的项是按顺序执行的,所以使用时需要注意顺序

  • 任意 API 均可在多层结构内使用。可查看扩展用法示例

  • 可以同时执行多个 API 操作,但是请注意:多个 API 在一个语句中执行时,只会执行最后一个!!!。可查看注意用法示例

常用 API

  • {$push: array} 同数组的 push 方法,将参数 array 中的所有项 push 到目标数组中

  • {$unshift: array} 同数组的 unshift 方法,将参数 array 中的所有项 unshift 到目标数组中

  • {$splice: array of arrays} 同数组的 splice 方法,对于参数 arrays 中的每一项,使用该项提供的参数对目标数组调用 splice()

    PS: 参数 arrays 中的项是按顺序应用的,所以顺序很重要。在操作过程中,目标的指针可能会发生变化

  • {$set: any} 使用 any 值替换目标

  • {$toggle: array of strings} 将参数 array 中提供的下标或者属性的值切换成相反的布尔值

  • {$unset: array of strings} 从目标对象中移除参数 array 中的键列表

  • {$merge: object} 将参数 object 的键与目标合并

  • {$apply: function} 将当前值传递给函数并用新的返回值更新它

  • {$add: array of objects} 向 Set 或 Map 中添加值。添加到 Set 时,参数 array 为要添加的对象数组,添加到 Map 时,参数 array 为 [key, value] 数组

  • {$remove: array of strings} 从 Set 或 Map 中移除参数 array 中的键列表

API 用法及示例

初始化四个变量,之后的各种 API 操作都是基于这四个变量

const initialObject = {
    name: 'Jack',
    age: 22,
    gender: 'Man'
};
const initialArray = ['a', 'b', 'c', 'd', 'e'];
const initialSet = new Set(['2', '0', '1', '9', '猪', '年', '快', '乐']);
const initialMap = new Map([['id', '1'], ['color', 'blue'], ['alias', 'map']]);
复制代码

{$push: array}

/**
 * API: {$push: array}
 * 同数组的 push 方法,将数组 array 中包含的所有元素添加到 initialArray 的后面,作为一个新数组返回
 */
const pushArray = update(initialArray, { $push: ['f'] });
console.log('pushArray:', pushArray);  // => [ 'a', 'b', 'c', 'd', 'e', 'f' ]
复制代码

{$unshift: array}

/**
 * API: {$unshift: array}
 * 同数组的 unshift 方法,将数组 ['f'] 中包含的所有元素添加到 initialArray 的前面,作为一个新数组返回
 */
const unshiftArray = update(initialArray, { $unshift: ['f'] });
console.log('unshiftArray:', unshiftArray);   // => [ 'f', 'a', 'b', 'c', 'd', 'e' ]
复制代码

{$splice: array of arrays}

/**
 * API: {$splice: array of arrays}
 * 同数组的 splice 方法
 *      数组 arrays 中包含的是所有需要执行的操作集合
 *      元素 array 中第一个元素代表下标,第二个元素代表需要删除的个数,第三个元素代表需要插入到 initialArray 中的的元素
 * 
 * PS:  1、可以在 arrays 中执行多个集合;
 *      2、两个操作不是同时执行,而是按顺序执行,后面的操作会在前面一个操作的执行结果上执行
 */
const spliceArray = update(initialArray, { $splice: [[1, 2], [2, 0, 'f', 'g']] });
console.log('spliceArray:', spliceArray);  // => [ 'a', 'd', 'f', 'g', 'e' ]
复制代码

{$set: any}

/**
 * API: {$set: any}
 * 可以将数组或者对象中某一下标或者属性的值进行替换
 */
// 将 initialArray 数组中下标为 1 的元素修改为 'f'
const setArray = update(initialArray, { 1: { $set: 'f' } });
console.log('setArray', setArray);  // => [ 'a', 'f', 'c', 'd', 'e' ]

// 将 initialObject 对象中 age 属性值修改为 26
const setObject = update(initialObject, { age: { $set: 26 } });
console.log('setObject', setObject);    // => { name: 'Jack', age: 26, gender: 'Man' }
复制代码

{$toggle: array of strings}

/**
 * API: {$toggle: array of strings}
 * 可以将数组或者对象中下标集合或者属性集合的值进行切换:任何 Truthy 都会切换成 false,任何 Falsy 值都会切换成 true
 */
// 将 initialArray 中下标为 1、2 的元素值进行切换
const toggleArray = update(initialArray, { $toggle: [ 1, 2 ] });
console.log('toggleArray:', toggleArray);    // => [ 'a', false, false, 'd', 'e' ]

const toggleObject = update(initialObject, { $toggle: [ 'name', 'gender' ] });
console.log('toggleObject:', toggleObject);  // => { name: false, age: 22, gender: false }
复制代码

{$unset: array of strings}

/**
 * API: {$unset: array of strings}
 * 从目标数组或者对象中移除 array 中的下标或者属性列表
 */
// 删除数组 initialArray 中下标为 1 和 2 的两个元素,但是保留占位
const unsetArray = update(initialArray, { $unset: [1, 2] });
console.log('unsetArray:', unsetArray.length, unsetArray); // 5    [ 'a', <2 empty items>, 'd', 'e' ]

// 删除对象 initialObject 中 name 和 gender 属性
const unsetObject = update(initialObject, { $unset: ['name', 'gender'] });
console.log('unsetObject', unsetObject);    // unsetObject { age: 22 }
复制代码

{$merge: object}

/**
 * API: {$merge: object}
 * 从目标数组或者对象中合并 object 中下标或者属性相同的元素,下标或属性相同时 object 中的元素会替换掉目标中的元素
 */
// 将 initialArray 数组中的 'a', 'b', 'c' 替换为 1, 2, 3
const mergeArray = update(initialArray, { $merge: [1, 2, 3] });
console.log('mergeArray:', mergeArray);    // => [ 1, 2, 3, 'd', 'e' ]

// 将 initialObject 和 { name: 'Rose', gender: 'Woman', hobby: 'Swimming' } } 对象进行合并
const mergeObject = update(initialObject, { $merge: { name: 'Rose', gender: 'Woman', hobby: 'Swimming' } });
console.log('mergeObject', mergeObject);    // => { name: 'Rose', age: 22, gender: 'Woman', hobby: 'Swimming' }
复制代码

{$apply: function}

/**
 * API: {$apply: function}
 * 为目标数组或者对象中某个下标或者属性应用 function
 */
const apply = (val) => val + '--apply'
// 为 initialArray 数组中下标为 1 的元素执行 apply 函数
const applyArray = update(initialArray, { 1: { $apply: apply } });
console.log('applyArray:', applyArray);    // => [ 'a', 'b--apply', 'c', 'd', 'e' ]

// 为 initialObject 对象中 name 属性执行 apply 函数
const applyObject = update(initialObject, { name: { $apply: apply } });
console.log('applyObject:', applyObject);  // => { name: 'Jack--apply', age: 22, gender: 'Man' }
复制代码

{$add: array of objects}

/**
 * API: {$add: array of objects}
 * 向 Set 中添加元素时,array 是一个对象的数组,向 Map 中添加元素时, array 是一个 [key, value] 的数组
 */
// 将 ['Hello', 'World'] 中的元素添加到 initialSet 后,并返回一个新的 Set
const addSet = update(initialSet, { $add: ['Hello', 'World'] });
console.log('addSet:', addSet);    // => Set { '2', '0', '1', '9', '猪', '年', '快', '乐', 'Hello', 'World' }

// 将 [[3, 'Hello'], ['width', '20px']] 中的元素添加到 initialMap 中,并返回一个新的 Map
const addMap = update(initialMap, { $add: [[3, 'Hello'], ['width', '20px']] });
console.log('addMap', addMap);  // => Map { 'id' => '1', 'color' => 'blue', 3 => 'Hello', 'width' => '20px' }
复制代码

{$remove: array of strings}

/**
 * API: {$remove: array of strings}
 * 从 Set 或者 Map 中移除 array 中的键列表
 */
// 删除 initialSet 中的 '猪' 和 '年' 这两个元素
const removeSet = update(initialSet, { $remove: ['猪', '年'] });
console.log('removeSet:', removeSet);  // => removeSet: Set { '2', '0', '1', '9', '快', '乐' }

// 删除 initialMap 中的 'color'和 'alias' 对应的两个键值对
const removeMap = update(initialMap, { $remove: ['color', 'alias'] });
console.log('removeMap:', removeMap);  // => Map { 'id' => '1' }
复制代码

扩展用法

  • 可多层结构内使用
/**
 * 扩展用法:可多层结构内使用
 */
const initialConfig = {
    width: 100,
    height: 100,
    options: [
        { color: 'red', shape: 'Square' },
        { color: 'blue', shape: 'Circular' }
    ]
}
// 多层结构内使用
const multiConfig1 = update(initialConfig, { options: { color: { $set: 'pink' } } });
console.log('multiConfig1:', multiConfig1);
/* => 
{ width: 100,
  height: 100,
  options:
   [ { color: 'red', shape: 'Square' },
     { color: 'blue', shape: 'Circular' },
     color: 'pink' ] }
*/
复制代码

注意用法

  • 多种操作不要一起使用,否则只会执行最后的一个操作
/**
 * 注意用法:多种操作不要一起使用,否则只会执行最后的一个操作
 */

const initialConfig = {
    width: 100,
    height: 100,
    options: [
        { color: 'red', shape: 'Square' },
        { color: 'blue', shape: 'Circular' }
    ]
}

// 例子:只会执行最后的设置 color 属性的操作
const multiConfig2 = update(initialConfig, { options: { $push: [ { color: 'deepPink', shape: 'Triangle' } ] }, options: { color: { $set: 'pink' } } });
console.log('multiConfig2:', multiConfig2);    
/* => 
{ width: 100,
  height: 100,
  options:
   [ { color: 'red', shape: 'Square' },
     { color: 'blue', shape: 'Circular' },
     color: 'pink' ] }
*/
复制代码
关注下面的标签,发现更多相似文章
评论