@tarojs/taro 3.4.0-beta.2 → 3.4.2

package/types/api/base/update.d.ts

@@ -1,6 +1,17 @@
 import Taro from '../../index'
 
 declare module '../../index' {
+  namespace updateWeChatApp {
+    interface Option {
+      /** 接口调用成功的回调函数 */
+      success?: (res: TaroGeneral.CallbackResult) => void
+      /** 接口调用失败的回调函数 */
+      fail?: (res: TaroGeneral.CallbackResult) => void
+      /** 接口调用结束的回调函数（调用成功、失败都会执行） */
+      complete?: (res: TaroGeneral.CallbackResult) => void
+    }
+  }
+
   namespace UpdateManager {
     /** 向微信后台请求检查更新结果事件的回调函数 */
     type OnCheckForUpdateCallback = (
@@ -13,37 +24,78 @@ declare module '../../index' {
   }
 
   /** UpdateManager 对象，用来管理更新，可通过 Taro.getUpdateManager 接口获取实例。
+   * 
+   * **Tips**
+   *  - 微信开发者工具上可以通过「编译模式」下的「下次编译模拟更新」开关来调试
+   *  - 小程序开发版/体验版没有「版本」概念，所以无法在开发版/体验版上测试更版本更新情况
+   * @supported weapp
+   * @example
+   * ```tsx
+   * const updateManager = Taro.getUpdateManager()
+   *
+   * updateManager.onCheckForUpdate(function (res) {
+   *   // 请求完新版本信息的回调
+   *   console.log(res.hasUpdate)
+   * })
+   *
+   * updateManager.onUpdateReady(function () {
+   *   wx.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/UpdateManager.html
    */
   interface UpdateManager {
     /** 强制小程序重启并使用新版本。在小程序新版本下载完成后（即收到 `onUpdateReady` 回调）调用。
+     * @supported weapp
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/update/UpdateManager.applyUpdate.html
      */
     applyUpdate(): void
     /** 监听向微信后台请求检查更新结果事件。微信在小程序冷启动时自动检查更新，不需由开发者主动触发。
+     * @supported weapp
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/update/UpdateManager.onCheckForUpdate.html
      */
     onCheckForUpdate(
         /** 向微信后台请求检查更新结果事件的回调函数 */
         callback: UpdateManager.OnCheckForUpdateCallback,
     ): void
-    /** 监听小程序更新失败事件。小程序有新版本，客户端主动触发下载（无需开发者触发），下载失败（可能是网络原因等）后回调
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/update/UpdateManager.onUpdateFailed.html
-     */
-    onUpdateFailed(
-        /** 小程序更新失败事件的回调函数 */
-        callback: (res: TaroGeneral.CallbackResult) => void,
-    ): void
     /** 监听小程序有版本更新事件。客户端主动触发下载（无需开发者触发），下载成功后回调
+     * @supported weapp
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/update/UpdateManager.onUpdateReady.html
      */
     onUpdateReady(
         /** 小程序有版本更新事件的回调函数 */
         callback: (res: TaroGeneral.CallbackResult) => void,
     ): void
+    /** 监听小程序更新失败事件。小程序有新版本，客户端主动触发下载（无需开发者触发），下载失败（可能是网络原因等）后回调
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/update/UpdateManager.onUpdateFailed.html
+     */
+    onUpdateFailed(
+        /** 小程序更新失败事件的回调函数 */
+        callback: (res: TaroGeneral.CallbackResult) => void,
+    ): void
   }
 
   interface TaroStatic {
+    /** 更新客户端版本。当判断用户小程序所在客户端版本过低时，可使用该接口跳转到更新微信页面。
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/update/wx.updateWeChatApp.html
+     */
+    updateWeChatApp(option: updateWeChatApp.Option): Promise<TaroGeneral.CallbackResult>
+
     /**
      * 获取**全局唯一**的版本更新管理器，用于管理小程序更新。
      * 关于小程序的更新机制，可以查看[运行机制](https://developers.weixin.qq.com/miniprogram/dev/framework/runtime/operating-mechanism.html)文档。

package/types/api/base/weapp/app-event.d.ts

@@ -9,7 +9,7 @@ declare module '../../../index' {
       path: string
       /** 打开不存在页面的 query 参数 */
       query: TaroGeneral.IAnyObject
-  }
+    }
     /** 小程序要打开的页面不存在事件的回调函数 */
     type Callback = (res: Result) => void
   }
@@ -44,30 +44,53 @@ declare module '../../../index' {
     }
   }
 
-  namespace themeChange {
+  namespace onUnhandledRejection {
+    type Callback<T = any> = (res: Result<T>) => void
+    type Result<T = any> = {
+      /** 拒绝原因，一般是一个 Error 对象 */
+      reason: string | Error
+      /** 被拒绝的 Promise 对象 */
+      promise: Promise<T>
+    }
+  }
+
+  namespace onThemeChange {
+    /** 系统主题改变事件的回调函数 */
+    type Callback = (res: Result) => void
+    interface Result {
+      /** 系统当前的主题，取值为`light`或`dark` */
+      theme: keyof ITheme
+    }
     interface ITheme {
       /** 浅色主题 */
       light
       /** 深色主题 */
       dark
     }
-    interface onThemeChangeResult {
-      /** 系统当前的主题，取值为`light`或`dark` */
-      theme: keyof ITheme
-    }
-    /** 系统主题改变事件的回调函数 */
-    type onThemeChangeCallback = (res: onThemeChangeResult) => void
-    /** 系统主题改变事件的回调函数 */
-    type offThemeChangeCallback = (res: TaroGeneral.CallbackResult) => void
   }
 
   interface TaroStatic {
+    /** 监听未处理的 Promise 拒绝事件。该事件与 [`App.onUnhandledRejection`](https://developers.weixin.qq.com/miniprogram/dev/reference/api/App.html#onUnhandledRejection-Object-object) 的回调时机与参数一致。
+     * 
+     * **注意**
+     *  - 所有的 unhandledRejection 都可以被这一监听捕获，但只有 Error 类型的才会在小程序后台触发报警。
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.onUnhandledRejection.html
+     */
+    onUnhandledRejection<T = any>(callback: onUnhandledRejection.Callback<T>): void
+
+    /** 监听系统主题改变事件。该事件与 [`App.onThemeChange`](https://developers.weixin.qq.com/miniprogram/dev/reference/api/App.html#onThemeChange-Object-object) 的回调时机一致。
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.onThemeChange.html
+     */
+    onThemeChange(callback: onThemeChange.Callback): void
+
     /**
      * 监听小程序要打开的页面不存在事件。该事件与 [`App.onPageNotFound`](https://developers.weixin.qq.com/miniprogram/dev/reference/api/App.html#onpagenotfoundobject-object) 的回调时机一致。
      *
      * **注意**
      * - 开发者可以在回调中进行页面重定向，但必须在回调中**同步**处理，异步处理（例如 `setTimeout` 异步执行）无效。
-     * - 若开发者没有调用 [Taro.onPageNotFound](https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.onPageNotFound.html) 绑定监听，也没有声明 `App.onPageNotFound`，当跳转页面不存在时，将推入微信客户端原生的页面不存在提示页面。
+     * - 若开发者没有调用 [Taro.onPageNotFound](/docs/apis/base/weapp/app-event/onPageNotFound) 绑定监听，也没有声明 `App.onPageNotFound`，当跳转页面不存在时，将推入微信客户端原生的页面不存在提示页面。
      * - 如果回调中又重定向到另一个不存在的页面，将推入微信客户端原生的页面不存在提示页面，并且不再第二次回调。
      * @supported weapp, h5
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.onPageNotFound.html
@@ -130,16 +153,28 @@ declare module '../../../index' {
      */
     onAppHide(
       /** 小程序切后台事件的回调函数 */
-      callback: (res: TaroGeneral.CallbackResult) => void,
+      callback: (res: onAppShow.CallbackResult) => void,
     ): void
 
+    /** 取消监听未处理的 Promise 拒绝事件
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.offUnhandledRejection.html
+     */
+    offUnhandledRejection<T = any>(callback: onUnhandledRejection.Callback<T>): void
+
+    /** 取消监听系统主题改变事件
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.offThemeChange.html
+     */
+    offThemeChange(callback: onThemeChange.Callback): void
+
     /** 取消监听小程序要打开的页面不存在事件
      * @supported weapp
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.offPageNotFound.html
      */
     offPageNotFound(
       /** 小程序要打开的页面不存在事件的回调函数 */
-      callback: (res: TaroGeneral.CallbackResult) => void,
+      callback: (res: onPageNotFound.Callback) => void,
     ): void
 
     /** 取消监听音频播放错误事件
@@ -149,7 +184,7 @@ declare module '../../../index' {
 
     offError(
       /** 音频播放错误事件的回调函数 */
-      callback: (res: TaroGeneral.CallbackResult) => void,
+      callback: (res: onError.Callback) => void,
     ): void
 
     /** 取消监听音频中断结束事件
@@ -187,17 +222,5 @@ declare module '../../../index' {
       /** 小程序切后台事件的回调函数 */
       callback: (res: TaroGeneral.CallbackResult) => void,
     ): void
-
-    /** 监听系统主题改变事件。该事件与 [`App.onThemeChange`](https://developers.weixin.qq.com/miniprogram/dev/reference/api/App.html#onThemeChange-Object-object) 的回调时机一致。
-     * @supported weapp
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.onThemeChange.html
-     */
-    onThemeChange(callback: themeChange.onThemeChangeCallback): void
-
-    /** 取消监听系统主题改变事件
-     * @supported weapp
-     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/app/app-event/wx.offThemeChange.html
-     */
-    offThemeChange(callback: themeChange.offThemeChangeCallback): void
   }
 }

package/types/api/base/weapp/life-cycle.d.ts

@@ -1,6 +1,136 @@
 import Taro from '../../../index'
 
 declare module '../../../index' {
+  namespace getLaunchOptionsSync {
+    /** 启动参数 */
+    interface LaunchOptions {
+      /** 启动小程序的路径 */
+      path: string
+      /** 启动小程序的 query 参数 */
+      query: TaroGeneral.IAnyObject
+      /** 启动小程序的[场景值](https://developers.weixin.qq.com/miniprogram/dev/framework/app-service/scene.html) */
+      scene: number
+      /** shareTicket，详见[获取更多转发信息](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/share.html) */
+      shareTicket: string
+      /** 来源信息。从另一个小程序、公众号或 App 进入小程序时返回。否则返回 `{}`。(参见后文注意) */
+      referrerInfo: LaunchOptions.ReferrerInfo
+      /** 打开的文件信息数组，只有从聊天素材场景打开（scene为1173）才会携带该参数 */
+      forwardMaterials?: LaunchOptions.ForwardMaterial[]
+      /** 从微信群聊/单聊打开小程序时，chatType 表示具体微信群聊/单聊类型 */
+      chatType?: keyof LaunchOptions.ChatType
+      /** API 类别 */
+      apiCategory?: keyof LaunchOptions.ApiCategory
+    }
+  
+    namespace LaunchOptions {
+      /** 来源信息 */
+      interface ReferrerInfo {
+        /** 来源小程序、公众号或 App 的 appId */
+        appId: string
+        /** 来源小程序传过来的数据，scene=1037或1038时支持 */
+        extraData: TaroGeneral.IAnyObject
+      }
+      /** ChatType 类型合法值 */
+      interface ForwardMaterial {
+        /** 文件的mimetype类型 */
+        type: string
+        /** 文件名 */
+        name: string
+        /** 文件路径（如果是webview则是url） */
+        path: string
+        /** 文件大小 */
+        size: number
+      }
+      /** ChatType 类型合法值 */
+      interface ChatType {
+        /** 微信联系人单聊 */
+        1
+        /** 企业微信联系人单聊 */
+        2
+        /** 普通微信群聊 */
+        3
+        /** 企业微信互通群聊 */
+        4
+      }
+      /** API 类别合法值 */
+      interface ApiCategory {
+        /** 默认类别 */
+        default
+        /** 原生功能化，视频号直播商品、商品橱窗等场景打开的小程序 */
+        nativeFunctionalized
+        /** 仅浏览，朋友圈快照页等场景打开的小程序 */
+        browseOnly
+        /** 内嵌，通过打开半屏小程序能力打开的小程序 */
+        embedded
+      }
+    }
+  }
+
+  namespace getEnterOptionsSync {
+    /** 启动参数 */
+    interface EnterOptions {
+      /** 启动小程序的路径 */
+      path: string
+      /** 启动小程序的[场景值](https://developers.weixin.qq.com/miniprogram/dev/framework/app-service/scene.html) */
+      scene: number
+      /** 启动小程序的 query 参数 */
+      query: TaroGeneral.IAnyObject
+      /** shareTicket，详见[获取更多转发信息](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/share.html) */
+      shareTicket: string
+      /** 来源信息。从另一个小程序、公众号或 App 进入小程序时返回。否则返回 `{}`。(参见后文注意) */
+      referrerInfo: EnterOptions.ReferrerInfo
+      /** 打开的文件信息数组，只有从聊天素材场景打开（scene为1173）才会携带该参数 */
+      forwardMaterials?: EnterOptions.ForwardMaterial[]
+      /** 从微信群聊/单聊打开小程序时，chatType 表示具体微信群聊/单聊类型 */
+      chatType?: keyof EnterOptions.ChatType
+      /** API 类别 */
+      apiCategory?: keyof EnterOptions.ApiCategory
+    }
+  
+    namespace EnterOptions {
+      /** 来源信息 */
+      interface ReferrerInfo {
+        /** 来源小程序、公众号或 App 的 appId */
+        appId: string
+        /** 来源小程序传过来的数据，scene=1037或1038时支持 */
+        extraData: TaroGeneral.IAnyObject
+      }
+      /** ChatType 类型合法值 */
+      interface ForwardMaterial {
+        /** 文件的mimetype类型 */
+        type: string
+        /** 文件名 */
+        name: string
+        /** 文件路径（如果是webview则是url） */
+        path: string
+        /** 文件大小 */
+        size: number
+      }
+      /** ChatType 类型合法值 */
+      interface ChatType {
+        /** 微信联系人单聊 */
+        1
+        /** 企业微信联系人单聊 */
+        2
+        /** 普通微信群聊 */
+        3
+        /** 企业微信互通群聊 */
+        4
+      }
+      /** API 类别合法值 */
+      interface ApiCategory {
+        /** 默认类别 */
+        default
+        /** 原生功能化，视频号直播商品、商品橱窗等场景打开的小程序 */
+        nativeFunctionalized
+        /** 仅浏览，朋友圈快照页等场景打开的小程序 */
+        browseOnly
+        /** 内嵌，通过打开半屏小程序能力打开的小程序 */
+        embedded
+      }
+    }
+  }
+
   interface TaroStatic {
     /**
      * 获取小程序启动时的参数。与 [`App.onLaunch`](https://developers.weixin.qq.com/miniprogram/dev/reference/api/App.html#onlaunchobject-object) 的回调参数一致。
@@ -10,6 +140,16 @@ declare module '../../../index' {
      * @supported weapp
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/app/life-cycle/wx.getLaunchOptionsSync.html
      */
-    getLaunchOptionsSync(): TaroGeneral.LaunchOptionsApp
+    getLaunchOptionsSync(): getLaunchOptionsSync.LaunchOptions
+
+    /**
+     * 获取本次小程序启动时的参数。如果当前是冷启动，则返回值与 [`App.onLaunch`](https://developers.weixin.qq.com/miniprogram/dev/reference/api/App.html#onLaunch-Object-object) 的回调参数一致；如果当前是热启动，则返回值与 [`App.onShow`](https://developers.weixin.qq.com/miniprogram/dev/reference/api/App.html#onShow-Object-object) 一致。
+     *
+     * **注意**
+     * 部分版本在无 `referrerInfo` 的时候会返回 `undefined`，建议使用 `options.referrerInfo && options.referrerInfo.appId` 进行判断。
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/app/life-cycle/wx.getEnterOptionsSync.html
+     */
+    getEnterOptionsSync(): getEnterOptionsSync.EnterOptions
   }
 }