diff --git a/docs/worktile/auto/api.md b/docs/worktile/auto/api.md index 3e68a0788f32ff9ee979c24607957317a9ed80b9..26e5ab456e021296756bae7f78e769c98bda08d5 100644 --- a/docs/worktile/auto/api.md +++ b/docs/worktile/auto/api.md @@ -1,26 +1,406 @@ # API -### Page +## program + +program 是uni-automator自动注入的全局对象 + + +### 方法 + +#### program.pageStack + +获取页面堆栈。 + +`program.pageStack(): Promise ` + + +#### program.navigateTo + +保留当前页面,跳转到应用内的某个页面,同 `uni.navigateTo`。 + +`program.navigateTo(url: string): Promise` + + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|url|string|是|-|需要跳转的应用内非 tabBar 的页面的路径| + +示例代码: + +``` + const page = await program.navigateTo('/pages/index/index') + console.log(page.path)// -> 'page/index/index' +``` + + + +#### program.redirectTo + +关闭当前页面,跳转到应用内的某个页面,同 `uni.redirectTo`。 + +`program.redirectTo(url: string): Promise` + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|url|string|是|-|需要跳转的应用内非 tabBar 的页面的路径| + + +#### program.navigateBack + +关闭当前页面,返回上一页面或多级页面,同 `uni.navigateBack`。 + + +`program.navigateBack(): Promise` + + + +#### program.reLaunch + +关闭所有页面,打开到应用内的某个页面,同 `uni.reLaunch`。 + +`program.reLaunch(url: string): Promise` + + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|url|string|是|-|需要跳转的应用内页面路径| + + +#### program.switchTab + +跳转到 tabBar 页面,并关闭其他所有非 tabBar 页面,同 `uni.switchTab`。 + + +`program.switchTab(url: string): Promise` + + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|url|string|是|-|需要跳转的 tabBar 页面的路径| + + +#### program.currentPage + +获取当前页面。 + +`program.currentPage(): Promise` + + +#### program.systemInfo + +获取系统信息,同 `uni.getSystemInfo`。 + + +`program.systemInfo(): Promise` + + +示例代码: + +``` + const systemInfo = await program.systemInfo() + if (systemInfo.uniPlatform === 'devtools') { + // Do something + } +``` + + + +#### program.pageScrollTo + +将页面滚动到目标位置,同 `uni.pageScrollTo`。 + + +`program.pageScrollTo(scrollTop: number): Promise` + + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|scrollTop|number|是|-|滚动到页面的目标位置,单位 px| + +示例代码: + +``` + const page = await program.currentPage() + await program.pageScrollTo(20) + console.log(await page.scrollTop()) +``` + + + + +#### program.callUniMethod + +调用 uni 对象上的指定方法。 + + +`program.callUniMethod(method: string, ...args: any[]): Promise` + + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|method|string|是|-|需要调用的方法名| +|...args|`array`|否|-|方法参数| + +调用异步方法时无需传入 success 及 fail 回调函数。 + +示例代码: + +``` + await program.callUniMethod('setStorage', { + key: 'test', + data: '123456' + }) + const data = await program.callUniMethod('getStorageSync', 'test') + console.log(data) // -> '123456' +``` + + + +#### program.screenshot + +对当前页面截图,目前只有开发者工具模拟器支持,客户端无法使用。 + +`program.screenshot(options?: Object): Promise` + + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|options|Object|否|-|截图选项| + +如果不传 options,该方法返回图片数据的 base64 编码。 + +options 字段定义如下: + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|path|string|是|-|图片保存路径| + + +``` + it('screenshot', async () => { + await program.screenshot({ + path: "static/screenshot.png" // 默认项目根目录 + }) + }); +``` + + + +#### program.mockUniMethod + +覆盖 uni 对象上指定方法的调用结果。 + +利用该接口,你可以很方便地直接指定 `uni.chooseLocation` 等调用系统组件的返回结果。 + + +`program.mockUniMethod(method: string, result: any): Promise ` + + +参数说明 + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|method|string|是|-|需要覆盖的方法名| +|result|any|是|-|指定调用结果| + + +`program.mockUniMethod(method: string, fn: Function | string, ...args: any[]): Promise` + +参数说明 + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|method|string|是|-|需要覆盖的方法名| +|fn|Function string|是|-|处理返回函数| +|...args|`array`|否|-|传入参数| + + +> fn 同 program.evaluate 的 appFunction 参数一样,无法使用闭包来引用外部变量。此外,你还可以在方法内使用 this.origin 来调用原始方法。 + + +示例代码: + +``` + await program.mockUniMethod('showModal', { + confirm: true, + cancel: false + }) + + await program.mockUniMethod( + 'getStorageSync', + function(key, defVal) { + if (key === 'name') return 'redhoodsu' + if (key === 'sex') return 'male' + return defVal + }, + 'unknown', + ) + // 调用 uni.getStorageSync('name') 返回 'redhoodsu' + + // 更改 getSystemInfo 中的 platform 字段 + await program.mockUniMethod( + 'getSystemInfo', + function(obj, platform) { + return new Promise(resolve => { + // origin 指向原始方法 + this.origin({ + success(res) { + res.platform = platform + resolve(res) + }, + }) + }) + }, + 'test', + ) +``` + + +#### program.restoreUniMethod + +重置 uni 指定方法,消除 mockUniMethod 调用的影响。 + +`program.restoreUniMethod(method: string): Promise` + + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|method|string|是|-|需要覆盖的方法名| + + +示例代码: + +``` + console.log(await program.callUniMethod('getStorageSync', 'test')) // -> '' + await program.mockUniMethod('getStorageSync', 'mockValue') + console.log(await program.callUniMethod('getStorageSync', 'test')) // -> 'mockValue' + await program.restoreUniMethod('getStorageSync') + console.log(await program.callUniMethod('getStorageSync', 'test')) // -> '' +``` + + + +#### program.evaluate + +注入代码片段并返回执行结果。(仅微信小程序支持) + +`program.evaluate(appFunction: Function | string, ...args: any[]): Promise` + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|appFunction|Function string|是|-|代码片段| +|...args|`array`|否|-|执行时传入参数| + +> appFunction 最终会被序列化传递到开发者工具,因此你无法在函数中利用闭包来引用外部变量。也就是说,传递 function () {} 函数事实上等同于传递其字符串。 + +示例代码: + +``` + let systemInfo = await program.evaluate(() => { + return new Promise(resolve => { + uni.getSystemInfo({ + success(result) { + resolve(result) + } + }) + }) + }) + systemInfo = await program.evaluate(() => { + return uni.getSystemInfoSync() + }) + console.log(systemInfo) + await program.evaluate(key => { + uni.setStorageSync(key, 'test') + }, 'test') + const hasLogin = await program.evaluate(() => getApp().globalData.hasLogin) + console.log(hasLogin) +``` + + + +#### program.testAccounts + +获取多账号调试中已添加的用户列表。(仅微信小程序支持) + + +`program.testAccounts(): Promise` + +Account 字段定义如下: + + +|字段|类型|说明| +|:-:|:-:|:-:| +|nickName|string|用户昵称| +|openid|string|账号 openid| + +示例代码: + +``` + const testAccounts = await program.testAccounts() + for (let i = 0, len = testAccounts.length; i < len; i++) { + const miniProgram = await automator.launch({ + projectPath: 'path/to/project', + account: testAccounts[i].openid + }) + // 控制多个用户登录的不同小程序 + } +``` + + +#### program.exposeFunction + +在全局暴露方法,供小程序侧调用测试脚本中的方法(仅微信小程序支持) + + +`program.exposeFunction(name: string, bindingFunction: Function): Promise` + + +|字段|类型|必填|默认值|说明| +|:-:|:-:|:-:|:-:|:-:| +|name|string|是|-|全局方法名| +|bindingFunction|Function|是|-|脚本方法| + +> 你可以利用该方法来监听事件,不支持在小程序侧获取调用结果。 + + +示例代码: + +``` + await program.exposeFunction('onAppShow', options => { + // Do something... + }) + await program.evaluate(function() { + uni.onAppShow(function(options) { + onAppShow(options) + }) + }) +``` + + + + + +## Page Page 模块提供了控制页面的方法。 -#### 属性 +### 属性 -page.path +#### page.path 页面路径。 `page.path: string` -page.query +#### page.query 页面参数。 `page.query: Object` -#### 方法 +### 方法 -page.$ +#### page.$ 获取页面元素。 @@ -40,7 +420,7 @@ page.$ ``` -page.$$ +#### page.$$ 获取页面元素数组。 @@ -62,7 +442,7 @@ page.$$ console.log(elements.length) ``` -page.waitFor +#### page.waitFor 等待直到指定条件成立。 @@ -93,7 +473,7 @@ page.waitFor }) // 等待页面中 picker 元素数量大于 5 ``` -page.data +#### page.data 获取页面渲染数据。 @@ -113,7 +493,7 @@ page.data ``` -page.setData +#### page.setData 设置页面渲染数据。 @@ -135,7 +515,7 @@ page.setData ``` -page.size +#### page.size 获取页面大小。 @@ -158,7 +538,7 @@ page.size ``` -page.scrollTop +#### page.scrollTop 获取页面滚动位置。 @@ -173,7 +553,7 @@ page.scrollTop ``` -page.callMethod +#### page.callMethod 调用页面指定方法。 @@ -196,21 +576,21 @@ page.callMethod -### Element +## Element Element 模块提供了控制页面元素的方法。 -#### 属性 +### 属性 -element.tagName +#### element.tagName 标签名,小写。 `element.tagName: string` -#### 方法 +### 方法 -element.$ +#### element.$ 在元素范围内获取元素。 @@ -232,7 +612,7 @@ element.$ ``` -element.$$ +#### element.$$ 在元素范围内获取元素数组。 @@ -254,7 +634,7 @@ element.$$ ``` -element.size +#### element.size 获取元素大小。 @@ -277,7 +657,7 @@ element.size ``` -element.offset +#### element.offset 获取元素绝对位置。 @@ -303,7 +683,7 @@ element.offset ``` -element.text +#### element.text 获取元素文本。 @@ -318,7 +698,7 @@ element.text ``` -element.attribute +#### element.attribute 获取元素特性。 @@ -339,7 +719,7 @@ element.attribute ``` -element.property +#### element.property 获取元素属性。 @@ -369,14 +749,14 @@ element.property ``` -element.html +#### element.html 获取元素 HTML。 `element.html(): Promise` -element.outerHtml +#### element.outerHtml 同 html,只是会获取到元素本身。 @@ -392,7 +772,7 @@ element.outerHtml ``` -element.value +#### element.value 获取元素值。 @@ -407,7 +787,7 @@ element.value ``` -element.style +#### element.style 获取元素样式值。 @@ -428,7 +808,7 @@ element.style ``` -element.tap +#### element.tap 点击元素。 @@ -443,14 +823,14 @@ element.tap ``` -element.longpress +#### element.longpress 长按元素。 `element.longpress(): Promise` -element.touchstart +#### element.touchstart 手指开始触摸元素。 @@ -465,7 +845,7 @@ options 字段定义如下: |changedTouches|array|是|-|触摸事件,当前变化的触摸点信息的数组| -element.touchmove +#### element.touchmove 手指触摸元素后移动。 @@ -474,7 +854,7 @@ element.touchmove options 字段同 touchstart。 -element.touchend +#### element.touchend 手指结束触摸元素。 @@ -515,7 +895,7 @@ options 字段同 touchstart。 ``` -element.trigger +#### element.trigger 触发元素事件。 @@ -538,7 +918,7 @@ element.trigger 该方法无法改变组件状态,仅触发响应方法,也无法触发用户操作事件,即 `tap`,`longpress` 等事件,请使用对应的其它方法调用。 -element.input +#### element.input 输入文本,仅 input、textarea 组件可以使用。 @@ -559,7 +939,7 @@ element.input ``` -element.callMethod +#### element.callMethod 调用组件实例指定方法,仅自定义组件可以使用。 @@ -581,7 +961,7 @@ element.callMethod ``` -element.data +#### element.data 获取组件实例渲染数据,仅自定义组件可以使用。 @@ -602,7 +982,7 @@ element.data ``` -element.setData +#### element.setData 设置组件实例渲染数据,仅自定义组件可以使用。 @@ -625,7 +1005,7 @@ element.setData ``` -element.callContextMethod +#### element.callContextMethod 调用上下文 Context 对象方法,仅 video 组件可以使用。 @@ -648,21 +1028,21 @@ video 组件必须设置了 id 才能使用。 ``` -element.scrollWidth +#### element.scrollWidth 获取滚动宽度,仅 scroll-view 组件可以使用。 `element.scrollWidth(): Promise` -element.scrollHeight +#### element.scrollHeight 获取滚动高度,仅 scroll-view 组件可以使用。 `element.scrollHeight(): Promise` -element.scrollTo +#### element.scrollTo 滚动到指定位置,仅 scroll-view 组件可以使用。 @@ -685,7 +1065,7 @@ element.scrollTo ``` -element.swipeTo +#### element.swipeTo 滑动到指定滑块,仅 swiper 组件可以使用。 @@ -706,7 +1086,7 @@ element.swipeTo ``` -element.moveTo +#### element.moveTo 移动视图容器,仅 movable-view 组件可以使用。 @@ -728,7 +1108,7 @@ element.moveTo ``` -element.slideTo +#### element.slideTo 滑动到指定数值,仅 slider 组件可以使用。 @@ -750,10 +1130,9 @@ element.slideTo ``` +## 平台差异 -**平台差异** - -#### program(全局对象) +### program(全局对象) |方法 |APP-NVUE |APP-VUE|H5 |微信小程序 |百度小程序 |说明 | |-- |-- |-- |-- |-- |-- |-- | @@ -774,7 +1153,7 @@ element.slideTo |evaluate |x |x |x |√ |x |注入代码片段并返回执行结果 | |exposeFunction |x |x |x |√ |x |在全局暴露方法,供小程序侧调用测试脚本中的方法 | -#### Page +### Page |属性 |APP-NVUE |APP-VUE|H5 |微信小程序 |百度小程序 |说明 | |-- |-- |-- |-- |-- |-- |-- | @@ -792,7 +1171,7 @@ element.slideTo |scrollTop |√ |√ |√ |√ |√ |获取页面滚动位置 | |callMethod |√ |√ |√ |√ |√ |调用页面指定方法 | -#### Element +### Element |属性 |APP-NVUE |APP-VUE|H5 |微信小程序 |百度小程序 |说明 | |-- |-- |-- |-- |-- |-- |-- | |tagName|√ |√ |√ |√ |√ |标签名,小写 | @@ -829,7 +1208,7 @@ element.slideTo |slideTo |√ |√ |√ |√ |x |滑动到指定数值,仅 slider 组件可以使用 | -#### 测试平台判断 +### 测试平台判断 ``` if (process.env.UNI_PLATFORM === "h5") {} if (process.env.UNI_PLATFORM === "app-plus") {}