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