应用工程配置

manifest.json文件内配置如下

  "location": {
    "background": {
      "paths": ["/butler/sidebar"],
      "feature": ["app.production.procedureJobBooking"],
    }
  }

APP ↔ H5 数据传输协议（扩展字段联动）

本文档描述 APP 与 H5 之间围绕“扩展字段（extend field）联动控制”的数据传输 JSON 结构与字段含义。

1. APP → H5（事件：onExtendFieldValueChanged）

APP 会通过事件 onExtendFieldValueChanged 向 H5 推送当前页面数据与扩展字段列表。

1.1 JSON 结构

{
  "fieldList": [],
  "jbkQuantity": 0,
  "jbkUnQuantity": 0,
  "totalJbkQty": 0,
  "selfInspect": false
}

1.1.1 fieldList 单项结构（ExtendField.toH5Param）

fieldList 中每一个元素为扩展字段对象，来自 APP 侧 toH5Param()：

{
  "fieldId": 0,
  "fieldType": 1,
  "fieldName": "字段名",
  "required": 0,
  "selectValue": [
    {
      "id": 0,
      "value": "11",
      "fieldId": 0,
      "isDeleted": 0
    }
  ],
  "date": 0,
  "value": "文本值",
  "valueId": 0,
  "currentChangeField": false,
  "editEnable": true,
  "hasValue": false
}

字段说明（对应 APP 侧数据结构）：

字段名	类型	说明
fieldId	number	字段 ID
fieldType	number	字段类型：1 文本、2 下拉框、3 时间
fieldName	string	字段名称
required	number	是否必填：通常 1/0（H5 侧也可能用 true/false 控制更新）
selectValue	Array	下拉框选项列表（仅 `fieldType=2` 有意义），每项为 `{id,value,fieldId,isDeleted}`
date	number \| null	时间戳（毫秒），仅 `fieldType=3` 有意义；未赋值时可能为 null
value	string \| null	文本值，仅 `fieldType=1` 有意义；下拉框/时间类型通常不使用该字段赋值
valueId	number \| null	下拉框当前选中的选项 id，仅 `fieldType=2` 有意义
currentChangeField	boolean	本次变更是否由该字段触发（用于联动：仅在 true 时处理“当前字段变更”逻辑）
editEnable	boolean	是否允许编辑
hasValue	boolean	是否有值（用于校验）；规则：`fieldType=2` 看 `valueId!=null`，否则看 `value` 是否非空

1.2 字段说明

字段名	类型	说明
fieldList	Array	扩展字段列表（`fieldList.map((e) => e.toH5Param())` 的结果）
jbkQuantity	number	报工数（或合格报工数，取决于业务场景）
jbkUnQuantity	number	不合格报工数
totalJbkQty	number	累计报工数
selfInspect	boolean	是否自检

2. H5 → APP（trigger：update）

H5 通过 client.trigger("update", data) 将数据回传给 APP，以驱动页面联动更新。

2.1 Data JSON 结构

{
  "jbkQty": 800, // 报工数 或 合格报工数
  "jbkUnQuantity": 100,  // 开启自检场景 不合格数 ，不支持SN场景
  "updateExtendFieldList": [
    {
      "fieldId": 1100,
      "required": true,  // 设置为必填  可选
      "date": 1776162289833,  // 日期类型 赋值到此date值
      "value": "dynamic Value",  // 文本类型 赋值到此value值
      "valueId": 12,  // 下拉框类型 赋值到此valueId值  selectValue里的选项id
      "editEnable": true,  // 是否允许编辑  可选
    }
  ]
}

2.2 字段说明

字段名	类型	说明
jbkQty	number	报工数（或合格报工数）
jbkUnQuantity	number	不合格报工数
updateExtendFieldList	Array	只需要回传“需要变动值”的自定义字段列表即可

updateExtendFieldList 中每一项表示一个自定义字段的控制更新：

字段名	类型	说明
fieldId	number	字段 ID（必填）
required	boolean \| number	是否必填（true/false 或 1/0，按端侧兼容）
editEnable	boolean	是否允许编辑
date	number	时间戳（仅时间类型字段使用）
value	string \| number	文本值（仅文本类型字段使用）
valueId	number	选项 ID（仅下拉框类型字段使用）

3. 扩展字段类型（fieldType）

扩展字段通过 fieldType 标识字段类型：

fieldType	类型	赋值字段
1	文本	`value = "xxx"`
2	下拉框	`valueId = optionId`
3	时间	`date = timestamp`

3.1 下拉框类型如何赋值（fieldType = 2）

下拉框字段不能直接写 value="33"，应写入对应选项的 id：

valueId = 取 testField.selectValue 里 value 为 "xx" 的那条的 id

示例（设置下拉框字段为“33”）：

{
  "updateExtendFieldList": [
    {
      "fieldId": 10005380,
      "valueId": 10004672
    }
  ]
}

3.2 时间类型如何赋值（fieldType = 3）

时间字段用 date 传时间戳（毫秒）：

{
  "jbkQty": 22,
  "updateExtendFieldList": [
    {
      "fieldId": 10005381,
      "required": true,  // 设置为必填  可选
      "date": 1776700800000
    }
  ]
}

3.3 文本类型如何赋值（fieldType = 1）

文本字段用 value 传文本内容：

{
  "updateExtendFieldList": [
    {
      "fieldId": 10005438,
      "required": true,  // 设置为必填  可选
      "editEnable": false,  // 是否允许编辑  可选
      "value": "2026-04-30"
    }
  ]
}

###4 Background 应用Example 示例代码

APP 报工页自定义字段支持SideBar说明

应用工程配置#

APP ↔ H5 数据传输协议（扩展字段联动）#

1. APP → H5（事件：onExtendFieldValueChanged）#

1.1 JSON 结构#

1.1.1 fieldList 单项结构（ExtendField.toH5Param）#

1.2 字段说明#

2. H5 → APP（trigger：update）#

2.1 Data JSON 结构#

2.2 字段说明#

3. 扩展字段类型（fieldType）#

3.1 下拉框类型如何赋值（fieldType = 2）#

3.2 时间类型如何赋值（fieldType = 3）#

3.3 文本类型如何赋值（fieldType = 1）#