tencent cloud

All product documents
Tencent Cloud Super App as a Service
Last updated: 2025-03-20 18:01:56
WXML
Last updated: 2025-03-20 18:01:56

createSelectorQuery

The application of this API is through SelectorQuery wx.createSelectorQuery().
Function Description: Returns an instance of the SelectorQuery object. In custom components or pages containing custom components, replace with this.createSelectorQuery().
Return Value: SelectorQuery.
Sample Code:
const query = wx.createSelectorQuery()
query.select('#the-id').boundingClientRect()
query.selectViewport().scrollOffset()
query.exec(function (res) {
res[0].top // The upper boundary coordinate of the #the-id node.
res[1].scrollTop // The vertical scroll position of the display area.
})

createIntersectionObserver

The usage of this API is IntersectionObserver wx.createIntersectionObserver(Object component, Object options).
Function Description: Creates and returns an instance of the IntersectionObserver object. In custom components or pages containing custom components, this.createIntersectionObserver([options]) should be used as a substitute.
Parameters and Description: Object this
Object component, a custom component instance;
Object options, with the following legal values:
Attributes
Types
Default value
Required
Note
thresholds
Array.<number>
[0]
Not required
An array of numerical values, encompassing all thresholds.
initialRatio
number
0
Not required
The initial intersection ratio, if the detected intersection ratio at the time of invocation is not equivalent to this value and reaches the threshold, it will trigger a callback function of the listener once.
observeAll
boolean
false
Not required
Whether to observe multiple target nodes simultaneously (rather than a single one). If set to true, the targetSelector of observe will select multiple nodes (be aware: selecting too many nodes at once may impact rendering performance).
Return Value: IntersectionObserver.

IntersectionObserver

IntersectionObserver object, used to infer whether certain nodes can be seen by the user and what percentage can be seen by the user.

.relativeTo

The method is utilized as follows: IntersectionObserver.relativeTo(string selector, Object margins)
Function Description: Utilize a selector to designate a node, serving as one of the reference areas.
Parameters and Description:
string selector, the selector;
Object margins, the boundaries used to expand (or contract) the layout area of the reference node.
Attributes
Types
Default value
Required
Note
left
number
-
Not required
The left boundary of the node's layout area.
right
number
-
Not required
The right boundary of the node's layout area.
top
number
-
Not required
The upper boundary of the node's layout area.
bottom
number
-
Not required
The lower boundary of the node's layout area.

.relativeToViewport

The method is utilized as IntersectionObserver.relativeToViewport(Object margins).
Function Description: Designates the page display area as one of the reference regions.
Parameters and Description: Object margins, utilized to expand (or contract) the boundaries of the reference node's layout area.
Attributes
Types
Default value
Required
Note
left
number
-
Not required
The left boundary of the node's layout area.
right
number
-
Not required
The right boundary of the node's layout area.
top
number
-
Not required
The upper boundary of the node's layout area.
bottom
number
-
Not required
The lower boundary of the node's layout area.
Example Code
In the following example code, if the target node (specified by the selector .target-class) enters 100px below the display area, the callback function will be triggered.
Page({
onLoad() {
wx.createIntersectionObserver().rela
onLoad: function(){
wx.createIntersectionObserver().relativeToViewport({bottom: 100}).observe('.target-class', (res) => {
res.intersectionRatio // the ratio of the intersection region to the layout region of the target node
res.intersectionRect // intersection region
res.intersectionRect.left // coordinates of the left boundary of the intersection region
res.intersectionRect.top // the upper boundary of the intersection region
res.intersectionRect.width // width of the intersection region
res.intersectionRect.height // height of the intersection region
})
}
})

.disconnect

The method is utilized as IntersectionObserver.disconnect().
Function Description: Ceases monitoring, the callback function will no longer be triggered.

.observe

The method is utilized as IntersectionObserver.observe(string targetSelector, function callback).
Function Description: Designates the target node and commences monitoring for changes in intersection status.
Parameters and Description:
string targetSelector, selector;
function callback, a callback function that listens for changes in the intersection state, with the following arguments Object res:
Parameters for the Callback Function Monitoring Intersection Status Changes: Object res.
Structural attributes
Types
Note
intersectionRatio
number
Intersection Ratio
intersectionRect
object
Boundary of the Intersection Area
boundingClientRect
object
Target Boundary
relativeRect
object
Boundary of the Reference Area
time
number
Timestamp during Intersection Detection
Structure of res.intersectionRect
Structural attributes
Types
Note
left
number
Left Boundary
right
number
Right Boundary
top
number
Upper Boundary
bottom
number
Lower Boundary
Structure of res.
boundingClientRect

Structural attributes
Types
Note
left
number
Left Boundary
right
number
Right Boundary
top
number
Upper Boundary
bottom
number
Lower Boundary
Structure of
res.relativeRect

Structural attributes
Types
Note
left
number
Left Boundary
right
number
Right Boundary
top
number
Upper Boundary
bottom
number
Lower Boundary

NodesRef

An object used to obtain information about a WXML node.

.fields

The method is utilized as NodesRef.fields(Object fields, function callback)
Function Description: Get information about the node. The fields to be fetched are specified in fields. The return value is the selectorQuery corresponding to nodesRef.
Parameters and Description:
Object fields, the legal parameters are as follows.
Attributes
Types
Default value
Required
Note
id
boolean
false
Not required
Whether to return the node id
dataset
boolean
false
Not required
Whether to return the node dataset
rect
boolean
false
Not required
Whether to return the layout position of the node (left, right, top, bottom)
size
boolean
false
Not required
Whether to return the dimensions of the node (width, height)
scrollOffset
boolean
false
Not required
Whether to return the scrollLeft scrollTop of the node, the node must be a scroll-view or viewport
properties
Array.<string>
-
Not required
Specify a list of attribute names to return the current attribute values of the corresponding node (only the regular attribute values marked in the component documentation can be obtained, the attribute values of id, class, style, and event binding cannot be retrieved)
computedStyle
Array.<string>
-
Not required
Specify a list of style names to return the current values of the corresponding style names for the node
context
boolean
false
Not required
Whether to return the corresponding Context object of the node
Note:
The priority of computedStyle is higher than size. If width/height is specified in computedStyle and size: true is passed in at the same time, the width/height obtained from computedStyle will be returned preferentially.
function callback, callback function, argument Object res is node related information.
Return Value: The selectorQuery corresponding to nodesRef.
Sample Code
Page({
getFields () {
wx.createSelectorQuery().select('#the-id').fields({
dataset: true,
size: true,
scrollOffset: true,
properties: ['scrollX', 'scrollY'],
computedStyle: ['margin', 'backgroundColor'],
context: true, }, function (res) { {
}, function (res) {
res.dataset // the node's dataset
res.width // width of the node
res.height // the height of the node
res.scrollLeft // The horizontal scroll position of the node.
res.scrollTop // The vertical scroll position of the node.
res.scrollX // The current value of the node's scroll-x property.
res.scrollY // The current value of the node's scroll-y property.
// This returns the name of the style to be returned.
res.margin
res.backgroundColor
res.context // The node's corresponding Context object.
res.ref // The Ref object for the node.
res.ref // Ref object for the node }).exec()
}
})

.boundingClientRect

The method is used as follows:SelectorQuery NodesRef.boundingClientRect(function callback)
Function Description: Adds a query request for the layout position of the node. Relative to the display area, in pixels. Its function is similar to the getBoundingClientRect of the DOM.
Parameters and Description: function callback. This is a callback function. After executing the SelectorQuery.exec method, the node information will be returned in the callback.
Object res
Attributes
Types
Note
id
string
Node's ID
dataset
Object
Node's dataset
left
number
Node's left boundary coordinate
right
number
Node's right boundary coordinate
top
number
Node's upper boundary coordinate
bottom
number
Node's lower boundary coordinate
width
number
Node's width
height
number
Node's height
Return Value: SelectorQuery.
Sample Code:
Page({
getRect() {
wx.createSelectorQuery().select('#the-id').boundingClientRect(function (rect) {
rect.id // Node's ID
rect.dataset // Node's dataset
rect.left // Node's left boundary coordinate
rect.right // Node's right boundary coordinate
rect.top // Node's upper boundary coordinate
rect.bottom // Node's lower boundary coordinate
rect.width // Node's width
rect.height // Node's height
}).exec()
},
getAllRects() {
wx.createSelectorQuery().selectAll('.a-class').boundingClientRect(function (rects) {
rects.forEach(function (rect) {
rect.id // Node's ID
rect.dataset // Node's dataset
rect.left // Node's left boundary coordinate
rect.right // Node's right boundary coordinate
rect.top // Node's upper boundary coordinate
rect.bottom // Node's lower boundary coordinate
rect.width // Node's width
rect.height // Node's height
})
}).exec()
}
})

.scrollOffset

The method is utilized as SelectorQuery NodesRef.scrollOffset(function callback)
Function Description: Adds a query request for the node's scroll position. Measured in pixels. The node must be a scroll-view or a viewport.
Parameters and Description: function callback, a callback function, after executing the SelectorQuery.exec method, the node information will be returned in the callback.
Object res
Attributes
Types
Note
id
string
Node's ID
dataset
Object
Node's dataset
scrollLeft
number
Node's horizontal scroll position
scrollTop
number
Node's vertical scroll position
Return Value: SelectorQuery.
Sample Code:
Page({
getScrollOffset() {
wx.createSelectorQuery().selectViewport().scrollOffset(function (res) {
res.id // Node's ID
res.dataset // Node's dataset
res.scrollLeft // Node's horizontal scroll position
res.scrollTop // Node's vertical scroll position
}).exec()
}
})

.context

The method is utilized as follows: SelectorQuery NodesRef.context(function callback)
Function Description: Adds a query request for the Context object of the node. Currently supports the acquisition of MapContext.
Parameters and Description: function callback, a callback function that returns node information after executing the SelectorQuery.exec method.
Object res。
Attributes
Types
Note
context
Object
Context object corresponding to the node
Return Value: SelectorQuery.
Sample Code:
Page({
getContext() {
wx.createSelectorQuery().select('.the-video-class').context(function (res) {
console.log(res.context) // Context object corresponding to the node. For instance, if the selected node is a <map> component, then a MapContext object is returned here.
}).exec()
}
})

.node

The method is employed as follows: SelectorQuery NodesRef.node(NodesRef.nodeCallback callback)
Function Description: Get Node node instance. Currently supports ScrollViewContext and Canvas.
Parameters and Description: function callback, a callback function that returns node information upon the execution of the SelectorQuery.exec method.
Object res
Attributes
Types
Note
node
Object
Node instance corresponding to the node
Return Value: SelectorQuery.
Sample Code:
Page({
getNode() {
wx.createSelectorQuery().select('.canvas').node(function(res){
console.log(res.node) // Canvas instance corresponding to the node.
}).exec()
}
})

SelectorQuery

Object for querying node information.

.exec

The method is utilized as follows: NodesRef SelectorQuery.exec(function callback)
Function Description: Executes all requests. The results of the requests are arranged in an array according to the order of the requests and returned in the first parameter of the callback.
Parameters and Description: function callback, a callback function.
Return Value: NodesRef.

.in

The method is utilized as follows: SelectorQuery SelectorQuery.in(Component component)
Function Description: Modifies the selection range of the selector to be within the custom component, component. (Initially, the selector only selects nodes within the page range and does not select any nodes within custom components).
Parameters and Description: Component component, a custom component instance.
Return Value: SelectorQuery.
Sample Code:
Component({
queryMultipleNodes() {
const query = wx.createSelectorQuery().in(this)
query.select('#the-id').boundingClientRect(function (res) {
res.top // The upper boundary coordinate of the #the-id node within this component.
}).exec()
}
})

.select

The method is utilized as follows: NodesRef SelectorQuery.select(string selector)
Function Description: Selects the first node that matches the selector, selector, on the current page. Returns an instance of a NodesRef object, which can be used to retrieve node information.
Parameters and Description: string selector, the selector.
Return Value:NodesRef
Selector Syntax: The selector is similar to a CSS selector, but only supports the following syntax.
ID Selector: #the-id.
Class Selector (multiple can be specified consecutively): .a-class.another-class.
Child Selector: .the-parent > .the-child.
Descendant Selector: .the-ancestor .the-descendant.
Cross-component Descendant Selector: .the-ancestor >>> .the-descendant.
Union of Multiple Selectors: #a-node, .some-other-nodes.

.selectAll

The method is utilized as follows: NodesRef SelectorQuery.selectAll(string selector)
Function Description: Selects all nodes matching the selector 'selector' within the current page.
Parameters and Description: string selector, the selector.
Return Value:NodesRef
Selector Syntax: The selector is similar to a CSS selector, but only supports the following syntax.
ID Selector: #the-id.
Class Selector (multiple can be specified consecutively): .a-class.another-class.
Child Selector: .the-parent > .the-child.
Descendant Selector: .the-ancestor .the-descendant.
Cross-component Descendant Selector: .the-ancestor >>> .the-descendant.
Union of Multiple Selectors: #a-node, .some-other-nodes.

.selectViewport

The method is utilized as follows: NodesRef SelectorQuery.selectViewport()
Function Description: Selects the display area. This can be used to obtain information such as the size of the display area and the scroll position.
Return Value:NodesRef

MediaQueryObserver

MediaQueryObserver object, utilized for monitoring changes in the media query status, such as whether the interface's length and width are within a specified range.

.disconnect

The method is utilized as follows: MediaQueryObserver.disconnect()
Function Description: Ceases monitoring. The callback function will no longer be triggered.

.observe

The method is utilized as follows: MediaQueryObserver.observe(Object descriptor, function callback)
Function Description: Initiates monitoring of media query changes.
Parameters and Descriptions:
Object descriptor, a descriptor for the media query.
Attributes
Types
Default value
Required
Note
minWidth
number
-
Supported
Minimum page width (in pixels)
maxWidth
number
-
Supported
Maximum page width (in pixels)
width
number
-
Supported
Page width (in pixels)
minHeight
number
-
Supported
Minimum page height (in pixels)
maxHeight
number
-
Supported
Maximum page height (in pixels)
height
number
-
Supported
Page height (in pixels)
orientation
string
-
Supported
Screen orientation (landscape or portrait)
function callback, a callback function that listens for changes in the state of the media query. The arguments Object res are as follows:
Attributes
Types
Note
matches
boolean
Whether the current status of the page satisfies the specified media query.

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 available.

7x24 Phone Support