{"id":16407088,"url":"https://github.com/cipchk/ngx-address","last_synced_at":"2025-03-21T03:30:58.725Z","repository":{"id":65458795,"uuid":"88459220","full_name":"cipchk/ngx-address","owner":"cipchk","description":"A simple address picker in angular.","archived":false,"fork":false,"pushed_at":"2017-11-02T09:41:42.000Z","size":558,"stargazers_count":46,"open_issues_count":4,"forks_count":16,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-10-12T06:11:56.201Z","etag":null,"topics":["address","address-picker","angular","angular5","ngx-address"],"latest_commit_sha":null,"homepage":"https://cipchk.github.io/ngx-address/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cipchk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-17T02:26:58.000Z","updated_at":"2023-12-19T06:49:36.000Z","dependencies_parsed_at":"2023-01-24T14:45:28.365Z","dependency_job_id":null,"html_url":"https://github.com/cipchk/ngx-address","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipchk%2Fngx-address","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipchk%2Fngx-address/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipchk%2Fngx-address/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cipchk%2Fngx-address/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cipchk","download_url":"https://codeload.github.com/cipchk/ngx-address/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221811375,"owners_count":16884305,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["address","address-picker","angular","angular5","ngx-address"],"created_at":"2024-10-11T06:12:03.630Z","updated_at":"2024-10-28T09:13:47.292Z","avatar_url":"https://github.com/cipchk.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ngx-address\nA simple address picker in angular.\n\n[![NPM version](https://img.shields.io/npm/v/ngx-address.svg)](https://www.npmjs.com/package/ngx-address)\n[![Build Status](https://travis-ci.org/cipchk/ngx-address.svg?branch=master)](https://travis-ci.org/cipchk/ngx-address)\n\n\u003c!-- TOC --\u003e\n\n- [Usage](#usage)\n- [DEMO](#demo)\n- [API](#api)\n    - [ngx-address](#ngx-address)\n    - [[options]](#options)\n    - [[values]](#values)\n    - [(onSelected)](#onselected)\n    - [Options Interface](#options-interface)\n    - [Result Interface](#result-interface)\n- [Address Library](#address-library)\n    - [List](#list)\n    - [User Defined](#user-defined)\n    - [NOTE](#note)\n- [Troubleshooting](#troubleshooting)\n\n\u003c!-- /TOC --\u003e\n\n## Usage\n\nInstall `ngx-address` from `npm`\n\n```\nnpm install ngx-address --save\n```\n\nImport the `NgxAddressModule` in to your root `AppModule`.\n\n```\nimport { NgxAddressModule } from 'ngx-address';\n\n@NgModule({\n    imports: [BrowserModule, NgxAddressModule ],\n    declarations: [AppComponent],\n    bootstrap: [AppComponent]\n})\nexport class AppModule { }\n```\n\n```\nimport { AddressDataChinaService } from 'ngx-address/data/china';\n\n@Component({\n    selector: 'demo',\n    template: `\n        \u003cngx-address \n        [(ngModel)]=\"id\" \n        [options]=\"opt\"\u003e\u003c/ngx-address\u003e\n    `\n})\nexport class DemoComponent implements OnInit {\n    public id: any;\n    public opt: any;\n    constructor(private china: AddressDataChinaService) {\n        this.opt = {\n            jumps: this.china.getJumps(),\n            data: this.china.getData.bind(this.china)\n        };\n    }\n}\n```\n\n## DEMO\n\n[Live Demo](https://cipchk.github.io/ngx-address/)\n\n## API\n\n```\n\u003cngx-address \n    [(ngModel)]=\"custom.id\" \n    [options]=\"custom.options\"\n    [values]=\"custom.values\"\n    (onSelected)=\"onCustomSelected($event)\"\u003e\u003c/ngx-address\u003e\n```\n\n### [options]\n\n参数配置项，参数的变更（指整个 `options` 对象变更而非对象下某个属性）会使组件重新初始化，见[Options](#options-interface)。\n\n### [values]\n\n设置默认地址值，传递值可是**字符串编号**或与 _options.types.length_ 等同数量的**字符串数组**。\n\n默认 ngx-address 实现了一套以国家标准地址区域代码信息规则。\n\n_标准市县区规则_\n\n310105：表示【上海-长宁】，最终会解析成：[ '310000', '310100', '310105' ]\n\n_标准市县区街道规则_\n\n310105001：表示【上海-长宁-某街道】，最终会解析成：[ '310000', '310100', '310105', '310105001' ]\n\n如果你使用的 `id` 编号是以上两种规则之一的话，那么 `(values)` 完全可以**忽略**，因为 `[(ngModel)]` 本身是双向绑定，ngx-address 会自动根据外部变化重新选择，更多体验见[Live Demo](https://cipchk.github.io/ngx-address/)。\n\n### (onSelected)\n\n每一次选择会触一次，接收一个 `Result` 参数，见[Result](#result-interface)。\n\n由于默认ngx-adress组件并不包括地址数据，所以需要定义 `options`，可以自定义获取或使用[内置的地址库](#address-library)。\n\n```\nlet types = ['区域', '公司', '部门'];\nthis.custom = {\n    id: '',\n    result: {},\n    options: {\n        placeholder: '请选择区域、公司、部门',\n        types: types,\n        http: (index: number, id: string) =\u003e {\n            return new Observable(observer =\u003e {\n                if (customData.findIndex(w =\u003e w.index === index) === -1) {\n                    customData.push(...Array.from({\n                        length: Math.floor(Math.random() * 10) + 1\n                    }).map((item, idx) =\u003e {\n                        return {\n                            index: index,\n                            id: (index + 1) + idx,\n                            name: types[index] + '-' + idx\n                        }\n                    }))\n                }\n                const _tmp: Data = {\n                    type: DataType.list,\n                    list: customData.filter(w =\u003e w.index === index)\n                };\n                observer.next(_tmp);\n                observer.complete();\n            });\n        }\n    }\n};\n\nonCustomSelected(value: any) {\n    this.custom.result = value;\n}\n```\n\n### Options Interface\n\n| 名称    | 类型           | 默认值  | 描述 |\n| ------- | ------------- | ----- | ----- |\n| placeholder | string | 请选择省市区 | 提示信息 ||\n| separator | string | / | 提示分隔符信息 ||\n| types | string[] | [ '省份', '城市', '县区' ] | 数据类型集合 ||\n| jumps | string[] |  | 可被跳过的面板，以 `id` 为判断标准 |\n| data | Function |  | 调用时会传递 `index` （当前面板下标位，从0开始）、`id`（上一个面板选择的编号，如果第一个面板传递 `''`），返回 `Observable\u003cData\u003e` 类型。 |\n| http | Function |  | 调用时会传递 `index` （当前面板下标位，从0开始）、`id`（上一个面板选择的编号，如果第一个面板传递 `''`），返回 `Observable\u003cData\u003e` 类型。 |\n| setAddress | Function |  | 返回 `Observable\u003cstring[]\u003e` 类型（数组数量必须与 {types.length} 一致） 。 |\n| className | string |  | 面板样式，同 `class`。 |\n| offset | { x: number, y: number } | { x: 0, y: 25 } | 面板偏移值 |\n\n### Result Interface\n\n| 名称    | 类型           | 默认值  | 描述 |\n| ------- | ------------- | ----- | ----- |\n| id | string |  | 编号 |\n| name | string |  | 名称 |\n| paths | any[] |  | 已选择路径项 |\n\n## Address Library\n\nngx-address 还内置几种地址库，所有中国地址库都是按[国家标准地址区域代码信息](http://www.stats.gov.cn/tjsj/tjbz/xzqhdm/201703/t20170310_1471429.html)为准，地址库与 ngx-address 属于独立模块，需要单独引入。\n\n```\nimport { AddressDataChinaModule } from 'ngx-address/data/china';\n\n@NgModule({\n    imports: [BrowserModule, AddressDataChinaModule ],\n    declarations: [AppComponent],\n    bootstrap: [AppComponent]\n})\nexport class AppModule { }\n```\n\n```\nconstructor(private china: AddressDataChinaService) {\n    this.options = {\n        types: this.china.getTypes(),\n        jumps: this.china.getJumps(),\n        // 务必需要 `.bind` 来保证内部 `this` 指针。\n        data: this.china.getData.bind(this.china)\n    }\n}\n```\n\n### List\n\n| Module Name | 名称 |  描述 |\n| ------- | ------------- | ----- |\n| AddressDataChinaModule | 中国（含港澳） | 最小县区级 |\n| AddressDataCNModule | 中国（不含港澳） | 最小县区级 |\n| AddressDataKotModule | 港澳 | 最小县区级 |\n| AddressDataTWModule | 台湾 | 最小县区级 |\n| AddressDataMaModule | 马来西亚 | 最小城市级 |\n\n_以上地址库将会持续更新_\n\n### User Defined\n\n通过实现 `IExternalData` 接口，创建属于自己地址库，有关细节可以参考 `src/data/china/data.service.ts`。\n\n| 名称    | 类型           | 默认值  | 描述 |\n| ------- | ------------- | ----- | ----- |\n| getTypes | Array\u003cstring\u003e |  | 数据类型集合 |\n| getJumps | Array\u003cstring\u003e |  | 可跳过数据，以 `id` 为判断标准 |\n| getData | Function |  | 调用时会传递 `index` （当前面板下标位，从0开始）、`id`（上一个面板选择的编号，如果第一个面板传递 `''`），返回 `Observable\u003cData\u003e` 类型。 |\n| setAddress | Function |  | 返回 `Observable\u003cstring[]\u003e` 类型（数组数量必须与 {types.length} 一致） 。 |\n\n### NOTE\n\nngx-adress 提供静态数据 `data` 和 远程数据 `http` 两个参数，且二者按 `data` \u003e `http` 的顺序执行（当 `data` 结果返回 `null` 或 `undefined` 时尝试调用 `http` 请求）。\n\n因此，可以使用内置地址库配合远程的街道数据一起使用，可以参考[Live Demo](https://cipchk.github.io/ngx-address/)中的【含街道】示例。\n\n## Troubleshooting\n\nPlease follow this guidelines when reporting bugs and feature requests:\n\n1. Use [GitHub Issues](https://github.com/cipchk/ngx-address/issues) board to report bugs and feature requests (not our email address)\n2. 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.\n\nThanks for understanding!\n\n### License\n\nThe MIT License (see the [LICENSE](https://github.com/cipchk/ngx-address/blob/master/LICENSE) file for the full text)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipchk%2Fngx-address","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcipchk%2Fngx-address","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcipchk%2Fngx-address/lists"}