核心目标：实现「源字段」修改后，「目标字段」自动赋值、同步更新，且保证页面正常渲染、数据正常保存，避免出现循环触发、赋值失效等问题。

## 一、前置说明（必看）

### 1. 适用场景

当你需要实现“一个单元格（源字段）修改后，另一个单元格（目标字段）自动填充对应内容”时，使用本文档的方法，例如：

- 修改“姓名”字段，“备注”字段自动填充“姓名+备注后缀”；
- 修改“选择框”字段，“文本框”字段自动填充选择框的对应内容；
- 任何单元格修改后，关联字段自动同步更新。

### 2. 核心原则

- 联动修改必须同时做“两步赋值”：既要更新页面显示（底层表格），也要更新保存的数据（业务层）；
- 必须添加“防循环判断”：只处理“源字段”的修改，避免联动时反复触发修改函数；
- 所有修改仅需在“配置区”操作，核心代码无需改动。

### 3. 必备信息（提前准备）

开发前需获取两个字段的「fieldId」（字段唯一标识，从后台列配置中复制，复制后保存好，后续会用到）：

- 源字段：被修改的字段（触发联动的字段），例如“姓名”字段；
- 目标字段：需要自动同步修改的字段，例如“备注”字段。

示例：fieldId格式（仅供参考）：746177360030318593、1055965933663887361。

### 4. 工具/环境

ecode平台

```javascript
import { regOvProps } from '@weapp/utils';
```

## 二、详细开发步骤

### 步骤1：复制基础模板代码

将以下完整代码复制到你的二开文件中（无需修改任何内容，先复制完整代码）：

```javascript
import { regOvProps } from '@weapp/utils';

// 【核心配置区】仅需修改这里的字段ID，其余代码无需动
const CONFIG = {
  // 触发联动的源字段ID（被修改的字段，从后台复制）
  SOURCE_FIELD: '',
  // 需要被自动赋值的目标字段ID（自动同步的字段，从后台复制）
  TARGET_FIELD: ''
};

regOvProps('weappEbdfpage', 'ExcelList', (props) => {
  // 获取表格数据实例（固定写法，无需修改）
  const getStore = () => window.ebdfListSdk?.getListStore()?.excelListStore;

  // 单元格修改监听函数（核心逻辑，无需修改）
  const handleCellChange = (value, info) => {
    const store = getStore();
    // 解构当前修改的字段、行号、行数据（固定写法）
    const { columnName, rowIndex, rowData } = info;

    // 防循环核心：只处理源字段的修改，目标字段修改时直接跳过
    if (columnName !== CONFIG.SOURCE_FIELD) {
      // 保留原生功能，不影响原有操作（固定写法）
      return props.onCellChange?.(value, info) || value;
    }

    // 业务逻辑：根据源字段的值，构造目标字段的值（可根据需求修改赋值规则）
    const targetValue = {
      dataText: { 
        content: value.content || '',
        richContent: value.content || '' 
      },
      content: value.content || ''
    };

    // 联动赋值：两步都要做，缺一不可（固定写法）
    if (store && rowIndex !== undefined) {
      // 1. 更新页面显示（底层表格，确保页面能看到修改后的值）
      store.refStore.grid.setValue(rowIndex, CONFIG.TARGET_FIELD, targetValue);
      // 2. 更新保存的数据（业务层，确保修改后的数据能正常保存）
      store.onCellChange(targetValue, {
        columnName: CONFIG.TARGET_FIELD,
        rowIndex,
        rowData
      });
    }

    // 保留原生功能，不影响源字段本身的修改（固定写法）
    return props.onCellChange?.(value, info) || value;
  };

  // 覆盖组件原有监听方法，实现联动（固定写法）
  return {
    ...props,
    onCellChange: handleCellChange
  };
},0);
```

### 步骤2：修改配置区（唯一需要手动修改的地方）

找到代码中的「核心配置区」，将你提前准备好的「源字段ID」和「目标字段ID」，填入对应的位置：

```javascript
// 【核心配置区】仅需修改这里的字段ID，其余代码无需动
const CONFIG = {
  // 触发联动的源字段ID（被修改的字段，从后台复制）
  SOURCE_FIELD: '这里填源字段的fieldId', // 示例：'746177360030318593'
  // 需要被自动赋值的目标字段ID（自动同步的字段，从后台复制）
  TARGET_FIELD: '这里填目标字段的fieldId' // 示例：'1055965933663887361'
};
```

示例（修改后）：

```javascript
const CONFIG = {
  SOURCE_FIELD: '746177360030318593', // 源字段：姓名
  TARGET_FIELD: '1055965933663887361' // 目标字段：备注
};
```

### 步骤3：调整目标字段赋值规则（可选，根据需求修改）

代码中「targetValue」是目标字段的赋值内容，默认适配“多行文本+普通文本”类型，若你的目标字段类型不同（如文本框、选择框），需修改「targetValue」的格式，参考下方“值类型速查表”。

示例1：目标字段是普通文本框（只需修改targetValue）：

```javascript
// 普通文本框赋值格式
const targetValue = {
  content: value.content || '' // 直接将源字段的内容赋值给目标字段
};
```

示例2：目标字段是选择框（只需修改targetValue）：

```javascript
// 选择框赋值格式（需替换optionId和content为实际选项值）
const targetValue = {
  dataOptions: [{ optionId: 1, content: value.content }]
};
```

## 三、值类型速查表（必看，适配不同字段）

不同类型的字段，「targetValue」的格式不同，直接对照表格复制修改即可，无需理解原理：

| **目标字段类型** | **targetValue赋值格式（直接复制使用）** | **说明** |
| --- | --- | --- |
| 普通文本框、数值框 | { content: '具体内容' } | 示例：{ content: value.content }（同步源字段内容） |
| 多行文本框 | { dataText: { content: '具体内容', richContent: '具体内容' }, content: '具体内容' } | 模板默认格式，content和richContent保持一致即可 |
| 下拉选择框 | { dataOptions: \[{ optionId: 选项ID, content: '选项内容' }\] } | optionId和content需从后台选项配置中获取 |
| 日期区间 | \[{ content: '开始日期', formField: { id: '开始字段ID' } }, { content: '结束日期', formField: { id: '结束字段ID' } }\] | 需替换“开始/结束字段ID”为实际字段的fieldId |
| 地理位置 | { content: '地址文本', formField: { id: '字段ID' }, latitude: '纬度', longitude: '经度' } | 纬度、经度可根据需求填写，或从源字段获取 |

## 四、常见问题及解决方法（基础开发者必看）

开发中遇到问题，直接对照以下场景查找解决方法，无需排查复杂代码：

### 问题1：修改源字段后，目标字段不显示修改内容（赋值失效）

- 原因1：字段ID填错（最常见）→ 解决：重新核对CONFIG中的SOURCE\_FIELD和TARGET\_FIELD，确保和后台的fieldId完全一致（区分大小写，不能多空格）；
- 原因2：只做了一步赋值→ 解决：确保代码中同时有“store.refStore.grid.setValue”和“store.onCellChange”两行代码，缺一不可；
- 原因3：targetValue格式错误→ 解决：对照“值类型速查表”，确认格式和目标字段类型匹配。

### 问题2：修改后页面卡顿、无限循环（反复触发修改）

- 原因：没有防循环判断，或判断条件错误→ 解决：检查代码中是否有“if (columnName !== CONFIG.SOURCE\_FIELD)”这行代码，确保没有修改这行逻辑。

### 问题3：修改后能看到内容，但保存后数据丢失

- 原因：只更新了页面渲染，没有更新业务数据→ 解决：确保执行了“store.onCellChange”这行代码，且参数中的columnName、rowIndex正确。

## 五、注意事项（必看）

- 字段ID必须从后台列配置中复制，不能手动输入（容易输错）；
- 测试时，先修改源字段，观察目标字段是否同步更新，再保存数据，确认数据没有丢失；
- 若需要多个字段联动（一个源字段联动多个目标字段），可在handleCellChange中添加多个targetValue和赋值逻辑（参考步骤3）；
- 如果目标字段是“日期区间、地理位置”等特殊类型，严格对照“值类型速查表”修改格式，否则会赋值失败。
- 随着开发迭代，值结构可能出现变化。可以先自行修改目标字段，看下保存接口中的值的结构。
