一、 功能概述

1.1 功能简介

动态地址字段是一种地址录入组件，可根据用户选择的国家或地区，自动匹配对应的地址格式规则，动态调整地址字段的显示顺序、字段名称、必填属性等，使多国地址录入符合当地习惯和合规要求。

1.2 使用场景

• 销售人员，在录入美国客户地址时，只需选择"美国"，系统自动将"省"切换为"州（State）"，并调整字段顺序为"街道→城市→州→邮编"，避免因不熟悉美国地址格式而录入错误。
• 物流人员，在处理欧盟订单时，需要地址符合欧盟海关清关标准（国家代码+邮编+完整街道信息），动态地址字段自动按德国格式显示"街道→门牌号→邮编→城市"，确保包裹顺利清关。
• 跨国企业管理人员，在新加坡使用系统时，由于新加坡是城邦国家没有"省/州"概念，动态地址字段自动隐藏省级字段，不再强制填写"无"，大幅提升填写体验。

二、操作指南

2.1 功能入口

入口：管理后台 → 对象管理 → 选择业务对象 → 【新建字段】→ 字段类型选择【动态地址】

2.2 新建动态地址字段

2.2.1 动态地址包含的子字段

动态地址字段是一个字段组，包含以下16个子字段：

2.2.2 特殊说明

• 每个对象只能创建一个动态地址类型字段（含已禁用字段）
• 字段组中所有子字段，不支持单独在字段配置中禁用
• 每个子字段可单独配置字段名称、API Name、安全等级、提示信息等

2.3 地区定位字段升级为动态地址字段

如果原有业务对象上已有【地区定位】类型的预置字段，可直接升级为动态地址字段。

2.3.1 操作步骤

1. 进入【字段管理】页面，找到需要升级的地区定位字段
2. 点击编辑，在编辑页面右上角找到 【动态地址】开关
3. 点击开关，系统弹出二次确认提示：

   开启后默认将此字段刷为【动态地址】类型字段，可根据所选国家/地区动态显示地址相关字段。
   此操作不能撤回，请谨慎操作！

4. 确认无误后，点击【确定】完成升级

2.3.2 升级前置校验

点击升级时，系统会自动检测以下条件：

• 如果有按钮将该字段作为入参字段，不允许升级，提示请先删除按钮中的配置
• 如果有布局规则将该字段作为控制字段，不允许升级，提示请先调整布局规则

2.3.3 升级后的影响

• 原字段的字段名、字段值会保持不变
• 原字段配置的默认值、提示信息等属性保持不变
• 字段类型变更为"动态地址"，新增了地区定位中没有的字段（如街道、门牌号、格式化地址等）
• 原来基于国家省市区等字段配置的布局规则、UI事件、插件继续正常生效
• 客户对象上的预置字段【手机归属地】字段，不支持此开关
• 若升级的字段关联了客户对象，需同步升级相关对象上的对应字段

2.4 前端使用指南

2.4.1 新建/编辑数据时的地址录入

1. 打开数据的新建或编辑页面
2. 动态地址字段默认显示 "国家/地区" 和 "地址格式" 两个字段在第一行
3. 选择国家/地区后，系统自动匹配该国家下的地址格式规则：
   • 动态调整字段显示顺序和显示名称
   • 例如：选择"美国"时，"省"自动变为"州（State）"，按美国格式排列字段
   • 若该国家有多套地址格式，默认选中设为默认格式的那套，用户可切换
4. 按规则提示填写各地址字段
5. 保存数据时，系统自动按文本拼接格式规则生成【格式化地址】字段内容

2.4.2 初始状态的默认展示

当国家/地区字段为空时（新建页初始状态），系统按以下优先级匹配地址格式：

1. 第一优先：当前登录人的个人设置 → 多区域配置 → 对应国家地区的地址格式
2. 第二优先：个人设置为空时 → 企业默认区域 → 对应国家地区的地址格式
3. 兜底逻辑：以上都找不到时 → 按预置的国际标准地址格式展示

匹配到多套地址格式时，展示其中的默认格式。

2.4.3 详情页展示

• 动态地址字段有值：按数据中存储的国家对应的地址格式及显示名称展示（如：编辑时选的是美国，详情页就按美国格式展示省、市、街道等）
• 动态地址字段无值：按当前登录人个人区域 → 企业默认区域对应的地址格式展示，个人设置优先

2.4.4 列表页展示

每个子字段（国家/地区、省、市、详细地址等）独立展示在列表页的各列中，可按列筛选和排序。

2.5 注意事项

1. 必须配置地址格式规则：动态地址字段须与【地址格式】管理后台配合使用，如果未配置对应国家的地址格式规则，前端会提示"当前国家或地区没有可用的地址格式，请联系管理员增加地址格式后再试"
2. 不要混用两种组件：动态地址组件与原有的地区定位组件是两套独立组件。国内业务不需要复杂地址格式的场景，可继续使用地区定位组件
3. 导入导出：支持新建导入、更新导入、导出；导入时不校验地址格式规则中的必填等属性
4. OpenAPI和函数创建：通过API或函数创建数据时，不校验地址格式中的字段显隐和必填逻辑
5. 按钮入参：按钮入参弹框中，动态地址字段以字段组形式展示，组内每个字段以一列显示，只能以组为单位设置必填属性
6. 地址格式变更不影响历史数据：管理员编辑地址格式规则后，只对新数据生效，历史数据保留原值不变

三、常见问题

1：动态地址组件和原来的地区定位组件有什么区别？应该用哪个？
地区定位组件适用于没有国际业务的企业或业务模块（只需简单选国家省市区）。动态地址组件适用于有国际业务的企业（需要按不同国家显示不同地址格式）。两种组件可共存于同一系统，按需选用。

2：为什么我选择了某个国家，但动态地址组件没有按预期显示字段？
请检查管理后台是否已为该国配置了地址格式规则，查看该国是否有已启用的地址格式。

3：能否在一个对象上创建多个动态地址字段？
不能。每个对象最多创建一个动态地址类型字段（含已禁用字段）。如需多个地址字段（如收货地址和开票地址），可提特殊申请。

4：升级为动态地址字段后能撤回吗？
不能。升级操作不可撤回，请在升级前确认业务需求。升级后原字段名称和已录入数据不受影响。

5：格式化地址字段的内容是如何生成的？
格式化地址是在保存数据时，根据地址格式规则中的"文本拼接格式"配置自动生成的，包含字段的前缀、后缀、分隔符等拼接规则。该字段不在新建/编辑页中直接显示和编辑。