dystudio / ngx-address

A simple address picker in angular.

ngx-address

A simple address picker in angular.

• Usage
• DEMO
• API
  • ngx-address
  • [options]
  • [values]
  • (onSelected)
  • Options Interface
  • Result Interface
• Address Library
  • List
  • User Defined
  • NOTE
• 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: `
        <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 结果返回 null 或 undefined 时尝试调用 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)