Skip to main content
Supported Regions:上海

Map Positioning

WdLocation

Applicable Scenarios​

Point Selection and Positioning in Forms

image df955fc69a826d22169315c9fdaaa3bfimage 760de127f263be54a6ad5a89633384d4

Basic Capabilities​

Bind Geographic Location Field​

After the form container binds to the data model, the "geographic location" field in the model is automatically rendered as a map positioning component, enabling point selection and positioning.

Precautions​

Important: Read Before Use

Before using the map positioning component, ensure that the following configurations are completed; otherwise, the component may fail to function properly.

1. Tencent Maps API Configuration (Required)​

The map positioning component requires map API configuration to function. Click the map API and select Tencent Maps API. If no API is available, first create a new Tencent Maps API. For details, see Tencent Maps API.

This component calls Tencent Maps services and consumes relevant API quotas. To view key consumption status, visit Tencent Maps Open Platform. For details, refer to Quota Description.

The main services used within the component include:

Service NameService Path
Nearby Recommendations/ws/place/v1/explore
Place Search/ws/place/v1/search
Keyword Input Suggestion/ws/place/v1/suggestion
Geocoding/ws/geocoder/v1/?address=*

2. Permission Configuration (V2 Protocol)​

The component has supported the use of V2 protocol APIs since version 3.30.0. When using the V2 protocol, non-super administrator roles require permission configuration. See APIs 2.0 User Role Permission Configuration Guide to grant permissions in the cloud console.

3. Request Domain Configuration (V2 Protocol + Mini Program Side)​

The component has supported the use of V2 protocol APIs since version 3.30.0. When using the V2 protocol on the Mini Program side, additional request domain configuration is required:

Request Domain Configuration

The request domain format is https://{envId}.api.tcloudbasegateway.com, where the domain prefix is the current TCB environment ID.

4. Mini Program Configuration​

To use the map positioning component on the Mini Program side, configure it according to the following steps:

Step 1: Enable Location API Permissions

The Mini Program application calls the WeChat official wx.getLocation API to implement positioning. This must conform to the category requirements restricted by Mini Programs. On the WeChat Official Account Platform, navigate to "Development" - "Development Settings" - "API Settings" module, and self-activate the permission for the "Obtain current geographic location and speed" API.

Enable Location API Permissions

Step 2: Configure appJson

Starting from July 14, 2022, developers need to configure in app.json in advance when using location-related APIs. Please open the low-code editor commom/mp_config file and configure the following properties for appJson:

appJson: {
  permission: {
    'scope.userLocation': {
      desc: 'Your location information will be used to present the functionality of the location API in the Mini Program',
    },
  },
  requiredPrivateInfos: [ "getLocation" ]
}

appJson Configuration

Step 3: Refine the Privacy Agreement

After submitting the official Mini Program for review, it is necessary to refine the user privacy agreement protection. Specifically, see Mini Program Privacy Protection Guidance Adaptation Instructions.

Privacy Agreement Configuration 1

Privacy Agreement Configuration 2

5. Frequently Asked Questions​

Error Reported During Mini Program Submission for Review​

Error MessageSolution
The code contains the privacy API getLocation that is not configured in ext.jsonPlease see Step 2: Configure appJson above to complete the configuration
The privacy API getLocation configured in ext.json lacks permissionPlease see Step 1: Enable Location API Permission above to apply for permission

Browser Positioning Failure​

Error MessageCause and Solution
Browser not Support html5 geolocationThe browser does not support the native geolocation API, such as lower versions of Internet Explorer
Geolocation permission deniedThe user has disabled location permission; enable location permission for the device and browser, or the browser blocks location requests from non-secure domains; upgrade the site to HTTPS.
Get geolocation time outBrowser geolocation timeout; consider increasing the timeout attribute setting value
Get geolocation failedGeolocation failed; browsers like Chrome and Firefox access geolocation services located overseas, resulting in a higher failure rate

Extended Scenarios​

Positioning Adjustment Range Configuration​

The component provides the "Positioning Adjustment Range" attribute, which can constrain the user's selected point positioning range to only within a certain range of the current actual location.

image 8eb3dd4638111675a8083ecf322e4dbfimage 1010569f3c90ed9275bc5158d9bd21db

Other Scenario Practices​

Refer to the Form Scenario Practice Guide to learn about various supported scenarios and implementation solutions for forms.

Example​

Interactive Preview​

Component Input State​

Style API Example​

#wd-page-root .wd-pc-location-root .wd-location__label {
  color: cyan;
  background-color: black;
  display: flex;
  justify-content: center;
}
#wd-page-root .wd-h5-location-root .wd-location-location {
  border-color: cyan;
  color: cyan;
  background-color: black;
  border-width: 2px;
  border-radius: 6px;
}

Properties​

External properties received by the component

Property Name
Property Identifier
Type
Description
Display HeadlineslabelVisibleboolean

Default value: true

Title alignmentlabelAlignstring

In the scenario, the form by default follows the title alignment configuration of the form container.

Line break in headinglabelWrapboolean

If the title content is too long when closed, show one line with overflow omitted; when enabled, show with line breaks. In form scenarios, it follows the form container's title line break configuration by default.

Title positionlayoutstring

Set title display position in form component. In the scenario, it follows the title position configuration of the form container by default.

Title widthlabelWidthstring

You can enter a value with units such as px or %, for example: 200px.

In the scenario, the form follows the title width configuration of the form container by default.

Heading NotelabelTipsstring

Take effect on PC/H5

Configure tooltip content for the heading

Display clear buttonclearableboolean

Enabled, quick clear button is provided by

Default value: true

Prompt.extrastring

The prompt content is displayed below the input box after configuration.

Display longitude and latitudeshowLngLatboolean

Display longitude and latitude of the selected location

display mapshowMapboolean

Display the selected location on the map

打开微信内置地图(Mini Program)openLocationboolean

仅支持小程序端开启，开启后，可点击地图调起微信内置地图查看位置，或者开始导航

使用微信内置地图查看位置

Display underscore on mobile terminalborderedH5boolean

After closing, the mobile terminal does not show the bottom underline

Default value: true

Locating adjustment rangelocationRangestring0
custom scopecustomRangenumber0
Permission to scalezoomboolean

Permission to scale the map

Default value: true

Allow dragdragboolean

Permission to drag the map

Example: true

Status.statusstring

Example: "edit"

Requiredrequiredboolean
Required identifierrequiredFlagboolean

Enabled, the component will display a required asterisk tag if mandatory.

Default value: true

Required validation noterequiredMsgstring

Example: "该项为必填项"

Bound fieldnamestring

The Key value of a form field is used to match the field identifier of the data model when submitting data. It must be unique within the form.

Title content.labelstring

Example: "地图"

Map APIsdataSourceobject

If needed for WeChat Mini Program usage, ensure to refer to the configuration guide to complete WeChat API permission application and adjust the appJson content.

Associate Tencent Maps APIs, the mini program will call the Official WeChat API for localization. Please ensure the relevant APIs are approved. For details, refer to the component documentation.

Default positionlocationTypenumber

Default location value

Example: 1

Default valuevalueobject

Latitude ranges from -90 to 90; longitude ranges from -180 to 180. For location coordinates, go to Tencent Location Service Obtain

Example: null

Placeholder textplaceholderstring

Example: "选择地理位置"

Events​

Events exposed by the component. You can listen to component events to trigger external actions

Event Name
Event Code
Event Output Parameters event.detail
Applicable Scenarios
Description
value changechangeobject
  • value: object 值
    • address: string

      地点名称
    • geopoint: object

      经纬度
      • type: string Default value: Point
      • coordinates: array
Compatible with all platforms

Trigger when a user modifies a component value

Map component error eventerrorobject
  • error: object 错误信息

    组件内部抛出的错误信息
    • requestid: string请求 id

      如果是接口相关错误会提供请求 id
    • message: string错误提示信息
    • code: string错误码
    • original: 原始错误
Mobile,PC

Map loading failed, or trigger on abnormality in map component usage

Properties API​

Through the Property API, you can access the internal state and property values of components. You can access internal values using$w.componentId.propertyName, such as $w.input1.value. For details, please refer to Property API

Read-only Property Name
Property Identifier
Type
Description
Bound fieldnamestring

The Key value of a form field is used to match the field identifier of the data model when submitting data. It must be unique within the form.

Title content.labelstring
Default valuevalueobject
Requiredrequiredboolean
Indicates whether to displayvisibleboolean

Whether to display the component

Whether to disabledisabledboolean

Component Disabled

Specify whether it is read-only or not.readOnlyboolean

Whether the component is read-only

Method API​

Through the Method API, you can programmatically trigger internal methods of components, such as submitting forms, displaying popups, etc. You can call component methods using $w.componentId.methodName, such as $w.form1.submit()

Method Name
Method Identifier
Parameters
Method Description
set valuesetValueobject
  • value: object 值
    • address: string

      地点名称
    • geopoint: object

      经纬度
      • type: string Default value: Point
      • coordinates: array

通过 $w.id1.setValue({address:"深圳站",geopoint:{coordinates:[114.117209,22.53168]}}) 设置组件值

Show/Hide SettingssetVisibleboolean显示

Set the component to hidden via $w.id1.setVisible(false)

Set DisabledsetDisabledboolean禁用

Set the component to disabled with $w.id1.setDisabled(true)

Clear valueclearValue

Clear the component value with $w.id1.clearValue()

Set as read-onlysetReadOnlyboolean只读

Set the component to read-only via $w.id1.setReadOnly(true)

Trigger validationhandleValidate

Validate the component value via $w.id1.handleValidate()

Clear verificationclearValidate

Clear component validation via $w.id1.clearValidate()

Style API​

Through the Style API, you can override the styles of internal elements in components to achieve customization. For example, in the low-code editor, you can write styles for all button components using #wd-page-root .wd-btn, and control individual component styles with :scope. For detailed instructions, please refer toStyle API

Name
Class Name
Description and Examples
root element.wd-location-rootOutermost component element
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope.wd-location-root {
  /* Write CSS styles here */
}
H5 root element.wd-h5-location-rootSettable root element style for the H5 side
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope.wd-h5-location-root {
  /* Write CSS styles here */
}
PC-side root element.wd-pc-location-rootSettable root element style for the PC side
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope.wd-pc-location-root {
  /* Write CSS styles here */
}
Mini program root element.wd-mp-location-rootSettable root element style for mini program
/* :scope refers to the current component element */
/* For details, refer to the Style API documentation */
:scope.wd-mp-location-root {
  /* Write CSS styles here */
}
Component title style.wd-location-root .wd-form-item-wrap__labelComponent title element

:scope .wd-form-item-wrap__label {
  font-size: 20px;
  color: gray;
  padding: 0;
  display: flex;
  align-items: center;
}
form control root node style.wd-location-root .wd-form-item-wrap__controlSet form control root element style

:scope .wd-form-item-wrap__control {
  font-size: 20px;
  color: gray;
  padding: 0;
  display: flex;
  align-items: center;
}
Editing status - Location information style.wd-location-root .wd-location__infoEditing status - Location information style

          :scope .wd-location__info {
font-size: 20px;
color: gray;
          }
Editing status - Placeholder text style.wd-location-root .form-location-con__textEditing status - Placeholder text style

          :scope .form-location-con__text {
color: lightgray;
          }
Editing status - Verification information.wd-location-root .wd-g-text-errorSet component verification information style

:scope .wd-g-text-error {
    font-size: 20px;
    color: gray;
  }
prompt text.wd-location-root .wd-form-item__help-textSet the text style of the component prompt

:scope .wd-form-item__help-text {
    font-size: 20px;
    color: gray;
  }
Disabled status - Location information style.wd-location-root .is-disabled .wd-location__infoDisabled status - Location information style

          :scope .is-disabled .wd-location__info {
font-size: 20px;
color: gray;
          }
read-only status - form value style.wd-location-root .wd-form-item__readonly-valueSet component read-only status

:scope .wd-form-item__readonly-value {
    font-size: 20px;
    color: gray;
  }

Learn about Style API

Version Changes​

  • Properties Changes
  • Style Changes
  • widget api changes