Skip to main content
Supported Regions:上海

Map Location

WdLocation

Notes​

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 key Quota Description.

Applicable Scenarios​

Enabling location pinning in forms

Image df955fc69a826d22169315c9fdaaa3bfImage 760de127f263be54a6ad5a89633384d4

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.

Configuration Guide​

  1. 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.

  2. For Mini Program usage, configure according to the following steps

    1. 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 (specific categories are introduced in the wx.getLocation documentation click to view). Additionally, 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.

      img

    2. Due to Mini Program restrictions: To enable developers to normally use interfaces such as obtaining approximate geographic locations and to optimize subsequent code review processes, starting from July 14, 2022, developers must pre-configure in the app.json file when using location-related interfaces. WeChat Documentation Please open the commom/mp_config file in the low-code editor and configure the following properties in appJson.

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

  3. Description of Mini Program submission for review error scenarios (Open the console to view error messages)

    1. Error message: Request to WeChat interface data error; 61040; The code contains unconfigured privacy interface getLocation in ext.json (temporary..._use set to true). Please refer to step 2 in the Mini Program configuration above to configure the appJson file.
    2. Error message: Request to WeChat interface data error; 61040; The privacy interface getLocation configured in ext.json lacks permission. Apply for permission before resubmitting for review. Refer to step 1 in the Mini Program configuration above to apply for the wx.getLocation interface permission.

  4. Description of browser location failure scenarios

    1) Browser not Support html5 geolocation: The browser does not support the native geolocation interface, such as lower versions of IE browsers, etc.

    2) Geolocation permission denied: The location permission has been disabled by the user. The user needs to enable location permissions for both the device and browser, and click the "Allow location access" option in the browser pop-up window.

    3) Geolocation permission denied: The browser prohibits location requests from non-secure domains. For example, Chrome and iOS 10 have progressively banned such requests. In this case, you need to upgrade the site to HTTPS. Note that Chrome does not prohibit location access under HTTP protocol for domains like localhost.

    4) Geolocation permission denied: Access to geolocation was blocked over secure connection with mixed content, meaning http resources are referenced within an Https page.

    5) Get geolocation time out: Browser geolocation times out, including native timeouts. You can increase the timeout setting appropriately to reduce this occurrence. Additionally, the geolocation interface of certain browsers (such as google Chrome) is a 'black hole', where location requests receive no response at all, resulting in timeout failures.

    6) Get geolocation failed: Geolocation failed. Chrome, Firefox, and some shell browsers access geolocation services located abroad, which face significant restrictions and have a high failure rate.

  5. Quota Limits Description: After the map location component is configured with the Tencent Maps API, the quota limits of Tencent Maps API will directly impact the functionality of the map location component. For details, refer to: Quota Limits 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=*

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.

Image 8eb3dd4638111675a8083ecf322e4dbfImage 1010569f3c90ed9275bc5158d9bd21db

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 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

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​

  • Property Changes
  • Style Changes
  • widget api Changes