# ngx-address **Repository Path**: mirrors_cipchk/ngx-address ## Basic Information - **Project Name**: ngx-address - **Description**: A simple address picker in angular. - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2020-08-08 - **Last Updated**: 2026-05-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ngx-address A simple address picker in angular. [![NPM version](https://img.shields.io/npm/v/ngx-address.svg)](https://www.npmjs.com/package/ngx-address) [![Build Status](https://travis-ci.org/cipchk/ngx-address.svg?branch=master)](https://travis-ci.org/cipchk/ngx-address) - [Usage](#usage) - [DEMO](#demo) - [API](#api) - [ngx-address](#ngx-address) - [[options]](#options) - [[values]](#values) - [(onSelected)](#onselected) - [Options Interface](#options-interface) - [Result Interface](#result-interface) - [Address Library](#address-library) - [List](#list) - [User Defined](#user-defined) - [NOTE](#note) - [Troubleshooting](#troubleshooting) ## Usage Install `ngx-address` from `npm` ``` npm install ngx-address --save ``` Import the `NgxAddressModule` in to your root `AppModule`. ``` import { NgxAddressModule } from 'ngx-address'; @NgModule({ imports: [BrowserModule, NgxAddressModule ], declarations: [AppComponent], bootstrap: [AppComponent] }) export class AppModule { } ``` ``` import { AddressDataChinaService } from 'ngx-address/data/china'; @Component({ selector: 'demo', template: ` ` }) export class DemoComponent implements OnInit { public id: any; public opt: any; constructor(private china: AddressDataChinaService) { this.opt = { jumps: this.china.getJumps(), data: this.china.getData.bind(this.china) }; } } ``` ## DEMO [Live Demo](https://cipchk.github.io/ngx-address/) ## API ``` ``` ### [options] 参数配置项，参数的变更（指整个 `options` 对象变更而非对象下某个属性）会使组件重新初始化，见[Options](#options-interface)。 ### [values] 设置默认地址值，传递值可是**字符串编号**或与 _options.types.length_ 等同数量的**字符串数组**。默认 ngx-address 实现了一套以国家标准地址区域代码信息规则。 _标准市县区规则_ 310105：表示【上海-长宁】，最终会解析成：[ '310000', '310100', '310105' ] _标准市县区街道规则_ 310105001：表示【上海-长宁-某街道】，最终会解析成：[ '310000', '310100', '310105', '310105001' ] 如果你使用的 `id` 编号是以上两种规则之一的话，那么 `(values)` 完全可以**忽略**，因为 `[(ngModel)]` 本身是双向绑定，ngx-address 会自动根据外部变化重新选择，更多体验见[Live Demo](https://cipchk.github.io/ngx-address/)。 ### (onSelected) 每一次选择会触一次，接收一个 `Result` 参数，见[Result](#result-interface)。由于默认ngx-adress组件并不包括地址数据，所以需要定义 `options`，可以自定义获取或使用[内置的地址库](#address-library)。 ``` let types = ['区域', '公司', '部门']; this.custom = { id: '', result: {}, options: { placeholder: '请选择区域、公司、部门', types: types, http: (index: number, id: string) => { return new Observable(observer => { if (customData.findIndex(w => w.index === index) === -1) { customData.push(...Array.from({ length: Math.floor(Math.random() * 10) + 1 }).map((item, idx) => { return { index: index, id: (index + 1) + idx, name: types[index] + '-' + idx } })) } const _tmp: Data = { type: DataType.list, list: customData.filter(w => w.index === index) }; observer.next(_tmp); observer.complete(); }); } } }; onCustomSelected(value: any) { this.custom.result = value; } ``` ### Options Interface | 名称 | 类型 | 默认值 | 描述 | | ------- | ------------- | ----- | ----- | | placeholder | string | 请选择省市区 | 提示信息 || | separator | string | / | 提示分隔符信息 || | types | string[] | [ '省份', '城市', '县区' ] | 数据类型集合 || | jumps | string[] | | 可被跳过的面板，以 `id` 为判断标准 | | data | Function | | 调用时会传递 `index` （当前面板下标位，从0开始）、`id`（上一个面板选择的编号，如果第一个面板传递 `''`），返回 `Observable` 类型。 | | http | Function | | 调用时会传递 `index` （当前面板下标位，从0开始）、`id`（上一个面板选择的编号，如果第一个面板传递 `''`），返回 `Observable` 类型。 | | setAddress | Function | | 返回 `Observable` 类型（数组数量必须与 {types.length} 一致）。 | | className | string | | 面板样式，同 `class`。 | | offset | { x: number, y: number } | { x: 0, y: 25 } | 面板偏移值 | ### Result Interface | 名称 | 类型 | 默认值 | 描述 | | ------- | ------------- | ----- | ----- | | id | string | | 编号 | | name | string | | 名称 | | paths | any[] | | 已选择路径项 | ## Address Library ngx-address 还内置几种地址库，所有中国地址库都是按[国家标准地址区域代码信息](http://www.stats.gov.cn/tjsj/tjbz/xzqhdm/201703/t20170310_1471429.html)为准，地址库与 ngx-address 属于独立模块，需要单独引入。 ``` import { AddressDataChinaModule } from 'ngx-address/data/china'; @NgModule({ imports: [BrowserModule, AddressDataChinaModule ], declarations: [AppComponent], bootstrap: [AppComponent] }) export class AppModule { } ``` ``` constructor(private china: AddressDataChinaService) { this.options = { types: this.china.getTypes(), jumps: this.china.getJumps(), // 务必需要 `.bind` 来保证内部 `this` 指针。 data: this.china.getData.bind(this.china) } } ``` ### List | Module Name | 名称 | 描述 | | ------- | ------------- | ----- | | AddressDataChinaModule | 中国（含港澳） | 最小县区级 | | AddressDataCNModule | 中国（不含港澳） | 最小县区级 | | AddressDataKotModule | 港澳 | 最小县区级 | | AddressDataTWModule | 台湾 | 最小县区级 | | AddressDataMaModule | 马来西亚 | 最小城市级 | _以上地址库将会持续更新_ ### User Defined 通过实现 `IExternalData` 接口，创建属于自己地址库，有关细节可以参考 `src/data/china/data.service.ts`。 | 名称 | 类型 | 默认值 | 描述 | | ------- | ------------- | ----- | ----- | | getTypes | Array | | 数据类型集合 | | getJumps | Array | | 可跳过数据，以 `id` 为判断标准 | | getData | Function | | 调用时会传递 `index` （当前面板下标位，从0开始）、`id`（上一个面板选择的编号，如果第一个面板传递 `''`），返回 `Observable` 类型。 | | setAddress | Function | | 返回 `Observable` 类型（数组数量必须与 {types.length} 一致）。 | ### NOTE ngx-adress 提供静态数据 `data` 和远程数据 `http` 两个参数，且二者按 `data` > `http` 的顺序执行（当 `data` 结果返回 `null` 或 `undefined` 时尝试调用 `http` 请求）。因此，可以使用内置地址库配合远程的街道数据一起使用，可以参考[Live Demo](https://cipchk.github.io/ngx-address/)中的【含街道】示例。 ## Troubleshooting Please follow this guidelines when reporting bugs and feature requests: 1. Use [GitHub Issues](https://github.com/cipchk/ngx-address/issues) board to report bugs and feature requests (not our email address) 2. Please **always** write steps to reproduce the error. That way we can focus on fixing the bug, not scratching our heads trying to reproduce it. Thanks for understanding! ### License The MIT License (see the [LICENSE](https://github.com/cipchk/ngx-address/blob/master/LICENSE) file for the full text)