@cainiaofe/cn-address
TypeScript icon, indicating that this package has built-in type declarations

0.4.1 • Public • Published

通用文档

基于 @cainiaofe/cn-ui 版本

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: '', // 填申请并填写
	}}
/>

Readme

Keywords

Package Sidebar

Install

npm i @cainiaofe/cn-address

Weekly Downloads

6

Version

0.4.1

License

MIT

Unpacked Size

5.52 MB

Total Files

166

Last publish

Collaborators

  • hahaiwin
  • gz.sanqi
  • feiyanqiu
  • walker.whq
  • yuqiaoling
  • majiangqi.mjq
  • wulie88
  • vincent.ljq
  • snowden_
  • test_zy
  • leannechen
  • tgshell
  • chenyongqing.cyq
  • fengyue1
  • juntao.wjt
  • hadon
  • lanjian.yj
  • connerliu
  • qianqianyinian
  • zhen.hz
  • mcdyzg
  • zhouhuan
  • ystar
  • cismous
  • wangyuhao.wyh
  • beside4ever
  • joshuasui
  • shdongdongshihao