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: 一、能夠在 arrays 中執行多個集合； * 二、兩個操做不是同時執行，而是按順序執行，後面的操做會在前面一個操做的執行結果上執行 */
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 中下標爲 一、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' ] } */
複製代碼