Skip to content

deepMerge — Deep Merge ​

17:43

Description ​

$u.deepMerge recursively merges two JsonObject values: fields in source override those in target, plain objects on both sides are merged further, and arrays are replaced as a whole.

Examples ​

Basic object merge ​

The age and email fields of source override or add to target, and the address objects merge recursively into one containing fields from both sides.

View source
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item title="目标对象" :label="JSON.stringify(targetObj)" :arrow="false" />
        <ux-cell-item title="源对象" :label="JSON.stringify(sourceObj)" :arrow="false" :border-bottom="false" />
    </ux-cell-group>
    <ux-gap :height="8" />
    <ux-button size="small" type="primary" block text="执行合并" @click="handleMerge()" />
    <template v-if="mergedObj != null">
        <ux-gap :height="8" />
        <ux-cell-group :border="false">
            <ux-cell-item title="合并结果" :label="JSON.stringify(mergedObj)" :arrow="false" :border-bottom="false" />
        </ux-cell-group>
    </template>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';

const targetObj = ref<JsonObject>({
    name: '张三',
    age: 25,
    address: { city: '北京', district: '朝阳区' }
});
const sourceObj = ref<JsonObject>({
    age: 30,
    email: 'zhangsan@example.com',
    address: { city: '上海', street: '南京路' }
});
const mergedObj = ref<JsonObject | null>(null);

function handleMerge(): void {
    mergedObj.value = $u.deepMerge(targetObj.value, sourceObj.value);
}
</script>

Array property merge ​

Both items values are arrays, so the result replaces the whole array with source's [3, 4] instead of merging items.

View source
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item title="目标" :value="JSON.stringify(targetArr)" :arrow="false" />
        <ux-cell-item title="源" :value="JSON.stringify(sourceArr)" :arrow="false" :border-bottom="false" />
    </ux-cell-group>
    <ux-gap :height="8" />
    <ux-button size="small" type="primary" block text="合并数组" @click="handleMergeArray()" />
    <template v-if="mergedArr != null">
        <ux-gap :height="8" />
        <ux-cell-group :border="false">
            <ux-cell-item title="结果" :value="JSON.stringify(mergedArr)" :arrow="false" :border-bottom="false" />
        </ux-cell-group>
    </template>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';

const targetArr = ref<JsonObject>({ items: [1, 2] });
const sourceArr = ref<JsonObject>({ items: [3, 4] });
const mergedArr = ref<JsonObject | null>(null);

function handleMergeArray(): void {
    mergedArr.value = $u.deepMerge(targetArr.value, sourceArr.value);
}
</script>

Deeply nested merge ​

user.profile.settings is merged level by level, keeping theme and adding language.

View source
vue
<template>
    <ux-cell-group :border="false">
        <ux-cell-item title="目标" :label="JSON.stringify(complexTarget)" :arrow="false" />
        <ux-cell-item title="源" :label="JSON.stringify(complexSource)" :arrow="false" :border-bottom="false" />
    </ux-cell-group>
    <ux-gap :height="8" />
    <ux-button size="small" type="primary" block text="嵌套合并" @click="handleComplexMerge()" />
    <template v-if="complexMerged != null">
        <ux-gap :height="8" />
        <ux-cell-group :border="false">
            <ux-cell-item title="结果" :label="JSON.stringify(complexMerged)" :arrow="false" :border-bottom="false" />
        </ux-cell-group>
    </template>
</template>

<script setup lang="ts">
import { $u } from '@/uni_modules/uview-pro-x';

const complexTarget = ref<JsonObject>({
    user: { profile: { name: '张三', settings: { theme: 'light' } } }
});
const complexSource = ref<JsonObject>({
    user: { profile: { settings: { language: 'zh-CN' } } }
});
const complexMerged = ref<JsonObject | null>(null);

function handleComplexMerge(): void {
    complexMerged.value = $u.deepMerge(complexTarget.value, complexSource.value);
}
</script>

API ​

Parameters ​

ParameterDescriptionTypeDefaultVersion
targetTarget object with lower priorityJsonObject--
sourceSource object whose fields override the targetJsonObject--

Returns ​

TypeDescription
JsonObjectA new merged object; the inputs themselves are not modified

Notes ​

  • Only JsonObject values are handled; fields in source override target, and recursion continues only when both sides are plain objects.
  • Arrays are replaced as a whole and are never merged item by item.
  • The top-level object is new, but nested fields not overridden by source still share references with target.
  • Passing null or non-object values is outside the signature contract, so callers must guarantee the input types.