Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cipchk/ngx-address

A simple address picker in angular.
https://github.com/cipchk/ngx-address

address address-picker angular angular5 ngx-address

Last synced: 18 days ago
JSON representation

A simple address picker in angular.

Host: GitHub
URL: https://github.com/cipchk/ngx-address
Owner: cipchk
License: mit
Created: 2017-04-17T02:26:58.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2017-11-02T09:41:42.000Z (about 7 years ago)
Last Synced: 2024-10-12T06:11:56.201Z (about 1 month ago)
Topics: address, address-picker, angular, angular5, ngx-address
Language: TypeScript
Homepage: https://cipchk.github.io/ngx-address/
Size: 545 KB
Stars: 46
Watchers: 7
Forks: 16
Open Issues: 4
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Awesome Lists containing this project

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)