Map Location

WdLocation

Applicable Scenarios

Enabling location pinning in forms

Basic Capabilities

Bind Geographic Location Field

After the form container is bound to the data model, geographic location fields in the model are automatically rendered as a map location component, enabling location pinning.

Notes

Required Before Use

Please ensure the following configurations are completed before using the Map Location component, otherwise the component may not work properly.

1. Tencent Maps API Configuration (Required)

The map location component requires map API configuration to be used. Click Map API and select Tencent Maps API. If no API exists, create a new Tencent Maps API first. For details, refer to Tencent Maps API.

This component calls the Tencent Maps Service and consumes API quota. You can check key usage at the Tencent Maps Open Platform. For details, refer to the Quota Description.

The main services used within the component include:

Service Name	Service 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)

Starting from version 3.30.0, this component supports V2 protocol APIs. When using V2 protocol, non-super administrator roles need to complete permission configuration. Please refer to APIs 2.0 User Role Permission Configuration Guide to complete the authorization in the cloud backend.

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

Starting from version 3.30.0, this component supports V2 protocol APIs. When using V2 protocol on Mini Program, you need to configure request domains additionally:

4. Mini Program Configuration

To use the Map Location component on Mini Program, follow these steps:

Step 1: Enable Location Interface Permission

Mini Program applications invoke WeChat's official wx.getLocation interface to achieve location positioning. They must comply with the category requirements restricted by Mini Programs. Under the "Development" - "Development Management" - "Interface Settings" module in the WeChat Official Platform, self-enable the permission for the "Obtain current geographic location and speed" interface.

Step 2: Configure appJson

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

appJson: {
  permission: {
    'scope.userLocation': {
      desc: 'Your location information will be used to demonstrate the effect of the Mini Program location interface',
    },
  },
  requiredPrivateInfos: [ "getLocation" ]
}

Step 3: Complete Privacy Agreement

After publishing the official Mini Program for review, you need to complete the user privacy agreement protection. For details, refer to Mini Program Privacy Protection Guidelines Adaptation Instructions.

5. Common Issues

Mini Program Review Submission Errors

Error Message	Solution
Code contains unconfigured privacy interface getLocation in ext.json	Please refer to "Step 2: Configure appJson" above
Privacy interface getLocation configured in ext.json lacks permission	Please refer to "Step 1: Enable Location Interface Permission" above

Browser Location Failure

Error Message	Cause and Solution
Browser not Support html5 geolocation	The browser does not support the native geolocation interface, such as lower versions of IE browsers
Geolocation permission denied	User disabled location permission, need to enable device and browser location permissions; or browser prohibits location requests from non-secure domains, need to upgrade site to HTTPS
Get geolocation time out	Browser geolocation times out, you can increase the timeout setting appropriately
Get geolocation failed	Geolocation failed. Chrome, Firefox and some browsers access geolocation services located abroad, which have high failure rates

Extended Scenarios

Positioning Adjustment Range Configuration

The component provides a "Positioning Adjustment Range" attribute that constrains the user's point selection range, allowing positioning only within a certain radius of the actual current location point.

Practices for Other Scenarios

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

Example

Interactive Preview

Component Input Status

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 Headlines	labelVisible	boolean	Default value: true
Title alignment	labelAlign	string	In the scenario, the form by default follows the title alignment configuration of the form container.
Line break in heading	labelWrap	boolean	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 position	layout	string	Set title display position in form component. In the scenario, it follows the title position configuration of the form container by default.
Title width	labelWidth	string	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 Note	labelTips	string	Take effect on PC/H5 Configure tooltip content for the heading
Display clear button	clearable	boolean	Enabled, quick clear button is provided by Default value: true
Prompt.	extra	string	The prompt content is displayed below the input box after configuration.
Display longitude and latitude	showLngLat	boolean	Display longitude and latitude of the selected location
display map	showMap	boolean	Display the selected location on the map
打开微信内置地图(Mini Program)	openLocation	boolean	仅支持小程序端开启，开启后，可点击地图调起微信内置地图查看位置，或者开始导航 使用微信内置地图查看位置
Display underscore on mobile terminal	borderedH5	boolean	After closing, the mobile terminal does not show the bottom underline Default value: true
Locating adjustment range	locationRange	string	0
custom scope	customRange	number	0
Permission to scale	zoom	boolean	Permission to scale the map Default value: true
Allow drag	drag	boolean	Permission to drag the map Example: true
Status.	status	string	Example: "edit"
Required	required	boolean
Required identifier	requiredFlag	boolean	Enabled, the component will display a required asterisk tag if mandatory. Default value: true
Required validation note	requiredMsg	string	Example: "该项为必填项"
Bound field	name	string	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.	label	string	Example: "地图"
Map APIs	dataSource	object	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 position	locationType	number	Default location value Example: 1
Default value	value	object	Latitude ranges from -90 to 90; longitude ranges from -180 to 180. For location coordinates, go to Tencent Location Service Obtain Example: null
Placeholder text	placeholder	string	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 change	change	object 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 event	error	object 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 field	name	string	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.	label	string
Default value	value	object
Required	required	boolean
Indicates whether to display	visible	boolean	Whether to display the component
Whether to disable	disabled	boolean	Component Disabled
Specify whether it is read-only or not.	readOnly	boolean	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 value	setValue	object 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 Settings	setVisible	boolean显示	Set the component to hidden via $w.id1.setVisible(false)
Set Disabled	setDisabled	boolean禁用	Set the component to disabled with $w.id1.setDisabled(true)
Clear value	clearValue		Clear the component value with $w.id1.clearValue()
Set as read-only	setReadOnly	boolean只读	Set the component to read-only via $w.id1.setReadOnly(true)
Trigger validation	handleValidate		Validate the component value via $w.id1.handleValidate()
Clear verification	clearValidate		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-root	Outermost 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-root	Settable 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-root	Settable 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-root	Settable 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__label	Component 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__control	Set 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__info	Editing status - Location information style :scope .wd-location__info { font-size: 20px; color: gray; }
Editing status - Placeholder text style	.wd-location-root .form-location-con__text	Editing status - Placeholder text style :scope .form-location-con__text { color: lightgray; }
Editing status - Verification information	.wd-location-root .wd-g-text-error	Set component verification information style :scope .wd-g-text-error { font-size: 20px; color: gray; }
prompt text	.wd-location-root .wd-form-item__help-text	Set 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__info	Disabled 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-value	Set component read-only status :scope .wd-form-item__readonly-value { font-size: 20px; color: gray; }

Learn about Style API

Version Changes

• Property Changes
• Style Changes
• widget api Changes