# OcAddress

@alicd/oc-address

地址选择组件，支持单选和多选。 无线暂时只支持单选

fork from @alicd/crui-address, 修正按需打包，对一码多端支持

### 规则
* 地址选择的数据源可以被替换，如果发现数据不符合你的诉求，请参考 API 进行替换

## API

### Address

|   属性   | 说明 | 类型 | 默认值 |
| ----- | ----- | ----- | ----- |
| value | 当前组件中的地址值，以 JSON 对象的形式表示，其中包含 `country`，`province`，`city`，`area`，`town` 等字段 | `object` | N/A |
| onChange | 用户的选择、清空等交互使地址值变化时所调用的函数<br>_参数_:<br>_value_: `object` 改变后的地址值，可直接设置到 `value` 属性上<br>_nodeChain_: `[object]` 该 `value` 值对应的地址详细信息，可用来取地名等 | `(value: object, nodeChain: [object], nodeChain: [object]) => void` | N/A |
| defaultValue | 默认选择的地址值，以 JSON 对象的形式表示 | `object`  | `{ "country": "1" }` (默认选择中国) |
| className | 自定义类名 | `string` | N/A |
| style | 自定义组件内联样式 | `object` | N/A |
| size | 选择框大小 | `"small"` 或 `"medium"` 或 `"large"` | `"medium"` |
| overseas | 是否显示国家选择列表 | `boolean` | `false` |
| level | 选择到几级地址，1 为只选择省，4 为从省到街道全部选择（国家选择请使用 `overseas` 属性） | `number` | `4` (省、市、区、街道四级全部启用) |
| hasClear | 是否显示清空按钮（包含国家和地区选择框上的清空“X”，以及选择器弹层上的“清空”按钮） | `boolean` | `false` |
| addressSelectPlaceholder | 地址选择框没有值时显示的内容 | `string` | `请选择地址` |
| countrySelectPlaceholder | 国家选择框没有值时显示的内容 | `string` | `请选择国家` |
| disabled | 是否禁止用户编辑地址 | `boolean` | `false` |
| provincePartition |是否对中国的省级行政区细分以方便用户定位特定省。设置为 `"letter"` 则会以拼音首字母 `"A–G"`, `"H–K"`, `"L–S"`, `"T–Z"` 划分。|`"letter"`|N/A|,
| showSearch |是否在省市区选择框中启用搜索，搜索仅限省市区三级地址数据|`boolean`|`false`|,
| readOnly | 是否禁止用户编辑地址，该属性为 `disabled` 属性的别名 | `boolean` | `false` |
| fixedWidth | 是否固定选择器弹层的宽度 | `boolean` | `true` |
| animation | 是否启用组件的动效 | `boolean` | `true` |
| container | 指定渲染地址选择弹层的容器，一般不需要设置该属性 | any | 默认为地址组件本身 |
| popupProps | 地址选择弹层的属性，参见 SelectField 组件 | `object` | N/A |
| popupClassName | 地址选择弹层的类名 | `string` | N/A |
| countryPopupProps | 国家选择弹层的属性，参见 SelectField 组件 | `object` | N/A |
| countryPopupClassName | 国家选择弹层的类名 | `string` | N/A |
| requestAddressUrl | 国家、省、市、区四级数据的接口地址，默认拉取最新数据 | `string` | `"//division-data.alicdn.com/simple/addr_4_1111_1_0.js"` |
| requestTownUrl | 用于街道一级数据的接口地址 | `string` | `"//lsp.wuliu.taobao.com/locationservice/addr/output_address_town.do"` |
| requestAddressLevelUrl | 用于街道一级数据的接口地址 | `string` | `"//lsp.wuliu.taobao.com/locationservice/addr/outputParentDivisons.do"` |
| hasToSelectToLastLevel | 用户必须选择到指定的层级，如果为 `true`，则使用 `level` 所指定的最后一层，如果为数字则使用相应数字的层级 | `boolean` 或 `number` | `false` |
| partialSelectionOverlayClosable | 如果启用了 `hasToSelectToLastLevel`，在尚未选择到指定的层级时，是否允许关闭选择弹层（如果为 `true` 则会关闭弹层，当前弹层内的选择状态由于不满足 `hasToSelectToLastLevel` 的条件会丢失） | `boolean` | `true` |
| hiddenData |数据中不做展示的地址 ID 数组，用于去除部分数据。**注意不要将该属性误写为 "hidden"，"hidden" 属性将会将组件隐藏**|`string[]`|`[]`|
| ignored |数据中忽略的地址 ID 数组，用于去除部分数据。注意 `hiddenData` 与本属性的区别，`ignored` 会将地址节点从数据中彻底剔除（用户无法选择，且使用被忽略掉的地址进行 setValue() 不被识别），`hiddenData` 仅仅在展示时隐藏地址节点（用户无法选择），且 `ignored`、`dataOverride`、`preprocessor` 等属性仅在地址数据加载时有效，之后对这些属性的更新均无效。一般推荐使用 `hiddenData` 属性|`string[]`|`[]`|
| dataOverride |需要临时复写、增加新的地址数据时使用|`{ [addressID: number]: string[] }`||`{}`|
| preprocessor |需要对地址数据定制更细致的预处理工作时使用的回调接口，一般优先使用 `hiddenData`, `ignored`, `dataOverride` 等属性，需求无法满足时再考虑使用本属性|`(dataRaw: { [addressID: number]: string[] }) => { [addressID: number]: string[] }`|默认直接返回第一个参数（不进行任何操作）|

### Address.Multi

|   属性   | 说明 | 类型 | 默认值 |
| ----- | ----- | ----- | ----- |
| value | 当前组件中的地址值，以 JSON 对象的数组的形式表示，每一个元素包含 `country`，`province`，`city`，`area`，`town` 等字段 | `object[]` | N/A |
| onChange | 用户的选择等交互使地址值变化时所调用的函数<br>_参数_:<br>_value_: `object` 改变后的地址数组，可直接设置到 `value` 属性上<br>_nodes_: `object[]` 该 `value` 各值对应的地址详细信息，可用来取地名等 | `(value: object[], nodes: object[]) => void` | N/A |
| root | 多选框选择弹层的根地址节点，用于指定地址选择的区域，地址组件只能选择区域内的地址 | `object` | `{ "country": 1 }`（默认选择国内地址） |
| className | 自定义类名 | `string` | N/A |
| style | 自定义组件内联样式 | `object` | N/A |
| level | 选择到几级地址，1 为只选择省，4 为从省到街道全部选择（国家选择请使用 `root` 属性控制） | `number` | `4` (省、市、区、街道四级全部启用) |
| placeholder | 选择框占位符 | `string` | N/A |
| disabled | 是否禁止用户编辑地址 | `boolean` | `false` |
| container | 指定渲染地址选择弹层的容器，一般不需要设置该属性 | any | 默认为地址组件本身 |
| popupProps | 弹层的属性，参见 SelectField 组件 | `object` | N/A |
| popupClassName | 弹层的类名 | `string` | N/A |
| requestAddressUrl | 国家、省、市、区四级数据的接口地址，默认拉取最新数据 | `string` | `"//division-data.alicdn.com/simple/addr_4_1111_1_0.js"` |
| requestTownUrl | 用于街道一级数据的接口地址 | `string` | `"//lsp.wuliu.taobao.com/locationservice/addr/output_address_town.do"` |
| requestAddressLevelUrl | 用于街道一级数据的接口地址 | `string` | `"//lsp.wuliu.taobao.com/locationservice/addr/outputParentDivisons.do"` |
| hiddenData |数据中不做展示的地址 ID 数组，用于去除部分数据。**注意不要将该属性误写为 "hidden"，"hidden" 属性将会将组件隐藏**|`string[]`|`[]`|
| ignored |数据中忽略的地址 ID 数组，用于去除部分数据。注意 `hiddenData` 与本属性的区别，`ignored` 会将地址节点从数据中彻底剔除（用户无法选择，且使用被忽略掉的地址进行 setValue() 不被识别），`hiddenData` 仅仅在展示时隐藏地址节点（用户无法选择），且 `ignored`、`dataOverride`、`preprocessor` 等属性仅在地址数据加载时有效，之后对这些属性的更新均无效。一般推荐使用 `hiddenData` 属性|`string[]`|`[]`|
| dataOverride |需要临时复写、增加新的地址数据时使用|`{ [addressID: number]: string[] }`||`{}`|
| preprocessor |需要对地址数据定制更细致的预处理工作时使用的回调接口，一般优先使用 `hiddenData`, `ignored`, `dataOverride` 等属性，需求无法满足时再考虑使用本属性|`(dataRaw: { [addressID: number]: string[] }) => { [addressID: number]: string[] }`|默认直接返回第一个参数（不进行任何操作）|