cn-address-select-pro
v0.1.6
Published
地址选择器
Readme
说明
地址选择组件
使用
引入
import AddressSelect from 'cn-address-select-pro';使用
<AddressSelect
config={{
apiModel: 'api',
urlBase: 'your urlBase', // 必填，对应接口域名
}}
/>API
| 属性 | 是否必填 | 默认值 | 说明 |
| -------------------- | -------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| value | 否 | [] (单选时为'') | (受控)当前值, 传入最后一级的 regionId, 例如 广东省-广州市-天河区 则传入天河区的 regionId |
| defaultValue | 否 | [] (单选时为'') | (非受控)默认值 |
| onChange | 否 | (value, data, extra) => {} | 传入 onChange 成为受控组件, 透出的 value: string[] regionId[](单选时为 regionId: string), 最下级的 regionId, 例如 广东省-广州市-天河区 则透出天河区的 regionId |
| useDetailValue | 否 | false | 把 value onChange 第一个参数从字符串变成对象，具体格式如下 |
| onVisibleChange | 否 | (visible, type) => {} | 下拉框显示或关闭时触发事件的回调函数 |
| multiple | 否 | true | |
| disabled | 否 | false | 是否禁用选择器 |
| showTopLevel | 否 | false | 是否展示【国家】层级 |
| showSearch | 否 | false | 开启搜索,cdn 模式和 mtop 模式行为不同,api 模式暂不支持 |
| showFooter | 否 | false | 开启底部快捷操作（全选、反选、清除），仅多选模式下生效 |
| dataLanguage | 否 | local | 地址数据国际化, 缺省为 local。可选值为 ISO 码,如 CN、EN |
| locale | 否 | - | 文案多语言，默认中文。文案内置中、英、日、韩、俄语言包，也可自行传入。 |
| maxLevel | 否 | 4 | 显示到几级地址,针对所有国家都生效 |
| levelConfig | 否 | - | 只有在多个国家时(iso='')生效，适用于单独设置某个国家区划层级，优先级高于 maxLevel。示例： { CN: 2 }, key 为国家对应 iso |
| iso | 否 | CN | (填''或其他空值)且(showTopLevel=true)时,可选择国家 |
| maxTagCount | 否 | - | 最多显示多少个 tag, 仅在多选模式下有效 |
| maxTagPlaceholder | 否 | - | 隐藏多余 tag 时显示的内容，在 maxTagCount 生效时起作用 |
| changeOnSelect | 否 | false | 是否选中即发生改变, 仅在单选模式下有效 |
| canOnlyCheckLeaf | 否 | false | 是否仅叶子节点可勾选，仅在多选模式下有效 |
| showDisabledDivision | 否 | false | 地址数据库中,是否展示已删除数据 |
| markedDeletion | 否 | true | 标记已删除数据，配置已删除数据显示时生效, 如果传入了 itemRender 需要自己处理, 不开启 showDisabledDivision 也不会有这个 |
| needSkipLevelData | 否 | true | 是否需要跳级数据,例如,maxLevel = 3, showTopLevel = false, 广东省-中山市 广东省-东莞市 下没有区, 直接到街道, 开启 false 就不显示 |
| includeList | 否 | [] | 国家列表显示,只显示某些国家,ISO 码['CN', 'SG'] |
| excludeList | 否 | [] | 国家列表显示,隐藏某些国家, ISO 码['CN', 'SG'] |
| blackList | 否 | [] | 过滤某些区划不显示，数组内为区划 id。不包括国家级别，过滤国家请使用 excludeList |
| divisionSort | 否 | - | 区划排序，默认按字母进行排序。可选值 ID 和 EN |
| readOnly | 否 | - | 预览模式 |
| config | 是 | configProps | 地址库参数 |
config 相关配置
| 属性 | 是否必填 | 默认值 | 说明 |
| -------- | -------- | ------ | -------------------------------------------------------------------------------------------------- |
| apiModel | 否 | mtop | 可选值，"api","cdn" |
| cdnUrl | 是 | 无 | apiModel 为 cdn 模式下的 cdn 地址 当前版本:https://division-data.alicdn.com/simple/addr_1_4_all.js |
| urlBase | 否 | 无 | apiModel 为 api 时必填, host 地址,如https://oneapi.alibaba-inc.com/mock/CNBP |
| params | 否 | 无 | api 模式，请求时携带参数，例如 { version: '18Q4' } |
useDetailValue 开启时数据格式
{
countryCode: null,
countryName: null,
provinceCode: null,
provinceName: null,
cityCode: null,
cityName: null,
countyCode: null,
countyName: null,
streetCode: null,
streetName: null,
}本地调试指南（npm link）
当你需要在另一个工程中调试本库的源码时，可以通过 npm link 将本地代码链接到目标工程。
前置条件
- 本项目已安装依赖（
npm install） - 目标工程已安装依赖
步骤 1：构建本项目
cd /path/to/cn-address-select-pro
npm run build构建后产物会输出到 packages/lib 目录，同时 package.json 和 README.md 会被拷贝到 packages 目录。
步骤 2：在 packages 目录创建全局 link
cd packages
npm link注意：
npm link必须在包含package.json的packages目录下执行，而不是项目根目录。
步骤 3：在目标工程中链接
cd /path/to/your-project
npm link cn-address-select-pro步骤 4：验证 link 是否成功
ls -la node_modules/cn-address-select-pro如果输出类似以下内容（软链接指向 packages 目录），说明 link 成功：
lrwxr-xr-x 1 user staff 53 Apr 14 16:35 node_modules/cn-address-select-pro -> ../../../address-debug/cn-address-select-pro/packages日常调试流程
每次修改源码后，需要重新构建才能让目标工程生效：
# 1. 在本项目根目录重新构建
cd /path/to/cn-address-select-pro
npm run build
# 2. 在目标工程中清除缓存并重启开发服务器
cd /path/to/your-project
rm -rf node_modules/.vite # Vite 项目需要清除预构建缓存
npm run dev # 重启开发服务器重要：Vite 等构建工具会缓存依赖的预构建结果（
node_modules/.vite），即使 link 的包内容更新了，缓存可能还是旧的。每次重新 build 后务必清除缓存再重启。
解除 link
调试完成后，解除 link 恢复到 npm 包：
# 1. 在目标工程中解除链接
cd /path/to/your-project
npm unlink cn-address-select-pro
# 2. 重新安装依赖（恢复为 npm 上的版本）
npm install
# 3.（可选）移除全局 link
cd /path/to/cn-address-select-pro/packages
npm unlink查看当前全局 link 列表
npm ls -g --depth=0 --link=true常见问题
| 问题 | 解决方案 |
|------|---------|
| 修改代码后目标工程没有生效 | 重新 npm run build，然后清除目标工程缓存 rm -rf node_modules/.vite 并重启 |
| npm link 后 node_modules 中没有出现软链接 | 确认是在 packages 目录下执行的 npm link，而不是项目根目录 |
| 目标工程报模块找不到 | 检查 packages/package.json 中的 main 和 module 字段路径是否正确 |