@tarojs/taro 3.5.0-canary.1 → 3.5.0

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

@@ -23,10 +23,10 @@ declare module '../../index' {
       /**
        * @default 0
        */
-      level?: keyof level
+      level?: keyof Level
     }
 
-    type level = {
+    type Level = {
       /** 表示会把 App、Page 的生命周期函数和 wx 命名空间下的函数调用写入日志 */
       0
       /** 表示不会把 App、Page 的生命周期函数和 wx 命名空间下的函数调用写入日志 */
@@ -34,6 +34,76 @@ declare module '../../index' {
     }
   }
 
+  /** 向调试面板中打印日志。console 是一个全局对象，可以直接访问。在微信客户端中，向 vConsole 中输出日志。
+   * 
+   * **注意**
+   *  - 由于 vConsole 功能有限，以及不同客户端对 console 方法的支持情况有差异，建议开发者在小程序中只使用本文档中提供的方法。
+   *  - 部分内容展示的限制请参见调试
+   * @supported weapp
+   * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/console.html
+   */
+  interface console {
+    /** 向调试面板中打印 debug 日志
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/console.debug.html
+     */
+    debug(
+      /** 日志内容，可以有任意多个。 */
+      ...args: any[]
+    ): void
+    /** 向调试面板中打印 error 日志
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/console.error.html
+     */
+    error(
+      /** 日志内容，可以有任意多个。 */
+      ...args: any[]
+    ): void
+    /** 在调试面板中创建一个新的分组
+     *
+     * **注意**
+     * 仅在工具中有效，在 vConsole 中为空函数实现。
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/console.group.html
+     */
+    group(
+      /** 分组标记 */
+      label?: string,
+    ): void
+    /** 结束由 [console.group](#group) 创建的分组
+     *
+     * **注意**
+     * 仅在工具中有效，在 vConsole 中为空函数实现。
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/console.groupEnd.html
+     */
+    groupEnd(): void
+    /** 向调试面板中打印 info 日志
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/console.info.html
+     */
+    info(
+      /** 日志内容，可以有任意多个。 */
+      ...args: any[]
+    ): void
+    /** 向调试面板中打印 log 日志
+     * @supported weapp, tt
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/console.log.html
+     */
+    log(
+      /** 日志内容，可以有任意多个。 */
+      ...args: any[]
+    ): void
+    /** 向调试面板中打印 warn 日志
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/console.warn.html
+     */
+    warn(
+      /** 日志内容，可以有任意多个。 */
+      ...args: any[]
+    ): void
+  }
+
   /**
    * 日志管理器实例，可以通过 Taro.getLogManager 获取。
    *
@@ -44,6 +114,8 @@ declare module '../../index' {
    * 开发者可以通过小程序管理后台左侧菜单“反馈管理”页面查看相关打印日志。
    *
    * 基础库默认会把 App、Page 的生命周期函数和 wx 命名空间下的函数调用写入日志。
+   * @supported weapp
+   * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/LogManager.html
    */
   interface LogManager {
     /** 写 debug 日志
@@ -86,6 +158,8 @@ declare module '../../index' {
    * 使用说明
    * 为帮助小程序开发者快捷地排查小程序漏洞、定位问题，我们推出了实时日志功能。从基础库2.7.1开始，开发者可通过提供的接口打印日志，日志汇聚并实时上报到小程序后台。
    * 开发者可从小程序管理后台“开发->运维中心->实时日志”进入日志查询页面，查看开发者打印的日志信息。
+   * @supported weapp
+   * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/RealtimeLogManager.html
    */
 
   interface RealtimeLogManager {
@@ -129,6 +203,14 @@ declare module '../../index' {
       /** 过滤关键字，最多不超过1Kb，可以在小程序管理后台根据设置的内容搜索得到对应的日志。 */
       msg: string
     ): void
+    /** 获取给定标签的日志管理器实例，目前只支持在插件使用
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/RealtimeLogManager.tag.html
+     */
+    tag(
+      /** 标签名 */
+      tagName: string
+    ): RealtimeTagLogManager
     /** 写 warn 日志
      * @supported weapp
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/RealtimeLogManager.warn.html
@@ -139,6 +221,63 @@ declare module '../../index' {
     ): void
   }
 
+  /** 给定标签的实时日志管理器实例，可以通过 给定标签的实时日志管理器实例，可以通过 [RealtimeLogManager.tag](./RealtimeLogManager#tag) 接口获取，目前只支持在插件使用。 接口获取，目前只支持在插件使用。
+   * 
+   * **使用说明**
+   * RealtimeTagLogManager 功能和 [RealtimeLogManager](./RealtimeLogManager) 相似，但是为了让输出的实时日志更易于分析，其具有更严格的格式要求。
+   * RealtimeTagLogManager 使用时需要传入标签，调用该实例所输出的日志均会被汇集到对应标签下，同时该实例的日志只支持 key-value 格式进行输出。
+   * @supported weapp
+   * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/RealtimeTagLogManager.html
+   */
+  interface RealtimeTagLogManager {
+    /** 添加过滤关键字
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/RealtimeTagLogManager.addFilterMsg.html
+     */
+    addFilterMsg(
+      /** 是 setFilterMsg 的添加接口。用于设置多个过滤关键字。 */
+      msg: string
+    ): void
+    /** 写 error 日志
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/RealtimeTagLogManager.error.html
+     */
+    error(
+      /** 日志的 key */
+      key: string,
+      /** 日志的 key */
+      value: Object | any[] | number | string,
+    ): void
+    /** 写 info 日志
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/RealtimeTagLogManager.info.html
+     */
+    info(
+      /** 日志的 key */
+      key: string,
+      /** 日志的 key */
+      value: Object | any[] | number | string,
+    ): void
+    /** 设置过滤关键字
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/RealtimeTagLogManager.setFilterMsg.html
+     */
+    setFilterMsg(
+      /** 过滤关键字，最多不超过1Kb，可以在小程序管理后台根据设置的内容搜索得到对应的日志。 */
+      msg: string
+    ): void
+    /** 写 warn 日志
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/debug/RealtimeTagLogManager.warn.html
+     */
+    warn(
+      /** 日志的 key */
+      key: string,
+      /** 日志的 key */
+      value: Object | any[] | number | string,
+    ): void
+  }
+
   interface TaroStatic {
     /**
      * 设置是否打开调试开关，此开关对正式版也能生效。
@@ -159,32 +298,32 @@ declare module '../../index' {
     setEnableDebug(res: setEnableDebug.Option): Promise<setEnableDebug.Promised>
 
     /**
-     * 获取日志管理器对象。
+     * 获取实时日志管理器对象。
      * @supported weapp
      * @example
      * ```tsx
-     * const logger = Taro.getLogManager({level: 1})
-     *
-     * logger.log({str: 'hello world'}, 'basic log', 100, [1, 2, 3])
+     * const logger = Taro.getRealtimeLogManager()
      * logger.info({str: 'hello world'}, 'info log', 100, [1, 2, 3])
-     * logger.debug({str: 'hello world'}, 'debug log', 100, [1, 2, 3])
+     * logger.error({str: 'hello world'}, 'error 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
      */
-    getLogManager(res?: getLogManager.Option): LogManager
+    getRealtimeLogManager(): RealtimeLogManager
 
     /**
-     * 获取实时日志管理器对象。
+     * 获取日志管理器对象。
      * @supported weapp
      * @example
      * ```tsx
-     * const logger = Taro.getRealtimeLogManager()
+     * 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.error({str: 'hello world'}, 'error 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
      */
-    getRealtimeLogManager(): RealtimeLogManager
+    getLogManager(res?: getLogManager.Option): LogManager
   }
 }

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

@@ -3,10 +3,11 @@ import Taro from '../../index'
 declare module '../../index' {
   interface TaroStatic {
     /**
-     * @supported weapp
+     * @supported weapp, h5, rn
      * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/env/envObj.html
      */
     env: {
+      [key: string]: string | undefined
       /** 文件系统中的用户目录路径 (本地路径) */
       USER_DATA_PATH: string
     }

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

@@ -3,7 +3,7 @@ import Taro from '../../index'
 declare module '../../index' {
   interface TaroStatic {
     /** 判断小程序的 API，回调，参数，组件等是否在当前版本可用。
-     * @supported weapp
+     * @supported weapp, tt
      * @example
      * ```tsx
      * Taro.canIUse('openBluetoothAdapter')
@@ -35,9 +35,16 @@ declare module '../../index' {
       schema: string
     ): boolean
 
+    /** 判断能否使用 WebP 格式
+     * 
+     * > 在小程序平台中仅在 android 和 devtools 设备时可用
+     * @supported global
+     */
+    canIUseWebp(): boolean
+
     /**
      * 将 Base64 字符串转成 ArrayBuffer 数据。
-     * @supported weapp, h5
+     * @supported weapp, h5, rn, tt
      * @example
      * ```tsx
      * const base64 = 'CxYh'
@@ -52,7 +59,7 @@ declare module '../../index' {
 
     /**
      * 将 ArrayBuffer 数据转成 Base64 字符串。
-     * @supported weapp, h5
+     * @supported weapp, h5, rn, tt
      * @example
      * ```tsx
      * const arrayBuffer = new Uint8Array([11, 22, 33])
@@ -88,6 +95,7 @@ declare module '../../index' {
 
     /**
      * 预加载的数据
+     * @ignore
      */
     preloadData: Record<string, any>
   }

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

@@ -0,0 +1,195 @@
+import Taro from '../../index'
+
+declare module '../../index' {
+  /** EntryList 对象
+   * @supported weapp
+   * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/EntryList.html
+   */
+  interface EntryList {
+    /** 该方法返回当前列表中的所有性能数据
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/EntryList.getEntries.html
+     */
+    getEntries(): PerformanceEntry[]
+    /** 获取当前列表中所有名称为 [name] 且类型为 [entryType] 的性能数据
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/EntryList.getEntriesByName.html
+     */
+    getEntriesByName(name: string, entryType: string): PerformanceEntry[]
+    /** 获取当前列表中所有类型为 [entryType] 的性能数据
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/EntryList.getEntriesByType.html
+     */
+    getEntriesByType(entryType: string): PerformanceEntry[]
+  }
+
+  /** Performance 对象，用于获取性能数据及创建性能监听器
+   * @supported weapp, tt
+   * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/Performance.html
+   */
+  interface Performance {
+    /** 创建全局性能事件监听器
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/Performance.createObserver.html
+     */
+    createObserver(callback: Function): PerformanceObserver
+    /** 该方法返回当前缓冲区中的所有性能数据
+     * @supported weapp, tt
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/Performance.getEntries.html
+     */
+    getEntries(): PerformanceEntry[]
+    /** 获取当前缓冲区中所有名称为 [name] 且类型为 [entryType] 的性能数据
+     * @supported weapp, tt
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/Performance.getEntriesByName.html
+     */
+    getEntriesByName(name: string, entryType: string): PerformanceEntry[]
+    /** 获取当前缓冲区中所有类型为 [entryType] 的性能数据
+     * @supported weapp, tt
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/Performance.getEntriesByType.html
+     */
+    getEntriesByType(entryType: string): PerformanceEntry[]
+    /** 设置缓冲区大小，默认缓冲 30 条性能数据
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/Performance.setBufferSize.html
+     */
+    setBufferSize(size: number): void
+  }
+
+  /** 单条性能数据
+   * @supported weapp
+   * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/PerformanceEntry.html
+   */
+  interface PerformanceEntry {
+    /** 指标类型 */
+    entryType: keyof PerformanceEntry.EntryType
+    /** 指标名称 */
+    name: keyof PerformanceEntry.EntryName
+    /** 开始时间，不同指标的具体含义会有差异 */
+    startTime: number
+    /** 耗时 ms。仅对于表示阶段的指标有效。 */
+    duration: number
+    /** 页面路径。仅 render 和 navigation 类型指标有效。 */
+    path: string
+    /** 路由真正响应开始时间。仅 navigation 类型指标有效。 */
+    navigationStart: number
+    /** 路由详细类型，与小程序路由方法对应。仅 navigation 类型指标有效。 */
+    navigationType: string
+    /** 分包名，主包表示为 APP。仅 evaluateScript 指标有效。 */
+    moduleName: string
+    /** 注入文件列表。仅 evaluateScript 指标有效。 */
+    fileList: string[]
+    /** 渲染层代码注入完成时间。仅 firstRender 指标有效。 */
+    viewLayerReadyTime: number
+    /** 首次渲染参数从逻辑层发出的时间。仅 firstRender 指标有效。 */
+    initDataSendTime: number
+    /** 首次渲染参数在渲染层收到的时间。仅 firstRender 指标有效。 */
+    initDataRecvTime: number
+    /** 渲染层执行渲染开始时间。仅 firstRender 指标有效。 */
+    viewLayerRenderStartTime: number
+    /** 渲染层执行渲染结束时间。仅 firstRender 指标有效。 */
+    viewLayerRenderEndTime: number
+  }
+
+  /** PerformanceObserver 对象，用于监听性能相关事件
+   * @supported weapp
+   * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/PerformanceObserver.html
+   */
+  interface PerformanceObserver {
+    /** 获取当前支持的所有性能指标类型 */
+    supportedEntryTypes: PerformanceEntry[]
+    /** 停止监听
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/PerformanceObserver.disconnect.html
+     */
+    disconnect(): void
+    /** 开始监听
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/PerformanceObserver.observe.html
+     */
+    observe(option: PerformanceObserver.observe.Option): void
+  }
+
+  namespace PerformanceEntry {
+    /** entryType 的合法值 */
+    interface EntryType {
+      /** 路由 */
+      navigation
+      /** 渲染 */
+      render
+      /** 脚本 */
+      script
+    }
+    /** name 的合法值 */
+    interface EntryName {
+      /** 小程序启动耗时。起点为用户点击小程序图标，或小程序被拉起的时间；终点为首页 onReady。(entryType: navigation) */
+      appLaunch
+      /** 路由处理耗时。(entryType: navigation) */
+      route
+      /** 页面首次渲染耗时。起点为逻辑层收到路由事件，包括逻辑层页面与组件初始化、VD 同步、渲染层执行渲染的时间；终点为首页 onReady。(entryType: render) */
+      firstRender
+      /** [页面首次绘制](https://developer.mozilla.org/en-US/docs/Glossary/First_paint)。第一个像素渲染到屏幕上所用的时间。(entryType: render) */
+      firstPaint
+      /** [页面首次内容绘制](https://developer.mozilla.org/en-US/docs/Glossary/First_contentful_paint)。第一块内容渲染到屏幕上所用的时间。(entryType: render) */
+      firstContentfulPaint
+      /** 逻辑层 JS 代码注入耗时。(entryType: script) */
+      evaluateScript
+    }
+  }
+
+  namespace PerformanceObserver {
+    namespace observe {
+      interface Option {
+        /** 指标类型。不能和 entryTypes 同时使用 */
+        type: keyof EntryType
+        /** 指标类型列表。不能和 type 同时使用。 */
+        entryTypes: (keyof EntryType)[]
+      }
+      interface EntryType {
+        /** 路由 */
+        navigation
+        /** 渲染 */
+        render
+        /** 脚本 */
+        script
+      }
+    }
+  }
+
+  interface TaroStatic {
+    /** 小程序测速上报。使用前，需要在小程序管理后台配置。 详情参见[小程序测速](https://developers.weixin.qq.com/miniprogram/dev/framework/performanceReport/index.html)指南。
+     * @supported weapp
+     * @example
+     * ```tsx
+     * Taro.reportPerformance(1101, 680)
+     * Taro.reportPerformance(1101, 680, 'custom')
+     * ```
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/wx.reportPerformance.html
+     */
+    reportPerformance(
+      /** 指标 id */
+      id: number,
+      /** 需要上报的数值 */
+      value: number,
+      /** 自定义维度 */
+      dimensions?: string | string[],
+    ): void
+
+    /** 小程序测速上报。使用前，需要在小程序管理后台配置。 详情参见[小程序测速](https://developers.weixin.qq.com/miniprogram/dev/framework/performanceReport/index.html)指南。
+     * 
+     * **注意**
+     *  - 目前，当开启代码 [按需注入](https://developers.weixin.qq.com/miniprogram/dev/framework/ability/lazyload.html) `时，evaluateScript` 将仅包含公有部分代码，页面和组件的代码注入的时间会包含在 `firstRender` 中（因为页面和组件的代码注入过程成为了首次渲染过程的一部分）。因此开启按需注入后，脚本耗时降低，渲染时间提高属于正常现象，优化效果可以关注整体启动耗时（`appLaunch`）来评估。
+     *  - `firstPaint` 和 `firstContentfulPaint` 指标在开启 `vconsole` 的情况下，由于绘制 `vconsoel` 的面板，会导致数据提前。
+     * @supported weapp, tt
+     * @example
+     * ```tsx
+     * const performance = Taro.getPerformance()
+     * const observer = performance.createObserver((entryList) => {
+     *   console.log(entryList.getEntries())
+     * })
+     * observer.observe({ entryTypes: ['render', 'script', 'navigation'] })
+     * ```
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/base/performance/wx.getPerformance.html
+     */
+    getPerformance(): Performance
+  }
+}