/ngx-address

A simple address picker in angular.

Primary LanguageTypeScriptMIT LicenseMIT

ngx-address

A simple address picker in angular.

NPM version Build Status

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: `
        <ngx-address 
        [(ngModel)]="id" 
        [options]="opt"></ngx-address>
    `
})
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

API

<ngx-address 
    [(ngModel)]="custom.id" 
    [options]="custom.options"
    [values]="custom.values"
    (onSelected)="onCustomSelected($event)"></ngx-address>

[options]

参数配置项,参数的变更(指整个 options 对象变更而非对象下某个属性)会使组件重新初始化,见Options

[values]

设置默认地址值,传递值可是字符串编号或与 options.types.length 等同数量的字符串数组

默认 ngx-address 实现了一套以国家标准地址区域代码信息规则。

标准市县区规则

310105:表示【上海-长宁】,最终会解析成:[ '310000', '310100', '310105' ]

标准市县区街道规则

310105001:表示【上海-长宁-某街道】,最终会解析成:[ '310000', '310100', '310105', '310105001' ]

如果你使用的 id 编号是以上两种规则之一的话,那么 (values) 完全可以忽略,因为 [(ngModel)] 本身是双向绑定,ngx-address 会自动根据外部变化重新选择,更多体验见Live Demo

(onSelected)

每一次选择会触一次,接收一个 Result 参数,见Result

由于默认ngx-adress组件并不包括地址数据,所以需要定义 options,可以自定义获取或使用内置的地址库

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<Data> 类型。
http Function 调用时会传递 index (当前面板下标位,从0开始)、id(上一个面板选择的编号,如果第一个面板传递 ''),返回 Observable<Data> 类型。
setAddress Function 返回 Observable<string[]> 类型(数组数量必须与 {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 还内置几种地址库,所有**地址库都是按国家标准地址区域代码信息为准,地址库与 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<Data> 类型。
setAddress Function 返回 Observable<string[]> 类型(数组数量必须与 {types.length} 一致) 。

NOTE

ngx-adress 提供静态数据 data 和 远程数据 http 两个参数,且二者按 data > http 的顺序执行(当 data 结果返回 nullundefined 时尝试调用 http 请求)。

因此,可以使用内置地址库配合远程的街道数据一起使用,可以参考Live Demo中的【含街道】示例。

Troubleshooting

Please follow this guidelines when reporting bugs and feature requests:

  1. Use GitHub 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 file for the full text)