@tarojs/taro 3.6.17 → 3.6.19

package/types/api/location/index.d.ts

@@ -7,16 +7,23 @@ declare module '../../index' {
       latitude: number
       /** 经度，范围为-180~180，负数表示西经。使用 gcj02 国测局坐标系 */
       longitude: number
+      /** 缩放比例
+       * @weapp 范围 5~18，默认值18
+       * @alipay 范围 3~19，默认值15
+       */
+      scale?: number
+      /** 位置名 */
+      name?: string
       /** 地址的详细说明 */
       address?: string
+      /** 定义在拉起的地图 App 面板中需要被屏蔽的地图类 App
+       * @supported swan
+       */
+      ignoredApps?: Array<any>
       /** 接口调用结束的回调函数（调用成功、失败都会执行） */
       complete?: (res: TaroGeneral.CallbackResult) => void
       /** 接口调用失败的回调函数 */
       fail?: (res: TaroGeneral.CallbackResult) => void
-      /** 位置名 */
-      name?: string
-      /** 缩放比例，范围5~18 */
-      scale?: number
       /** 接口调用成功的回调函数 */
       success?: (res: TaroGeneral.CallbackResult) => void
     }
@@ -24,20 +31,32 @@ declare module '../../index' {
 
   namespace getLocation {
     interface Option {
-      /** 传入 true 会返回高度信息，由于获取高度需要较高精确度，会减慢接口返回速度 */
-      altitude?: string
+      /** 传入 true 会返回高度信息，由于获取高度需要较高精确度，会减慢接口返回速度
+       * @default false
+       */
+      altitude?: boolean
       /** 接口调用结束的回调函数（调用成功、失败都会执行） */
       complete?: (res: TaroGeneral.CallbackResult) => void
       /** 接口调用失败的回调函数 */
       fail?: (res: TaroGeneral.CallbackResult) => void
       /** 高精度定位超时时间(ms)，指定时间内返回最高精度，该值3000ms以上高精度定位才有效果 */
       highAccuracyExpireTime?: number
-      /** 开启高精度定位 */
+      /** 开启高精度定位
+       * @default false
+       */
       isHighAccuracy?: boolean
       /** 接口调用成功的回调函数 */
       success?: (result: SuccessCallbackResult) => void
-      /** wgs84 返回 gps 坐标，gcj02 返回可用于 Taro.openLocation 的坐标 */
+      /** wgs84 返回 gps 坐标，gcj02 返回可用于 Taro.openLocation 的坐标
+       * @default "wgs84"
+       */
       type?: string
+      /** 针对 iOS14/Android12 及以上的新特性，其他情况本参数忽略。默认情况宿主是精确定位就返回精确定位信息。
+       * 传入 true 会强制使用精确定位信息，iOS14/Android12 及以上如果没有精确定位权限，会弹出精确定位授权弹框
+       * @supported swan
+       * @default false
+       */
+      needFullAccuracy?: boolean
     }
     interface SuccessCallbackResult extends TaroGeneral.CallbackResult {
       /** 位置的精确度 */
@@ -54,6 +73,42 @@ declare module '../../index' {
       speed: number
       /** 垂直精度，单位 m（Android 无法获取，返回 0） */
       verticalAccuracy: number
+      /** 城市名称
+       * @supported swan
+       */
+      street?: string
+      /** 国家代码
+       * @supported swan
+       */
+      cityCode?: string
+      /** 城市名称
+       * @supported swan, tt
+       */
+      city?: string
+      /** 国家
+       * @supported swan
+       */
+      country?: string
+      /** 国家代码
+       * @supported swan
+       */
+      countryCode?: string
+      /** 省份
+       * @supported swan
+       */
+      province?: string
+      /** 街道号码
+       * @supported swan
+       */
+      streetNumber?: string
+      /** 区
+       * @supported swan
+       */
+      district?: string
+      /** 是不是精确定位信息
+       * @supported swan
+       */
+      isFullAccuracy?: boolean
       /** 调用结果 */
       errMsg: string
     }
@@ -97,6 +152,12 @@ declare module '../../index' {
        * @see https://lbs.qq.com/webApi/component/componentGuide/componentPicker
        */
       mapOpts?: Record<string, unknown>
+      /** 页面显示标题
+       * @supported alipay
+       * @alipay 安卓默认值为 位置，iOS、IDE 默认值为 你在哪里?
+       * @see https://opendocs.alipay.com/mini/api/location?pathHash=951b46a1
+       */
+      title?: string
       /** 接口调用成功的回调函数 */
       success?: (result: SuccessCallbackResult) => void
       /** 接口调用失败的回调函数 */
@@ -114,6 +175,30 @@ declare module '../../index' {
       longitude: number
       /** 位置名称 */
       name: string
+      /** 区县代码
+       * @supported alipay
+       */
+      adCode?: number
+      /** 区县名称
+       * @supported alipay
+       */
+      adName?: string
+      /** 城市代码
+       * @supported alipay
+       */
+      cityCode?: string
+      /** 城市名称
+       * @supported alipay
+       */
+      cityName?: string
+      /** 省份代码
+       * @supported alipay
+       */
+      provinceCode?: number
+      /** 省份名称
+       * @supported alipay
+       */
+      provinceName?: string
       /** 调用结果 */
       errMsg: string
     }
@@ -132,6 +217,10 @@ declare module '../../index' {
 
   namespace startLocationUpdateBackground {
     interface Option {
+      /** wgs84 返回 gps 坐标，gcj02 返回可用于 wx.openLocation 的坐标
+       * @default "gcj02"
+       */
+      type?: string
       /** 接口调用结束的回调函数（调用成功、失败都会执行） */
       complete?: (res: TaroGeneral.CallbackResult) => void
       /** 接口调用失败的回调函数 */
@@ -143,6 +232,16 @@ declare module '../../index' {
 
   namespace startLocationUpdate {
     interface Option {
+      /** wgs84 返回 gps 坐标，gcj02 返回可用于 wx.openLocation 的坐标
+       * @default "gcj02"
+       */
+      type?: string
+      /** 针对 iOS14/Android12 及以上的新特性，其他情况本参数忽略。默认情况宿主是精确定位就返回精确定位信息。
+       * 传入 true 会强制使用精确定位信息，iOS14/Android12 及以上如果没有精确定位权限，会弹出精确定位授权弹框
+       * @supported swan
+       * @default false
+       */
+      needFullAccuracy?: boolean
       /** 接口调用结束的回调函数（调用成功、失败都会执行） */
       complete?: (res: TaroGeneral.CallbackResult) => void
       /** 接口调用失败的回调函数 */
@@ -161,6 +260,11 @@ declare module '../../index' {
     interface CallbackResult {
       /** 错误码 */
       errCode: number
+      /** 错误信息
+       * @supported tt
+       * @tt 最低支持版本 2.48.0
+       */
+      errMsg?: string
     }
   }
 
@@ -185,13 +289,50 @@ declare module '../../index' {
       speed: number
       /** 垂直精度，单位 m（Android 无法获取，返回 0） */
       verticalAccuracy: number
+      /** 街道名称
+       * @supported swan
+       */
+      street?: string
+      /** 城市编码
+       * @supported swan
+       */
+      cityCode?: string
+      /** 城市名称
+       * @supported swan, tt
+       * @tt iOS 不支持
+       */
+      city?: string
+      /** 国家
+       * @supported swan
+       */
+      country?: string
+      /** 国家代码
+       * @supported swan
+       */
+      countryCode?: string
+      /** 省份
+       * @supported swan
+       */
+      province?: string
+      /** 街道号码
+       * @supported swan
+       */
+      streetNumber?: string
+      /** 区
+       * @supported swan
+       */
+      district?: string
+      /** 是不是精确定位信息
+       * @supported swan
+       */
+      isFullAccuracy?: boolean
     }
   }
 
   namespace getFuzzyLocation {
     interface Option {
       /** wgs84 返回 gps 坐标，gcj02 返回可用于 Taro.openLocation 的坐标 */
-      type?: 'wgs84' | 'gcj02'
+      type?: keyof Type
       /** 接口调用结束的回调函数（调用成功、失败都会执行） */
       complete?: (res: TaroGeneral.CallbackResult) => void
       /** 接口调用失败的回调函数 */
@@ -200,6 +341,13 @@ declare module '../../index' {
       success?: (result: SuccessCallbackResult) => void
     }
 
+    interface Type {
+      /** 返回 gps 坐标 */
+      wgs84
+      /** 返回 gcj02 坐标*/
+      gcj02
+    }
+
     interface SuccessCallbackResult extends TaroGeneral.CallbackResult {
       /** 纬度，范围为 -90~90，负数表示南纬 */
       latitude: number
@@ -210,7 +358,7 @@ declare module '../../index' {
 
   interface TaroStatic {
     /** 关闭监听实时位置变化，前后台都停止消息接收
-     * @supported weapp, rn, tt
+     * @supported weapp, swan, tt, rn
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.stopLocationUpdate.html
      */
     stopLocationUpdate(option?: stopLocationUpdate.Option): void
@@ -232,13 +380,13 @@ declare module '../../index' {
      *
      * **注意**
      * - 获取位置信息需配置[地理位置用途说明](https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html#permission)。
-     * @supported weapp, rn, tt
+     * @supported weapp, swan, tt, rn
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.startLocationUpdate.html
      */
     startLocationUpdate(option?: startLocationUpdate.Option): void
 
     /** 使用微信内置地图查看位置
-     * @supported weapp, h5, tt
+     * @supported weapp, alipay, swan, jd, tt, h5
      * @example
      * ```tsx
      * Taro.getLocation({
@@ -268,7 +416,7 @@ declare module '../../index' {
     ): void
 
     /** 监听实时地理位置变化事件，需结合 Taro.startLocationUpdateBackground、Taro.startLocationUpdate 使用。
-     * @supported weapp, rn, tt
+     * @supported weapp, swan, tt, rn
      * @example
      * ```tsx
      * const _locationChangeFn = function (res) {
@@ -290,16 +438,16 @@ declare module '../../index' {
      */
     offLocationChangeError(
       /** 监听持续定位接口返回失败时触发的回调函数 */
-      callback: onLocationChangeError.Callback,
+      callback?: onLocationChangeError.Callback,
     ): void
 
     /** 取消监听实时地理位置变化事件
-     * @supported weapp, rn, tt
+     * @supported weapp, swan, tt, rn
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/location/wx.offLocationChange.html
      */
     offLocationChange(
       /** 实时地理位置变化事件的回调函数 */
-      callback: (res: TaroGeneral.CallbackResult) => void,
+      callback?: onLocationChange.Callback,
     ): void
 
     /** 获取当前的地理位置、速度。当用户离开小程序后，此接口无法调用。开启高精度定位，接口耗时会增加，可指定 highAccuracyExpireTime 作为超时时间。
@@ -307,7 +455,7 @@ declare module '../../index' {
      * **注意**
      * - 工具中定位模拟使用IP定位，可能会有一定误差。且工具目前仅支持 gcj02 坐标。
      * - 使用第三方服务进行逆地址解析时，请确认第三方服务默认的坐标系，正确进行坐标转换。
-     * @supported weapp, rn, tt
+     * @supported weapp, swan, jd, qq, tt, rn
      * @example
      *  ```tsx
      * Taro.getLocation({
@@ -333,7 +481,7 @@ declare module '../../index' {
     /** 打开地图选择位置。
      *
      * `chooseLocation` api功能是依赖于腾讯位置服务，所以需要使用 api 密钥。如果您没有，可以前往腾讯位置服务[开发者控制台](https://lbs.qq.com/console/mykey.html?console=mykey)进行申请。
-     * @supported weapp, h5, tt
+     * @supported weapp, alipay, swan, jd, tt, h5
      * @example
      * ```tsx
      * // config/index.js

package/types/api/media/camera.d.ts

@@ -90,15 +90,15 @@ declare module '../../index' {
        * @supported alipay
        */
       height: string
-       /** 视频文件的宽度。
+      /** 视频文件的宽度。
        * @supported alipay
        */
       width: string
-       /** 视频文件的尺寸。
+      /** 视频文件的尺寸。
        * @supported alipay
        */
       size: string
-       /** 录制的持续时间。
+      /** 录制的持续时间。
        * @supported alipay
        */
       duration: string
@@ -152,6 +152,8 @@ declare module '../../index' {
       normal
       /** 低质量 */
       low
+      /** 原图 */
+      original
     }
   }
 
@@ -192,6 +194,7 @@ declare module '../../index' {
 
   interface TaroStatic {
     /** 创建 camera 上下文 CameraContext 对象。
+     * @alipay 支付宝小程序需指定 camera 组件中的 id 属性
      * @supported weapp, rn, tt, alipay
      * @example
      * ```tsx

package/types/api/open-api/login.d.ts

@@ -81,7 +81,7 @@ declare module '../../index' {
      *
      * 通过 Taro.login 接口获得的用户登录态拥有一定的时效性。用户越久未使用小程序，用户登录态越有可能失效。反之如果用户一直在使用小程序，则用户登录态一直保持有效。具体时效逻辑由微信维护，对开发者透明。开发者只需要调用 Taro.checkSession 接口检测当前用户登录态是否有效。
      *
-     * 登录态过期后开发者可以再调用 Taro.login 获取新的用户登录态。调用成功说明当前 session_key 未过期，调用失败说明 session_key 已过期。更多使用方法详见 [小程序登录](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/login.html)。
+     * 登录态过期后开发者可以再调用 Taro.login 获取新的用户登录态。调用 Taro.checkSession 成功说明当前 session_key 未过期，调用失败说明 session_key 已过期。更多使用方法详见 [小程序登录](https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/login.html)。
      * @supported weapp
      * @example
      * ```tsx

package/types/api/storage/background-fetch.d.ts

@@ -25,6 +25,25 @@ declare module '../../index' {
       /** 接口调用成功的回调函数 */
       success?: (res: TaroGeneral.CallbackResult) => void
     }
+
+    type Callback = (
+      result: CallbackResult,
+    ) => void
+
+    interface CallbackResult {
+      /** 缓存数据类别，取值为 periodic 或 pre */
+      fetchType: string
+      /** 缓存数据 */
+      fetchedData: string
+      /** 客户端拿到缓存数据的时间戳 */
+      timeStamp: number
+      /** 小程序页面路径 */
+      path: string
+      /** 传给页面的 query 参数 */
+      query: string
+      /** 进入小程序的场景值 */
+      scene: number
+    }
   }
 
   namespace getBackgroundFetchToken {
@@ -34,46 +53,79 @@ declare module '../../index' {
       /** 接口调用失败的回调函数 */
       fail?: (res: TaroGeneral.CallbackResult) => void
       /** 接口调用成功的回调函数 */
-      success?: (res: TaroGeneral.CallbackResult) => void
+      success?: (res: SuccessCallbackResult) => void
+    }
+    interface SuccessCallbackResult extends TaroGeneral.CallbackResult {
+      /** 自定义的登录态 */
+      token: string
+      /** 接口调用结果 */
+      errMsg: string
     }
   }
 
   namespace getBackgroundFetchData {
     interface Option {
-      /** 取值为 periodic */
+      /** 缓存数据类别
+       * @weapp 取值为 periodic
+       * @qq 取值为 periodic
+       * @alipay 取值为 pre: 数据预拉取; jsapiPre: API 预调用（目前仅支持地理位置预拉取）
+       */
       fetchType: string
       /** 接口调用结束的回调函数（调用成功、失败都会执行） */
       complete?: (res: TaroGeneral.CallbackResult) => void
       /** 接口调用失败的回调函数 */
       fail?: (res: TaroGeneral.CallbackResult) => void
       /** 接口调用成功的回调函数 */
-      success?: (res: TaroGeneral.CallbackResult) => void
+      success?: (res: SuccessCallbackResult) => void
+    }
+
+    interface SuccessCallbackResult extends TaroGeneral.CallbackResult {
+      /** 缓存数据
+       *  @alipay Object
+       */
+      fetchedData: string | Object
+      /** 客户端拿到缓存数据的时间戳 ms。(iOS 时间戳存在异常，8.0.27 修复) */
+      timeStamp: number
+      /** 小程序页面路径 */
+      path: string
+      /** 传给页面的 query 参数 */
+      query: string
+      /** 进入小程序的场景值 */
+      scene: number
+      /** 缓存数据类型，与入参 fetchType 一致
+       * @supported alipay
+       */
+      fetchType?: string
+      /** 缓存数据的时间戳。单位：ms。
+       * @supported alipay
+       */
+      timestamp?: number
     }
   }
 
   interface TaroStatic {
     /** 设置自定义登录态，在周期性拉取数据时带上，便于第三方服务器验证请求合法性
-     * @supported weapp
+     * @supported weapp, qq
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/background-fetch/wx.setBackgroundFetchToken.html
      */
-    setBackgroundFetchToken(option: setBackgroundFetchToken.Option): void
+    setBackgroundFetchToken(option: setBackgroundFetchToken.Option): Promise<TaroGeneral.CallbackResult>
 
     /** 收到 backgroundFetch 数据时的回调
-     * @supported weapp
+     * @supported weapp, qq
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/background-fetch/wx.onBackgroundFetchData.html
      */
-    onBackgroundFetchData(option?: onBackgroundFetchData.Option): void
+    onBackgroundFetchData(option?: onBackgroundFetchData.Option | onBackgroundFetchData.Callback): void
 
     /** 获取设置过的自定义登录态。若无，则返回 fail。
-     * @supported weapp
+     * @supported weapp, qq
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/background-fetch/wx.getBackgroundFetchToken.html
      */
-    getBackgroundFetchToken(option?: getBackgroundFetchToken.Option): void
+    getBackgroundFetchToken(option?: getBackgroundFetchToken.Option): Promise<TaroGeneral.CallbackResult>
 
     /** 拉取 backgroundFetch 客户端缓存数据
-     * @supported weapp
+     * @supported weapp, alipay, qq
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/background-fetch/wx.getBackgroundFetchData.html
      */
-    getBackgroundFetchData(option: getBackgroundFetchData.Option): void
+    getBackgroundFetchData(option: getBackgroundFetchData.Option): Promise<getBackgroundFetchData.SuccessCallbackResult>
   }
 }

package/types/api/storage/cache-manager.d.ts

@@ -2,8 +2,42 @@ import Taro from '../../index'
 
 declare module '../../index' {
   interface CacheManager {
+    /** 当前缓存模式 */
+    mode: keyof CacheManager.Mode
+    /** 全局 origin */
+    origin: string
+    /** 全局缓存有效时间 */
+    maxAge: number
+    /** 当前缓存管理器状态 */
+    state: keyof CacheManager.State
     /** 添加规则
      * @supported weapp
+     * @example
+     * ```tsx
+     * const ruleId = cacheManager.addRule({
+     *   id: 'haha-rule',
+     *   method: 'GET',
+     *   url: '/haha',
+     *   maxAge: 123455,
+     *   dataSchema: [
+     *     // data 字段的匹配，默认为空，表示不匹配
+     *     // 类型可以是：string、number、boolean、null、object、any（表示任意类型均可），以及这些类型的数组表示方式
+     *     {name: 'aaa', schema: {type: 'string'}}, // 类型为 string
+     *     {name: 'bbb', schema: [{type: 'number'}, {type: 'string'}]}, // 类型为 number, string
+     *     {name: 'ccc', schema: {type: 'string', value: 'abc'}}, // 值为 abc
+     *     {name: 'ddd', schema: {type: 'string', value: /(abc|cba)/ig}}, // 值符合该正则匹配，如果该值不是字符串类型，则会被尝试转成字符串后再进行比较
+     *     {name: 'ddd', schema: {type: 'string', value: val => val === '123'}}, // 传入函数来校验值
+     *     {name: 'eee', schema: {type: 'object', value: [{ // 类型为对象，则通过嵌套的方式来逐层校验
+     *       name: 'aaa', schema: {type: 'string'},
+     *       // ...
+     *       // 嵌套 dataSchema，同上面的方式一样来匹配嵌套的对象
+     *     }]}},
+     *     {name: 'fff', schema: {type: 'string[]'}}, // 类型为 string 数组
+     *     {name: 'ggg', schema: {type: 'any'}}, // 类型为任意类型
+     *     {name: 'hhh', schema: {type: 'any[]'}}, // 类型为任意类型的数组
+     *   ]
+     * })
+     * ```
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.addRule.html
      */
     addRule(option: CacheManager.AddRuleOption): string
@@ -92,6 +126,22 @@ declare module '../../index' {
   }
 
   namespace CacheManager {
+    interface Mode {
+      /** 默认值，弱网/离线使用缓存返回 */
+      weakNetwork
+      /** 总是使用缓存返回 */
+      always
+      /** 不开启，后续可手动开启/停止使用缓存返回	*/
+      none
+    }
+    interface State {
+      /** 不使用缓存返回 */
+      0
+      /** 使用缓存返回 */
+      1
+      /** 未知 */
+      2
+    }
     interface DataSchema {
       /** 需要匹配的 data 对象的参数类型
        * string、number、boolean、null、object、any（表示任意类型），
@@ -135,6 +185,7 @@ declare module '../../index' {
       rule: Rule
     }
     interface AddRulesOption {
+      /** 规则列表 */
       rules: Rule[]
     }
     interface MatchOption {
@@ -191,7 +242,7 @@ declare module '../../index' {
   interface TaroStatic {
     /** 创建缓存管理器
      * @supported weapp
-     * @see declare https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/wx.createCacheManager.html
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/wx.createCacheManager.html
      */
     createCacheManager(option: createCacheManager.Option): CacheManager
   }