通用文档

基于 @cainiaofe/cn-ui 版本

• Web 组件研发规约
• 开发环境配置
  • 请确保 git 版本不小于 2.9
• 样式方案
• 地址数据国际化方案
• [代码质量] (https://yuque.antfin-inc.com/c-one/cli/ryyt5x)
• [地址库] （https://address-console.cainiao-inc.com）
• [收费说明] (https://yuque.antfin-inc.com/cndzk/lkbpfo/pgwcvp)
• mtop 接口出入参说明
• 地址组件设计

Getting Started

tnpm i

tnpm start

Running the tests

tnpm run test

组件名称

菜鸟地址选择组件

简介

内部采用地址库标准数据，支持国内外数据和单选多选，支持多种数据源

支持功能

功能支持包括：

• 国家或地区选择
• 默认值设置，设置后默认选中
• 支持受控和非受控两种模式
• 区划选择
• 禁用选择器
• 单选或多选
• 区划层级设置(可对全部或单独某个国家设置国家)
• 快捷操作栏是否开启（仅多选模式），全选、反选、取消
• 指定某个国家区划选择
• 已删除区划数据是否显示
• 标记已删除数据（显示已删除数据时生效）
• 指定某几个国家显示
• 指定某几个国家不显示
• 过滤黑名单区划（非国家级别区划）
• 数据源支持 mtop 地址库数据、自定义接口形式, 接口要求，以及 cdn 形式，需传入 cdn 地址
• 数据版本定制
• 支持菜鸟地址库数据和lazada数据
• 区划数据自动升级
• 支持与 CnFilter 结合使用
• 支持与 Form 结合使用
• 多语言支持，数据多语言及文案
• 支持搜索功能
• 支持预览模式
• 区划排序，默认按字母进行排序。可选值 ID(按 id 排序)和 EN(按 en 或 pinyin 名称排序)
• 选择即生效（单选模式）
• 仅叶子节点可选（多选模式）
• 最多显示多少个 tag（多选模式）
• 支持 useDetailValue 模式
• 支持 useDetailMap 自定义映射
• value 可接收string或者对象类型数据

API

| 属性 | 是否必填 | 默认值 | 说明 | | -------------------- | -------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | value | 否 | [] (单选时为'') | (受控)当前值, 传入最后一级的 regionId。 例如 广东省-广州市-天河区 则传入天河区的 regionId - 440106 | | defaultValue | 否 | [] (单选时为'') | (非受控)默认值 | | onChange | 否 | (value: String/Array, data: Object/Array, extra: Object) => {} | 选中值改变时触发的回调函数 - value 选中的值, 例如 广东省-广州市-天河区对应 regionId - data 选中的数据 - extra 额外参数 | | onVisibleChange | 否 | (visible, type) => {} | 下拉框显示或关闭时触发事件的回调函数 | | multiple | 否 | true | 是否多选 | | disabled | 否 | false | 是否禁用选择器 | | showTopLevel | 否 | false | 是否展示【国家】层级，iso 指定某个国家时生效 | | showSearch | 否 | false | 开启搜索。cdn 模式和 mtop 模式行为不同 | | showFooter | 否 | false | 开启底部快捷操作（全选、反选、清除），仅多选模式下生效 | | dataLanguage | 否 | local | 地址数据国际化, 缺省为 local。可选值为 ISO 码,如 CN、EN,iso 码列表 | | locale | 否 | - | 文案多语言，默认中文。文案内置中、英、日、韩、俄、西班牙、法、葡语言包，也可自行传入。 | | maxLevel | 否 | 4 | 设置显示到几级地址。针对所有国家都生效 | | levelConfig | 否 | - | 只有在多个国家时(iso='')生效，适用于单独设置某个国家区划层级，优先级高于 maxLevel。示例： { CN: 2 }, key 为国家对应 iso | | iso | 否 | CN | 设置某个国家数据（开启所有国家时设置为 ''） iso 码列表 | | maxTagCount | 否 | - | 最多显示多少个 tag, 仅在多选模式下有效 | | maxTagPlaceholder | 否 | - | 隐藏多余 tag 时显示的内容，在 maxTagCount 生效时起作用 | | changeOnSelect | 否 | false | 是否选中即发生改变, 仅在单选模式下有效 | | canOnlyCheckLeaf | 否 | false | 是否仅叶子节点可勾选，仅在多选模式下有效 | | showDisabledDivision | 否 | false | 地址数据库中,是否展示已删除数据 | | markedDeletion | 否 | true | 标记已删除数据，配置已删除数据显示时生效 | | needSkipLevelData | 否 | true | 是否需要跳级数据,例如,maxLevel = 3, showTopLevel = false, 广东省-中山市 广东省-东莞市 下没有区, 直接到街道, 开启 false 就不显示 | | includeList | 否 | [] | 国家列表显示,设置只显示某些国家,ISO 码['CN', 'SG']。只在开启全部国家时生效（iso=''） iso 码列表 | | excludeList | 否 | [] | 国家列表显示,隐藏某些国家, ISO 码['CN', 'SG']。只在开启全部国家时生效（iso=''） iso 码列表 | | blackList | 否 | [] | 过滤某些区划不显示，数组内为区划 id。不包括国家级别，过滤国家请使用 excludeList | | divisionSort | 否 | - | 区划排序，默认按字母进行排序。可选值 ID 和 EN | | readOnly | 否 | - | 预览模式 | | useDetailValue | 否 | false | 将onChange的第一个参数由字符串转化为对象格式，使用方式见示例或参考文章。 0.1.9版本后新增 | | useDetailMap | 否 | - | 将默认 useDetailValue 结构转化为自定义字段。仅 useDetailValue 开启时生效。 | | mtopConfig | 否 | - | 设置 mtop 配置相关，参数见文档, 例如{ subDomain: 'm' } | | config | 是 | configProps | 地址库参数 |

• configProps 地址库参数:

| 字段名 | 是否必填 | 缺省 | 说明 | | --------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | apiModel | 否 | mtop | mtop api cdn, api 需要后端实现 5 个接口,地址数据找客户要或其他渠道,地址库接口要求; mtop 要申请 businessId,mtop 模式下回填数据量受限制,50 条,通过 config.maxLength 控制,回填数据大了会卡死,回填数据大用 cdn 模式; cdn 注意一定要用菜鸟地址库提供的数据(最顶级来源要 实时 从地址库的 cdn 拿,不允许私自存储,可以用自己的 cdn) | | cdnUrl | 否 | | apiModel 为 cdn 模式下的 cdn 地址 当前版本:https://division-data.alicdn.com/simple/addr_mtop_20220401.js 可以自己搞 cdn 数据,但必须实时从该地址获取,确保数据受地址团队控制 | | businessId | 是 | 无 | apiModel 为 mtop 时必填,组件唯一标识。需要向地址库申请的唯一 id，走 mtop 时必填,否则无法正常调用。申请 ID 请钉钉联系@曦辉,或点此申请 | | urlBase | 是 | 无 | apiModel 为 api 时必填,host 地址,如https://oneapi.alibaba-inc.com/mock/CNBP | | applicationType | 否 | query | ---- | | realm | 否 | default | ---- | | apiType | 否 | cndzk | 接口类型- lazada：对应 Lazada 数据接口，https://yuque.antfin-inc.com/docs/share/a2827674-93d3-4250-b6c0-50a907c0a253?#，有问题可联系@曦辉 ，谢谢～- cndzk：对应地址库数据接口，https://yuque.antfin-inc.com/docs/share/f5248ac3-c07a-4c58-8acd-c2e4aaf2c225?# |

• 地址库数据参考

dataLanguage为local时,取值为 names[item.language]
此时item.language = 'CN'
{
  "disable": false,
  "id": "310000",
  "iso": "CN",
  "language": "CN",
  "leaf": false,
  "level": 2,
  "names": {
    "EN": "Shanghai",
    "CN": "上海"
  }
}

用例

<CnAddress
	className='w'
	onChange={(v, data, extra) => {
		console.log(v, data, extra);
	}}
	maxLevel={5}
	iso='CN'
	showTopLevel={true}
	config={{
		businessId: '', // 填申请并填写
	}}
/>