用于字段映射和数据转换，支持数组/对象映射、函数处理、默认值、动态 key 等。

安装

npm install @yuliqi/node-red-contrib-qmapping

🧩 mapping 配置说明文档

🎯 作用

用于把原始数据转换为目标结构，支持字段提取、函数处理、默认值、数组/对象映射、忽略特定值等。

🧱 基本写法

const mapping = {
  key1: 'a.b.c',                    // 等价于 { path: 'a.b.c' }
  key2: {
    path: 'x.y',
    func: 'v => v.trim()',
    default: '未知',
    omitValues: [null, ''],
    fallbackToPathString: true
  }
}

🔁 数组映射

const mapping = {
  list: {
    path: 'data.items[]',
    mapping: {
      id: 'id',
      name: {
        path: 'info.name',
        func: 'v => v.toUpperCase()'
      }
    }
  }
}

🔗 对象嵌套映射

const mapping = {
  user: {
    path: 'userInfo',
    mapping: {
      name: 'name',
      age: {
        path: 'details.age',
        default: 0
      }
    }
  }
}

💡 特殊写法：_ 占位符

用于动态 key 的场景，例如字段名未知，但值结构确定：

const mapping = {
  "_": {
    path: "userList",
    mapping: {
      _: {
        path: "*",  // 表示遍历对象的每个 key
        mapping: {
          name: "name",
          age: "age"
        }
      }
    }
  }
}

也支持单个对象中仅保留特定字段：

const mapping = {
  "_": {
    ke: "value"
  }
}
// 等价于从整个对象中提取 key 为 "ke"，值为 "value"

⚙️ 配置字段说明

| 字段名 | 类型 | 说明 | | ---------------------- | ------------ | -------------------------------- | | path | string | 数据路径，如 a.b.c，数组用 path[] 表示 | | func | string 或数组 | 对取到的值进行处理，支持 async | | default | any | 当取值为空时，使用默认值 | | omitValues | any[] | 如果值等于这些内容，将被忽略 | | fallbackToPathString | boolean | 如果找不到 path，用 path 自身作为值（可用于常量注入） | | "_" | object | 特殊字段，用于动态 key 或保留 key-value 结构 |

🧪 输入输出示例

输入：

{
  "data": {
    "users": {
      "u1": { "name": "Tom" },
      "u2": { "name": "Jerry" }
    }
  }
}

mapping：

{
  users: {
    path: 'data.users',
    mapping: {
      _: {
        path: '*',
        mapping: {
          name: 'name'
        }
      }
    }
  }
}

输出：

{
  "users": {
    "u1": { "name": "Tom" },
    "u2": { "name": "Jerry" }
  }
}