diff --git a/packages/taro-router/src/__tests__/router-test.tsx b/packages/taro-router/src/__tests__/router-test.tsx index 82e9cc0d2b6f..1d49673183df 100644 --- a/packages/taro-router/src/__tests__/router-test.tsx +++ b/packages/taro-router/src/__tests__/router-test.tsx @@ -76,7 +76,7 @@ describe('router component', () => { } } - const routerComponent = + const routerComponent: any = const getComputedStyle = window.getComputedStyle Nerv.render(routerComponent, document.createElement('div')) const dom = routerComponent.dom diff --git a/packages/taro-router/src/router/route.tsx b/packages/taro-router/src/router/route.tsx index 9ec502860d10..b18b6e4e663f 100644 --- a/packages/taro-router/src/router/route.tsx +++ b/packages/taro-router/src/router/route.tsx @@ -147,7 +147,7 @@ class Route extends Taro.Component {
+ style={{ height: '100%' }}>
) diff --git a/packages/taro-router/src/router/router.tsx b/packages/taro-router/src/router/router.tsx index 579c030e6447..657acbc20809 100644 --- a/packages/taro-router/src/router/router.tsx +++ b/packages/taro-router/src/router/router.tsx @@ -156,7 +156,7 @@ class Router extends Taro.Component { return (
+ style={{ height: '100%' }}> {this.state.routeStack.map(({ path, componentLoader, isIndex, key, isRedirect }, k) => { return ( +} diff --git a/packages/taro/types/api/base/base.d.ts b/packages/taro/types/api/base/base.d.ts new file mode 100644 index 000000000000..424b8e0461ec --- /dev/null +++ b/packages/taro/types/api/base/base.d.ts @@ -0,0 +1,47 @@ +declare namespace Taro { + /** + * **注意：此接口从基础库 1.1.1 版本开始支持。** + * + * 判断小程序的API，回调，参数，组件等是否在当前版本可用。 + * + * **String参数说明：** 使用`${API}.${method}.${param}.${options}`或者`${component}.${attribute}.${option}`方式来调用，例如： + * + * * `${API}` 代表 API 名字 + * * `${method}` 代表调用方式，有效值为`return`, `success`, `object`, `callback` + * * `${param}` 代表参数或者返回值 + * * `${options}` 代表参数的可选值 + * * `${component}` 代表组件名字 + * * `${attribute}` 代表组件属性 + * * `${option}` 代表组件属性的可选值 + * + * 例子： + * + * **示例：** + * + ```js + Taro.canIUse('openBluetoothAdapter') + Taro.canIUse('getSystemInfoSync.return.screenWidth') + Taro.canIUse('getSystemInfo.success.screenWidth') + Taro.canIUse('showToast.object.image') + Taro.canIUse('onCompassChange.callback.direction') + Taro.canIUse('request.object.method.GET') + Taro.canIUse('live-player') + Taro.canIUse('text.selectable') + Taro.canIUse('button.open-type.contact') + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/wx.canIUse.html + */ + function canIUse(String: any): boolean + + type arrayBuffer = Uint8Array | Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | ArrayBuffer + + /** + * 将 Base64 字符串转成 ArrayBuffer 数据 + */ + function base64ToArrayBuffer(base64: string): arrayBuffer + + /** + * 将 ArrayBuffer 数据转成 Base64 字符串 + */ + function arrayBufferToBase64(buffer: arrayBuffer): string +} diff --git a/packages/taro/types/api/base/base.debug.d.ts b/packages/taro/types/api/base/base.debug.d.ts new file mode 100644 index 000000000000..f26309728e9a --- /dev/null +++ b/packages/taro/types/api/base/base.debug.d.ts @@ -0,0 +1,84 @@ +declare namespace Taro { + namespace setEnableDebug { + type Promised = { + /** + * 调用结果 + */ + errMsg: string + } + type Param = { + /** + * 是否打开调试 + */ + enableDebug: boolean + } + } + /** + * @since 1.4.0 + * + * 设置是否打开调试开关，此开关对正式版也能生效。 + * + * **示例代码：** + * + ```javascript + // 打开调试 + Taro.setEnableDebug({ + enableDebug: true + }) + // 关闭调试 + Taro.setEnableDebug({ + enableDebug: false + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/wx.setEnableDebug.html + */ + function setEnableDebug(OBJECT: setEnableDebug.Param): Promise + + namespace getLogManager { + type Param = { + /** + * @since 2.3.2 + * + * 取值为0/1，取值为0表示是否会把 App、Page 的生命周期函数和 wx 命名空间下的函数调用写入日志，取值为1则不会。默认值是 0 + */ + level?: number + } + type Return = { + /** + * 写 debug 日志 + */ + debug(...args: any[]): void + /** + * 写 info 日志 + */ + info(...args: any[]): void + /** + * 写 log 日志 + */ + log(...args: any[]): void + /** + * 写 warn 日志 + */ + warn(...args: any[]): void + } + } + /** + * @since 2.1.0 + * + * 获取日志管理器对象。 + * + * **示例代码：** + * + ```javascript + const logger = Taro.getLogManager({level: 1}) + logger.log({str: 'hello world'}, 'basic log', 100, [1, 2, 3]) + logger.info({str: 'hello world'}, 'info log', 100, [1, 2, 3]) + logger.debug({str: 'hello world'}, 'debug log', 100, [1, 2, 3]) + logger.warn({str: 'hello world'}, 'warn log', 100, [1, 2, 3]) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/wx.getLogManager.html + */ + function getLogManager(OBJECT?: getLogManager.Param): getLogManager.Return + + // TODO: wx.getRealtimeLogManager +} diff --git a/packages/taro/types/api/base/base.system.d.ts b/packages/taro/types/api/base/base.system.d.ts new file mode 100644 index 000000000000..f9d9f67ce79a --- /dev/null +++ b/packages/taro/types/api/base/base.system.d.ts @@ -0,0 +1,195 @@ +declare namespace Taro { + /** + * 系统信息 + */ + + namespace getSystemInfoSync { + type Return = { + /** + * 手机品牌 + * + * @since 1.5.0 + */ + brand: string + /** + * 手机型号 + */ + model: string + /** + * 设备像素比 + */ + pixelRatio: number + /** + * 屏幕宽度 + * + * @since 1.1.0 + */ + screenWidth: number + /** + * 屏幕高度 + * + * @since 1.1.0 + */ + screenHeight: number + /** + * 可使用窗口宽度 + */ + windowWidth: number + /** + * 可使用窗口高度 + */ + windowHeight: number + /** + * 状态栏的高度 + * + * @since 1.9.0 + */ + statusBarHeight: number + /** + * 微信设置的语言 + */ + language: string + /** + * 微信版本号 + */ + version: string + /** + * 操作系统版本 + */ + system: string + /** + * 客户端平台 + */ + platform: string + /** + * 用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准，单位：px + * + * @since 1.5.0 + */ + fontSizeSetting: number + /** + * 客户端基础库版本 + * + * @since 1.1.0 + */ + SDKVersion: string + } + } + /** + * 获取系统信息同步接口 + * + * **示例代码：** + * + ```javascript + try { + var res = Taro.getSystemInfoSync() + console.log(res.model) + console.log(res.pixelRatio) + console.log(res.windowWidth) + console.log(res.windowHeight) + console.log(res.language) + console.log(res.version) + console.log(res.platform) + } catch (e) { + // Do something when catch error + } + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/system/system-info/wx.getSystemInfoSync.html + */ + function getSystemInfoSync(): getSystemInfoSync.Return + + namespace getSystemInfo { + type Promised = { + /** + * 手机品牌 + * + * @since 1.5.0 + */ + brand: string + /** + * 手机型号 + */ + model: string + /** + * 设备像素比 + */ + pixelRatio: string + /** + * 屏幕宽度 + * + * @since 1.1.0 + */ + screenWidth: number + /** + * 屏幕高度 + * + * @since 1.1.0 + */ + screenHeight: number + /** + * 可使用窗口宽度 + */ + windowWidth: number + /** + * 可使用窗口高度 + */ + windowHeight: number + /** + * 状态栏的高度 + * + * @since 1.9.0 + */ + statusBarHeight: number + /** + * 微信设置的语言 + */ + language: string + /** + * 微信版本号 + */ + version: string + /** + * 操作系统版本 + */ + system: string + /** + * 客户端平台 + */ + platform: string + /** + * 用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准，单位：px + * + * @since 1.5.0 + */ + fontSizeSetting: number + /** + * 客户端基础库版本 + * + * @since 1.1.0 + */ + SDKVersion: string + } + type Param = {} + } + /** + * 获取系统信息。 + * + * **示例代码：** + * + ```javascript + Taro.getSystemInfo({ + success: function(res) { + console.log(res.model) + console.log(res.pixelRatio) + console.log(res.windowWidth) + console.log(res.windowHeight) + console.log(res.language) + console.log(res.version) + console.log(res.platform) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/system/system-info/wx.getSystemInfo.html + */ + function getSystemInfo(OBJECT?: getSystemInfo.Param): Promise +} diff --git a/packages/taro/types/api/base/base.update.d.ts b/packages/taro/types/api/base/base.update.d.ts new file mode 100644 index 000000000000..096ff94d8c01 --- /dev/null +++ b/packages/taro/types/api/base/base.update.d.ts @@ -0,0 +1,81 @@ +declare namespace Taro { + /** + * @since 1.9.90 + * + * 获取**全局唯一**的版本更新管理器，用于管理小程序更新。 + * + * 关于小程序的更新机制，可以查看 [运行机制](https://developers.weixin.qq.com/miniprogram/dev/framework/runtime/operating-mechanism.html) 文档。 + * + * **示例代码：** + * + ```javascript + const updateManager = Taro.getUpdateManager() + updateManager.onCheckForUpdate(function (res) { + // 请求完新版本信息的回调 + console.log(res.hasUpdate) + }) + updateManager.onUpdateReady(function () { + Taro.showModal({ + title: '更新提示', + content: '新版本已经准备好，是否重启应用？', + success: function (res) { + if (res.confirm) { + // 新的版本已经下载好，调用 applyUpdate 应用新版本并重启 + updateManager.applyUpdate() + } + } + }) + }) + updateManager.onUpdateFailed(function () { + // 新的版本下载失败 + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/update/wx.getUpdateManager.html + */ + function getUpdateManager(): UpdateManager + + namespace UpdateManager { + namespace onCheckForUpdate { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * 是否有新的版本 + */ + hasUpdate: boolean + } + } + } + + class UpdateManager { + /** + * 当向微信后台请求完新版本信息，会进行回调 + * + * **注：** 检查更新操作由微信在小程序冷启动时自动触发，不需由开发者主动触发，开发者只需监听检查结果即可。 + */ + onCheckForUpdate(callback: UpdateManager.onCheckForUpdate.Param): any + /** + * 当新版本下载完成，会进行回调 + * + * **onUpdateReady(callback) 回调结果说明：** + * + * 当微信检查到小程序有新版本，会主动触发下载操作（无需开发者触发），当下载完成后，会通过 `onUpdateReady` 告知开发者。 + */ + onUpdateReady(callback: any): any + /** + * 当新版本下载失败，会进行回调 + * + * **onUpdateFailed(callback) 回调结果说明：** + * + * 当微信检查到小程序有新版本，会主动触发下载操作（无需开发者触发），如果下载失败（可能是网络原因等），会通过 `onUpdateFailed` 告知开发者。 + */ + onUpdateFailed(callback: any): any + /** + * 当新版本下载完成，调用该方法会强制当前小程序应用上新版本并重启 + * + * **applyUpdate() 说明：** + * + * 当小程序新版本已经下载时（即收到 `onUpdateReady` 回调），可以通过这个方法强制重启小程序并应用上最新版本。 + */ + applyUpdate(): any + } +} diff --git a/packages/taro/types/api/base/base.weapp.d.ts b/packages/taro/types/api/base/base.weapp.d.ts new file mode 100644 index 000000000000..dc03baffda43 --- /dev/null +++ b/packages/taro/types/api/base/base.weapp.d.ts @@ -0,0 +1,117 @@ +declare namespace Taro { + /** + * 生命周期 + */ + + namespace getLaunchOptionsSync { + interface Return { + /** + * 启动小程序的路径 + */ + path: string + /** + * 启动小程序的[场景值](https://developers.weixin.qq.com/miniprogram/dev/framework/app-service/scene.html) + */ + scene: number + /** + * 启动小程序的 query 参数 + */ + query: { [k: string]: any } + /** + * shareTicket，详见[获取更多转发信息](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/share.html) + */ + shareTicket: string + /** + * 来源信息。从另一个小程序、公众号或 App 进入小程序时返回。否则返回 {}。 + */ + referrerInfo: { appId: string, extraData: { [k: string]: any} } + } + } + /** + * @since 微信小程序 2.1.2 + * + * 获取小程序启动时的参数。与 `App.onLaunch` 的回调参数一致。 + * + * **注意** + * 部分版本在无 `referrerInfo` 的时候会返回 undefined， + * 建议使用 `options.referrerInfo && options.referrerInfo.appId` 进行判断。 + * + * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/app/life-cycle/wx.getLaunchOptionsSync.html + */ + function getLaunchOptionsSync(): getLaunchOptionsSync.Return + + /** + * 应用级事件 + */ + + namespace onPageNotFound { + /** + * 小程序要打开的页面不存在事件的回调函数参数 + */ + interface onPageNotFoundCallbackParam { + /** + * 不存在页面的路径 + */ + path: string, + /** + * 打开不存在页面的 query 参数 + */ + query: Object, + /** + * 是否本次启动的首个页面（例如从分享等入口进来，首个页面是开发者配置的分享页面） + */ + isEntryPage: boolean + } + /** + * 小程序要打开的页面不存在事件的回调函数 + */ + type onPageNotFoundCallback = (parma: onPageNotFoundCallbackParam) => void + } + /** + * @since 微信小程序 2.1.2 + * + * 监听小程序要打开的页面不存在事件。该事件与 `App.onPageNotFound` 的回调时机一致 + * + */ + function onPageNotFound(callback: onPageNotFound.onPageNotFoundCallback): void + + namespace onError { + interface onErrorParam { + /** + * 错误信息，包含堆栈 + */ + error: string + } + + type onErrorCallback = (param: onErrorParam) => void + } + /** + * @since 微信小程序 2.1.2 + * + * 监听小程序错误事件。如脚本错误或 API 调用报错等。该事件与 App.onError 的回调时机与参数一致 + */ + function onError(callback: onError.onErrorCallback): void + + /** + * @since 微信小程序 2.6.2 + * + * 监听音频中断结束事件。在收到 onAudioInterruptionBegin 事件之后，小程序内所有音频会暂停，收到此事件之后才可再次播放成功 + */ + function onAudioInterruptionEnd(callback: () => void): void + + /** + * @since 微信小程序 2.6.2 + * + * 监听音频因为受到系统占用而被中断开始事件。以下场景会触发此事件：闹钟、电话、FaceTime 通话、微信语音聊天、微信视频聊天。此事件触发后，小程序内所有音频会暂停 + */ + function onAudioInterruptionBegin(callback: () => void): void + + // TODO: wx.onAppShow + // TODO: wx.onAppHide + // TODO: wx.offPageNotFound + // TODO: wx.offError + // TODO: wx.offAudioInterruptionEnd + // TODO: wx.offAudioInterruptionBegin + // TODO: wx.offAppShow + // TODO: wx.offAppHide +} diff --git a/packages/taro/types/api/canvas/canvas.d.ts b/packages/taro/types/api/canvas/canvas.d.ts new file mode 100644 index 000000000000..d3d3d2542677 --- /dev/null +++ b/packages/taro/types/api/canvas/canvas.d.ts @@ -0,0 +1,1575 @@ +declare namespace Taro { + /** + * @since 微信小程序 2.7.0 + * + * 创建离屏 canvas 实例 + */ + function createOffscreenCanvas(): OffscreenCanvas + interface OffscreenCanvas { + /** + * + * @param contextType + * + * 该方法返回 OffscreenCanvas 的绘图上下文 + */ + getContext(contextType: string): any + } + + /** + * + * **定义：** + * + * 创建 canvas 绘图上下文（指定 canvasId）。在自定义组件下，第二个参数传入组件实例this，以操作组件内 `` 组件 + * + * **Tip**: 需要指定 canvasId，该绘图上下文只作用于对应的 `` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/canvas/wx.createCanvasContext.html + */ + function createCanvasContext(canvasId: string, componentInstance: any): CanvasContext + interface Color {} + namespace CanvasContext { + namespace draw { type Param1 = () => any } + } + interface CanvasContext { + /** 填充颜色。用法同 [CanvasContext.setFillStyle()]。 + * + * 最低基础库： `1.9.90` */ + fillStyle: string + /** 当前字体样式的属性。符合 [CSS font 语法](https://developer.mozilla.org/zh-CN/docs/Web/CSS/font) 的 DOMString 字符串，至少需要提供字体大小和字体族名。默认值为 10px sans-serif。 + * + * 最低基础库： `1.9.90` */ + font: string + /** 全局画笔透明度。范围 0-1，0 表示完全透明，1 表示完全不透明。 */ + globalAlpha: number + /** 在绘制新形状时应用的合成操作的类型。目前安卓版本只适用于 `fill` 填充块的合成，用于 `stroke` 线段的合成效果都是 `source-over`。 + * + * 目前支持的操作有 + * - 安卓：xor, source-over, source-atop, destination-out, lighter, overlay, darken, lighten, hard-light + * - iOS：xor, source-over, source-atop, destination-over, destination-out, lighter, multiply, overlay, darken, lighten, color-dodge, color-burn, hard-light, soft-light, difference, exclusion, saturation, luminosity + * + * 最低基础库： `1.9.90` */ + globalCompositeOperation: string + /** 线条的端点样式。用法同 [CanvasContext.setLineCap()]。 + * + * 最低基础库： `1.9.90` */ + lineCap: number + /** 虚线偏移量，初始值为0 + * + * 最低基础库： `1.9.90` */ + lineDashOffset: number + /** 线条的交点样式。用法同 [CanvasContext.setLineJoin()]。 + * + * 最低基础库： `1.9.90` */ + lineJoin: number + /** 线条的宽度。用法同 [CanvasContext.setLineWidth()]。 + * + * 最低基础库： `1.9.90` */ + lineWidth: number + /** 最大斜接长度。用法同 [CanvasContext.setMiterLimit()]。 + * + * 最低基础库： `1.9.90` */ + miterLimit: number + /** 阴影的模糊级别 + * + * 最低基础库： `1.9.90` */ + shadowBlur: number + /** 阴影的颜色 + * + * 最低基础库： `1.9.90` */ + shadowColor: number + /** 阴影相对于形状在水平方向的偏移 + * + * 最低基础库： `1.9.90` */ + shadowOffsetX: number + /** 阴影相对于形状在竖直方向的偏移 + * + * 最低基础库： `1.9.90` */ + shadowOffsetY: number + /** 边框颜色。用法同 [CanvasContext.setFillStyle()]。 + * + * 最低基础库： `1.9.90` */ + strokeStyle: string + /** [CanvasContext.arc(number x, number y, number r, number sAngle, number eAngle, boolean counterclockwise)](CanvasContext.arc.md) + * + * 创建一条弧线。 + * + * - 创建一个圆可以指定起始弧度为 0，终止弧度为 2 * Math.PI。 + * - 用 `stroke` 或者 `fill` 方法来在 `canvas` 中画弧线。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + // Draw coordinates + ctx.arc(100, 75, 50, 0, 2 Math.PI) + ctx.setFillStyle('#EEEEEE') + ctx.fill() + ctx.beginPath() + ctx.moveTo(40, 75) + ctx.lineTo(160, 75) + ctx.moveTo(100, 15) + ctx.lineTo(100, 135) + ctx.setStrokeStyle('#AAAAAA') + ctx.stroke() + ctx.setFontSize(12) + ctx.setFillStyle('black') + ctx.fillText('0', 165, 78) + ctx.fillText('0.5 PI', 83, 145) + ctx.fillText('1 PI', 15, 78) + ctx.fillText('1.5 PI', 83, 10) + // Draw points + ctx.beginPath() + ctx.arc(100, 75, 2, 0, 2 Math.PI) + ctx.setFillStyle('lightgreen') + ctx.fill() + ctx.beginPath() + ctx.arc(100, 25, 2, 0, 2 Math.PI) + ctx.setFillStyle('blue') + ctx.fill() + ctx.beginPath() + ctx.arc(150, 75, 2, 0, 2 Math.PI) + ctx.setFillStyle('red') + ctx.fill() + // Draw arc + ctx.beginPath() + ctx.arc(100, 75, 50, 0, 1.5 Math.PI) + ctx.setStrokeStyle('#333333') + ctx.stroke() + ctx.draw() + ``` + * + * ![] + * + * 针对 arc(100, 75, 50, 0, 1.5 * Math.PI)的三个关键坐标如下： + * + * - 绿色: 圆心 (100, 75) + * - 红色: 起始弧度 (0) + * - 蓝色: 终止弧度 (1.5 * Math.PI) */ + arc( + /** 圆心的 x 坐标 */ + x: number, + /** 圆心的 y 坐标 */ + y: number, + /** 圆的半径 */ + r: number, + /** 起始弧度，单位弧度（在3点钟方向） */ + sAngle: number, + /** 终止弧度 */ + eAngle: number, + /** 弧度的方向是否是逆时针 */ + counterclockwise?: boolean + ): void + /** [CanvasContext.arcTo(number x1, number y1, number x2, number y2, number radius)](CanvasContext.arcTo.md) + * + * 根据控制点和半径绘制圆弧路径。 + * + * 最低基础库： `1.9.90` */ + arcTo( + /** 第一个控制点的 x 轴坐标 */ + x1: number, + /** 第一个控制点的 y 轴坐标 */ + y1: number, + /** 第二个控制点的 x 轴坐标 */ + x2: number, + /** 第二个控制点的 y 轴坐标 */ + y2: number, + /** 圆弧的半径 */ + radius: number + ): void + /** [CanvasContext.beginPath()](CanvasContext.beginPath.md) + * + * 开始创建一个路径。需要调用 `fill` 或者 `stroke` 才会使用路径进行填充或描边 + * + * - 在最开始的时候相当于调用了一次 `beginPath`。 + * - 同一个路径内的多次 `setFillStyle`、`setStrokeStyle`、`setLineWidth`等设置，以最后一次设置为准。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + // begin path + ctx.rect(10, 10, 100, 30) + ctx.setFillStyle('yellow') + ctx.fill() + // begin another path + ctx.beginPath() + ctx.rect(10, 40, 100, 30) + // only fill this rect, not in current path + ctx.setFillStyle('blue') + ctx.fillRect(10, 70, 100, 30) + ctx.rect(10, 100, 100, 30) + // it will fill current path + ctx.setFillStyle('red') + ctx.fill() + ctx.draw() + ``` + * + * ![] */ + beginPath(): void + /** [CanvasContext.bezierCurveTo()](CanvasContext.bezierCurveTo.md) + * + * 创建三次方贝塞尔曲线路径。曲线的起始点为路径中前一个点。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + // Draw points + ctx.beginPath() + ctx.arc(20, 20, 2, 0, 2 Math.PI) + ctx.setFillStyle('red') + ctx.fill() + ctx.beginPath() + ctx.arc(200, 20, 2, 0, 2 Math.PI) + ctx.setFillStyle('lightgreen') + ctx.fill() + ctx.beginPath() + ctx.arc(20, 100, 2, 0, 2 Math.PI) + ctx.arc(200, 100, 2, 0, 2 Math.PI) + ctx.setFillStyle('blue') + ctx.fill() + ctx.setFillStyle('black') + ctx.setFontSize(12) + // Draw guides + ctx.beginPath() + ctx.moveTo(20, 20) + ctx.lineTo(20, 100) + ctx.lineTo(150, 75) + ctx.moveTo(200, 20) + ctx.lineTo(200, 100) + ctx.lineTo(70, 75) + ctx.setStrokeStyle('#AAAAAA') + ctx.stroke() + // Draw quadratic curve + ctx.beginPath() + ctx.moveTo(20, 20) + ctx.bezierCurveTo(20, 100, 200, 100, 200, 20) + ctx.setStrokeStyle('black') + ctx.stroke() + ctx.draw() + ``` + * + * ![] + * + * 针对 moveTo(20, 20) bezierCurveTo(20, 100, 200, 100, 200, 20) 的三个关键坐标如下： + * + * - 红色：起始点(20, 20) + * - 蓝色：两个控制点(20, 100) (200, 100) + * - 绿色：终止点(200, 20) */ + bezierCurveTo(): void + /** [CanvasContext.clearRect(number x, number y, number width, number height)](CanvasContext.clearRect.md) + * + * 清除画布上在该矩形区域内的内容 + * + * **示例代码** + * + * + * clearRect 并非画一个白色的矩形在地址区域，而是清空，为了有直观感受，对 canvas 加了一层背景色。 + ```html + + ``` + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.setFillStyle('red') + ctx.fillRect(0, 0, 150, 200) + ctx.setFillStyle('blue') + ctx.fillRect(150, 0, 150, 200) + ctx.clearRect(10, 10, 150, 75) + ctx.draw() + ``` + * ![] */ + clearRect( + /** 矩形路径左上角的横坐标 */ + x: number, + /** 矩形路径左上角的纵坐标 */ + y: number, + /** 矩形路径的宽度 */ + width: number, + /** 矩形路径的高度 */ + height: number + ): void + /** [CanvasContext.clip()](CanvasContext.clip.md) + * + * 从原始画布中剪切任意形状和尺寸。一旦剪切了某个区域，则所有之后的绘图都会被限制在被剪切的区域内（不能访问画布上的其他区域）。可以在使用 `clip` 方法前通过使用 `save` 方法对当前画布区域进行保存，并在以后的任意时间通过`restore`方法对其进行恢复。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + wx.downloadFile({ + url: 'http://is5.mzstatic.com/image/thumb/Purple128/v4/75/3b/90/753b907c-b7fb-5877-215a-759bd73691a4/source/50x50bb.jpg', + success: function(res) { + ctx.save() + ctx.beginPath() + ctx.arc(50, 50, 25, 0, 2 Math.PI) + ctx.clip() + ctx.drawImage(res.tempFilePath, 25, 25) + ctx.restore() + ctx.draw() + } + }) + ``` + * ![] + * + * 最低基础库： `1.6.0` */ + clip(): void + /** [CanvasContext.closePath()](CanvasContext.closePath.md) + * + * 关闭一个路径。会连接起点和终点。如果关闭路径后没有调用 `fill` 或者 `stroke` 并开启了新的路径，那之前的路径将不会被渲染。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.moveTo(10, 10) + ctx.lineTo(100, 10) + ctx.lineTo(100, 100) + ctx.closePath() + ctx.stroke() + ctx.draw() + ``` + * ![] + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + // begin path + ctx.rect(10, 10, 100, 30) + ctx.closePath() + // begin another path + ctx.beginPath() + ctx.rect(10, 40, 100, 30) + // only fill this rect, not in current path + ctx.setFillStyle('blue') + ctx.fillRect(10, 70, 100, 30) + ctx.rect(10, 100, 100, 30) + // it will fill current path + ctx.setFillStyle('red') + ctx.fill() + ctx.draw() + ``` + * + * ![] */ + closePath(): void + /** [CanvasContext.createPattern(string image, string repetition)](CanvasContext.createPattern.md) + * + * 对指定的图像创建模式的方法，可在指定的方向上重复元图像 + * + * 最低基础库： `1.9.90` */ + createPattern( + /** 重复的图像源，仅支持包内路径和临时路径 */ + image: string, + /** 如何重复图像 */ + repetition: string + ): void + /** [CanvasContext.draw(boolean reserve, function callback)](CanvasContext.draw.md) + * + * 将之前在绘图上下文中的描述（路径、变形、样式）画到 canvas 中。 + * + * **示例代码** + * + * + * 第二次 draw() reserve 为 true。所以保留了上一次的绘制结果，在上下文设置的 fillStyle 'red' 也变成了默认的 'black'。 + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.setFillStyle('red') + ctx.fillRect(10, 10, 150, 100) + ctx.draw() + ctx.fillRect(50, 50, 150, 100) + ctx.draw(true) + ``` + * ![] + * + * **示例代码** + * + * + * 第二次 draw() reserve 为 false。所以没有保留了上一次的绘制结果和在上下文设置的 fillStyle 'red'。 + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.setFillStyle('red') + ctx.fillRect(10, 10, 150, 100) + ctx.draw() + ctx.fillRect(50, 50, 150, 100) + ctx.draw() + ``` + * ![] */ + draw( + /** 本次绘制是否接着上一次绘制。即 reserve 参数为 false，则在本次调用绘制之前 native 层会先清空画布再继续绘制；若 reserve 参数为 true，则保留当前画布上的内容，本次调用 drawCanvas 绘制的内容覆盖在上面，默认 false。 */ + reserve?: boolean, + /** 绘制完成后执行的回调函数 */ + callback?: Function + ): void + /** [CanvasContext.drawImage(string imageResource, number sx, number sy, number sWidth, number sHeight, number dx, number dy, number dWidth, number dHeight)](CanvasContext.drawImage.md) + * + * 绘制图像到画布 + * + * **示例代码** + * + * + * + * 有三个版本的写法： + * + * - drawImage(imageResource, dx, dy) + * - drawImage(imageResource, dx, dy, dWidth, dHeight) + * - drawImage(imageResource, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight) 从 1.9.0 起支持 + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + wx.chooseImage({ + success: function(res){ + ctx.drawImage(res.tempFilePaths[0], 0, 0, 150, 100) + ctx.draw() + } + }) + ``` + * ![] */ + drawImage( + /** 所要绘制的图片资源 */ + imageResource: string, + /** 图像的左上角在目标 canvas 上 x 轴的位置 */ + dx: number, + /** 图像的左上角在目标 canvas 上 y 轴的位置 */ + dy: number + ): void + + drawImage( + /** 所要绘制的图片资源 */ + imageResource: string, + /** 图像的左上角在目标 canvas 上 x 轴的位置 */ + dx: number, + /** 图像的左上角在目标 canvas 上 y 轴的位置 */ + dy: number, + /** 在目标画布上绘制图像的宽度，允许对绘制的图像进行缩放 */ + dWidth: number, + /** 在目标画布上绘制图像的高度，允许对绘制的图像进行缩放 */ + dHeight: number + ): void + + drawImage( + /** 所要绘制的图片资源 */ + imageResource: string, + /** 源图像的矩形选择框的左上角 x 坐标 */ + sx: number, + /** 源图像的矩形选择框的左上角 y 坐标 */ + sy: number, + /** 源图像的矩形选择框的宽度 */ + sWidth: number, + /** 源图像的矩形选择框的高度 */ + sHeight: number, + /** 图像的左上角在目标 canvas 上 x 轴的位置 */ + dx: number, + /** 图像的左上角在目标 canvas 上 y 轴的位置 */ + dy: number, + /** 在目标画布上绘制图像的宽度，允许对绘制的图像进行缩放 */ + dWidth: number, + /** 在目标画布上绘制图像的高度，允许对绘制的图像进行缩放 */ + dHeight: number + ): void + /** [CanvasContext.fill()](CanvasContext.fill.md) + * + * 对当前路径中的内容进行填充。默认的填充色为黑色。 + * + * **示例代码** + * + * + * + * 如果当前路径没有闭合，fill() 方法会将起点和终点进行连接，然后填充。 + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.moveTo(10, 10) + ctx.lineTo(100, 10) + ctx.lineTo(100, 100) + ctx.fill() + ctx.draw() + ``` + * + * fill() 填充的的路径是从 beginPath() 开始计算，但是不会将 fillRect() 包含进去。 + * + * ![] + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + // begin path + ctx.rect(10, 10, 100, 30) + ctx.setFillStyle('yellow') + ctx.fill() + // begin another path + ctx.beginPath() + ctx.rect(10, 40, 100, 30) + // only fill this rect, not in current path + ctx.setFillStyle('blue') + ctx.fillRect(10, 70, 100, 30) + ctx.rect(10, 100, 100, 30) + // it will fill current path + ctx.setFillStyle('red') + ctx.fill() + ctx.draw() + ``` + * + * ![] */ + fill(): void + /** [CanvasContext.fillRect(number x, number y, number width, number height)](CanvasContext.fillRect.md) + * + * 填充一个矩形。用 [`setFillStyle`] 设置矩形的填充色，如果没设置默认是黑色。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.setFillStyle('red') + ctx.fillRect(10, 10, 150, 75) + ctx.draw() + ``` + * ![] */ + fillRect( + /** 矩形路径左上角的横坐标 */ + x: number, + /** 矩形路径左上角的纵坐标 */ + y: number, + /** 矩形路径的宽度 */ + width: number, + /** 矩形路径的高度 */ + height: number + ): void + /** [CanvasContext.fillText(string text, number x, number y, number maxWidth)](CanvasContext.fillText.md) + * + * 在画布上绘制被填充的文本 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.setFontSize(20) + ctx.fillText('Hello', 20, 20) + ctx.fillText('MINA', 100, 100) + ctx.draw() + ``` + * ![] */ + fillText( + /** 在画布上输出的文本 */ + text: string, + /** 绘制文本的左上角 x 坐标位置 */ + x: number, + /** 绘制文本的左上角 y 坐标位置 */ + y: number, + /** 需要绘制的最大宽度，可选 */ + maxWidth?: number + ): void + /** [CanvasContext.lineTo(number x, number y)](CanvasContext.lineTo.md) + * + * 增加一个新点，然后创建一条从上次指定点到目标点的线。用 `stroke` 方法来画线条 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.moveTo(10, 10) + ctx.rect(10, 10, 100, 50) + ctx.lineTo(110, 60) + ctx.stroke() + ctx.draw() + ``` + * ![] */ + lineTo( + /** 目标位置的 x 坐标 */ + x: number, + /** 目标位置的 y 坐标 */ + y: number + ): void + /** [CanvasContext.moveTo(number x, number y)](CanvasContext.moveTo.md) + * + * 把路径移动到画布中的指定点，不创建线条。用 `stroke` 方法来画线条 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.moveTo(10, 10) + ctx.lineTo(100, 10) + ctx.moveTo(10, 50) + ctx.lineTo(100, 50) + ctx.stroke() + ctx.draw() + ``` + * ![] */ + moveTo( + /** 目标位置的 x 坐标 */ + x: number, + /** 目标位置的 y 坐标 */ + y: number + ): void + /** [CanvasContext.quadraticCurveTo(number cpx, number cpy, number x, number y)](CanvasContext.quadraticCurveTo.md) + * + * 创建二次贝塞尔曲线路径。曲线的起始点为路径中前一个点。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + // Draw points + ctx.beginPath() + ctx.arc(20, 20, 2, 0, 2 Math.PI) + ctx.setFillStyle('red') + ctx.fill() + ctx.beginPath() + ctx.arc(200, 20, 2, 0, 2 Math.PI) + ctx.setFillStyle('lightgreen') + ctx.fill() + ctx.beginPath() + ctx.arc(20, 100, 2, 0, 2 Math.PI) + ctx.setFillStyle('blue') + ctx.fill() + ctx.setFillStyle('black') + ctx.setFontSize(12) + // Draw guides + ctx.beginPath() + ctx.moveTo(20, 20) + ctx.lineTo(20, 100) + ctx.lineTo(200, 20) + ctx.setStrokeStyle('#AAAAAA') + ctx.stroke() + // Draw quadratic curve + ctx.beginPath() + ctx.moveTo(20, 20) + ctx.quadraticCurveTo(20, 100, 200, 20) + ctx.setStrokeStyle('black') + ctx.stroke() + ctx.draw() + ``` + * + * ![] + * + * 针对 moveTo(20, 20) quadraticCurveTo(20, 100, 200, 20) 的三个关键坐标如下： + * + * - 红色：起始点(20, 20) + * - 蓝色：控制点(20, 100) + * - 绿色：终止点(200, 20) */ + quadraticCurveTo( + /** 贝塞尔控制点的 x 坐标 */ + cpx: number, + /** 贝塞尔控制点的 y 坐标 */ + cpy: number, + /** 结束点的 x 坐标 */ + x: number, + /** 结束点的 y 坐标 */ + y: number + ): void + /** [CanvasContext.rect(number x, number y, number width, number height)](CanvasContext.rect.md) + * + * 创建一个矩形路径。需要用 [`fill`] 方法将矩形真正的画到 `canvas` 中 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.rect(10, 10, 150, 75) + ctx.setFillStyle('red') + ctx.fill() + ctx.draw() + ``` + * ![] */ + rect( + /** 矩形路径左上角的横坐标 */ + x: number, + /** 矩形路径左上角的纵坐标 */ + y: number, + /** 矩形路径的宽度 */ + width: number, + /** 矩形路径的高度 */ + height: number + ): void + /** [CanvasContext.restore()](CanvasContext.restore.md) + * + * 恢复之前保存的绘图上下文。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + // save the default fill style + ctx.save() + ctx.setFillStyle('red') + ctx.fillRect(10, 10, 150, 100) + // restore to the previous saved state + ctx.restore() + ctx.fillRect(50, 50, 150, 100) + ctx.draw() + ``` + * ![] */ + restore(): void + /** [CanvasContext.rotate(number rotate)](CanvasContext.rotate.md) + * + * 以原点为中心顺时针旋转当前坐标轴。多次调用旋转的角度会叠加。原点可以用 `translate` 方法修改。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.strokeRect(100, 10, 150, 100) + ctx.rotate(20 Math.PI / 180) + ctx.strokeRect(100, 10, 150, 100) + ctx.rotate(20 Math.PI / 180) + ctx.strokeRect(100, 10, 150, 100) + ctx.draw() + ``` + * ![] */ + rotate( + /** 旋转角度，以弧度计 degrees * Math.PI/180；degrees 范围为 0-360 */ + rotate: number + ): void + /** [CanvasContext.save()](CanvasContext.save.md) + * + * 保存绘图上下文。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + // save the default fill style + ctx.save() + ctx.setFillStyle('red') + ctx.fillRect(10, 10, 150, 100) + // restore to the previous saved state + ctx.restore() + ctx.fillRect(50, 50, 150, 100) + ctx.draw() + ``` + * ![] */ + save(): void + /** [CanvasContext.scale(number scaleWidth, number scaleHeight)](CanvasContext.scale.md) + * + * 在调用后，之后创建的路径其横纵坐标会被缩放。多次调用倍数会相乘。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.strokeRect(10, 10, 25, 15) + ctx.scale(2, 2) + ctx.strokeRect(10, 10, 25, 15) + ctx.scale(2, 2) + ctx.strokeRect(10, 10, 25, 15) + ctx.draw() + ``` + * ![] */ + scale( + /** 横坐标缩放的倍数 (1 = 100%，0.5 = 50%，2 = 200%) */ + scaleWidth: number, + /** 纵坐标轴缩放的倍数 (1 = 100%，0.5 = 50%，2 = 200%) */ + scaleHeight: number + ): void + /** [CanvasContext.setFillStyle([Color] color)](CanvasContext.setFillStyle.md) + * + * 设置填充色。 + * + * **代码示例** + * + * + ```js + const ctx = wx.createCanvasContext('myCanvas') + ctx.setFillStyle('red') + ctx.fillRect(10, 10, 150, 75) + ctx.draw() + ``` + * ![] */ + setFillStyle( + /** [Color] + * + * 填充的颜色，默认颜色为 black。 */ + color: Color + ): void + /** [CanvasContext.setFontSize(number fontSize)](CanvasContext.setFontSize.md) + * + * 设置字体的字号 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.setFontSize(20) + ctx.fillText('20', 20, 20) + ctx.setFontSize(30) + ctx.fillText('30', 40, 40) + ctx.setFontSize(40) + ctx.fillText('40', 60, 60) + ctx.setFontSize(50) + ctx.fillText('50', 90, 90) + ctx.draw() + ``` + * ![] */ + setFontSize( + /** 字体的字号 */ + fontSize: number + ): void + /** [CanvasContext.setGlobalAlpha(number alpha)](CanvasContext.setGlobalAlpha.md) + * + * 设置全局画笔透明度。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.setFillStyle('red') + ctx.fillRect(10, 10, 150, 100) + ctx.setGlobalAlpha(0.2) + ctx.setFillStyle('blue') + ctx.fillRect(50, 50, 150, 100) + ctx.setFillStyle('yellow') + ctx.fillRect(100, 100, 150, 100) + ctx.draw() + ``` + * ![] */ + setGlobalAlpha( + /** 透明度。范围 0-1，0 表示完全透明，1 表示完全不透明。 */ + alpha: number + ): void + /** [CanvasContext.setLineCap(string lineCap)](CanvasContext.setLineCap.md) + * + * 设置线条的端点样式 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.beginPath() + ctx.moveTo(10, 10) + ctx.lineTo(150, 10) + ctx.stroke() + ctx.beginPath() + ctx.setLineCap('butt') + ctx.setLineWidth(10) + ctx.moveTo(10, 30) + ctx.lineTo(150, 30) + ctx.stroke() + ctx.beginPath() + ctx.setLineCap('round') + ctx.setLineWidth(10) + ctx.moveTo(10, 50) + ctx.lineTo(150, 50) + ctx.stroke() + ctx.beginPath() + ctx.setLineCap('square') + ctx.setLineWidth(10) + ctx.moveTo(10, 70) + ctx.lineTo(150, 70) + ctx.stroke() + ctx.draw() + ``` + * ![] */ + setLineCap( + /** 线条的结束端点样式 */ + lineCap: string + ): void + /** [CanvasContext.setLineDash(Array. pattern, number offset)](CanvasContext.setLineDash.md) + * + * 设置虚线样式。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.setLineDash([10, 20], 5); + ctx.beginPath(); + ctx.moveTo(0,100); + ctx.lineTo(400, 100); + ctx.stroke(); + ctx.draw() + ``` + * ![] + * + * 最低基础库： `1.6.0` */ + setLineDash( + /** 一组描述交替绘制线段和间距（坐标空间单位）长度的数字 */ + pattern: Array, + /** 虚线偏移量 */ + offset: number + ): void + /** [CanvasContext.setLineJoin(string lineJoin)](CanvasContext.setLineJoin.md) + * + * 设置线条的交点样式 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.beginPath() + ctx.moveTo(10, 10) + ctx.lineTo(100, 50) + ctx.lineTo(10, 90) + ctx.stroke() + ctx.beginPath() + ctx.setLineJoin('bevel') + ctx.setLineWidth(10) + ctx.moveTo(50, 10) + ctx.lineTo(140, 50) + ctx.lineTo(50, 90) + ctx.stroke() + ctx.beginPath() + ctx.setLineJoin('round') + ctx.setLineWidth(10) + ctx.moveTo(90, 10) + ctx.lineTo(180, 50) + ctx.lineTo(90, 90) + ctx.stroke() + ctx.beginPath() + ctx.setLineJoin('miter') + ctx.setLineWidth(10) + ctx.moveTo(130, 10) + ctx.lineTo(220, 50) + ctx.lineTo(130, 90) + ctx.stroke() + ctx.draw() + ``` + * ![] */ + setLineJoin( + /** 线条的结束交点样式 */ + lineJoin: string + ): void + /** [CanvasContext.setLineWidth(number lineWidth)](CanvasContext.setLineWidth.md) + * + * 设置线条的宽度 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.beginPath() + ctx.moveTo(10, 10) + ctx.lineTo(150, 10) + ctx.stroke() + ctx.beginPath() + ctx.setLineWidth(5) + ctx.moveTo(10, 30) + ctx.lineTo(150, 30) + ctx.stroke() + ctx.beginPath() + ctx.setLineWidth(10) + ctx.moveTo(10, 50) + ctx.lineTo(150, 50) + ctx.stroke() + ctx.beginPath() + ctx.setLineWidth(15) + ctx.moveTo(10, 70) + ctx.lineTo(150, 70) + ctx.stroke() + ctx.draw() + ``` + * + * ![] */ + setLineWidth( + /** 线条的宽度，单位px */ + lineWidth: number + ): void + /** [CanvasContext.setMiterLimit(number miterLimit)](CanvasContext.setMiterLimit.md) + * + * 设置最大斜接长度。斜接长度指的是在两条线交汇处内角和外角之间的距离。当 [CanvasContext.setLineJoin()] 为 miter 时才有效。超过最大倾斜长度的，连接处将以 lineJoin 为 bevel 来显示。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.beginPath() + ctx.setLineWidth(10) + ctx.setLineJoin('miter') + ctx.setMiterLimit(1) + ctx.moveTo(10, 10) + ctx.lineTo(100, 50) + ctx.lineTo(10, 90) + ctx.stroke() + ctx.beginPath() + ctx.setLineWidth(10) + ctx.setLineJoin('miter') + ctx.setMiterLimit(2) + ctx.moveTo(50, 10) + ctx.lineTo(140, 50) + ctx.lineTo(50, 90) + ctx.stroke() + ctx.beginPath() + ctx.setLineWidth(10) + ctx.setLineJoin('miter') + ctx.setMiterLimit(3) + ctx.moveTo(90, 10) + ctx.lineTo(180, 50) + ctx.lineTo(90, 90) + ctx.stroke() + ctx.beginPath() + ctx.setLineWidth(10) + ctx.setLineJoin('miter') + ctx.setMiterLimit(4) + ctx.moveTo(130, 10) + ctx.lineTo(220, 50) + ctx.lineTo(130, 90) + ctx.stroke() + ctx.draw() + ``` + * ![] */ + setMiterLimit( + /** 最大斜接长度 */ + miterLimit: number + ): void + /** [CanvasContext.setShadow(number offsetX, number offsetY, number blur, string color)](CanvasContext.setShadow.md) + * + * 设定阴影样式。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.setFillStyle('red') + ctx.setShadow(10, 50, 50, 'blue') + ctx.fillRect(10, 10, 150, 75) + ctx.draw() + ``` + * ![] */ + setShadow( + /** 阴影相对于形状在水平方向的偏移，默认值为 0。 */ + offsetX: number, + /** 阴影相对于形状在竖直方向的偏移，默认值为 0。 */ + offsetY: number, + /** 阴影的模糊级别，数值越大越模糊。范围 0- 100。，默认值为 0。 */ + blur: number, + /** 阴影的颜色。默认值为 black。 */ + color: string + ): void + /** [CanvasContext.setStrokeStyle([Color] color)](CanvasContext.setStrokeStyle.md) + * + * 设置描边颜色。 + * + * **代码示例** + * + * + ```js + const ctx = wx.createCanvasContext('myCanvas') + ctx.setStrokeStyle('red') + ctx.strokeRect(10, 10, 150, 75) + ctx.draw() + ``` + * ![] */ + setStrokeStyle( + /** [Color] + * + * 描边的颜色，默认颜色为 black。 */ + color: Color + ): void + /** [CanvasContext.setTextAlign(string align)](CanvasContext.setTextAlign.md) + * + * 设置文字的对齐 + * + * **示例代码** + * + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.setStrokeStyle('red') + ctx.moveTo(150, 20) + ctx.lineTo(150, 170) + ctx.stroke() + ctx.setFontSize(15) + ctx.setTextAlign('left') + ctx.fillText('textAlign=left', 150, 60) + ctx.setTextAlign('center') + ctx.fillText('textAlign=center', 150, 80) + ctx.setTextAlign('right') + ctx.fillText('textAlign=right', 150, 100) + ctx.draw() + ``` + * + * ![] + * + * 最低基础库： `1.1.0` */ + setTextAlign( + /** 文字的对齐方式 */ + align: string + ): void + /** [CanvasContext.setTextBaseline(string textBaseline)](CanvasContext.setTextBaseline.md) + * + * 设置文字的竖直对齐 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.setStrokeStyle('red') + ctx.moveTo(5, 75) + ctx.lineTo(295, 75) + ctx.stroke() + ctx.setFontSize(20) + ctx.setTextBaseline('top') + ctx.fillText('top', 5, 75) + ctx.setTextBaseline('middle') + ctx.fillText('middle', 50, 75) + ctx.setTextBaseline('bottom') + ctx.fillText('bottom', 120, 75) + ctx.setTextBaseline('normal') + ctx.fillText('normal', 200, 75) + ctx.draw() + ``` + * ![] + * + * 最低基础库： `1.4.0` */ + setTextBaseline( + /** 文字的竖直对齐方式 */ + textBaseline: string + ): void + /** [CanvasContext.setTransform(number scaleX, number scaleY, number skewX, number skewY, number translateX, number translateY)](CanvasContext.setTransform.md) + * + * 使用矩阵重新设置（覆盖）当前变换的方法 + * + * 最低基础库： `1.9.90` */ + setTransform( + /** 水平缩放 */ + scaleX: number, + /** 垂直缩放 */ + scaleY: number, + /** 水平倾斜 */ + skewX: number, + /** 垂直倾斜 */ + skewY: number, + /** 水平移动 */ + translateX: number, + /** 垂直移动 */ + translateY: number + ): void + /** [CanvasContext.stroke()](CanvasContext.stroke.md) + * + * 画出当前路径的边框。默认颜色色为黑色。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.moveTo(10, 10) + ctx.lineTo(100, 10) + ctx.lineTo(100, 100) + ctx.stroke() + ctx.draw() + ``` + * ![] + * + * stroke() 描绘的的路径是从 beginPath() 开始计算，但是不会将 strokeRect() 包含进去。 + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + // begin path + ctx.rect(10, 10, 100, 30) + ctx.setStrokeStyle('yellow') + ctx.stroke() + // begin another path + ctx.beginPath() + ctx.rect(10, 40, 100, 30) + // only stoke this rect, not in current path + ctx.setStrokeStyle('blue') + ctx.strokeRect(10, 70, 100, 30) + ctx.rect(10, 100, 100, 30) + // it will stroke current path + ctx.setStrokeStyle('red') + ctx.stroke() + ctx.draw() + ``` + * + * ![] */ + stroke(): void + /** [CanvasContext.strokeRect(number x, number y, number width, number height)](CanvasContext.strokeRect.md) + * + * 画一个矩形(非填充)。 用 [`setStrokeStyle`] 设置矩形线条的颜色，如果没设置默认是黑色。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.setStrokeStyle('red') + ctx.strokeRect(10, 10, 150, 75) + ctx.draw() + ``` + * ![] */ + strokeRect( + /** 矩形路径左上角的横坐标 */ + x: number, + /** 矩形路径左上角的纵坐标 */ + y: number, + /** 矩形路径的宽度 */ + width: number, + /** 矩形路径的高度 */ + height: number + ): void + /** [CanvasContext.strokeText(string text, number x, number y, number maxWidth)](CanvasContext.strokeText.md) + * + * 给定的 (x, y) 位置绘制文本描边的方法 + * + * 最低基础库： `1.9.90` */ + strokeText( + /** 要绘制的文本 */ + text: string, + /** 文本起始点的 x 轴坐标 */ + x: number, + /** 文本起始点的 y 轴坐标 */ + y: number, + /** 需要绘制的最大宽度，可选 */ + maxWidth?: number + ): void + /** [CanvasContext.transform(number scaleX, number scaleY, number skewX, number skewY, number translateX, number translateY)](CanvasContext.transform.md) + * + * 使用矩阵多次叠加当前变换的方法 + * + * 最低基础库： `1.9.90` */ + transform( + /** 水平缩放 */ + scaleX: number, + /** 垂直缩放 */ + scaleY: number, + /** 水平倾斜 */ + skewX: number, + /** 垂直倾斜 */ + skewY: number, + /** 水平移动 */ + translateX: number, + /** 垂直移动 */ + translateY: number + ): void + /** [CanvasContext.translate(number x, number y)](CanvasContext.translate.md) + * + * 对当前坐标系的原点 (0, 0) 进行变换。默认的坐标系原点为页面左上角。 + * + * **示例代码** + * + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + ctx.strokeRect(10, 10, 150, 100) + ctx.translate(20, 20) + ctx.strokeRect(10, 10, 150, 100) + ctx.translate(20, 20) + ctx.strokeRect(10, 10, 150, 100) + ctx.draw() + ``` + * + * ![] */ + translate( + /** 水平坐标平移量 */ + x: number, + /** 竖直坐标平移量 */ + y: number + ): void + /** [Object CanvasContext.measureText(string text)](CanvasContext.measureText.md) + * + * 测量文本尺寸信息。目前仅返回文本宽度。同步接口。 + * + * 最低基础库： `1.9.90` */ + measureText( + /** 要测量的文本 */ + text: string + ): TextMetrics + /** [[CanvasGradient] CanvasContext.createCircularGradient(number x, number y, number r)](CanvasContext.createCircularGradient.md) + * + * 创建一个圆形的渐变颜色。起点在圆心，终点在圆环。返回的`CanvasGradient`对象需要使用 [CanvasGradient.addColorStop()] 来指定渐变点，至少要两个。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + // Create circular gradient + const grd = ctx.createCircularGradient(75, 50, 50) + grd.addColorStop(0, 'red') + grd.addColorStop(1, 'white') + // Fill with gradient + ctx.setFillStyle(grd) + ctx.fillRect(10, 10, 150, 80) + ctx.draw() + ``` + * ![] */ + createCircularGradient( + /** 圆心的 x 坐标 */ + x: number, + /** 圆心的 y 坐标 */ + y: number, + /** 圆的半径 */ + r: number + ): CanvasGradient + /** [[CanvasGradient] CanvasContext.createLinearGradient(number x0, number y0, number x1, number y1)](CanvasContext.createLinearGradient.md) + * + * 创建一个线性的渐变颜色。返回的`CanvasGradient`对象需要使用 [CanvasGradient.addColorStop()] 来指定渐变点，至少要两个。 + * + * **示例代码** + * + * + ```javascript + const ctx = wx.createCanvasContext('myCanvas') + // Create linear gradient + const grd = ctx.createLinearGradient(0, 0, 200, 0) + grd.addColorStop(0, 'red') + grd.addColorStop(1, 'white') + // Fill with gradient + ctx.setFillStyle(grd) + ctx.fillRect(10, 10, 150, 80) + ctx.draw() + ``` + * ![] */ + createLinearGradient( + /** 起点的 x 坐标 */ + x0: number, + /** 起点的 y 坐标 */ + y0: number, + /** 终点的 x 坐标 */ + x1: number, + /** 终点的 y 坐标 */ + y1: number + ): CanvasGradient + } + + namespace canvasToTempFilePath { + type Param0 = { + /** + * 画布x轴起点（默认0） + * + * @since 1.2.0 + */ + x?: number + /** + * 画布y轴起点（默认0） + * + * @since 1.2.0 + */ + y?: number + /** + * 画布宽度（默认为canvas宽度-x） + * + * @since 1.2.0 + */ + width?: number + /** + * 画布高度（默认为canvas高度-y） + * + * @since 1.2.0 + */ + height?: number + /** + * 输出图片宽度（默认为width） + * + * @since 1.2.0 + */ + destWidth?: number + /** + * 输出图片高度（默认为height） + * + * @since 1.2.0 + */ + destHeight?: number + /** + * 画布标识，传入 [``](https://developers.weixin.qq.com/miniprogram/dev/component/canvas.html) 的 canvas-id + */ + canvasId: string + /** + * 目标文件的类型，只支持 'jpg' 或 'png'。默认为 'png' + * + * @since 1.7.0 + */ + fileType?: string + /** + * 图片的质量，取值范围为 (0, 1]，不在范围内时当作1.0处理 + * + * @since 1.7.0 + */ + quality?: number + /** + * 接口调用成功的回调函数 + */ + success?: Param0PropSuccess + /** + * 接口调用失败的回调函数 + */ + fail?: Param0PropFail + /** + * 接口调用结束的回调函数（调用成功、失败都会执行） + */ + complete?: Param0PropComplete + } + /** + * 接口调用成功的回调函数 + */ + type Param0PropSuccess = (res: any) => any + /** + * 接口调用失败的回调函数 + */ + type Param0PropFail = (err: any) => any + /** + * 接口调用结束的回调函数（调用成功、失败都会执行） + */ + type Param0PropComplete = () => any + } + /** + * 把当前画布指定区域的内容导出生成指定大小的图片，并返回文件路径。 + * + * **Bug & Tip：** + * + * 1. `tip`: 在 `draw` 回调里调用该方法才能保证图片导出成功。 + * + * **示例代码：** + * + ```javascript + Taro.canvasToTempFilePath({ + x: 100, + y: 200, + width: 50, + height: 50, + destWidth: 100, + destHeight: 100, + canvasId: 'myCanvas', + success: function(res) { + console.log(res.tempFilePath) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/canvas/wx.canvasToTempFilePath.html + */ + function canvasToTempFilePath(OBJECT: canvasToTempFilePath.Param0, instance?: any): void + + namespace canvasPutImageData { + type Param = { + /** + * 画布标识，传入 [``](https://developers.weixin.qq.com/miniprogram/dev/component/canvas.html) 的 canvas-id + */ + canvasId: string + /** + * 图像像素点数据，一维数组，每四项表示一个像素点的rgba + */ + data: Uint8ClampedArray + /** + * 源图像数据在目标画布中的位置偏移量（x 轴方向的偏移量） + */ + x: number + /** + * 源图像数据在目标画布中的位置偏移量（y 轴方向的偏移量） + */ + y: number + /** + * 源图像数据矩形区域的宽度 + */ + width: number + /** + * 源图像数据矩形区域的高度 + */ + height?: number + } + } + /** + * @since 1.9.0 + * + * 将像素数据绘制到画布的方法 + * + * **示例代码：** + * + ```javascript + const data = new Uint8ClampedArray([255, 0, 0, 1]) + Taro.canvasPutImageData({ + canvasId: 'myCanvas', + x: 0, + y: 0, + width: 1, + data: data, + success(res) {} + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/canvas/wx.canvasPutImageData.html + */ + function canvasPutImageData(OBJECT: canvasPutImageData.Param): Promise + + namespace canvasGetImageData { + type Promised = { + /** + * errMsg + */ + errMsg: string + /** + * 图像数据矩形的宽度 + */ + width: number + /** + * 图像数据矩形的高度 + */ + height: number + /** + * 图像像素点数据，一维数组，每四项表示一个像素点的rgba + */ + data: Uint8ClampedArray + } + type Param = { + /** + * 画布标识，传入 [``](https://developers.weixin.qq.com/miniprogram/dev/component/canvas.html) 的 canvas-id + */ + canvasId: string + /** + * 将要被提取的图像数据矩形区域的左上角 x 坐标 + */ + x: number + /** + * 将要被提取的图像数据矩形区域的左上角 y 坐标 + */ + y: number + /** + * 将要被提取的图像数据矩形区域的宽度 + */ + width: number + /** + * 将要被提取的图像数据矩形区域的高度 + */ + height: number + } + } + /** + * @since 1.9.0 + * + * 返回一个数组，用来描述 canvas 区域隐含的像素数据 + * + * **示例代码：** + * + ```javascript + Taro.canvasGetImageData({ + canvasId: 'myCanvas', + x: 0, + y: 0, + width: 100, + height: 100, + success(res) { + console.log(res.width) // 100 + console.log(res.height) // 100 + console.log(res.data instanceof Uint8ClampedArray) // true + console.log(res.data.length) // 100 100 4 + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/canvas/wx.canvasGetImageData.html + */ + function canvasGetImageData(OBJECT: canvasGetImageData.Param): Promise + + // TODO: RenderingContext +} diff --git a/packages/taro/types/api/cloud/cloud.d.ts b/packages/taro/types/api/cloud/cloud.d.ts new file mode 100644 index 000000000000..beafe5819762 --- /dev/null +++ b/packages/taro/types/api/cloud/cloud.d.ts @@ -0,0 +1,514 @@ +declare namespace Taro { + namespace cloud { + interface ICloudConfig { + env?: string | object + traceUser?: boolean + } + interface IAPIError { + errMsg: string + } + + interface IAPIParam { + config?: ICloudConfig + success?: (res: T) => void + fail?: (err: IAPIError) => void + complete?: (val: T | IAPIError) => void + } + + interface IAPISuccessParam { + errMsg: string + } + + class InternalSymbol {} + type AnyObject = { + [x: string]: any + } + type AnyFunction = (...args: any[]) => any + namespace ICloud { + interface ICloudAPIParam extends IAPIParam { + config?: ICloudConfig + } + // === API: callFunction === + export type CallFunctionData = AnyObject + + export interface CallFunctionResult extends IAPISuccessParam { + result: any + } + + export interface CallFunctionParam extends ICloudAPIParam { + name: string + data?: CallFunctionData + slow?: boolean + } + // === end === + + // === API: uploadFile === + export interface UploadFileResult extends IAPISuccessParam { + fileID: string + statusCode: number + } + + export interface UploadFileParam extends ICloudAPIParam { + cloudPath: string + filePath: string + header?: AnyObject + } + // === end === + + // === API: downloadFile === + export interface DownloadFileResult extends IAPISuccessParam { + tempFilePath: string + statusCode: number + } + + export interface DownloadFileParam extends ICloudAPIParam { + fileID: string + cloudPath?: string + } + // === end === + + // === API: getTempFileURL === + export interface GetTempFileURLResult extends IAPISuccessParam { + fileList: GetTempFileURLResultItem[] + } + + export interface GetTempFileURLResultItem { + fileID: string + tempFileURL: string + maxAge: number + status: number + errMsg: string + } + + export interface GetTempFileURLParam extends ICloudAPIParam { + fileList: string[] + } + // === end === + + // === API: deleteFile === + interface DeleteFileResult extends IAPISuccessParam { + fileList: DeleteFileResultItem[] + } + + interface DeleteFileResultItem { + fileID: string + status: number + errMsg: string + } + + interface DeleteFileParam extends ICloudAPIParam { + fileList: string[] + } + // === end === + } + + namespace WXNS { + interface AnyObject { + [key: string]: any + } + + interface IAPIParam { + success?: (res: T) => void + fail?: (err: IAPIError) => void + complete?: (val: T | IAPIError) => void + } + + interface CommonAPIResult { + errMsg: string + } + + interface IAPIError { + errMsg: string + } + + interface IProgressUpdateEvent { + progress: number + totalBytesWritten: number + totalBytesExpectedToWrite: number + } + + interface operateWXData { + (param: any): void + } + + interface uploadFile { + /** + * upload file + * @param param + */ + (param: IUploadFileParam): IUploadFileTask + } + + interface IUploadFileParam extends IAPIParam { + url: string + filePath: string + name: string + header?: AnyObject + } + + interface IUploadFileSuccessResult extends CommonAPIResult { + data: string + statusCode: number + } + + interface IUploadFileTask { + onProgressUpdate: (fn: (event: IProgressUpdateEvent) => void) => void + abort: AnyFunction + } + + interface downloadFile { + /** + * download file + * @param param + */ + (param: IDownloadFileParam): IDownloadFileTask + } + + interface IDownloadFileParam extends IAPIParam { + url: string + header?: AnyObject + } + + interface IDownloadFileSuccessResult extends CommonAPIResult { + tempFilePath: string + statusCode: number + } + + interface IDownloadFileTask { + onProgressUpdate: (fn: (event: IProgressUpdateEvent) => void) => void + abort: AnyFunction + } + + interface request { + (param: IRequestParam): IRequestTask + } + + interface IRequestParam extends IAPIParam { + url: string + data?: AnyObject | string | ArrayBuffer + header?: AnyObject + method?: string + dataType?: string + responseType?: string + } + + interface IRequestSuccessResult { + data: AnyObject | string | ArrayBuffer + statusCode: number + header: AnyObject + } + + interface IRequestTask { + abort: () => void + } + + interface getFileInfo { + (param: IGetFileInfoParam): void + } + + interface IGetFileInfoParam extends IAPIParam { + filePath: string + digestAlgorithm?: string + } + + interface IGetFileInfoSuccessResult { + size: number + digest: string + } + } + + // === Database === + namespace DB { + /** + * The class of all exposed cloud database instances + */ + export class Database { + public readonly config: ICloudConfig + public readonly command: DatabaseCommand + public readonly Geo: Geo + public readonly serverDate: () => ServerDate + + private constructor() + + collection(collectionName: string): CollectionReference + } + + export class CollectionReference extends Query { + public readonly collectionName: string + public readonly database: Database + + private constructor(name: string, database: Database) + + doc(docId: string | number): DocumentReference + + add(options: IAddDocumentOptions): Promise | void + } + + export class DocumentReference { + private constructor(docId: string | number, database: Database) + + field(object: object): this + + get(options?: IGetDocumentOptions): Promise | void + + set(options?: ISetSingleDocumentOptions): Promise | void + + update(options?: IUpdateSingleDocumentOptions): Promise | void + + remove(options?: IRemoveSingleDocumentOptions): Promise | void + } + + export class Query { + where(condition: IQueryCondition): Query + + orderBy(fieldPath: string, order: string): Query + + limit(max: number): Query + + skip(offset: number): Query + + field(object: object): Query + + get(options?: IGetDocumentOptions): Promise & void + + count(options?: ICountDocumentOptions): Promise & void + } + + export interface DatabaseCommand { + eq(val: any): DatabaseQueryCommand + neq(val: any): DatabaseQueryCommand + gt(val: any): DatabaseQueryCommand + gte(val: any): DatabaseQueryCommand + lt(val: any): DatabaseQueryCommand + lte(val: any): DatabaseQueryCommand + in(val: any[]): DatabaseQueryCommand + nin(val: any[]): DatabaseQueryCommand + + and(...expressions: (DatabaseLogicCommand | IQueryCondition)[]): DatabaseLogicCommand + or(...expressions: (DatabaseLogicCommand | IQueryCondition)[]): DatabaseLogicCommand + + set(val: any): DatabaseUpdateCommand + remove(): DatabaseUpdateCommand + inc(val: number): DatabaseUpdateCommand + mul(val: number): DatabaseUpdateCommand + + push(...values: any[]): DatabaseUpdateCommand + pop(): DatabaseUpdateCommand + shift(): DatabaseUpdateCommand + unshift(...values: any[]): DatabaseUpdateCommand + } + + export enum LOGIC_COMMANDS_LITERAL { + AND = 'and', + OR = 'or', + NOT = 'not', + NOR = 'nor' + } + + export class DatabaseLogicCommand { + public fieldName: string | InternalSymbol + public operator: LOGIC_COMMANDS_LITERAL | string + public operands: any[] + + _setFieldName(fieldName: string): DatabaseLogicCommand + + and(...expressions: (DatabaseLogicCommand | IQueryCondition)[]): DatabaseLogicCommand + or(...expressions: (DatabaseLogicCommand | IQueryCondition)[]): DatabaseLogicCommand + } + + export enum QUERY_COMMANDS_LITERAL { + EQ = 'eq', + NEQ = 'neq', + GT = 'gt', + GTE = 'gte', + LT = 'lt', + LTE = 'lte', + IN = 'in', + NIN = 'nin' + } + + export class DatabaseQueryCommand extends DatabaseLogicCommand { + public operator: QUERY_COMMANDS_LITERAL | string + + _setFieldName(fieldName: string): DatabaseQueryCommand + + eq(val: any): DatabaseLogicCommand + neq(val: any): DatabaseLogicCommand + gt(val: any): DatabaseLogicCommand + gte(val: any): DatabaseLogicCommand + lt(val: any): DatabaseLogicCommand + lte(val: any): DatabaseLogicCommand + in(val: any[]): DatabaseLogicCommand + nin(val: any[]): DatabaseLogicCommand + } + + export enum UPDATE_COMMANDS_LITERAL { + SET = 'set', + REMOVE = 'remove', + INC = 'inc', + MUL = 'mul', + PUSH = 'push', + POP = 'pop', + SHIFT = 'shift', + UNSHIFT = 'unshift' + } + + export class DatabaseUpdateCommand { + public fieldName: string | InternalSymbol + public operator: UPDATE_COMMANDS_LITERAL + public operands: any[] + + constructor(operator: UPDATE_COMMANDS_LITERAL, operands: any[], fieldName?: string | InternalSymbol) + + _setFieldName(fieldName: string): DatabaseUpdateCommand + } + + export class Batch {} + + /** + * A contract that all API provider must adhere to + */ + export class APIBaseContract { + getContext(param: PARAM): CONTEXT + + /** + * In case of callback-style invocation, this function will be called + */ + getCallbackReturn(param: PARAM, context: CONTEXT): CALLBACK_RETURN + + getFinalParam(param: PARAM, context: CONTEXT): T + + run(param: T): Promise + } + + export interface GeoPointConstructor { + new (longitude: number, latitide: number): GeoPoint + } + + export interface Geo { + Point: { + new (longitude: number, latitide: number): GeoPoint + (longitude: number, latitide: number): GeoPoint + } + } + + export abstract class GeoPoint { + public longitude: number + public latitude: number + + constructor(longitude: number, latitude: number) + + toJSON(): object + toString(): string + } + + export interface IServerDateOptions { + offset: number + } + + export abstract class ServerDate { + public readonly options: IServerDateOptions + constructor(options?: IServerDateOptions) + } + + export type DocumentId = string | number + + export interface IDocumentData { + _id?: DocumentId + [key: string]: any + } + + export interface IDBAPIParam extends IAPIParam {} + + export interface IAddDocumentOptions extends IDBAPIParam { + data: IDocumentData + } + + export interface IGetDocumentOptions extends IDBAPIParam {} + + export interface ICountDocumentOptions extends IDBAPIParam {} + + export interface IUpdateDocumentOptions extends IDBAPIParam { + data: IUpdateCondition + } + + export interface IUpdateSingleDocumentOptions extends IDBAPIParam { + data: IUpdateCondition + } + + export interface ISetDocumentOptions extends IDBAPIParam { + data: IUpdateCondition + } + + export interface ISetSingleDocumentOptions extends IDBAPIParam { + data: IUpdateCondition + } + + export interface IRemoveDocumentOptions extends IDBAPIParam { + query: IQueryCondition + } + + export interface IRemoveSingleDocumentOptions extends IDBAPIParam {} + + export interface IQueryCondition { + [key: string]: any + } + + export type IStringQueryCondition = string + + export interface IQueryResult extends IAPISuccessParam { + data: IDocumentData[] + } + + export interface IQuerySingleResult extends IAPISuccessParam { + data: IDocumentData + } + + export interface IUpdateCondition { + [key: string]: any + } + + export type IStringUpdateCondition = string + + export interface ISetCondition {} + + export interface IAddResult extends IAPISuccessParam { + _id: DocumentId + } + + export interface IUpdateResult extends IAPISuccessParam { + stats: { + updated: number + // created: number, + } + } + + export interface ISetResult extends IAPISuccessParam { + _id: DocumentId + stats: { + updated: number + created: number + } + } + + export interface IRemoveResult extends IAPISuccessParam { + stats: { + removed: number + } + } + + export interface ICountResult extends IAPISuccessParam { + total: number + } + } + function init(OBJECT?: ICloudConfig): void + + function callFunction(param: ICloud.CallFunctionParam): Promise & void + function uploadFile(param: ICloud.UploadFileParam): Promise & WXNS.IUploadFileTask + function downloadFile(param: ICloud.DownloadFileParam): Promise & WXNS.IDownloadFileTask + function getTempFileURL(param: ICloud.GetTempFileURLParam): Promise & void + function deleteFile(param: ICloud.DeleteFileParam): Promise & void + + function database(config?: ICloudConfig): DB.Database + } +} diff --git a/packages/taro/types/api/device/device.accelerometer.d.ts b/packages/taro/types/api/device/device.accelerometer.d.ts new file mode 100644 index 000000000000..6b2399b2959a --- /dev/null +++ b/packages/taro/types/api/device/device.accelerometer.d.ts @@ -0,0 +1,70 @@ +declare namespace Taro { + namespace stopAccelerometer { + type Param = {} + } + /** + * @since 1.1.0 + * + * 停止监听加速度数据。 + * + * **示例代码：** + * + ```javascript + Taro.stopAccelerometer() + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/accelerometer/wx.stopAccelerometer.html + */ + function stopAccelerometer(OBJECT?: stopAccelerometer.Param): Promise + + namespace startAccelerometer { + type Param = {} + } + /** + * @since 1.1.0 + * + * 开始监听加速度数据。 + * + * **示例代码：** + * + ```javascript + Taro.startAccelerometer() + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/accelerometer/wx.startAccelerometer.html + */ + function startAccelerometer(OBJECT?: startAccelerometer.Param): Promise + + namespace onAccelerometerChange { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * X 轴 + */ + x: number + /** + * Y 轴 + */ + y: number + /** + * Z 轴 + */ + z: number + } + } + /** + * 监听加速度数据，频率：5次/秒，接口调用后会自动开始监听，可使用 `Taro.stopAccelerometer` 停止监听。 + * + * **示例代码：** + * + ```javascript + Taro.onAccelerometerChange(function(res) { + console.log(res.x) + console.log(res.y) + console.log(res.z) + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/accelerometer/wx.onAccelerometerChange.html + */ + function onAccelerometerChange(CALLBACK: onAccelerometerChange.Param): void + + // TODO: wx.offAccelerometerChange +} diff --git a/packages/taro/types/api/device/device.battery.d.ts b/packages/taro/types/api/device/device.battery.d.ts new file mode 100644 index 000000000000..9ce0e9ad5c92 --- /dev/null +++ b/packages/taro/types/api/device/device.battery.d.ts @@ -0,0 +1,4 @@ +declare namespace Taro { + // TODO: wx.getBatteryInfoSync + // TODO: wx.getBatteryInfo +} diff --git a/packages/taro/types/api/device/device.ble.d.ts b/packages/taro/types/api/device/device.ble.d.ts new file mode 100644 index 000000000000..33bb0a9de1c3 --- /dev/null +++ b/packages/taro/types/api/device/device.ble.d.ts @@ -0,0 +1,476 @@ +declare namespace Taro { + namespace readBLECharacteristicValue { + type Promised = { + /** + * 错误码 + */ + errCode: number + /** + * 成功：ok，错误：详细信息 + */ + errMsg: string + } + type Param = { + /** + * 蓝牙设备 id，参考 device 对象 + */ + deviceId: string + /** + * 蓝牙特征值对应服务的 uuid + */ + serviceId: string + /** + * 蓝牙特征值的 uuid + */ + characteristicId: string + } + } + /** + * @since 1.1.0 + * + * 读取低功耗蓝牙设备的特征值的二进制数据值。注意：必须设备的特征值支持`read`才可以成功调用，具体参照 characteristic 的 properties 属性 + * + * **Bug & Tip：** + * + * 1. `tip`: 并行调用多次读写接口存在读写失败的可能性。 + * 2. `tip`: `read`接口读取到的信息需要在`onBLECharacteristicValueChange`方法注册的回调中获取。 + * + * **示例代码：** + * + ```javascript + // 必须在这里的回调才能获取 + Taro.onBLECharacteristicValueChange(function(characteristic) { + console.log('characteristic value comed:', characteristic) + }) + Taro.readBLECharacteristicValue({ + // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接 [ new ] + deviceId: deviceId, + // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取 + serviceId: serviceId, + // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取 + characteristicId: characteristicId, + success: function (res) { + console.log('readBLECharacteristicValue:', res.errCode) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.readBLECharacteristicValue.html + */ + function readBLECharacteristicValue(OBJECT: readBLECharacteristicValue.Param): Promise + + namespace onBLEConnectionStateChange { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * 蓝牙设备 id，参考 device 对象 + */ + deviceId: string + /** + * 连接目前的状态 + */ + connected: boolean + } + } + /** + * @since 1.1.1 + * + * 监听低功耗蓝牙连接状态的改变事件，包括开发者主动连接或断开连接，设备丢失，连接异常断开等等 + * + * **示例代码：** + * + ```javascript + Taro.onBLEConnectionStateChange(function(res) { + // 该方法回调中可以用于处理连接意外断开等异常情况 + console.log(`device ${res.deviceId} state has changed, connected: ${res.connected}`) + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.onBLEConnectionStateChange.html + */ + function onBLEConnectionStateChange(CALLBACK: onBLEConnectionStateChange.Param): void + + namespace onBLECharacteristicValueChange { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * 蓝牙设备 id，参考 device 对象 + */ + deviceId: string + /** + * 特征值所属服务 uuid + */ + serviceId: string + /** + * 特征值 uuid + */ + characteristicId: string + /** + * 特征值最新的值 **（注意：vConsole 无法打印出 ArrayBuffer 类型数据）** + */ + value: ArrayBuffer + } + } + /** + * @since 1.1.0 + * + * 监听低功耗蓝牙设备的特征值变化。必须先启用`notify`接口才能接收到设备推送的notification。 + * + * **示例代码：** + * + ```javascript + // ArrayBuffer转16进度字符串示例 + function ab2hex(buffer) { + var hexArr = Array.prototype.map.call( + new Uint8Array(buffer), + function(bit) { + return ('00' + bit.toString(16)).slice(-2) + } + ) + return hexArr.join(''); + } + Taro.onBLECharacteristicValueChange(function(res) { + console.log(`characteristic ${res.characteristicId} has changed, now is ${res.value}`) + console.log(ab2hext(res.value)) + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.onBLECharacteristicValueChange.html + */ + function onBLECharacteristicValueChange(CALLBACK: onBLECharacteristicValueChange.Param): void + + namespace notifyBLECharacteristicValueChange { + type Promised = { + /** + * 成功：ok，错误：详细信息 + */ + errMsg: string + } + type Param = { + /** + * 蓝牙设备 id，参考 device 对象 + */ + deviceId: string + /** + * 蓝牙特征值对应服务的 uuid + */ + serviceId: string + /** + * 蓝牙特征值的 uuid + */ + characteristicId: string + /** + * true: 启用 notify; false: 停用 notify + */ + state: boolean + } + } + /** + * @since 1.1.1 + * + * 启用低功耗蓝牙设备特征值变化时的 notify 功能，订阅特征值。注意：必须设备的特征值支持`notify`或者`indicate`才可以成功调用，具体参照 characteristic 的 properties 属性 + * + * 另外，必须先启用`notify`才能监听到设备 characteristicValueChange 事件 + * + * **Bug & Tip：** + * + * 1. `tip`: 订阅操作成功后需要设备主动更新特征值的value，才会触发 Taro.onBLECharacteristicValueChange 回调。 + * 2. `tip`: 安卓平台上，在调用notify成功后立即调用write接口，在部分机型上会发生 10008 系统错误 + * + * **示例代码：** + * + ```javascript + Taro.notifyBLECharacteristicValueChange({ + state: true, // 启用 notify 功能 + // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接 + deviceId: deviceId, + // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取 + serviceId: serviceId, + // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取 + characteristicId: characteristicId, + success: function (res) { + console.log('notifyBLECharacteristicValueChange success', res.errMsg) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.notifyBLECharacteristicValueChange.html + */ + function notifyBLECharacteristicValueChange(OBJECT: notifyBLECharacteristicValueChange.Param): Promise + + namespace getBLEDeviceServices { + type Promised = { + /** + * 设备服务列表 + */ + services: PromisedPropServices + /** + * 成功：ok，错误：详细信息 + */ + errMsg: string + } + /** + * 设备服务列表 + */ + type PromisedPropServices = PromisedPropServicesItem[] + type PromisedPropServicesItem = { + /** + * 蓝牙设备服务的 uuid + */ + uuid: string + /** + * 该服务是否为主服务 + */ + isPrimary: boolean + } + type Param = { + /** + * 蓝牙设备 id，参考 getDevices 接口 + */ + deviceId: string + } + } + /** + * @since 1.1.0 + * + * 获取蓝牙设备所有 service（服务） + * + * **Bug & Tip：** + * + * 1. `tip`:iOS平台上后续对特征值的read、write、notify，由于系统需要获取特征值实例，传入的 serviceId 与 characteristicId 必须由 getBLEDeviceServices 与 getBLEDeviceCharacteristics 中获取到后才能使用。建议双平台统一在建立链接后先执行 getBLEDeviceServices 与 getBLEDeviceCharacteristics 后再进行与蓝牙设备的数据交互 + * + * **示例代码：** + * + ```javascript + Taro.getBLEDeviceServices({ + // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接 + deviceId: deviceId, + success: function (res) { + console.log('device services:', res.services) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.getBLEDeviceServices.html + */ + function getBLEDeviceServices(OBJECT: getBLEDeviceServices.Param): Promise + + namespace getBLEDeviceCharacteristics { + type Promised = { + /** + * 设备特征值列表 + */ + characteristics: PromisedPropCharacteristics + /** + * 成功：ok，错误：详细信息 + */ + errMsg: string + } + /** + * 设备特征值列表 + */ + type PromisedPropCharacteristics = PromisedPropCharacteristicsItem[] + type PromisedPropCharacteristicsItem = { + /** + * 蓝牙设备特征值的 uuid + */ + uuid: string + /** + * 该特征值支持的操作类型 + */ + properties: PromisedPropCharacteristicsItemPropProperties + } + /** + * 该特征值支持的操作类型 + */ + type PromisedPropCharacteristicsItemPropProperties = { + /** + * 该特征值是否支持 read 操作 + */ + read: boolean + /** + * 该特征值是否支持 write 操作 + */ + write: boolean + /** + * 该特征值是否支持 notify 操作 + */ + notify: boolean + /** + * 该特征值是否支持 indicate 操作 + */ + indicate: boolean + } + type Param = { + /** + * 蓝牙设备 id，参考 device 对象 + */ + deviceId: string + /** + * 蓝牙服务 uuid + */ + serviceId: string + } + } + /** + * @since 1.1.0 + * + * 获取蓝牙设备某个服务中的所有 characteristic（特征值） + * + * **Bug & Tip：** + * + * 1. `tip`:传入的serviceId需要在getBLEDeviceServices获取到 + * 2. `tip`:iOS平台上后续对特征值的read、write、notify，由于系统需要获取特征值实例，传入的 serviceId 与 characteristicId 必须由 getBLEDeviceServices 与 getBLEDeviceCharacteristics 中获取到后才能使用。建议双平台统一在建立链接后先执行 getBLEDeviceServices 与 getBLEDeviceCharacteristics 后再进行与蓝牙设备的数据交互 + * + * **示例代码：** + * + ```javascript + Taro.getBLEDeviceCharacteristics({ + // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接 + deviceId: deviceId, + // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取 + serviceId: serviceId, + success: function (res) { + console.log('device getBLEDeviceCharacteristics:', res.characteristics) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.getBLEDeviceCharacteristics.html + */ + function getBLEDeviceCharacteristics(OBJECT: getBLEDeviceCharacteristics.Param): Promise + + namespace createBLEConnection { + type Promised = { + /** + * 成功：ok，错误：详细信息 + */ + errMsg: string + } + type Param = { + /** + * 蓝牙设备 id，参考 getDevices 接口 + */ + deviceId: string + } + } + /** + * @since 1.1.0 + * + * 连接低功耗蓝牙设备。 + * + * > 若小程序在之前已有搜索过某个蓝牙设备，并成功建立链接，可直接传入之前搜索获取的deviceId直接尝试连接该设备，无需进行搜索操作。 + * + * **Bug & Tip：** + * + * 1. `tip`: 安卓手机上如果多次调用create创建连接，有可能导致系统持有同一设备多个连接的实例，导致调用close的时候并不能真正的断开与设备的连接。因此请保证尽量成对的调用create和close接口 + * 2. `tip`: 蓝牙链接随时可能断开，建议监听 Taro.onBLEConnectionStateChange 回调事件，当蓝牙设备断开时按需执行重连操作 + * 3. `tip`: 若对未连接的设备或已断开连接的设备调用数据读写操作的接口，会返回10006错误，详见错误码，建议进行重连操作 + * + * **示例代码：** + * + ```javascript + Taro.createBLEConnection({ + // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接 + deviceId: deviceId, + success: function (res) { + console.log(res) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.createBLEConnection.html + */ + function createBLEConnection(OBJECT: createBLEConnection.Param): Promise + + namespace closeBLEConnection { + type Promised = { + /** + * 成功：ok，错误：详细信息 + */ + errMsg: string + } + type Param = { + /** + * 蓝牙设备 id，参考 getDevices 接口 + */ + deviceId: string + } + } + /** + * @since 1.1.0 + * + * 断开与低功耗蓝牙设备的连接 + * + * **示例代码：** + * + ```javascript + Taro.closeBLEConnection({ + deviceId:deviceId + success: function (res) { + console.log(res) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.closeBLEConnection.html + */ + function closeBLEConnection(OBJECT: closeBLEConnection.Param): Promise + + namespace writeBLECharacteristicValue { + type Promised = { + /** + * 成功：ok，错误：详细信息 + */ + errMsg: string + } + type Param = { + /** + * 蓝牙设备 id，参考 device 对象 + */ + deviceId: string + /** + * 蓝牙特征值对应服务的 uuid + */ + serviceId: string + /** + * 蓝牙特征值的 uuid + */ + characteristicId: string + /** + * 蓝牙设备特征值对应的二进制值 + */ + value: ArrayBuffer + } + } + /** + * @since 1.1.0 + * + * 向低功耗蓝牙设备特征值中写入二进制数据。注意：必须设备的特征值支持`write`才可以成功调用，具体参照 characteristic 的 properties 属性 + * + * _tips: 并行调用多次读写接口存在读写失败的可能性_ + * + * **Bug & Tip：** + * + * 1. `tip`: 并行调用多次读写接口存在读写失败的可能性。 + * 2. `tip`: 小程序不会对写入数据包大小做限制，但系统与蓝牙设备会确定蓝牙4.0单次传输的数据大小，超过最大字节数后会发生写入错误，建议每次写入不超过20字节。 + * 3. `tip`: 安卓平台上，在调用notify成功后立即调用write接口，在部分机型上会发生 10008 系统错误 + * 4. `bug`: 若单次写入数据过长，iOS平台上存在系统不会有任何回调的情况(包括错误回调)。 + * + * **示例代码：** + * + ```javascript + // 向蓝牙设备发送一个0x00的16进制数据 + let buffer = new ArrayBuffer(1) + let dataView = new DataView(buffer) + dataView.setUint8(0, 0) + Taro.writeBLECharacteristicValue({ + // 这里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中获取 + deviceId: deviceId, + // 这里的 serviceId 需要在上面的 getBLEDeviceServices 接口中获取 + serviceId: serviceId, + // 这里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中获取 + characteristicId: characteristicId, + // 这里的value是ArrayBuffer类型 + value: buffer, + success: function (res) { + console.log('writeBLECharacteristicValue success', res.errMsg) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth-ble/wx.writeBLECharacteristicValue.html + */ + function writeBLECharacteristicValue(OBJECT: writeBLECharacteristicValue.Param): Promise +} diff --git a/packages/taro/types/api/device/device.bluetooth.d.ts b/packages/taro/types/api/device/device.bluetooth.d.ts new file mode 100644 index 000000000000..0a20f36d9e1c --- /dev/null +++ b/packages/taro/types/api/device/device.bluetooth.d.ts @@ -0,0 +1,398 @@ +declare namespace Taro { + namespace stopBluetoothDevicesDiscovery { + type Promised = { + /** + * 成功：ok，错误：详细信息 + */ + errMsg: string + } + type Param = {} + } + /** + * @since 1.1.0 + * + * 停止搜寻附近的蓝牙外围设备。若已经找到需要的蓝牙设备并不需要继续搜索时，建议调用该接口停止蓝牙搜索。 + * + * **示例代码：** + * + ```javascript + Taro.stopBluetoothDevicesDiscovery({ + success: function (res) { + console.log(res) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth/wx.stopBluetoothDevicesDiscovery.html + */ + function stopBluetoothDevicesDiscovery(OBJECT?: stopBluetoothDevicesDiscovery.Param): Promise + + namespace startBluetoothDevicesDiscovery { + type Promised = { + /** + * 成功：ok，错误：详细信息 + */ + errMsg: string + } + type Param = { + /** + * 蓝牙设备主 service 的 uuid 列表 + */ + services?: any[] + /** + * 是否允许重复上报同一设备， 如果允许重复上报，则onDeviceFound 方法会多次上报同一设备，但是 RSSI 值会有不同 + */ + allowDuplicatesKey?: boolean + /** + * 上报设备的间隔，默认为0，意思是找到新设备立即上报，否则根据传入的间隔上报 + */ + interval?: number + } + } + /** + * @since 1.1.0 + * + * 开始搜寻附近的蓝牙外围设备。注意，该操作比较耗费系统资源，请在搜索并连接到设备后调用 stop 方法停止搜索。 + * + * **示例代码：** + * + ```javascript + // 以微信硬件平台的蓝牙智能灯为例，主服务的 UUID 是 FEE7。传入这个参数，只搜索主服务 UUID 为 FEE7 的设备 + Taro.startBluetoothDevicesDiscovery({ + services: ['FEE7'], + success: function (res) { + console.log(res) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth/wx.startBluetoothDevicesDiscovery.html + */ + function startBluetoothDevicesDiscovery(OBJECT?: startBluetoothDevicesDiscovery.Param): Promise + + namespace openBluetoothAdapter { + type Param = {} + } + /** + * @since 1.1.0 + * + * 初始化小程序蓝牙模块，生效周期为调用`Taro.openBluetoothAdapter`至调用`Taro.closeBluetoothAdapter`或小程序被销毁为止。 在小程序蓝牙适配器模块生效期间，开发者可以正常调用下面的小程序API，并会收到蓝牙模块相关的on回调。 + * + * **Bug & Tip：** + * + * 1. `tip`: 基础库版本 1.1.0 开始支持，低版本需做[兼容处理](https://developers.weixin.qq.com/miniprogram/dev/framework/compatibility.html) + * 2. `tip`: 在没有调用`Taro.openBluetoothAdapter`的情况下调用小程序其它蓝牙模块相关API，API会返回错误，错误码为`10000` + * 3. `bug`: 在用户蓝牙开关未开启或者手机不支持蓝牙功能的情况下，调用`Taro.openBluetoothAdapter`会返回错误，错误码为`10001`，表示手机蓝牙功能不可用；此时小程序蓝牙模块已经初始化完成，可通过`Taro.onBluetoothAdapterStateChange`监听手机蓝牙状态的改变，也可以调用蓝牙模块的所有API。 + * + * **示例代码：** + * + ```javascript + Taro.openBluetoothAdapter({ + success: function (res) { + console.log(res) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth/wx.openBluetoothAdapter.html + */ + function openBluetoothAdapter(OBJECT?: openBluetoothAdapter.Param): Promise + + namespace onBluetoothDeviceFound { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * 新搜索到的设备列表 + */ + devices: ParamParamPropDevices + } + /** + * 新搜索到的设备列表 + */ + type ParamParamPropDevices = ParamParamPropDevicesItem[] + type ParamParamPropDevicesItem = { + /** + * 蓝牙设备名称，某些设备可能没有 + */ + name: string + /** + * 用于区分设备的 id + */ + deviceId: string + /** + * 当前蓝牙设备的信号强度 + */ + RSSI: number + /** + * 当前蓝牙设备的广播数据段中的ManufacturerData数据段 **（注意：vConsole 无法打印出 ArrayBuffer 类型数据）** + */ + advertisData: ArrayBuffer + /** + * 当前蓝牙设备的广播数据段中的ServiceUUIDs数据段 + */ + advertisServiceUUIDs: any[] + /** + * 当前蓝牙设备的广播数据段中的LocalName数据段 + */ + localName: string + /** + * 当前蓝牙设备的广播数据段中的ServiceData数据段 + */ + serviceData: ArrayBuffer + } + } + /** + * @since 1.1.0 + * + * 监听寻找到新设备的事件 + * + * **Bug & Tip：** + * + * 1. `tip`: Mac系统可能无法获取`advertisData`及`RSSI`，请使用真机调试 + * 2. `tip`: 开发者工具和 Android 上获取到的`deviceId`为设备 MAC 地址，iOS 上则为设备 uuid。因此`deviceId`不能硬编码到代码中 + * 3. `tip`: 若在onBluetoothDeviceFound回调了某个设备，则此设备会添加到 Taro.getBluetoothDevices 接口获取到的数组中 + * + * **示例代码：** + * + ```javascript + // ArrayBuffer转16进度字符串示例 + function ab2hex(buffer) { + var hexArr = Array.prototype.map.call( + new Uint8Array(buffer), + function(bit) { + return ('00' + bit.toString(16)).slice(-2) + } + ) + return hexArr.join(''); + } + Taro.onBluetoothDeviceFound(function(devices) { + console.log('new device list has founded') + console.dir(devices) + console.log(ab2hex(devices[0].advertisData)) + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth/wx.onBluetoothDeviceFound.html + */ + function onBluetoothDeviceFound(CALLBACK: onBluetoothDeviceFound.Param): void + + namespace onBluetoothAdapterStateChange { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * 蓝牙适配器是否可用 + */ + available: boolean + /** + * 蓝牙适配器是否处于搜索状态 + */ + discovering: boolean + } + } + /** + * @since 1.1.0 + * + * 监听蓝牙适配器状态变化事件 + * + * **示例代码：** + * + ```javascript + Taro.onBluetoothAdapterStateChange(function(res) { + console.log(`adapterState changed, now is`, res) + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth/wx.onBluetoothAdapterStateChange.html + */ + function onBluetoothAdapterStateChange(CALLBACK: onBluetoothAdapterStateChange.Param): void + + namespace getConnectedBluetoothDevices { + type Promised = { + /** + * 搜索到的设备列表 + */ + devices: PromisedPropDevices + /** + * 成功：ok，错误：详细信息 + */ + errMsg: string + } + /** + * 搜索到的设备列表 + */ + type PromisedPropDevices = PromisedPropDevicesItem[] + type PromisedPropDevicesItem = { + /** + * 蓝牙设备名称，某些设备可能没有 + */ + name: string + /** + * 用于区分设备的 id + */ + deviceId: string + } + type Param = { + /** + * 蓝牙设备主 service 的 uuid 列表 + */ + services: any[] + } + } + /** + * @since 1.1.0 + * + * 根据 uuid 获取处于已连接状态的设备 + * + * **Bug & Tip：** + * + * 1. `tip`: 开发者工具和 Android 上获取到的`deviceId`为设备 MAC 地址，iOS 上则为设备 uuid。因此`deviceId`不能硬编码到代码中 + * + * **示例代码：** + * + ```javascript + Taro.getConnectedBluetoothDevices({ + success: function (res) { + console.log(res) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth/wx.getConnectedBluetoothDevices.html + */ + function getConnectedBluetoothDevices(OBJECT: getConnectedBluetoothDevices.Param): Promise + + namespace getBluetoothDevices { + type Promised = { + /** + * uuid 对应的的已连接设备列表 + */ + devices: PromisedPropDevices + /** + * 成功：ok，错误：详细信息 + */ + errMsg: string + } + /** + * uuid 对应的的已连接设备列表 + */ + type PromisedPropDevices = PromisedPropDevicesItem[] + type PromisedPropDevicesItem = { + /** + * 蓝牙设备名称，某些设备可能没有 + */ + name: string + /** + * 用于区分设备的 id + */ + deviceId: string + /** + * 当前蓝牙设备的信号强度 + */ + RSSI: number + /** + * 当前蓝牙设备的广播数据段中的ManufacturerData数据段 **（注意：vConsole 无法打印出 ArrayBuffer 类型数据）** + */ + advertisData: ArrayBuffer + /** + * 当前蓝牙设备的广播数据段中的ServiceUUIDs数据段 + */ + advertisServiceUUIDs: any[] + /** + * 当前蓝牙设备的广播数据段中的LocalName数据段 + */ + localName: string + /** + * 当前蓝牙设备的广播数据段中的ServiceData数据段 + */ + serviceData: ArrayBuffer + } + type Param = {} + } + /** + * @since 1.1.0 + * + * 获取在小程序蓝牙模块生效期间所有已发现的蓝牙设备，包括已经和本机处于连接状态的设备。 + * + * **Bug & Tip：** + * + * 1. `tip`: Mac系统可能无法获取`advertisData`及`RSSI`，请使用真机调试 + * 2. `tip`: 开发者工具和 Android 上获取到的`deviceId`为设备 MAC 地址，iOS 上则为设备 uuid。因此`deviceId`不能硬编码到代码中 + * 3. `tip`: 注意该接口获取到的设备列表为**小程序蓝牙模块生效期间所有搜索到的蓝牙设备**，若在蓝牙模块使用流程结束后未及时调用 Taro.closeBluetoothAdapter 释放资源，会存在调用该接口会返回之前的蓝牙使用流程中搜索到的蓝牙设备，可能设备已经不在用户身边，无法连接。 + * 4. `tips`: 蓝牙设备在被搜索到时，系统返回的 name 字段一般为广播包中的LocalName字段中的设备名称，而如果与蓝牙设备建立连接，系统返回的 name 字段会改为从蓝牙设备上获取到的GattName。若需要动态改变设备名称并展示，建议使用localName字段。 + * + * **示例代码：** + * + ```javascript + // ArrayBuffer转16进度字符串示例 + function ab2hex(buffer) { + var hexArr = Array.prototype.map.call( + new Uint8Array(buffer), + function(bit) { + return ('00' + bit.toString(16)).slice(-2) + } + ) + return hexArr.join(''); + } + Taro.getBluetoothDevices({ + success: function (res) { + console.log(res) + if (res.devices[0]) { + console.log(ab2hex(res.devices[0].advertisData)) + } + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth/wx.getBluetoothDevices.html + */ + function getBluetoothDevices(OBJECT?: getBluetoothDevices.Param): Promise + + namespace getBluetoothAdapterState { + type Promised = { + /** + * 是否正在搜索设备 + */ + discovering: boolean + /** + * 蓝牙适配器是否可用 + */ + available: boolean + /** + * 成功：ok，错误：详细信息 + */ + errMsg: string + } + type Param = {} + } + /** + * @since 1.1.0 + * + * 获取本机蓝牙适配器状态 + * + * **示例代码：** + * + ```javascript + Taro.getBluetoothAdapterState({ + success: function (res) { + console.log(res) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth/wx.getBluetoothAdapterState.html + */ + function getBluetoothAdapterState(OBJECT?: getBluetoothAdapterState.Param): Promise + + namespace closeBluetoothAdapter { + type Param = {} + } + /** + * @since 1.1.0 + * + * 关闭蓝牙模块，使其进入未初始化状态。调用该方法将断开所有已建立的链接并释放系统资源。建议在使用小程序蓝牙流程后调用，与`Taro.openBluetoothAdapter`成对调用。 + * + * **示例代码：** + * + ```javascript + Taro.closeBluetoothAdapter({ + success: function (res) { + console.log(res) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/bluetooth/wx.closeBluetoothAdapter.html + */ + function closeBluetoothAdapter(OBJECT?: closeBluetoothAdapter.Param): Promise +} diff --git a/packages/taro/types/api/device/device.clipboard.d.ts b/packages/taro/types/api/device/device.clipboard.d.ts new file mode 100644 index 000000000000..9903aa6d4185 --- /dev/null +++ b/packages/taro/types/api/device/device.clipboard.d.ts @@ -0,0 +1,59 @@ +declare namespace Taro { + namespace setClipboardData { + type Param = { + /** + * 需要设置的内容 + */ + data: string + } + } + /** + * @since 1.1.0 + * + * 设置系统剪贴板的内容 + * + * **示例代码：** + * + ```javascript + Taro.setClipboardData({ + data: 'data', + success: function(res) { + Taro.getClipboardData({ + success: function(res) { + console.log(res.data) // data + } + }) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/clipboard/wx.setClipboardData.html + */ + function setClipboardData(OBJECT: setClipboardData.Param): Promise + + namespace getClipboardData { + type Promised = { + /** + * 剪贴板的内容 + */ + data: string + } + type Param = {} + } + /** + * @since 1.1.0 + * + * 获取系统剪贴板内容 + * + * **示例代码：** + * + ```javascript + Taro.getClipboardData({ + success: function(res){ + console.log(res.data) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/clipboard/wx.getClipboardData.html + */ + function getClipboardData(OBJECT?: getClipboardData.Param): Promise +} diff --git a/packages/taro/types/api/device/device.compass.d.ts b/packages/taro/types/api/device/device.compass.d.ts new file mode 100644 index 000000000000..da889c138a46 --- /dev/null +++ b/packages/taro/types/api/device/device.compass.d.ts @@ -0,0 +1,60 @@ +declare namespace Taro { + namespace stopCompass { + type Param = {} + } + /** + * @since 1.1.0 + * + * 停止监听罗盘数据。 + * + * **示例代码：** + * + ```javascript + Taro.stopCompass() + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/compass/wx.stopCompass.html + */ + function stopCompass(OBJECT?: stopCompass.Param): Promise + + namespace startCompass { + type Param = {} + } + /** + * @since 1.1.0 + * + * 开始监听罗盘数据。 + * + * **示例代码：** + * + ```javascript + Taro.startCompass() + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/compass/wx.startCompass.html + */ + function startCompass(OBJECT?: startCompass.Param): Promise + + namespace onCompassChange { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * 面对的方向度数 + */ + direction: number + } + } + /** + * 监听罗盘数据，频率：5次/秒，接口调用后会自动开始监听，可使用`Taro.stopCompass`停止监听。 + * + * **示例代码：** + * + ```javascript + Taro.onCompassChange(function (res) { + console.log(res.direction) + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/compass/wx.onCompassChange.html + */ + function onCompassChange(CALLBACK: onCompassChange.Param): void + + // TODO: wx.offCompassChange +} diff --git a/packages/taro/types/api/device/device.contact.d.ts b/packages/taro/types/api/device/device.contact.d.ts new file mode 100644 index 000000000000..2e732b7c6c28 --- /dev/null +++ b/packages/taro/types/api/device/device.contact.d.ts @@ -0,0 +1,149 @@ +declare namespace Taro { + namespace addPhoneContact { + type Param = { + /** + * 头像本地文件路径 + */ + photoFilePath?: string + /** + * 昵称 + */ + nickName?: string + /** + * 姓氏 + */ + lastName?: string + /** + * 中间名 + */ + middleName?: string + /** + * 名字 + */ + firstName: string + /** + * 备注 + */ + remark?: string + /** + * 手机号 + */ + mobilePhoneNumber?: string + /** + * 微信号 + */ + weChatNumber?: string + /** + * 联系地址国家 + */ + addressCountry?: string + /** + * 联系地址省份 + */ + addressState?: string + /** + * 联系地址城市 + */ + addressCity?: string + /** + * 联系地址街道 + */ + addressStreet?: string + /** + * 联系地址邮政编码 + */ + addressPostalCode?: string + /** + * 公司 + */ + organization?: string + /** + * 职位 + */ + title?: string + /** + * 工作传真 + */ + workFaxNumber?: string + /** + * 工作电话 + */ + workPhoneNumber?: string + /** + * 公司电话 + */ + hostNumber?: string + /** + * 电子邮件 + */ + email?: string + /** + * 网站 + */ + url?: string + /** + * 工作地址国家 + */ + workAddressCountry?: string + /** + * 工作地址省份 + */ + workAddressState?: string + /** + * 工作地址城市 + */ + workAddressCity?: string + /** + * 工作地址街道 + */ + workAddressStreet?: string + /** + * 工作地址邮政编码 + */ + workAddressPostalCode?: string + /** + * 住宅传真 + */ + homeFaxNumber?: string + /** + * 住宅电话 + */ + homePhoneNumber?: string + /** + * 住宅地址国家 + */ + homeAddressCountry?: string + /** + * 住宅地址省份 + */ + homeAddressState?: string + /** + * 住宅地址城市 + */ + homeAddressCity?: string + /** + * 住宅地址街道 + */ + homeAddressStreet?: string + /** + * 住宅地址邮政编码 + */ + homeAddressPostalCode?: string + } + } + /** + * @since 1.2.0 + * + * 调用后，用户可以选择将该表单以“新增联系人”或“添加到已有联系人”的方式，写入手机系统通讯录，完成手机通讯录联系人和联系方式的增加。 + * + * **回调结果：** + * + * 回调类型 | errMsg | 说明 + * ------------|-------------------|----------------------- + * success | ok | 添加成功 + * fail | fail cancel | 用户取消操作 + * fail | fail ${detail} |调用失败，detail 加上详细信息 + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/contact/wx.addPhoneContact.html + */ + function addPhoneContact(OBJECT: addPhoneContact.Param): Promise +} diff --git a/packages/taro/types/api/device/device.gyroscope.d.ts b/packages/taro/types/api/device/device.gyroscope.d.ts new file mode 100644 index 000000000000..7b93123001bf --- /dev/null +++ b/packages/taro/types/api/device/device.gyroscope.d.ts @@ -0,0 +1,6 @@ +declare namespace Taro { + // TODO: wx.stopGyroscope + // TODO: wx.startGyroscope + // TODO: wx.onGyroscopeChange + // TODO: wx.offGyroscopeChange +} diff --git a/packages/taro/types/api/device/device.iBeacon.d.ts b/packages/taro/types/api/device/device.iBeacon.d.ts new file mode 100644 index 000000000000..4ea8467f18fc --- /dev/null +++ b/packages/taro/types/api/device/device.iBeacon.d.ts @@ -0,0 +1,171 @@ +declare namespace Taro { + namespace stopBeaconDiscovery { + type Promised = { + /** + * 调用结果 + */ + errMsg: string + } + type Param = {} + } + /** + * @since 1.2.0 + * + * 停止搜索附近的`iBeacon`设备 + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/ibeacon/wx.stopBeaconDiscovery.html + */ + function stopBeaconDiscovery(OBJECT?: stopBeaconDiscovery.Param): Promise + + namespace startBeaconDiscovery { + type Promised = { + /** + * 调用结果 + */ + errMsg: string + } + type Param = { + /** + * iBeacon设备广播的 uuids + */ + uuids: string[] + } + } + /** + * @since 1.2.0 + * + * 开始搜索附近的`iBeacon`设备 + * + * **示例代码：** + * + ```javascript + Taro.startBeaconDiscovery({ + success(res) { + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/ibeacon/wx.startBeaconDiscovery.html + */ + function startBeaconDiscovery(OBJECT: startBeaconDiscovery.Param): Promise + + namespace onBeaconUpdate { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * 当前搜寻到的所有 iBeacon 设备列表 + */ + beacons: ParamParamPropBeacons + } + /** + * 当前搜寻到的所有 iBeacon 设备列表 + */ + type ParamParamPropBeacons = ParamParamPropBeaconsItem[] + type ParamParamPropBeaconsItem = { + /** + * iBeacon 设备广播的 uuid + */ + uuid: string + /** + * iBeacon 设备的主 id + */ + major: string + /** + * iBeacon 设备的次 id + */ + minor: string + /** + * 表示设备距离的枚举值 + */ + proximity: number + /** + * iBeacon 设备的距离 + */ + accuracy: number + /** + * 表示设备的信号强度 + */ + rssi: number + } + } + /** + * @since 1.2.0 + * + * 监听 `iBeacon` 设备的更新事件 + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/ibeacon/wx.onBeaconUpdate.html + */ + function onBeaconUpdate(CALLBACK: onBeaconUpdate.Param): void + + namespace onBeaconServiceChange { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * 服务目前是否可用 + */ + available: boolean + /** + * 目前是否处于搜索状态 + */ + discovering: boolean + } + } + /** + * @since 1.2.0 + * + * 监听 `iBeacon` 服务的状态变化 + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/ibeacon/wx.onBeaconServiceChange.html + */ + function onBeaconServiceChange(CALLBACK: onBeaconServiceChange.Param): void + + namespace getBeacons { + type Promised = { + /** + * iBeacon 设备列表 + */ + beacons: PromisedPropBeacons + /** + * 调用结果 + */ + errMsg: string + } + /** + * iBeacon 设备列表 + */ + type PromisedPropBeacons = PromisedPropBeaconsItem[] + type PromisedPropBeaconsItem = { + /** + * iBeacon 设备广播的 uuid + */ + uuid: string + /** + * iBeacon 设备的主 id + */ + major: string + /** + * iBeacon 设备的次 id + */ + minor: string + /** + * 表示设备距离的枚举值 + */ + proximity: number + /** + * iBeacon 设备的距离 + */ + accuracy: number + /** + * 表示设备的信号强度 + */ + rssi: number + } + type Param = {} + } + /** + * @since 1.2.0 + * + * 获取所有已搜索到的`iBeacon`设备 + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/ibeacon/wx.getBeacons.html + */ + function getBeacons(OBJECT?: getBeacons.Param): Promise + + // TODO: wx.offBeaconUpdate + // TODO: wx.offBeaconServiceChange +} diff --git a/packages/taro/types/api/device/device.motion.d.ts b/packages/taro/types/api/device/device.motion.d.ts new file mode 100644 index 000000000000..19f7d3d2cce6 --- /dev/null +++ b/packages/taro/types/api/device/device.motion.d.ts @@ -0,0 +1,95 @@ +declare namespace Taro { + /** 接口调用结束的回调函数（调用成功、失败都会执行） */ + type StopDeviceMotionListeningCompleteCallback = ( + res: GeneralCallbackResult, + ) => void + /** 接口调用失败的回调函数 */ + type StopDeviceMotionListeningFailCallback = ( + res: GeneralCallbackResult, + ) => void + /** 接口调用成功的回调函数 */ + type StopDeviceMotionListeningSuccessCallback = ( + res: GeneralCallbackResult, + ) => void + interface StopDeviceMotionListeningOption { + /** 接口调用结束的回调函数（调用成功、失败都会执行） */ + complete?: StopDeviceMotionListeningCompleteCallback + /** 接口调用失败的回调函数 */ + fail?: StopDeviceMotionListeningFailCallback + /** 接口调用成功的回调函数 */ + success?: StopDeviceMotionListeningSuccessCallback + } + /** [wx.stopDeviceMotionListening(Object object)](https://developers.weixin.qq.com/miniprogram/dev/api/device/motion/wx.stopDeviceMotionListening.html) + * + * 停止监听设备方向的变化。 + * + * 最低基础库： `2.3.0` + */ + function stopDeviceMotionListening( + option?: StopDeviceMotionListeningOption, + ): void + + interface GeneralCallbackResult { + errMsg: string + } + type StartDeviceMotionListeningCompleteCallback = ( + res: GeneralCallbackResult, + ) => void + /** 接口调用失败的回调函数 */ + type StartDeviceMotionListeningFailCallback = ( + res: GeneralCallbackResult, + ) => void + /** 接口调用成功的回调函数 */ + type StartDeviceMotionListeningSuccessCallback = ( + res: GeneralCallbackResult, + ) => void + interface StartDeviceMotionListeningOption { + /** 接口调用结束的回调函数（调用成功、失败都会执行） */ + complete?: StartDeviceMotionListeningCompleteCallback + /** 接口调用失败的回调函数 */ + fail?: StartDeviceMotionListeningFailCallback + /** 监听设备方向的变化回调函数的执行频率 + * + * 可选值： + * - 'game': 适用于更新游戏的回调频率，在 20ms/次 左右; + * - 'ui': 适用于更新 UI 的回调频率，在 60ms/次 左右; + * - 'normal': 普通的回调频率，在 200ms/次 左右; */ + interval?: 'game' | 'ui' | 'normal' + /** 接口调用成功的回调函数 */ + success?: StartDeviceMotionListeningSuccessCallback + } + /** [wx.startDeviceMotionListening(Object object)](https://developers.weixin.qq.com/miniprogram/dev/api/device/motion/wx.startDeviceMotionListening.html) + * + * 开始监听设备方向的变化。 + * + * 最低基础库： `2.3.0` + */ + function startDeviceMotionListening( + option: StartDeviceMotionListeningOption, + ): void + + interface OnDeviceMotionChangeCallbackResult { + /** 当 手机坐标 X/Y 和 地球 X/Y 重合时，绕着 Z 轴转动的夹角为 alpha，范围值为 [0, 2*PI)。逆时针转动为正。 */ + alpha: number + /** 当手机坐标 Y/Z 和地球 Y/Z 重合时，绕着 X 轴转动的夹角为 beta。范围值为 [-1*PI, PI) 。顶部朝着地球表面转动为正。也有可能朝着用户为正。 */ + beta: number + /** 当手机 X/Z 和地球 X/Z 重合时，绕着 Y 轴转动的夹角为 gamma。范围值为 [-1*PI/2, PI/2)。右边朝着地球表面转动为正。 */ + gamma: number + } + /** 设备方向变化事件的回调函数 */ + type OnDeviceMotionChangeCallback = ( + result: OnDeviceMotionChangeCallbackResult, + ) => void + /** [wx.onDeviceMotionChange(function callback)](https://developers.weixin.qq.com/miniprogram/dev/api/device/motion/wx.onDeviceMotionChange.html) + * + * 监听设备方向变化事件。频率根据 [wx.startDeviceMotionListening()](https://developers.weixin.qq.com/miniprogram/dev/api/device/motion/wx.startDeviceMotionListening.html) 的 interval 参数。可以使用 [wx.stopDeviceMotionListening()](https://developers.weixin.qq.com/miniprogram/dev/api/device/motion/wx.stopDeviceMotionListening.html) 停止监听。 + * + * 最低基础库： `2.3.0` + */ + function onDeviceMotionChange( + /** 设备方向变化事件的回调函数 */ + callback: OnDeviceMotionChangeCallback + ): void + + // TODO: wx.offDeviceMotionChange +} diff --git a/packages/taro/types/api/device/device.network.d.ts b/packages/taro/types/api/device/device.network.d.ts new file mode 100644 index 000000000000..2517db3c2bb6 --- /dev/null +++ b/packages/taro/types/api/device/device.network.d.ts @@ -0,0 +1,71 @@ +declare namespace Taro { + namespace onNetworkStatusChange { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * 当前是否有网络连接 + */ + isConnected: boolean + /** + * 网络类型 + * + * **networkType 有效值：** + * + * 值 | 说明 + * ------------|--------------------- + * wifi | wifi 网络 + * 2g | 2g 网络 + * 3g | 3g 网络 + * 4g | 4g 网络 + * none | 无网络 + * unknown |Android下不常见的网络类型 + */ + networkType: string + } + } + /** + * @since 1.1.0 + * + * 监听网络状态变化。 + * + * **示例代码：** + * + ```javascript + Taro.onNetworkStatusChange(function(res) { + console.log(res.isConnected) + console.log(res.networkType) + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/network/wx.onNetworkStatusChange.html + */ + function onNetworkStatusChange(CALLBACK: onNetworkStatusChange.Param): void + + namespace getNetworkType { + type Promised = { + /** + * 网络类型 + */ + networkType: any + } + type Param = {} + } + /** + * 获取网络类型。 + * + * **success返回参数说明：** + * + ```javascript + Taro.getNetworkType({ + success: function(res) { + // 返回网络类型, 有效值： + // wifi/2g/3g/4g/unknown(Android下不常见的网络类型)/none(无网络) + var networkType = res.networkType + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/network/wx.getNetworkType.html + */ + function getNetworkType(OBJECT?: getNetworkType.Param): Promise + + // TODO: wx.offNetworkStatusChange +} diff --git a/packages/taro/types/api/device/device.nfc.d.ts b/packages/taro/types/api/device/device.nfc.d.ts new file mode 100644 index 000000000000..cbbe0e2df5ef --- /dev/null +++ b/packages/taro/types/api/device/device.nfc.d.ts @@ -0,0 +1,188 @@ +declare namespace Taro { + namespace stopHCE { + type Promised = { + /** + * 错误信息 + */ + errMsg: string + /** + * 错误码 + */ + errCode: number + } + type Param = {} + } + /** + * @since 1.7.0 + * + * 关闭 NFC 模块。仅在安卓系统下有效。 + * + * **示例代码：** + * + ```javascript + Taro.stopHCE({ + success: function(res) { + console.log(res.errMsg) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/nfc/wx.stopHCE.html + */ + function stopHCE(OBJECT?: stopHCE.Param): Promise + + namespace startHCE { + type Promised = { + /** + * 错误信息 + */ + errMsg: string + /** + * 错误码 + */ + errCode: number + } + type Param = { + /** + * 需要注册到系统的 AID 列表，每个 AID 为 String 类型 + */ + aid_list: any[] + } + } + /** + * @since 1.7.0 + * + * 初始化 NFC 模块。 + * + * **示例代码：** + * + ```javascript + Taro.startHCE({ + aid_list: ['F222222222'] + success: function(res) { + console.log(res.errMsg) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/nfc/wx.startHCE.html + */ + function startHCE(OBJECT: startHCE.Param): Promise + + namespace sendHCEMessage { + type Promised = { + /** + * 错误信息 + */ + errMsg: string + /** + * 错误码 + * + * **errCode列表：** + * + * 每个接口调用的时候，都会返回 `errCode` 字段。 + * + * 错误码 | 说明 + * ----------|--------------------------- + * 0 | Ok + * 13000 | 当前设备不支持 NFC + * 13001 |当前设备支持 NFC，但系统NFC开关未开启 + * 13002 |当前设备支持 NFC，但不支持HCE + * 13003 | AID 列表参数格式错误 + * 13004 |未设置微信为默认NFC支付应用 + * 13005 | 返回的指令不合法 + * 13006 | 注册 AID 失败 + */ + errCode: number + } + type Param = { + /** + * 二进制数据 + */ + data: ArrayBuffer + } + } + /** + * @since 1.7.0 + * + * 发送 NFC 消息。仅在安卓系统下有效。 + * + * **success返回参数说明：** + * + ```javascript + const buffer = new ArrayBuffer(1) + const dataView = new DataView(buffer) + dataView.setUint8(0, 0) + Taro.startHCE({ + success: function(res) { + Taro.onHCEMessage(function(res) { + if (res.messageType === 1) { + Taro.sendHCEMessage({data: buffer}) + } + }) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/nfc/wx.sendHCEMessage.html + */ + function sendHCEMessage(OBJECT: sendHCEMessage.Param): Promise + + namespace onHCEMessage { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * 消息类型 + */ + messageType: number + /** + * 客户端接收到 NFC 设备的指令，此参数当且仅当 `messageType=1` 时有效 + */ + data: ArrayBuffer + /** + * 此参数当且仅当 `messageType=2` 时有效 + */ + reason: number + } + } + /** + * @since 1.7.0 + * + * 监听 NFC 设备的消息回调，并在回调中处理。返回参数中 `messageType` 表示消息类型，目前有如下值： + * + * * 1：消息为HCE Apdu Command类型，小程序需对此指令进行处理，并调用 `sendHCEMessage` 接口返回处理指令； + * * 2：消息为设备离场事件 + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/nfc/wx.onHCEMessage.html + */ + function onHCEMessage(CALLBACK: onHCEMessage.Param): void + + namespace getHCEState { + type Promised = { + /** + * 错误信息 + */ + errMsg: string + /** + * 错误码 + */ + errCode: number + } + type Param = {} + } + /** + * @since 1.7.0 + * + * 判断当前设备是否支持 HCE 能力。 + * + * **success返回参数说明：** + * + ```javascript + Taro.getHCEState({ + success: function(res) { + console.log(res.errCode) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/nfc/wx.getHCEState.html + */ + function getHCEState(OBJECT?: getHCEState.Param): Promise + + // TODO: wx.offHCEMessage +} diff --git a/packages/taro/types/api/device/device.performance.d.ts b/packages/taro/types/api/device/device.performance.d.ts new file mode 100644 index 000000000000..74e762d2d029 --- /dev/null +++ b/packages/taro/types/api/device/device.performance.d.ts @@ -0,0 +1,3 @@ +declare namespace Taro { + // TODO: wx.onMemoryWarning +} diff --git a/packages/taro/types/api/device/device.phone.d.ts b/packages/taro/types/api/device/device.phone.d.ts new file mode 100644 index 000000000000..0fe17db66e83 --- /dev/null +++ b/packages/taro/types/api/device/device.phone.d.ts @@ -0,0 +1,22 @@ +declare namespace Taro { + namespace makePhoneCall { + type Param = { + /** + * 需要拨打的电话号码 + */ + phoneNumber: string + } + } + /** + * + * **示例代码：** + * + ```javascript + Taro.makePhoneCall({ + phoneNumber: '1340000' //仅为示例，并非真实的电话号码 + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/phone/wx.makePhoneCall.html + */ + function makePhoneCall(OBJECT: makePhoneCall.Param): Promise +} diff --git a/packages/taro/types/api/device/device.scan.d.ts b/packages/taro/types/api/device/device.scan.d.ts new file mode 100644 index 000000000000..d555e28e44ae --- /dev/null +++ b/packages/taro/types/api/device/device.scan.d.ts @@ -0,0 +1,59 @@ +declare namespace Taro { + namespace scanCode { + type Promised = { + /** + * 所扫码的内容 + */ + result: any + /** + * 所扫码的类型 + */ + scanType: any + /** + * 所扫码的字符集 + */ + charSet: any + /** + * 当所扫的码为当前小程序的合法二维码时，会返回此字段，内容为二维码携带的 path + */ + path: any + } + type Param = { + /** + * 是否只能从相机扫码，不允许从相册选择图片 + * + * @since 1.2.0 + */ + onlyFromCamera?: boolean + /** + * 扫码类型，参数类型是数组，二维码是'qrCode'，一维码是'barCode'，DataMatrix是‘datamatrix’，pdf417是‘pdf417’。 + * + * @since 1.7.0 + */ + scanType?: any[] + } + } + /** + * 调起客户端扫码界面，扫码成功后返回对应的结果 + * + * **示例代码：** + * + ```javascript + // 允许从相机和相册扫码 + Taro.scanCode({ + success: (res) => { + console.log(res) + } + }) + // 只允许从相机扫码 + Taro.scanCode({ + onlyFromCamera: true, + success: (res) => { + console.log(res) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/scan/wx.scanCode.html + */ + function scanCode(OBJECT?: scanCode.Param): Promise +} diff --git a/packages/taro/types/api/device/device.screen.d.ts b/packages/taro/types/api/device/device.screen.d.ts new file mode 100644 index 000000000000..1981165c95dc --- /dev/null +++ b/packages/taro/types/api/device/device.screen.d.ts @@ -0,0 +1,88 @@ +declare namespace Taro { + namespace setScreenBrightness { + type Param = { + /** + * 屏幕亮度值，范围 0~1，0 最暗，1 最亮 + */ + value: number + } + } + /** + * @since 1.2.0 + * + * 设置屏幕亮度。 + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/screen/wx.setScreenBrightness.html + */ + function setScreenBrightness(OBJECT: setScreenBrightness.Param): Promise + + namespace setKeepScreenOn { + type Promised = { + /** + * 调用结果 + */ + errMsg: string + } + type Param = { + /** + * 是否保持屏幕常亮 + */ + keepScreenOn: boolean + } + } + /** + * @since 1.4.0 + * + * 设置是否保持常亮状态。仅在当前小程序生效，离开小程序后设置失效。 + * + * **示例代码：** + * + ```javascript + // 保持屏幕常亮 + Taro.setKeepScreenOn({ + keepScreenOn: true + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/screen/wx.setKeepScreenOn.html + */ + function setKeepScreenOn(OBJECT: setKeepScreenOn.Param): Promise + + /** + * @since 1.4.0 + * + * 监听用户主动截屏事件，用户使用系统截屏按键截屏时触发此事件 + * + * **示例代码：** + * + ```javascript + Taro.onUserCaptureScreen(function(res) { + console.log('用户截屏了') + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/screen/wx.onUserCaptureScreen.html + */ + function onUserCaptureScreen(CALLBACK: any): void + + namespace getScreenBrightness { + type Promised = { + /** + * 屏幕亮度值，范围 0~1，0 最暗，1 最亮 + */ + value: number + } + type Param = {} + } + /** + * @since 1.2.0 + * + * 获取屏幕亮度。 + * + * **Bug & Tip：** + * + * 1. `tip`: `getScreenBrightness` 接口若安卓系统设置中开启了自动调节亮度功能，则屏幕亮度会根据光线自动调整，该接口仅能获取自动调节亮度之前的值，而非实时的亮度值。 + * + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/screen/wx.getScreenBrightness.html + */ + function getScreenBrightness(OBJECT?: getScreenBrightness.Param): Promise + + // TODO: wx.offUserCaptureScreen +} diff --git a/packages/taro/types/api/device/device.vibrate.d.ts b/packages/taro/types/api/device/device.vibrate.d.ts new file mode 100644 index 000000000000..c7e1d51d5c22 --- /dev/null +++ b/packages/taro/types/api/device/device.vibrate.d.ts @@ -0,0 +1,28 @@ +declare namespace Taro { + namespace vibrateShort { + type Param = {} + } + /** + * @since 1.2.0 + * + * 使手机发生较短时间的振动（15ms） + * + * **Bug & Tip：** + * + * 1. `tip`：`vibrateShort` 接口仅在 iPhone7/iPhone7Plus 及 Android 机型生效 + * + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/vibrate/wx.vibrateShort.html + */ + function vibrateShort(OBJECT?: vibrateShort.Param): Promise + + namespace vibrateLong { + type Param = {} + } + /** + * @since 1.2.0 + * + * 使手机发生较长时间的振动（400ms） + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/vibrate/wx.vibrateLong.html + */ + function vibrateLong(OBJECT?: vibrateLong.Param): Promise +} diff --git a/packages/taro/types/api/device/device.wifi.d.ts b/packages/taro/types/api/device/device.wifi.d.ts new file mode 100644 index 000000000000..b05d227bac8c --- /dev/null +++ b/packages/taro/types/api/device/device.wifi.d.ts @@ -0,0 +1,286 @@ +declare namespace Taro { + namespace stopWifi { + type Param = {} + } + /** + * @since 1.6.0 + * + * 关闭 Wi-Fi 模块。 + * + * **示例代码：** + * + ```javascript + Taro.stopWifi({ + success: function(res) { + console.log(res.errMsg) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/wifi/wx.stopWifi.html + */ + function stopWifi(OBJECT?: stopWifi.Param): Promise + + namespace startWifi { + type Param = {} + } + /** + * @since 1.6.0 + * + * 初始化 Wi-Fi 模块。 + * + * **示例代码：** + * + ```javascript + Taro.startWifi({ + success: function(res) { + console.log(res.errMsg) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/wifi/wx.startWifi.html + */ + function startWifi(OBJECT?: startWifi.Param): Promise + + namespace setWifiList { + type Param = { + /** + * 提供预设的 Wi-Fi 信息列表 + */ + wifiList: ParamPropWifiList + } + /** + * 提供预设的 Wi-Fi 信息列表 + */ + type ParamPropWifiList = ParamPropWifiListItem[] + type ParamPropWifiListItem = { + /** + * Wi-Fi 设备ssid + */ + SSID: string + /** + * Wi-Fi 设备bssid + */ + BSSID: string + /** + * Wi-Fi 设备密码 + */ + password: string + } + } + /** + * @since 1.6.0 + * + * **iOS特有接口** 在 `onGetWifiList` 回调后，利用接口设置 wifiList 中 AP 的相关信息。 + * + * 注意： + * + * 1. 该接口只能在 `onGetWifiList` 回调之后才能调用。 + * 2. 此时客户端会挂起，等待小程序设置 Wi-Fi 信息，请务必尽快调用该接口，若无数据请传入一个空数组。 + * 3. 有可能随着周边 Wi-Fi 列表的刷新，单个流程内收到多次带有存在重复的 Wi-Fi 列表的回调。 + * + * **示例代码：** + * + ```javascript + Taro.onGetWifiList(function(res) { + if (res.wifiList.length) { + Taro.setWifiList({ + wifiList: [{ + SSID: res.wifiList[0].SSID, + BSSID: res.wifiList[0].BSSID, + password: '123456' + }] + }) + } else { + Taro.setWifiList({ + wifiList: [] + }) + } + }) + Taro.getWifiList() + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/wifi/wx.setWifiList.html + */ + function setWifiList(OBJECT: setWifiList.Param): Promise + + namespace onWifiConnected { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * Wi-Fi 信息 + */ + wifi: ParamParamPropWifi + } + /** + * Wi-Fi 信息 + */ + type ParamParamPropWifi = { + /** + * Wi-Fi 的SSID + */ + SSID: string + /** + * Wi-Fi 的BSSID + */ + BSSID: string + /** + * Wi-Fi 是否安全 + */ + secure: boolean + /** + * Wi-Fi 信号强度 + */ + signalStrength: number + } + } + /** + * @since 1.6.0 + * + * 监听连接上 Wi-Fi 的事件。 + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/wifi/wx.onWifiConnected.html + */ + function onWifiConnected(CALLBACK: onWifiConnected.Param): void + + namespace onGetWifiList { + type Param = (res: ParamParam) => any + type ParamParam = { + /** + * Wi-Fi 列表数据 + */ + wifiList: ParamParamPropWifiList + } + /** + * Wi-Fi 列表数据 + */ + type ParamParamPropWifiList = ParamParamPropWifiListItem[] + type ParamParamPropWifiListItem = { + /** + * Wi-Fi 的SSID + */ + SSID: string + /** + * Wi-Fi 的BSSID + */ + BSSID: string + /** + * Wi-Fi 是否安全 + */ + secure: boolean + /** + * Wi-Fi 信号强度 + */ + signalStrength: number + } + } + /** + * @since 1.6.0 + * + * 监听在获取到 Wi-Fi 列表数据时的事件，在回调中将返回 wifiList。 + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/wifi/wx.onGetWifiList.html + */ + function onGetWifiList(CALLBACK: onGetWifiList.Param): void + + namespace getWifiList { + type Param = {} + } + /** + * @since 1.6.0 + * + * 请求获取 Wi-Fi 列表，在 `onGetWifiList` 注册的回调中返回 wifiList 数据。iOS 将跳转到系统的 Wi-Fi 界面，Android 不会跳转。 **iOS 11.0 及 iOS 11.1 两个版本因系统问题，该方法失效。但在 iOS 11.2 中已修复。** + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/wifi/wx.getWifiList.html + */ + function getWifiList(OBJECT?: getWifiList.Param): Promise + + namespace getConnectedWifi { + type Promised = { + /** + * Wi-Fi 信息 + */ + wifi: PromisedPropWifi + } + /** + * Wi-Fi 信息 + */ + type PromisedPropWifi = { + /** + * Wi-Fi 的SSID + */ + SSID: string + /** + * Wi-Fi 的BSSID + */ + BSSID: string + /** + * Wi-Fi 是否安全 + */ + secure: boolean + /** + * Wi-Fi 信号强度 + */ + signalStrength: number + } + type Param = {} + } + /** + * @since 1.6.0 + * + * 获取已连接中的 Wi-Fi 信息 + * + * **errCode列表：** + * + * 每个接口调用的时候，都会返回 `errCode` 字段。 + * + * 错误码 | 说明 | 备注 + * ----------|--------------------------|------------------------------ + * 0 | ok | 正常 + * 12000 | not init | 未先调用startWifi接口 + * 12001 | system not support | 当前系统不支持相关能力 + * 12002 | password error | Wi-Fi 密码错误 + * 12003 | connection timeout | 连接超时 + * 12004 | duplicate request | 重复连接 Wi-Fi + * 12005 | wifi not turned on |Android特有，未打开 Wi-Fi 开关 + * 12006 | gps not turned on |Android特有，未打开 GPS 定位开关 + * 12007 | user denied | 用户拒绝授权链接 Wi-Fi + * 12008 | invalid SSID | 无效SSID + * 12009 | system config err | 系统运营商配置拒绝连接 Wi-Fi + * 12010 | system internal error |系统其他错误，需要在errmsg打印具体的错误原因 + * 12011 | weapp in background | 应用在后台无法配置 Wi-Fi + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/wifi/wx.getConnectedWifi.html + */ + function getConnectedWifi(OBJECT?: getConnectedWifi.Param): Promise + + namespace connectWifi { + type Param = { + /** + * Wi-Fi 设备ssid + */ + SSID: string + /** + * Wi-Fi 设备bssid + */ + BSSID: string + /** + * Wi-Fi 设备密码 + */ + password?: string + } + } + /** + * @since 1.6.0 + * + * 连接 Wi-Fi。若已知 Wi-Fi 信息，可以直接利用该接口连接。仅 Android 与 iOS 11 以上版本支持。 + * + * **示例代码：** + * + ```javascript + Taro.connectWifi({ + SSID: '', + BSSID: '', + success: function(res) { + console.log(res.errMsg) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/device/wifi/wx.connectWifi.html + */ + function connectWifi(OBJECT: connectWifi.Param): Promise +} diff --git a/packages/taro/types/api/ext/ext.d.ts b/packages/taro/types/api/ext/ext.d.ts new file mode 100644 index 000000000000..2dd4e38f6d3c --- /dev/null +++ b/packages/taro/types/api/ext/ext.d.ts @@ -0,0 +1,65 @@ +declare namespace Taro { + namespace getExtConfigSync { + type Return = { + /** + * 第三方平台自定义的数据 + */ + extConfig: any + } + } + /** + * @since 1.1.0 + * + * 获取[第三方平台](https://mp.weixin.qq.com/debug/wxadoc/dev/devtools/ext.html)自定义的数据字段的同步接口。 + * + * **Bug & Tip：** + * + * 1. `Taro.getExtConfigSync` 暂时无法通过 `Taro.canIUse` 判断是否兼容，开发者需要自行判断 `Taro.getExtConfigSync` 是否存在来兼容 + * + * **示例代码：** + * + ```javascript + let extConfig = Taro.getExtConfigSync? Taro.getExtConfigSync(): {} + console.log(extConfig) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/ext/wx.getExtConfigSync.html + */ + function getExtConfigSync(): getExtConfigSync.Return + + namespace getExtConfig { + type Promised = { + /** + * 调用结果 + */ + errMsg: string + /** + * 第三方平台自定义的数据 + */ + extConfig: any + } + type Param = {} + } + /** + * @since 1.1.0 + * + * 获取[第三方平台](https://mp.weixin.qq.com/debug/wxadoc/dev/devtools/ext.html)自定义的数据字段。 + * + * **Bug & Tip：** + * + * 1. `Taro.getExtConfig` 暂时无法通过 `Taro.canIUse` 判断是否兼容，开发者需要自行判断 `Taro.getExtConfig` 是否存在来兼容 + * + * **示例代码：** + * + ```javascript + if(Taro.getExtConfig) { + Taro.getExtConfig({ + success: function (res) { + console.log(res.extConfig) + } + }) + } + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/ext/wx.getExtConfig.html + */ + function getExtConfig(OBJECT?: getExtConfig.Param): Promise +} diff --git a/packages/taro/types/api/files/files.d.ts b/packages/taro/types/api/files/files.d.ts new file mode 100644 index 000000000000..5f9dc764be21 --- /dev/null +++ b/packages/taro/types/api/files/files.d.ts @@ -0,0 +1,245 @@ +declare namespace Taro { + namespace saveFile { + type Promised = { + /** + * 文件的保存路径 + */ + savedFilePath: any + } + type Param = { + /** + * 需要保存的文件的临时路径 + */ + tempFilePath: string + } + } + /** + * 保存文件到本地。**注意：saveFile 会把临时文件移动，因此调用成功后传入的 tempFilePath 将不可用** + * + * **bug & tip：** + * + * 1. `tip`: 本地文件存储的大小限制为 10M + * + * **示例代码：** + * + ```javascript + Taro.chooseImage({ + success: function(res) { + var tempFilePaths = res.tempFilePaths + Taro.saveFile({ + tempFilePath: tempFilePaths[0], + success: function(res) { + var savedFilePath = res.savedFilePath + } + }) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/file/wx.saveFile.html + */ + function saveFile(OBJECT: saveFile.Param): Promise + + namespace removeSavedFile { + type Param = { + /** + * 需要删除的文件路径 + */ + filePath: string + } + } + /** + * 删除本地存储的文件 + * + * **示例代码：** + * + ```javascript + Taro.getSavedFileList({ + success: function(res) { + if (res.fileList.length > 0){ + Taro.removeSavedFile({ + filePath: res.fileList[0].filePath, + complete: function(res) { + console.log(res) + } + }) + } + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/file/wx.removeSavedFile.html + */ + function removeSavedFile(OBJECT: removeSavedFile.Param): Promise + + namespace openDocument { + type Param = { + /** + * 文件路径，可通过 downFile 获得 + */ + filePath: string + /** + * 文件类型，指定文件类型打开文件，有效值 doc, xls, ppt, pdf, docx, xlsx, pptx + * + * @since 1.4.0 + */ + fileType?: string + } + } + /** + * 新开页面打开文档，支持格式：doc, xls, ppt, pdf, docx, xlsx, pptx + * + * **示例代码：** + * + ```javascript + Taro.downloadFile({ + url: 'http://example.com/somefile.pdf', + success: function (res) { + var filePath = res.tempFilePath + Taro.openDocument({ + filePath: filePath, + success: function (res) { + console.log('打开文档成功') + } + }) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/file/wx.openDocument.html + */ + function openDocument(OBJECT: openDocument.Param): Promise + + namespace getSavedFileList { + type Promised = { + /** + * 接口调用结果 + */ + errMsg: string + /** + * 文件列表 + */ + fileList: PromisedPropFileList + } + /** + * 文件列表 + */ + type PromisedPropFileList = PromisedPropFileListItem[] + type PromisedPropFileListItem = { + /** + * 文件的本地路径 + */ + filePath: string + /** + * 文件的保存时的时间戳，从1970/01/01 08:00:00 到当前时间的秒数 + */ + createTime: number + /** + * 文件大小，单位B + */ + size: number + } + type Param = {} + } + /** + * 获取本地已保存的文件列表 + * + * **示例代码：** + * + ```javascript + Taro.getSavedFileList({ + success: function(res) { + console.log(res.fileList) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/file/wx.getSavedFileList.html + */ + function getSavedFileList(OBJECT?: getSavedFileList.Param): Promise + + namespace getSavedFileInfo { + type Promised = { + /** + * 接口调用结果 + */ + errMsg: string + /** + * 文件大小，单位B + */ + size: number + /** + * 文件保存时的时间戳，从1970/01/01 08:00:00 到该时刻的秒数 + */ + createTime: number + } + type Param = { + /** + * 文件路径 + */ + filePath: string + } + } + /** + * 获取本地文件的文件信息。此接口只能用于获取已保存到本地的文件，若需要获取临时文件信息，请使用 [Taro.getFileInfo](https://developers.weixin.qq.com/miniprogram/dev/api/file/wx.getFileInfo.html) 接口。 + * + * **示例代码：** + * + ```javascript + Taro.getSavedFileInfo({ + filePath: 'wxfile://somefile', //仅做示例用，非真正的文件路径 + success: function(res) { + console.log(res.size) + console.log(res.createTime) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/file/wx.getSavedFileInfo.html + */ + function getSavedFileInfo(OBJECT: getSavedFileInfo.Param): Promise + + namespace getFileInfo { + type Promised = { + /** + * 文件大小，单位：B + */ + size: number + /** + * 按照传入的 digestAlgorithm 计算得出的的文件摘要 + */ + digest: string + /** + * 调用结果 + */ + errMsg: string + } + type Param = { + /** + * 本地文件路径 + */ + filePath: string + /** + * 计算文件摘要的算法，默认值 md5，有效值：md5，sha1 + */ + digestAlgorithm?: string + } + } + /** + * @since 1.4.0 + * + * 获取文件信息 + * + * **示例代码：** + * + ```javascript + Taro.getFileInfo({ + success(res) { + console.log(res.size) + console.log(res.digest) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/file/wx.getFileInfo.html + */ + function getFileInfo(OBJECT: getFileInfo.Param): Promise + + // TODO: wx.getFileSystemManager + // TODO: FileSystemManager + // TODO: Stats +} diff --git a/packages/taro/types/api/framework/framework.d.ts b/packages/taro/types/api/framework/framework.d.ts new file mode 100644 index 000000000000..6bf07777536e --- /dev/null +++ b/packages/taro/types/api/framework/framework.d.ts @@ -0,0 +1,12 @@ +declare namespace Taro { + interface Page { + /** + * 当前页面的路径 + */ + route: string + + [k: string]: any + } + function getCurrentPages(): Page[] + function getApp(): any +} diff --git a/packages/taro/types/api/location/location.d.ts b/packages/taro/types/api/location/location.d.ts new file mode 100644 index 000000000000..32fd5e05e6d9 --- /dev/null +++ b/packages/taro/types/api/location/location.d.ts @@ -0,0 +1,183 @@ +declare namespace Taro { + namespace openLocation { + type Param = { + /** + * 纬度，范围为-90~90，负数表示南纬 + */ + latitude: number + /** + * 经度，范围为-180~180，负数表示西经 + */ + longitude: number + /** + * 缩放比例，范围5~18，默认为18 + */ + scale?: number + /** + * 位置名 + */ + name?: string + /** + * 地址的详细说明 + */ + address?: string + } + } + /** + * ​使用微信内置地图查看位置。 + * + * 需要[用户授权](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/authorize.html) scope.userLocation + * + * **Bug & Tip：** + * + * 1. `bug`: `iOS` `6.3.30` type 参数不生效，只会返回 wgs84 类型的坐标信息 + * + * **示例代码：** + * + ```javascript + Taro.getLocation({ + type: 'gcj02', //返回可以用于Taro.openLocation的经纬度 + success: function(res) { + var latitude = res.latitude + var longitude = res.longitude + Taro.openLocation({ + latitude: latitude, + longitude: longitude, + scale: 28 + }) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.openLocation.html + */ + function openLocation(OBJECT: openLocation.Param): Promise + + namespace getLocation { + type Promised = { + /** + * 纬度，浮点数，范围为-90~90，负数表示南纬 + */ + latitude: number + /** + * 经度，浮点数，范围为-180~180，负数表示西经 + */ + longitude: number + /** + * 速度，浮点数，单位m/s + */ + speed: number + /** + * 位置的精确度 + */ + accuracy: number + /** + * 高度，单位 m + * + * @since 1.2.0 + */ + altitude: number + /** + * 垂直精度，单位 m（Android 无法获取，返回 0） + * + * @since 1.2.0 + */ + verticalAccuracy: number + /** + * 水平精度，单位 m + * + * @since 1.2.0 + */ + horizontalAccuracy: number + } + type Param = { + /** + * 默认为 wgs84 返回 gps 坐标，gcj02 返回可用于`Taro.openLocation`的坐标 + */ + type?: 'wgs84' | 'gcj02' + /** + * 传入 true 会返回高度信息，由于获取高度需要较高精确度，会减慢接口返回速度 + * + * @since 1.6.0 + */ + altitude?: boolean + /** + * 接口调用成功的回调函数 + */ + success?: ParamPropSuccess + /** + * 接口调用失败的回调函数 + */ + fail?: ParamPropFail + /** + * 接口调用结束的回调函数（调用成功、失败都会执行） + */ + complete?: ParamPropComplete + } + /** + * 接口调用成功的回调函数 + */ + type ParamPropSuccess = (res: any) => any + /** + * 接口调用失败的回调函数 + */ + type ParamPropFail = (err: any) => any + /** + * 接口调用结束的回调函数（调用成功、失败都会执行） + */ + type ParamPropComplete = () => any + } + /** + * 获取当前的地理位置、速度。当用户离开小程序后，此接口无法调用；当用户点击“显示在聊天顶部”时，此接口可继续调用。 + * + * **示例代码：** + * + ```javascript + Taro.getLocation({ + type: 'wgs84', + success: function(res) { + var latitude = res.latitude + var longitude = res.longitude + var speed = res.speed + var accuracy = res.accuracy + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.getLocation.html + */ + function getLocation(OBJECT?: getLocation.Param): Promise + + namespace chooseLocation { + type Promised = { + /** + * 位置名称 + */ + name: any + /** + * 详细地址 + */ + address: any + /** + * 纬度，浮点数，范围为-90~90，负数表示南纬 + */ + latitude: any + /** + * 经度，浮点数，范围为-180~180，负数表示西经 + */ + longitude: any + } + type Param = {} + } + /** + * 打开地图选择位置。 + * + * 需要[用户授权](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/authorize.html) scope.userLocation + * @see https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.chooseLocation.html + */ + function chooseLocation(OBJECT?: chooseLocation.Param): Promise + + // TODO: wx.stopLocationUpdate + // TODO: wx.startLocationUpdateBackground + // TODO: wx.startLocationUpdate + // TODO: wx.onLocationChange + // TODO: wx.offLocationChange +} diff --git a/packages/taro/types/api/media/media.audio.d.ts b/packages/taro/types/api/media/media.audio.d.ts new file mode 100644 index 000000000000..7b47f0d6f2be --- /dev/null +++ b/packages/taro/types/api/media/media.audio.d.ts @@ -0,0 +1,499 @@ +declare namespace Taro { + /** + * **注意：1.6.0 版本开始，本接口不再维护。建议使用能力更强的 [Taro.createInnerAudioContext](https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.createInnerAudioContext.html) 接口** + * 结束播放语音。 + * + * **示例代码：** + * + ```javascript + Taro.startRecord({ + success: function(res) { + var tempFilePath = res.tempFilePath + Taro.playVoice({ + filePath:tempFilePath + }) + setTimeout(function(){ + Taro.stopVoice() + }, 5000) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.stopVoice.html + */ + function stopVoice(): void + + namespace setInnerAudioOption { + type Param = { + /** + * 是否与其他音频混播，设置为 true 之后，不会终止其他应用或微信内的音乐 + */ + mixWithOther?: boolean + /** + * （仅在 iOS 生效）是否遵循静音开关，设置为 false 之后，即使是在静音模式下，也能播放声音 + */ + obeyMuteSwitch?: boolean + /** + * 接口调用成功的回调函数 + */ + success?: ParamPropSuccess + /** + * 接口调用失败的回调函数 + */ + fail?: ParamPropFail + /** + * 接口调用结束的回调函数（调用成功、失败都会执行） + */ + complete?: ParamPropComplete + } + /** + * 接口调用成功的回调函数 + */ + type ParamPropSuccess = (res: any) => any + /** + * 接口调用失败的回调函数 + */ + type ParamPropFail = (err: any) => any + /** + * 接口调用结束的回调函数（调用成功、失败都会执行） + */ + type ParamPropComplete = () => any + } + /** + * @since 2.3.0 + * + * 设置 InnerAudioContext 的播放选项。设置之后对当前小程序全局生效。 + * + * @see https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.setInnerAudioOption.html + */ + function setInnerAudioOption(OBJECT: setInnerAudioOption.Param): Promise + + namespace playVoice { + type Param = { + /** + * 需要播放的语音文件的文件路径 + */ + filePath: string + /** + * 指定录音时长，到达指定的录音时长后会自动停止录音，单位：秒，默认值：60 + * + * @since 1.6.0 + */ + duration?: number + /** + * 接口调用成功的回调函数 + */ + success?: ParamPropSuccess + /** + * 接口调用失败的回调函数 + */ + fail?: ParamPropFail + /** + * 接口调用结束的回调函数（调用成功、失败都会执行） + */ + complete?: ParamPropComplete + } + /** + * 接口调用成功的回调函数 + */ + type ParamPropSuccess = (res: any) => any + /** + * 接口调用失败的回调函数 + */ + type ParamPropFail = (err: any) => any + /** + * 接口调用结束的回调函数（调用成功、失败都会执行） + */ + type ParamPropComplete = () => any + } + /** + * **注意：1.6.0 版本开始，本接口不再维护。建议使用能力更强的 [Taro.createInnerAudioContext](https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.createInnerAudioContext.html) 接口** + * + * 开始播放语音，同时只允许一个语音文件正在播放，如果前一个语音文件还没播放完，将中断前一个语音播放。 + * + * **示例代码：** + * + ```javascript + Taro.startRecord({ + success: function(res) { + var tempFilePath = res.tempFilePath + Taro.playVoice({ + filePath: tempFilePath, + complete: function(){ + } + }) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.playVoice.html + */ + function playVoice(OBJECT: playVoice.Param): Promise + + /** + * **注意：1.6.0 版本开始，本接口不再维护。建议使用能力更强的 [Taro.createInnerAudioContext](https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.createInnerAudioContext.html) 接口** + * 暂停正在播放的语音。再次调用Taro.playVoice播放同一个文件时，会从暂停处开始播放。如果想从头开始播放，需要先调用 Taro.stopVoice。 + * + * **示例代码：** + * + ```javascript + Taro.startRecord({ + success: function(res) { + var tempFilePath = res.tempFilePath + Taro.playVoice({ + filePath: tempFilePath + }) + setTimeout(function() { + //暂停播放 + Taro.pauseVoice() + }, 5000) + } + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.pauseVoice.html + */ + function pauseVoice(): void + + const enum audioSourcesTypes { + /** + * 自动设置，默认使用手机麦克风，插上耳麦后自动切换使用耳机麦克风，所有平台适用 + */ + auto = 'auto', + /** + * 手机麦克风，仅限 iOS + */ + buildInMic = 'buildInMic', + /** + * 耳机麦克风，仅限 iOS + */ + headsetMic = 'headsetMic', + /** + * 麦克风（没插耳麦时是手机麦克风，插耳麦时是耳机麦克风），仅限 Android + */ + mic = 'mic', + /** + * 同 mic，适用于录制音视频内容，仅限 Android + */ + camcorder = 'camcorder', + /** + * 同 mic，适用于实时沟通，仅限 Android + */ + voice_communication = 'voice_communication', + /** + * 同 mic，适用于语音识别，仅限 Android + */ + voice_recognition = 'voice_recognition' + } + namespace getAvailableAudioSources { + type Param = { + success?: ParamPropSuccess + /** + * 接口调用失败的回调函数 + */ + fail?: ParamPropFail + /** + * 接口调用结束的回调函数（调用成功、失败都会执行） + */ + complete?: ParamPropComplete + } + /** + * 接口调用成功的回调函数 + */ + type ParamPropSuccess = (res: Result) => any + /** + * 接口调用失败的回调函数 + */ + type ParamPropFail = (err: any) => any + /** + * 接口调用结束的回调函数（调用成功、失败都会执行） + */ + type ParamPropComplete = () => any + + type Result = { + /** + * 支持的音频输入源列表，可在 RecorderManager.start() 接口中使用。返回值定义参考 https://developer.android.com/reference/kotlin/android/media/MediaRecorder.AudioSourc + */ + audioSources: audioSourcesTypes[] + } + } + /** + * @since 2.1.0 + * 获取当前支持的音频输入源。 + * + * @see https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.getAvailableAudioSources.html + */ + function getAvailableAudioSources(OBJECT: getAvailableAudioSources.Param): Promise + + /** + * @since 1.6.0 + * + * 创建并返回内部 audio 上下文 `innerAudioContext` 对象。_本接口是 `Taro.createAudioContext` 升级版。_ + * + * **errCode 说明：** + * + * errCode | 说明 + * ------------|--------- + * 10001 | 系统错误 + * 10002 | 网络错误 + * 10003 | 文件错误 + * 10004 | 格式错误 + * -1 | 未知错误 + * + * **示例代码：** + * + ```javascript + const innerAudioContext = Taro.createInnerAudioContext() + innerAudioContext.autoplay = true + innerAudioContext.src = 'http://ws.stream.qqmusic.qq.com/M500001VfvsJ21xFqb.mp3?guid=ffffffff82def4af4b12b3cd9337d5e7&uin=346897220&vkey=6292F51E1E384E061FF02C31F716658E5C81F5594D561F2E88B854E81CAAB7806D5E4F103E55D33C16F3FAC506D1AB172DE8600B37E43FAD&fromtag=46' + innerAudioContext.onPlay(() => { + console.log('开始播放') + }) + innerAudioContext.onError((res) => { + console.log(res.errMsg) + console.log(res.errCode) + }) + ``` + * @see https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.createInnerAudioContext.html + */ + function createInnerAudioContext(): InnerAudioContext + class InnerAudioContext { + /** + * 音频的数据链接，用于直接播放。 + */ + src: string + /** + * 开始播放的位置（单位：s），默认 0 + */ + startTime: number + /** + * 是否自动开始播放，默认 false + */ + autoplay: boolean + /** + * 是否循环播放，默认 false + */ + loop: boolean + /** + * 是否遵循系统静音开关，当此参数为 false 时，即使用户打开了静音开关，也能继续发出声音，默认值 true + */ + obeyMuteSwitch: boolean + /** + * 当前音频的长度（单位：s），只有在当前有合法的 src 时返回 + * + * @readonly + */ + duration: number + /** + * 当前音频的播放位置（单位：s），只有在当前有合法的 src 时返回，时间不取整，保留小数点后 6 位 + * + * @readonly + */ + currentTime: number + /** + * 当前是是否暂停或停止状态，true 表示暂停或停止，false 表示正在播放 + * + * @readonly + */ + paused: boolean + /** + * 音频缓冲的时间点，仅保证当前播放时间点到此时间点内容已缓冲。 + * + * @readonly + */ + buffered: number + /** + * 音量。范围 0~1。 + * + * @since 1.9.90 + */ + volume: number + /** + * 播放 + */ + play(): void + /** + * 暂停 + */ + pause(): void + /** + * 停止 + */ + stop(): void + /** + * 跳转到指定位置，单位 s + */ + seek(position: number): void + /** + * 销毁当前实例 + */ + destroy(): void + /** + * 音频进入可以播放状态，但不保证后面可以流畅播放 + */ + onCanplay(callback?: () => void): void + /** + * 音频播放事件 + */ + onPlay(callback?: () => void): void + /** + * 音频暂停事件 + */ + onPause(callback?: () => void): void + /** + * 音频停止事件 + */ + onStop(callback?: () => void): void + /** + * 音频自然播放结束事件 + */ + onEnded(callback?: () => void): void + /** + * 音频播放进度更新事件 + */ + onTimeUpdate(callback?: () => void): void + /** + * 音频播放错误事件 + */ + onError(callback?: () => void): void + /** + * 音频加载中事件，当音频因为数据不足，需要停下来加载时会触发 + */ + onWaiting(callback?: () => void): void + /** + * 音频进行 seek 操作事件 + */ + onSeeking(callback?: () => void): void + /** + * 音频完成 seek 操作事件 + */ + onSeeked(callback?: () => void): void + /** + * 取消监听 onCanplay 事件 + * + * @since 1.9.0 + */ + offCanplay(callback?: () => void): void + /** + * 取消监听 onPlay 事件 + * + * @since 1.9.0 + */ + offPlay(callback?: () => void): void + /** + * 取消监听 onPause 事件 + * + * @since 1.9.0 + */ + offPause(callback?: () => void): void + /** + * 取消监听 onStop 事件 + * + * @since 1.9.0 + */ + offStop(callback?: () => void): void + /** + * 取消监听 onEnded 事件 + * + * @since 1.9.0 + */ + offEnded(callback?: () => void): void + /** + * 取消监听 onTimeUpdate 事件 + * + * @since 1.9.0 + */ + offTimeUpdate(callback?: () => void): void + /** + * 取消监听 onError 事件 + * + * @since 1.9.0 + */ + offError(callback?: () => void): void + /** + * 取消监听 onWaiting 事件 + * + * @since 1.9.0 + */ + offWaiting(callback?: () => void): void + /** + * 取消监听 onSeeking 事件 + * + * @since 1.9.0 + */ + offSeeking(callback?: () => void): void + /** + * 取消监听 onSeeked 事件 + * + * @since 1.9.0 + */ + offSeeked(callback?: () => void): void + } + + /** + * **注意：1.6.0 版本开始，本接口不再维护。建议使用能力更强的 [Taro.createInnerAudioContext](https://developers.weixin.qq.com/miniprogram/dev/api/media/audio/wx.createInnerAudioContext.html) 接口** + * + * 创建并返回 audio 上下文 `audioContext` 对象。在自定义组件下，第二个参数传入组件实例this，以操作组件内 `