Element

Element 模块提供了控制小程序页面元素的方法。

属性

element.tagName

标签名，小写。

  1. element.tagName: string

方法

element.$

在元素范围内获取元素。

  1. element.$(selector: string): Promise<Element>

参数说明

字段类型必填默认值说明
selectorstring是-选择器

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   let element = await page.$('.index-hd')
  4.   element = await element.$('.index-desc')
  5.   console.log(await element.text())
  6. })

element.$$

在元素范围内获取元素数组。

  1. element.$$(selector: string): Promise<Element[]>

参数说明

字段类型必填默认值说明
selectorstring是-选择器

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('.index-bd')
  4.   const elements = await element.$$('.kind-list-text')
  5.   console.log(await elements[0].text())
  6. })

element.size

获取元素大小。

  1. element.size(): Promise<Object>

返回值说明

字段类型说明
widthnumber元素宽度
heightnumber元素高度

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('.index-bd')
  4.   const { width, height } = await element.size()
  5.   console.log(width, height)
  6. })

element.offset

获取元素绝对位置。

  1. element.offset(): Promise<Object>

返回值说明

字段类型说明
leftnumber左上角 x 坐标，单位：px
topnumber左上角 y 坐标，单位：px

坐标信息以页面左上角为原点。

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('.index-bd')
  4.   const { left top } = await element.offset()
  5.   console.log(left, top)
  6. })

element.text

获取元素文本。

  1. element.text(): Promise<string>

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('.index-desc')
  4.   console.log(await element.text())
  5. })

element.attribute

获取元素特性。

  1. element.attribute(name: string): Promise<string>

参数说明

字段类型必填默认值说明
namestring是-特性名

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('.index-logo')
  4.   console.log(await element.attribute('src')) // -> 'resources/kind/logo.png'
  5. })

element.property

automator 0.9.0，基础库 2.9.5 开始支持。

获取元素属性。

  1. element.property(name: string): Promise<any>

参数说明

字段类型必填默认值说明
namestring是-属性名

element.property 与 element.attribute 主要区别如下：

  • element.attribute 获取的是标签上的值，因此它的返回类型一定是字符串，element.property 则不一定。
  • element.attribute 可以获取到 class 和 id 之类的值，element.property 不行。
  • element.property 可以获取到文档里对应组件列举的大部分属性值，比如表单 input 等组件的 value 值。

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('input')
  4.   console.log(await element.property('value'))
  5. })

element.wxml

获取元素 WXML。

  1. element.wxml(): Promise<string>

element.outerWxml

同 wxml，只是会获取到元素本身。

  1. element.outerWxml(): Promise<string>

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('.index-desc')
  4.   console.log(await element.wxml())
  5.   console.log(await element.outerWxml())
  6. })

element.value

获取元素值。

  1. element.value(): Promise<string>

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('.weui-input')
  4.   console.log(await element.value())
  5. })

element.style

获取元素样式值。

  1. element.style(name: string): Promise<string>

参数说明

字段类型必填默认值说明
namestring是-样式名

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('.index-desc')
  4.   console.log(await element.style('color')) // -> 'rgb(136, 136, 136)'
  5. })

element.tap

点击元素。

  1. element.tap(): Promise<void>

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('.kind-list-item-hd')
  4.   await element.tap()
  5. })

element.longpress

长按元素。

  1. element.longpress(): Promise<void>

element.touchstart

automator 0.8.0，基础库 2.9.1 开始支持。

手指开始触摸元素。

  1. element.touchstart(options: Object): Promise<void>

options 字段定义如下：

字段类型必填默认值说明
touchesarray<Touch>是-触摸事件，当前停留在屏幕中的触摸点信息的数组
changedTouchesarray<Touch>是-触摸事件，当前变化的触摸点信息的数组

element.touchmove

automator 0.8.0，基础库 2.9.1 开始支持。

手指触摸元素后移动。

  1. element.touchmove(options: Object): Promise<void>

options 字段同 touchstart。

element.touchend

automator 0.8.0，基础库 2.9.1 开始支持。

手指结束触摸元素。

  1. element.touchend(options: Object): Promise<void>

options 字段同 touchstart。

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('.touch')
  4.   await element.touchstart({
  5.     touches: [
  6.       {
  7.         identifier: 1,
  8.         pageX: 500,
  9.         pageY: 500
  10.       }
  11.     ],
  12.     changedTouches: [
  13.       {
  14.         identifier: 1,
  15.         pageX: 500,
  16.         pageY: 500
  17.       }
  18.     ]
  19.   })
  20.   await element.touchend({
  21.     touches: [],
  22.     changedTouches: [
  23.       {
  24.         identifier: 1,
  25.         pageX: 500,
  26.         pageY: 500
  27.       }
  28.     ]
  29.   })
  30. })

element.trigger

触发元素事件。

  1. element.trigger(type: string, detail?: Object): Promise<void>

参数说明

字段类型必填默认值说明
typestring是-触发事件类型
detailObject否-触发事件时传递的 detail 值

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('picker')
  4.   await element.trigger('change', { value: 1 })
  5. })

该方法无法改变组件状态，仅触发响应方法，也无法触发用户操作事件，即 tap，longpress 等事件，请使用对应的其它方法调用。

element.input

automator 0.9.0，基础库 2.9.5 开始支持。

输入文本，仅 input、textarea 组件可以使用。

  1. element.input(value: string): Promise<void>

参数说明

字段类型必填默认值说明
valuestring是-需要输入的文本

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('input')
  4.   await element.input('test')
  5. })

element.callMethod

automator 0.6.0，基础库 2.9.0 开始支持。

调用组件实例指定方法，仅自定义组件可以使用。

  1. element.callMethod(method: string, ...args: any[]): Promise<any>

参数说明

字段类型必填默认值说明
methodstring是-需要调用的方法名
…argsarray<any>否-方法参数

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('set-tab-bar')
  4.   await element.callMethod('navigateBack')
  5. })

element.data

automator 0.6.0，基础库 2.9.0 开始支持。

获取组件实例渲染数据，仅自定义组件可以使用。

  1. element.data(path?: string): Promise<Object>

参数说明

字段类型必填默认值说明
pathstring否-数据路径

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('set-tab-bar')
  4.   console.log(await element.data('hasSetTabBarBadge'))
  5. })

element.setData

automator 0.6.0，基础库 2.9.0 开始支持。

设置组件实例渲染数据，仅自定义组件可以使用。

  1. element.setData(data: Object): Promise<void>

参数说明

字段类型必填默认值说明
dataObject是-要改变的数据

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('set-tab-bar')
  4.   await page.setData({
  5.     hasSetTabBarBadge: true
  6.   })
  7. })

element.callContextMethod

automator 0.9.0，基础库 2.9.5 开始支持。

调用上下文 Context 对象方法，仅 video 组件可以使用。

  1. element.callContextMethod(method: string, ...args: any[]): Promise<any>

参数说明

字段类型必填默认值说明
methodstring是-需要调用的方法名
…argsarray<any>否-方法参数

video 组件必须设置了 id 才能使用。

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('video')
  4.   await element.callContextMethod('play')
  5. })

element.scrollWidth

automator 0.9.0，基础库 2.9.5 开始支持。

获取滚动宽度，仅 scroll-view 组件可以使用。

  1. element.scrollWidth(): Promise<number>

element.scrollHeight

automator 0.9.0，基础库 2.9.5 开始支持。

获取滚动高度，仅 scroll-view 组件可以使用。

  1. element.scrollHeight(): Promise<number>

element.scrollTo

automator 0.9.0，基础库 2.9.5 开始支持。

滚动到指定位置，仅 scroll-view 组件可以使用。

  1. element.scrollTo(x: number, y: number): Promise<void>

参数说明

字段类型必填默认值说明
xnumber是-横向滚动位置
ynumber是-纵向滚动位置

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('scroll-view')
  4.   const y = (await element.scrollHeight()) - 50
  5.   await element.scrollTo(0, y)
  6. })

element.swipeTo

automator 0.9.0，基础库 2.9.5 开始支持。

滑动到指定滑块，仅 swiper 组件可以使用。

  1. element.swipeTo(index: number): Promise<void>

参数说明

字段类型必填默认值说明
indexnumber是-目标滑块的 index

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('swiper')
  4.   await element.swipeTo(2)
  5. })

element.moveTo

automator 0.9.0，基础库 2.9.5 开始支持。

移动视图容器，仅 movable-view 组件可以使用。

  1. element.moveTo(x: number, y: number): Promise<void>

参数说明

字段类型必填默认值说明
xnumber是-x 轴方向的偏移
ynumber是-y 轴方向的偏移

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('movable-view')
  4.   await element.moveTo(40, 40)
  5. })

element.slideTo

automator 0.9.0，基础库 2.9.5 开始支持。

滑动到指定数值，仅 slider 组件可以使用。

  1. element.slideTo(value: number): Promise<void>

参数说明

字段类型必填默认值说明
valuenumber是-要设置的值

示例代码：

  1. automator.launch().then(async miniProgram => {
  2.   const page = await miniProgram.currentPage()
  3.   const element = await page.$('slider')
  4.   await element.slideTo(10)
  5. })