# FXML
# createSelectorQuery
SelectorQuery ft.createSelectorQuery()
返回一个 SelectorQuery 对象实例。在自定义组件或包含自定义组件的页面中,应使用 this.createSelectorQuery() 来代替。
返回值
SelectorQuery
示例代码
const query = ft.createSelectorQuery()
query.select('#the-id').boundingClientRect()
query.selectViewport().scrollOffset()
query.exec(function(res){
res[0].top // #the-id节点的上边界坐标
res[1].scrollTop // 显示区域的竖直滚动位置
})
# createIntersectionObserver
IntersectionObserver ft.createIntersectionObserver(Object component, Object options)
创建并返回一个 IntersectionObserver 对象实例。在自定义组件或包含自定义组件的页面中,应使用 this.createIntersectionObserver([options]) 来代替。
参数
Object component
自定义组件实例
Object options
选项
属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 |
---|---|---|---|---|---|
thresholds | Array.<number> | [0] | 否 | 一个数值数组,包含所有阈值。 | |
initialRatio | number | 0 | 否 | 初始的相交比例,如果调用时检测到的相交比例与这个值不相等且达到阈值,则会触发一次监听器的回调函数。 | |
observeAll | boolean | false | 否 | 是否同时观测多个目标节点(而非一个),如果设为 true ,observe 的 targetSelector 将选中多个节点(注意:同时选中过多节点将影响渲染性能) | 2.0.0 |
返回值
IntersectionObserver
# IntersectionObserver
IntersectionObserver 对象,用于推断某些节点是否可以被用户看见、有多大比例可以被用户看见。
# IntersectionObserver.relativeTo
IntersectionObserver IntersectionObserver.relativeTo(string selector, Object margins) 使用选择器指定一个节点,作为参照区域之一。
参数
string selector
选择器
Object margins
用来扩展(或收缩)参照节点布局区域的边界
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
left | number | 否 | 节点布局区域的左边界 | |
right | number | 否 | 节点布局区域的右边界 | |
top | number | 否 | 节点布局区域的上边界 | |
bottom | number | 否 | 节点布局区域的下边界 |
返回值
IntersectionObserver
# IntersectionObserver.relativeToViewport
IntersectionObserver IntersectionObserver.relativeToViewport(Object margins) 指定页面显示区域作为参照区域之一
参数
Object margins
用来扩展(或收缩)参照节点布局区域的边界
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
left | number | 否 | 节点布局区域的左边界 | |
right | number | 否 | 节点布局区域的右边界 | |
top | number | 否 | 节点布局区域的上边界 | |
bottom | number | 否 | 节点布局区域的下边界 |
返回值
IntersectionObserver
示例代码
下面的示例代码中,如果目标节点(用选择器 .target-class 指定)进入显示区域以下 100px 时,就会触发回调函数。
Page({
onLoad: function(){
ft.createIntersectionObserver().relativeToViewport({bottom: 100}).observe('.target-class', (res) => {
res.intersectionRatio // 相交区域占目标节点的布局区域的比例
res.intersectionRect // 相交区域
res.intersectionRect.left // 相交区域的左边界坐标
res.intersectionRect.top // 相交区域的上边界坐标
res.intersectionRect.width // 相交区域的宽度
res.intersectionRect.height // 相交区域的高度
})
}
})
# IntersectionObserver.observe
IntersectionObserver.observe(string targetSelector, IntersectionObserver.observeCallback callback) 指定目标节点并开始监听相交状态变化情况
参数
string targetSelector
选择器
function callback
监听相交状态变化的回调函数
参数
Object res
属性 | 类型 | 说明 |
---|---|---|
id | string | 节点 ID |
dataset | Record.<string, any> | 节点自定义数据属性 |
intersectionRatio | number | 相交比例 |
intersectionRect | Object | 相交区域的边界 |
boundingClientRect | Object | 目标边界 |
relativeRect | Object | 参照区域的边界 |
time | number | 相交检测时的时间戳 |
res.intersectionRect 的结构
属性 | 类型 | 说明 |
---|---|---|
left | number | 左边界 |
right | number | 右边界 |
top | number | 上边界 |
bottom | number | 下边界 |
width | number | 宽度 |
height | number | 高度 |
res.boundingClientRect 的结构
属性 | 类型 | 说明 |
---|---|---|
left | number | 左边界 |
right | number | 右边界 |
top | number | 上边界 |
bottom | number | 下边界 |
width | number | 宽度 |
height | number | 高度 |
res.relativeRect 的结构
属性 | 类型 | 说明 |
---|---|---|
left | number | 左边界 |
right | number | 右边界 |
top | number | 上边界 |
bottom | number | 下边界 |
# IntersectionObserver.disconnect
IntersectionObserver.disconnect() 停止监听。回调函数将不再触发
# MediaQueryObserver
# MediaQueryObserver.disconnect
MediaQueryObserver.disconnect() 停止监听。回调函数将不再触发
# MediaQueryObserver.observe
MediaQueryObserver.observe(Object descriptor, function callback)
开始监听页面 media query 变化情况
参数
Object descriptor
media query 描述符
属性 | 类型 | 默认值 | 必填 | 说明 |
---|---|---|---|---|
minWidth | number | 是 | 页面最小宽度( px 为单位) | |
maxWidth | number | 是 | 页面最大宽度( px 为单位) | |
width | number | 是 | 页面宽度( px 为单位) | |
minHeight | number | 是 | 页面最小高度( px 为单位) | |
maxHeight | number | 是 | 页面最大高度( px 为单位) | |
height | number | 是 | 页面高度( px 为单位) | |
orientation | string | 是 | 屏幕方向( landscape 或 portrait ) |
function callback
监听 media query 状态变化的回调函数
参数
Object res
属性 | 类型 | 说明 |
---|---|---|
matches | boolean | 页面的当前状态是否满足所指定的 media query |
# NodesRef
用于获取 FXML 节点信息的对象
# NodesRef.boundingClientRect
SelectorQuery NodesRef.boundingClientRect(function callback)
添加节点的布局位置的查询请求。相对于显示区域,以像素为单位。其功能类似于 DOM 的 getBoundingClientRect
。返回 NodesRef
对应的 SelectorQuery
。
参数
function callback
回调函数,在执行 SelectorQuery.exec
方法后,节点信息会在 callback
中返回。
参数
Object res
属性 | 类型 | 说明 |
---|---|---|
id | string | 节点的 ID |
dataset | Object | 节点的 dataset |
left | number | 节点的左边界坐标 |
right | number | 节点的右边界坐标 |
top | number | 节点的上边界坐标 |
bottom | number | 节点的下边界坐标 |
width | number | 节点的宽度 |
height | number | 节点的高度 |
返回值
SelectorQuery
示例代码
Page({
getRect () {
ft.createSelectorQuery().select('#the-id').boundingClientRect(function(rect){
rect.id // 节点的ID
rect.dataset // 节点的dataset
rect.left // 节点的左边界坐标
rect.right // 节点的右边界坐标
rect.top // 节点的上边界坐标
rect.bottom // 节点的下边界坐标
rect.width // 节点的宽度
rect.height // 节点的高度
}).exec()
},
getAllRects () {
ft.createSelectorQuery().selectAll('.a-class').boundingClientRect(function(rects){
rects.forEach(function(rect){
rect.id // 节点的ID
rect.dataset // 节点的dataset
rect.left // 节点的左边界坐标
rect.right // 节点的右边界坐标
rect.top // 节点的上边界坐标
rect.bottom // 节点的下边界坐标
rect.width // 节点的宽度
rect.height // 节点的高度
})
}).exec()
}
})
# NodesRef.context
SelectorQuery NodesRef.context(function callback)
添加节点的 Context 对象查询请求。目前支持 VideoContext、CanvasContext、LivePlayerContext、EditorContext和 MapContext 的获取。
参数
function callback
回调函数,在执行 SelectorQuery.exec
方法后,返回节点信息。
参数
Object res
属性 | 类型 | 说明 |
---|---|---|
context | Object | 节点对应的 Context 对象 |
返回值
SelectorQuery
示例代码
Page({
getContext () {
ft.createSelectorQuery().select('.the-video-class').context(function(res){
console.log(res.context) // 节点对应的 Context 对象。如:选中的节点是 <video> 组件,那么此处即返回 VideoContext 对象
}).exec()
}
})
# NodesRef.fields
SelectorQuery NodesRef.fields(Object fields, function callback)
获取节点的相关信息。需要获取的字段在fields中指定。返回值是 nodesRef
对应的 selectorQuery
参数
Object fields
属性 | 类型 | 默认值 | 必填 | 说明 | 最低版本 |
---|---|---|---|---|---|
id | boolean | false | 否 | 是否返回节点 id | |
dataset | boolean | false | 否 | 是否返回节点 dataset | |
mark | boolean | false | 否 | 是否返回节点 mark | |
rect | boolean | false | 否 | 是否返回节点布局位置(left right top bottom ) | |
size | boolean | false | 否 | 是否返回节点尺寸(width height ) | |
scrollOffset | boolean | false | 否 | 否 是否返回节点的 scrollLeft scrollTop ,节点必须是 scroll-view 或者 viewport | |
properties | Array.<string> | [] | 否 | 指定属性名列表,返回节点对应属性名的当前属性值(只能获得组件文档中标注的常规属性值,id class style 和事件绑定的属性值不可获取) | |
computedStyle | Array.<string> | ] | 否 | 指定样式名列表,返回节点对应样式名的当前值 | [2.1.0 |
context | boolean | false | 否 | 是否返回节点对应的 Context 对象 | 2.4.2 |
node | boolean | false | 否 | 是否返回节点对应的 Node 实例 | 2.7.0 |
function callback
回调函数
参数
Object res
节点的相关信息
返回值
SelectorQuery
注意
computedStyle 的优先级高于 size,当同时在 computedStyle 里指定了 width/height 和传入了 size: true,则优先返回 computedStyle 获取到的 width/height。
示例代码
Page({
getFields () {
ft.createSelectorQuery().select('#the-id').fields({
dataset: true,
size: true,
scrollOffset: true,
properties: ['scrollX', 'scrollY'],
computedStyle: ['margin', 'backgroundColor'],
context: true,
}, function (res) {
res.dataset // 节点的dataset
res.width // 节点的宽度
res.height // 节点的高度
res.scrollLeft // 节点的水平滚动位置
res.scrollTop // 节点的竖直滚动位置
res.scrollX // 节点 scroll-x 属性的当前值
res.scrollY // 节点 scroll-y 属性的当前值
// 此处返回指定要返回的样式名
res.margin
res.backgroundColor
res.context // 节点对应的 Context 对象
}).exec()
}
})
# NodesRef.scrollOffset
SelectorQuery NodesRef.scrollOffset(function callback)
添加节点的滚动位置查询请求。以像素为单位。节点必须是 scroll-view
或者 viewport
,返回 NodesRef
对应的 SelectorQuery
。
参数
function callback
回调函数,在执行 SelectorQuery.exec
方法后,节点信息会在 callback
中返回。
参数
Object res
属性 | 类型 | 说明 |
---|---|---|
id | string | 节点的 ID |
dataset | Object | 节点的 dataset |
scrollLeft | number | 节点的水平滚动位置 |
scrollTop | number | 节点的竖直滚动位置 |
返回值
SelectorQuery
示例代码
Page({
getScrollOffset () {
ft.createSelectorQuery().selectViewport().scrollOffset(function(res){
res.id // 节点的ID
res.dataset // 节点的dataset
res.scrollLeft // 节点的水平滚动位置
res.scrollTop // 节点的竖直滚动位置
}).exec()
}
})
# NodesRef.node
SelectorQuery NodesRef.node(function callback)
获取 Node 节点实例。
参数
function callback
回调函数,在执行 SelectorQuery.exec 方法后,返回节点信息。
参数
Object res
属性 | 类型 | 说明 |
---|---|---|
node | Object | 节点对应的 Node 实例 |
返回值
SelectorQuery
示例代码
Page({
getNode() {
ft.createSelectorQuery().select('.canvas').node(function(res){
console.log(res.node) // 节点对应的 Canvas 实例。
}).exec()
}
})
# SelectorQuery
查询节点信息的对象
# SelectorQuery.exec
NodesRef SelectorQuery.exec(function callback)
执行所有的请求。请求结果按请求次序构成数组,在callback的第一个参数中返回。
参数
function callback
回调函数
返回值
NodesRef
# SelectorQuery.in
SelectorQuery SelectorQuery.in(Component component)
将选择器的选取范围更改为自定义组件 component
内。(初始时,选择器仅选取页面范围的节点,不会选取任何自定义组件中的节点)。
参数
Component component
自定义组件实例
返回值
SelectorQuery
示例代码
Component({
queryMultipleNodes (){
const query = ft.createSelectorQuery().in(this)
query.select('#the-id').boundingClientRect(function(res){
res.top // 这个组件内 #the-id 节点的上边界坐标
}).exec()
}
})
# SelectorQuery.select
NodesRef SelectorQuery.select(string selector)
在当前页面下选择第一个匹配选择器 selector
的节点。返回一个 NodesRef
对象实例,可以用于获取节点信息。
参数
string selector
选择器
返回值
NodesRef
selector 语法
selector类似于 CSS 的选择器,但仅支持下列语法。
- ID选择器:#the-id
- class选择器(可以连续指定多个):.a-class.another-class
- 子元素选择器:.the-parent > .the-child
- 后代选择器:.the-ancestor .the-descendant
- 跨自定义组件的后代选择器:.the-ancestor >>> .the-descendant
- 多选择器的并集:#a-node, .some-other-nodes
# SelectorQuery.selectAll
NodesRef SelectorQuery.selectAll(string selector)
在当前页面下选择匹配选择器 selector 的所有节点。
参数
string selector
选择器
返回值
NodesRef
selector 语法
selector类似于 CSS 的选择器,但仅支持下列语法。
- ID选择器:#the-id
- class选择器(可以连续指定多个):.a-class.another-class
- 子元素选择器:.the-parent > .the-child
- 后代选择器:.the-ancestor .the-descendant
- 跨自定义组件的后代选择器:.the-ancestor >>> .the-descendant
- 多选择器的并集:#a-node, .some-other-nodes
# SelectorQuery.selectViewport
NodesRef SelectorQuery.selectViewport()
选择显示区域。可用于获取显示区域的尺寸、滚动位置等信息。
返回值
NodesRef