@acpaas-ui-widgets/ngx-location-picker 中文文档教程

Question

Location Picker Smart Widget UI (Angular)

Location Picker Smart Widget UI 提供了一个易于使用的界面，用于在安特卫普市内搜索位置或地址。 对于仍在使用 Angular 5 的项目，我们维护一个 v1 分支，它仍然会收到错误修复如果需要的话。

这个库在 Angular 6、7 和 8 中进行了测试。

Desktop view

Using the component

Installation

首先从 npm 安装组件

： location-picker

然后在您的模块中导入组件：

import {LocationPickerModule} from '@acpaas-ui-widgets/ngx-location-picker';

@NgModule({
  imports: [
    ...,
    LocationPickerModule
  ],
  ...
})

最后包括所需的样式：

在您的 index.html 文件中添加 Antwerp 核心品牌样式表：

<link rel="stylesheet" href="https://cdn.antwerpen.be/core_branding_scss/5.0.0/main.min.css">

在您的 angular.json 文件中添加所需的传单样式。

"styles": [
    "node_modules/leaflet/dist/leaflet.css",
    "node_modules/leaflet-draw/dist/leaflet.draw.css",
    "node_modules/@geoman-io/leaflet-geoman-free/dist/leaflet-geoman.css",
    "node_modules/leaflet.markercluster/dist/MarkerCluster.Default.css",
    "node_modules/leaflet.markercluster/dist/MarkerCluster.css"
]

接下来，您需要配置 BFF 以将所有位置选择器请求代理到正确的服务。 下面的示例基于 Express.js 支持的 BFF。 对于不同的技术，概念保持不变：

BFF 应该仅作为传递层运行，在代理之前，API KEY 被添加到请求标头中。

在下面的示例中，我们使用 axios 来处理请求。 随意使用任何其他库。

第 1 步：在 api-store 上与“LOCATIONPICKER”创建合同。

第 2 步：复制 api 密钥和 api url

第 3 步：在您的 BFF 中创建一个 .env 文件并添加：

API_KEY=00000000-0000-0000-0000-000000000000
LOCATION_PICKER_URL=https://api-gw-o.antwerpen.be/gis/locationpicker/v1

第 4 步：创建一个新文件 locations.routes.js 在/routes 中添加如下内容：

const express = require('express');
const router = express.Router();
const locationController = require('../controllers/location.controller');

/**
 * Proxy requests from /locations to location picker api.
 */
router.get('/*', locationController.proxyLocationRequest);

module.exports = router;

Step 5: 在/ 中新建文件locations.controller.js controllers 并添加以下内容：

const locationModel = require('../models/location.model');

/**
 * Catch all requests to /locations and proxy to location picker api.
 *
 * @param req {Request}
 * @param res {Response}
 */
exports.proxyLocationRequest = (req, res) => {
    const requestPath = req.originalUrl.replace('/api/v1/locations', '');

    locationModel.handleLocationRequest(requestPath)
        .then((response) => {
            res.status(response.status);
            res.json(response.data);
        })
        .catch((error) => {
            res.status(error.response.status);
            res.json(error.response.data);
        });
};

Step 6：在/models 中新建文件locations.model.js 并添加以下内容：

const axios = require('axios');

/**
 * Handle request to location picker api.
 * Add API_KEY to header
 */
exports.handleLocationRequest = (requestPath) => {
    return new Promise((resolve, reject) => {
        // Add our api key (which we added to our .env file) to the request headers
        const requestOptions = {
            headers: {
                'ApiKey': process.env.API_KEY
            }
        };

        axios.get(`${process.env.LOCATION_PICKER_URL}${requestPath}`, requestOptions).then((response) => {
            resolve(response);
        }).catch((error) => {
            reject(error);
        });
    });
};

Step 7：添加你新创建的 app.js 路径 <

// Add this to the top of app.js
const locationProxy = require('./routes/location.routes');

// Add this after const app = express(); and before any error handler routes
app.use('/api/v1/locations', locationProxy);

strong>就是这样！ ????

Usage

注意：选择位置后获取值的方法有3种：

方法一：locationSelect事件

<aui-location-picker
    ...
    (locationSelect)="onLocationSelect($event)"
></aui-location-picker>

方法二：NgModel

<aui-location-picker
    ...
    [(ngModel)]="selectedLocation"
></aui-location-picker>

方法三：响应式表单

<aui-location-picker
    ...
    formControlName="selectedLocation"
></aui-location-picker>

方法2 和 3 也可用于设置初始值：

selectedLocation: InitialLocationModel = {
    label: 'Generaal Armstrongweg 1, 2020 Antwerpen',
    position: {
        lat: 0,
        lng: 0
    },
    options: {triggerSearch: false} // Optional: whether to trigger a search or not.
};

Minimal example

<aui-location-picker
    [baseUrl]="baseUrl"
></aui-location-picker>

Full example

<aui-location-picker
    [baseUrl]="baseUrl"
    [defaultZoom]="defaultZoom"
    [onSelectZoom]="onSelectZoom"
    [changeZoomLevelOnLocationSelect]="changeZoomLevelOnLocationSelect"
    [mapCenter]="mapCenter"
    [hasSidebar]="hasSidebar"
    [showMap]="showMap"
    [featureLayers]="featureLayers"
    [placeholder]="placeholder"
    [label]="label"
    [noResultsLabel]="noResultsLabel"
    [defaultOptionLabel]="defaultOptionLabel"
    [clearInputAriaLabel]="clearInputAriaLabel"
    [defaultTileLayerLabel]="defaultTileLayerLabel"
    [locateMeAriaLabel]="locateMeAriaLabel"
    [locationPickAriaLabel]="locationPickAriaLabel"
    [textInputAriaLabel]="textInputAriaLabel"
    [zoomInAriaLabel]="zoomInAriaLabel"
    [zoomOutAriaLabel]="zoomOutAriaLabel"
    [tileLayer]="tileLayer"
    [locationLayers]="locationLayers"
    [locationsLimit]="locationsLimit"
    [minInputLength]="minInputLength"
    [prioritizeLayers]="prioritizeLayer"
    [showClearInputButton]="showClearInputButton"
    [sortBy]="sortBy"
    [coordinateErrorNotification]="coordinateErrorNotification"
    [locateMeNotAllowedNotification]="locateMeNotAllowedNotification"
    [locateMeNotSupportedNotification]="locateMeNotSupportedNotification"
    [locateMeTimeoutNotification]="locateMeTimeoutNotification"
    [locateMeUnavailableNotification]="locateMeUnavailableNotification"
    [locateMeUnknownNotification]="locateMeUnknownNotification"
    [zoomInfoNotification]="zoomInfoNotification"
    [locateUserOnInit]="locateUserOnInit"
    [debounceTime]="debounceTime"
    [cascadingCoordinateReturnSingle]="cascadingCoordinateReturnSingle"
    [cascadingCoordinateLimit]="cascadingCoordinateLimit"
    [cascadingCoordinateRules]="cascadingCoordinateRules"
    [locationKeywords]="locationKeywords"
    (addPolygon)="onAddPolygon($event)"
    (addLine)="onAddLine($event)"
    (editFeature)="onEditFeature($event)"
    (locationSelect)="onLocationSelect($event)"
>

<p>This is shown inside the leaflet sidebar if hasSidebar is set to true.</p>

</aui-location-picker>

class ExampleComponent {

    /* Url to the backend-for-frontend (bff) Should function as pass through to the Location Picker API. */
    @Input() baseUrl;
    /* The default zoom level on map load. */
    @Input() defaultZoom = 14;
    /**
    *  The zoom level when a location is selected.
    *  If null the zoomlevel won't change after location selection.
    */
    @Input() onSelectZoom? = 16;
    /* The zoom level will change after location selected (to fit selected geometry). */
    @Input() changeZoomLevelOnLocationSelect = false;
    /* The initial map center on load. */
    @Input() mapCenter: Array<number> = [51.215, 4.425];
    /* Show a sidebar next to the map leaflet. A sidebar can contain any additional info you like. */
    @Input() hasSidebar = false;
    /* Show or hide the map. */
    @Input() showMap = true;
    /* Toggle the clear button */
    @Input() showClearInputButton = true;
    /**
    * Add layers to show on the map. eg: A-card terminals, Velo stations, ...
    * A single featureLayer consists of:
    *
    * url: the url to the mapServer containing the features to be shown on the map.
    * icon: the marker to use to show featureLayer locations.
    *
    * An icon should include: Streamline icon class, the icon color (default: #0064B) and the icon size (default: 40px)
    * see: FeatureLayerIconModel
    */
    @Input() featureLayers: FeatureLayerModel[] = [];
    /* The input field placeholder text. */
    @Input() placeholder = 'Zoek een locatie…';
    /* Label to use when no results were found. */
    @Input() noResultsLabel = 'Er werd geen gekende locatie gevonden.';
    /* Label to use for "use selected coordinates option" */
    @Input() defaultOptionLabel = 'Gebruik gekozen coördinaat';
    /* Aria label for clear input button. */
    @Input() clearInputAriaLabel = 'Tekstveld leegmaken';
    /* Aria label for picking a location on the map */
    @Input() locationPickAriaLabel = 'Kies een locatie op de map';
    /* Aria label for zooming in */
    @Input() zoomInAriaLabel = 'Zoom in';
    /* Aria label for zooming out  */
    @Input() zoomOutAriaLabel = 'Zoom out';
    /* Aria label for text input */
    @Input() textInputAriaLabel = 'Locaties zoeken op basis van zoekterm';
    /* Aria label for locate me button */
    @Input() locateMeAriaLabel = 'Gebruik mijn locatie';
    /* Locate me error notification texts */
    @Input() locateMeNotSupportedNotification = 'Locatiebepaling wordt niet ondersteund op dit toestel.';
    @Input() locateMeNotAllowedNotification = 'Gelieve toegang tot je locatie toe te staan.';
    @Input() locateMeUnavailableNotification = 'Je locatie kon niet worden bepaald.';
    @Input() locateMeTimeoutNotification = 'Het duurde te lang om je locatie te bepalen.';
    @Input() locateMeUnknownNotification = 'Er trad een onbekende fout op bij het bepalen van je locatie.';
    /* No/invalid coordinate error notification text */
    @Input() coordinateErrorNotification = 'Locatie kan niet op de map getoond worden.';
    /* Zoom info notification text */
    @Input() zoomInfoNotification = 'Gebruik de Shift toets om te zoomen door te scrollen.';
    /* Default tile layer button label */
    @Input() defaultTileLayerLabel = 'Kaart';
    /* Custom leaflet tile layer, if provided, shows actions on the leaflet to toggle between default and custom tile layer. */
    @Input() tileLayer: LeafletTileLayerModel;
    /* Search input length requirement before triggering a search. */
    @Input() minInputLength = 2;
    /* The amount of results to return */
    @Input() locationsLimit = 5;
    /* The layers to search locations for, 'all' to search in all the layers, 'none' to disable location search */
    @Input() locationLayers = ['straatnaam'];
    /**
     * Prioritize specific layers, boosts results from given layers to the top of the found locations.
     * The order of the values in the array determines the priority. Overrides sortBy.
     */
    @Input() prioritizeLayers = ['straatnaam'];
    /* Sort locations by certain key. */
    @Input() sortBy = '';
    /* Use geolocation when the component finished loading */
    @Input() locateUserOnInit = false;
    /* Set time to wait after user stops typing before triggering a search */
    @Input() debounceTime = 200;
    /* whether or not to return a single cascading result */
    @Input() cascadingCoordinateReturnSingle = true;
    /* Limit total cascading result, useful when returnSingle is false */
    @Input() cascadingCoordinateLimit = 10;
    /* Cascading configuration for doing reverse lookups by coordinates */
    @Input() cascadingCoordinateRules: CascadingCoordinateRulesModel[] = [];
    /* Input params to pass through to location viewer */
    /* Geo API */
    @Input() geoApiBaseUrl: string;
    /* Shows layermangement inside the sidebar. Layermanagement is used to add or remove featurelayers. */
    @Input() showLayerManagement = false;
    /* Show selection tools */
    @Input() showSelectionTools = false;
    /* Show measure tools */
    @Input() showMeasureTools = false;
    /* show whatishere button */
    @Input() showWhatIsHereButton = false;
    /* Add supporting layers. If provided will be added as DynamicMapLayer to leaflet */
    @Input() supportingLayerOptions: SupportingLayerOptions;
    /* Add operationalLayer. If provided will be added as FeaturLayer(clustered) to leaflet */
    @Input() operationalLayerOptions: OperationalLayerOptions;
    /* Adds filter layer. If provided will be added as FeatureLayer to leaflet. Is used to filter operationallayer by geometry */
    @Input() filterLayers: FilterLayerOptions[];
    /* If provided, adds coordinate to resultList at index */ 
    @Input() addCoordinateToResultsAt?: number = null;
    /* If search string contains one of these words, search for locations instead of address */
    @Input() locationKeywords: string[] = ['kaainummer'];
    /* AddPolygon event */
    @Output() addPolygon = new EventEmitter<any>();
    /* AddLine event */
    @Output() addLine = new EventEmitter<any>();
    /* EditFeature event */
    @Output() editFeature = new EventEmitter<any>();
    /* LocationSelect event: fired when selecting a location. */
    @Output() locationSelect = new EventEmitter<LocationModel | AddressModel | CoordinateModel>();
    /* Operational layer filtered: fired when using selection tools rectangle/polygon, using filter layer or clicking on marker of operational layer*/
    @Output() filteredResult = new EventEmitter<GeofeatureDetail[] | OperationalMarker[] | any>();
}

Demo

现场演示可在以下位置找到： https://locationpicker-app1-o.antwerpen.be

你也可以选择在本地测试它：

在根目录运行：

npm install && ng build ngx-location-picker && ng serve

这将安装所有必需的依赖项，为位置选择器库创建优化构建并设置本地服务器在 http://localhost:4200。

Local development

安装所需的依赖项：

npm install

根据更改重建库

npm run dev

启动示例项目

ng serve

对库所做的任何更改都将在 http://localhost:4200 上可见

Build

运行 npm run build-lib 来构建项目。 构建工件将存储在 dist/ 目录中，并且将创建一个包含库的 .tgz 文件。 这是发布到 NPM 所必需的。

Contributing

我们欢迎您的错误报告和拉取请求。

请参阅我们的贡献指南。

Support

Jasper Van Proeyen (jasper.vanproeyen@digipolis.be)

Publishing

只有 Antwerp UI 团队发布新包。 如果您需要发布新版本，请联系我们。

Running unit tests

运行 ng test ngx-location-picker 以通过 Karma 执行单元测试。

Further help

要获得有关 Angular CLI 的更多帮助，请使用 ng help 或查看 角度 CLI 自述文件。