ngx-address v1.0.4

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

Result Interface

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

以上地址库将会持续更新

User Defined

通过实现 IExternalData 接口，创建属于自己地址库，有关细节可以参考 src/data/china/data.service.ts。

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)