@tarojs/taro 3.7.0-alpha.2 → 3.7.0-alpha.22

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

@@ -0,0 +1,198 @@
+import Taro from '../../index'
+
+declare module '../../index' {
+  interface CacheManager {
+    /** 添加规则
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.addRule.html
+     */
+    addRule(option: CacheManager.AddRuleOption): string
+    /** 批量添加规则
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.addRules.html
+     */
+    addRules(option: CacheManager.AddRulesOption): string[]
+    /** 清空所有缓存
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.clearCaches.html
+     */
+    clearCaches(): void
+    /** 清空所有规则，同时会删除对应规则下所有缓存
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.clearRules.html
+     */
+    clearRules(): void
+    /** 删除缓存
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.deleteCache.html
+     */
+    deleteCache(
+      /** 缓存 id */
+      id: string
+    ): void
+    /** 批量删除缓存
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.deleteCaches.html
+     */
+    deleteCaches(
+      /** 缓存 id 列表 */
+      ids: string[]
+    ): void
+    /** 删除规则，同时会删除对应规则下所有缓存
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.deleteRule.html
+     */
+    deleteRule(
+      /** 规则 id */
+      id: string
+    ): void
+    /** 批量删除规则，同时会删除对应规则下所有缓存
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.deleteRules.html
+     */
+    deleteRules(
+      /** 规则 id 列表 */
+      ids: string[]
+    ): void
+    /** 匹配命中的缓存规则，一般需要和 request 事件搭配使用
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.match.html
+     */
+    match(option: CacheManager.MatchOption): CacheManager.MatchResult
+    /** 取消事件监听
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.off.html
+     */
+    off(
+      /** 事件名称 */
+      eventName: string,
+      /** 事件监听函数 */
+      handler: TaroGeneral.EventCallback
+    ): void
+    /** 监听事件
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.on.html
+     */
+    on(
+      /** 事件名称 */
+      eventName: keyof CacheManager.OnEventName,
+      /** 事件监听函数 */
+      handler: TaroGeneral.EventCallback
+    ): void
+    /** 开启缓存，仅在 mode 为 none 时生效，调用后缓存管理器的 state 会置为 1
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.start.html
+     */
+    start(): void
+    /** 关闭缓存，仅在 mode 为 none 时生效，调用后缓存管理器的 state 会置为 0
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/CacheManager.stop.html
+     */
+    stop(): void
+  }
+
+  namespace CacheManager {
+    interface DataSchema {
+      /** 需要匹配的 data 对象的参数类型
+       * string、number、boolean、null、object、any（表示任意类型），
+       * 同时支持数组模式（数组模式则在类型后面加 []，如 string[] 表示字符串数组）
+       */
+      type: string
+      /** 需要匹配的 data 对象的参数值
+       * 当 type 为基本类型时，可以用 string/regexp 来匹配固定的值，
+       * 也可以通过 function 来确定值是否匹配，
+       * 如果传入的 type 是 object，那么表示需要嵌套匹配值是否正确，可以传入 Array
+       */
+      value?: string | RegExp | Function | DataRule[]
+    }
+    interface DataRule {
+      /** 需要匹配的参数名 */
+      name: string
+      schema: DataSchema | DataSchema[]
+    }
+    interface RuleObject {
+      /** 规则 id，如果不填则会由基础库生成  */
+      id: string
+      /** 请求方法，可选值 GET/POST/PATCH/PUT/DELETE，如果为空则表示前面提到的所有方法都能被匹配到  */
+      method: string
+      /** uri 匹配规则，可参考规则字符串写法和正则写法 */
+      url: any
+      /**
+       * 缓存有效时间，单位为 ms，不填则默认取缓存管理器全局的缓存有效时间
+       * @default 7 * 24 * 60 * 60 * 1000
+       */
+      maxAge: number
+      /**
+       * 匹配请求参数
+       */
+      dataSchema: DataRule[]
+    }
+
+    type Rule = string | RegExp | RuleObject
+
+    interface AddRuleOption {
+      /** 规则 */
+      rule: Rule
+    }
+    interface AddRulesOption {
+      rules: Rule[]
+    }
+    interface MatchOption {
+      /** request 事件对象  */
+      evt: any
+    }
+    interface MatchResult {
+      /** 命中的规则id */
+      ruleId: string
+      /** 缓存id */
+      cacheId: string
+      /** 缓存内容，会带有 fromCache 标记，方便开发者区分内容是否来自缓存 */
+      data: any
+      /** 缓存创建时间 */
+      createTime: number
+      /** 缓存有效时间 */
+      maxAge: number
+    }
+    interface OnEventName {
+      /** 发生 wx.request 请求，只在缓存管理器开启阶段会触发 */
+      request
+      /** 进入弱网/离线状态 */
+      enterWeakNetwork
+      /** 离开弱网/离线状态	 */
+      exitWeakNetwork
+    }
+  }
+
+  namespace createCacheManager {
+    interface Mode {
+      /** 弱网/离线使用缓存返回 */
+      weakNetwork
+      /** 总是使用缓存返回 */
+      always
+      /** 不开启，后续可手动开启/停止使用缓存返回 */
+      none
+    }
+    interface Extra {
+      /** 需要缓存的 wx api 接口，不传则表示支持缓存的接口全都做缓存处理。返回的如果是缓存数据，开发者可通过 fromCache 标记区分 */
+      apiList?: string[]
+    }
+    interface Option {
+      /** 全局 origin */
+      origin?: string
+      /** 缓存模式 */
+      mode?: keyof Mode
+      /** 全局缓存有效时间，单位为毫秒，默认为 7 天，最长不超过 30 天  */
+      maxAge?: number
+      /** 额外的缓存处理 */
+      extra?: Extra
+    }
+  }
+
+  interface TaroStatic {
+    /** 创建缓存管理器
+     * @supported weapp
+     * @see https://developers.weixin.qq.com/miniprogram/dev/api/storage/cachemanager/wx.createCacheManager.html
+     */
+    createCacheManager(option: createCacheManager.Option): CacheManager
+  }
+}

package/types/api/taro.extend.d.ts

@@ -0,0 +1,223 @@
+import React from 'react'
+
+import Taro from '../index'
+
+declare module '../index' {
+  namespace getAppInfo {
+    /** 应用信息 */
+    interface AppInfo {
+      platform: string
+      taroVersion: string
+      designWidth: number | ((size?: string | number) => number)
+    }
+  }
+
+  namespace getCurrentInstance {
+    interface Current {
+      app: AppInstance | null
+      router: RouterInfo | null
+      page: PageInstance | null
+      onReady: string
+      onHide: string
+      onShow: string
+      preloadData?: Record<any, any>
+      /**
+       * RN 私有对象navigationRef，用于使用底层接口控制路由
+       */
+      rnNavigationRef?: React.RefObject<any>
+    }
+  }
+
+  namespace setGlobalDataPlugin {
+    /** Vue3 插件，用于设置 `getApp()` 中的全局变量 */
+    interface Plugin {
+      install(app: any, data: any): void
+    }
+  }
+
+  /** @ignore */
+  interface TARO_ENV_TYPE {
+    [TaroGeneral.ENV_TYPE.WEAPP]: TaroGeneral.ENV_TYPE.WEAPP
+    [TaroGeneral.ENV_TYPE.WEB]: TaroGeneral.ENV_TYPE.WEB
+    [TaroGeneral.ENV_TYPE.RN]: TaroGeneral.ENV_TYPE.RN
+    [TaroGeneral.ENV_TYPE.SWAN]: TaroGeneral.ENV_TYPE.SWAN
+    [TaroGeneral.ENV_TYPE.ALIPAY]: TaroGeneral.ENV_TYPE.ALIPAY
+    [TaroGeneral.ENV_TYPE.TT]: TaroGeneral.ENV_TYPE.TT
+    [TaroGeneral.ENV_TYPE.QQ]: TaroGeneral.ENV_TYPE.QQ
+    [TaroGeneral.ENV_TYPE.JD]: TaroGeneral.ENV_TYPE.JD
+  }
+
+  namespace interceptorify {
+    type promiseifyApi<T, R> = (requestParams: T) => Promise<R>
+    interface InterceptorifyChain<T, R> {
+      requestParams: T
+      proceed: promiseifyApi<T, R>
+    }
+    type InterceptorifyInterceptor<T, R> = (chain: InterceptorifyChain<T, R>) => Promise<R>
+    interface Interceptorify<T, R> {
+      request(requestParams: T): Promise<R>
+      addInterceptor(interceptor: InterceptorifyInterceptor<T, R>): void
+      cleanInterceptors(): void
+    }
+  }
+
+  interface TaroStatic {
+    /** @ignore */
+    Events: {
+      new (): TaroGeneral.Events
+    }
+
+    /** 事件中心
+     * @supported global
+     */
+    eventCenter: TaroGeneral.Events
+
+    /** @ignore */
+    ENV_TYPE: TARO_ENV_TYPE
+
+    /** 获取环境变量
+     * @supported global
+     */
+    getEnv(): TaroGeneral.ENV_TYPE
+
+    /** 尺寸转换
+     * @supported global
+     */
+    pxTransform(size: number): string
+
+    /** 尺寸转换初始化
+     * @supported global
+     */
+    initPxTransform(config: {
+      baseFontSize?: number
+      deviceRatio?: TaroGeneral.TDeviceRatio
+      designWidth?: number | ((size?: string | number) => number)
+      targetUnit?: string
+      unitPrecision?: number
+    }): void
+
+    /** 小程序获取和 Taro 相关的 App 信息
+     * @supported weapp, alipay, jd, qq, swan, tt, h5
+     */
+    getAppInfo(): getAppInfo.AppInfo
+
+    getEnvInfoSync(): {
+      /** 小程序信息 */
+      microapp: {
+        /** 小程序版本号 */
+        mpVersion: string
+        /** 小程序环境 */
+        envType: string
+        /** 小程序appId */
+        appId: string
+      }
+      /** 插件信息 */
+      plugin: Record<string, unknown>
+      /** 通用参数 */
+      common: {
+        /** 用户数据存储的路径 */
+        USER_DATA_PATH: string
+        /** 校验白名单属性中的appInfoLaunchFrom后返回额外信息 */
+        location: string | undefined
+        launchFrom: string | undefined
+        schema: string | undefined
+      }
+    }
+
+    /** 小程序引用插件 JS 接口
+     * @supported weapp, alipay, h5, rn, jd, qq, swan, tt, quickapp
+     */
+    requirePlugin(pluginName: string): any
+
+    /** 获取当前页面实例
+     * @supported global
+     */
+    getCurrentInstance(): getCurrentInstance.Current
+
+    /** @ignore */
+    Current: getCurrentInstance.Current
+
+    /** Vue3 插件，用于设置 `getApp()` 中的全局变量
+     * @supported weapp, alipay, h5, rn, jd, qq, swan, tt, quickapp
+     * @example
+     * ```js
+     * // 使用插件
+     * const App = createApp(...)
+     * App.use(setGlobalDataPlugin, {
+     *   xxx: 999
+     * })
+     * // 获取全局变量
+     * Taro.getApp().xxx
+     * ```
+     */
+    setGlobalDataPlugin: setGlobalDataPlugin.Plugin
+
+    /** 获取自定义 TabBar 对应的 React 或 Vue 组件实例
+     * @supported weapp, jd
+     * @param page 小程序页面对象，可以通过 Taro.getCurrentInstance().page 获取
+     */
+    getTabBar<T>(page: getCurrentInstance.Current['page']): T | undefined
+
+    /** 获取当前页面渲染引擎类型
+     * @supported weapp
+     */
+    getRenderer(): 'webview' | 'skyline'
+
+    /**
+     * 包裹 promiseify api 的洋葱圈模型
+     * @supported global
+     * @param promiseifyApi
+     * @example
+     * ```tsx
+     * // 创建实例
+     * const modalInterceptorify = interceptorify(taro.showModal)
+     * // 添加拦截器
+     * modalInterceptorify.addInterceptor(async function (chain) {
+     *   const res = await chain.proceed({
+     *     ...chain.requestParams,
+     *     title: 'interceptor1'
+     *   })
+     *   return res
+     * })
+     * modalInterceptorify.addInterceptor(async function (chain) {
+     *   const res = await chain.proceed({
+     *     ...chain.requestParams,
+     *     content: 'interceptor2'
+     *   })
+     *   return res
+     * })
+     * // 使用
+     * modalInterceptorify.request({})
+     * ```
+     * @example
+     * ```tsx
+     * // 创建实例
+     * const fetchDataInterceptorify = interceptorify(taro.request)
+     * // 添加拦截器
+     * fetchDataInterceptorify.addInterceptor(async function (chain) {
+     *   taro.showLoading({
+     *     title: 'Loading...'
+     *   })
+     *   const res = await chain.proceed(chain.requestParams)
+     *   taro.hideLoading()
+     *   return res
+     * })
+     * fetchDataInterceptorify.addInterceptor(async function (chain) {
+     *   const params = chain.requestParams
+     *   const res = await chain.proceed({
+     *     url: 'http://httpbin.org' + params.url,
+     *   })
+     *   return res.data
+     * })
+     * // 使用
+     * fetchDataInterceptorify.request({
+     *   url: '/ip'
+     * }).then((res) => {
+     *   // log my ip
+     *   console.log(res.origin)
+     * })
+     * ```
+     */
+    interceptorify<T, R>(promiseifyApi: interceptorify.promiseifyApi<T, R>): interceptorify.Interceptorify<T, R>
+  }
+}

package/types/{taro.hooks.d.ts → api/taro.hooks.d.ts}

@@ -1,6 +1,6 @@
-import Taro from './index'
+import Taro from '../index'
 
-declare module './index' {
+declare module '../index' {
   interface TaroStatic {
     /**
      * 页面展示时的回调。
@@ -46,7 +46,7 @@ declare module './index' {
 
     /**
      * 当前是 tab 页时，tab 被点击时的回调。
-     * @supported weapp, rn
+     * @supported weapp, h5, rn
      */
     useTabItemTap(callback: (payload: TabItemTapObject) => void): void
 
@@ -85,7 +85,7 @@ declare module './index' {
 
     /**
      * 小程序有未处理的 Promise reject 时触发。也可以使用 Taro.onUnhandledRejection 绑定监听。
-     * @supported weapp, alipay
+     * @supported weapp, alipay, h5
      */
     useUnhandledRejection(callback: (error: { reason: Error, promise: Promise<Error> }) => void): void
 

package/types/api/ui/navigation-bar.d.ts

@@ -85,7 +85,7 @@ declare module '../../index' {
     showNavigationBarLoading(option?: showNavigationBarLoading.Option): void
 
     /** 动态设置当前页面的标题
-     * @supported weapp, h5, rn, tt
+     * @supported weapp, alipay, h5, rn, tt
      * @example
      * ```tsx
      * Taro.setNavigationBarTitle({

package/types/compile/compiler.d.ts

@@ -1,7 +1,9 @@
-import type swc from '@swc/core'
+import type { swc } from '@tarojs/helper'
 import type Webpack from 'webpack'
 
-type CompilerTypes = 'webpack4' | 'webpack5' | 'vite'
+export type CompilerTypes = CompilerWebpackTypes | 'vite'
+
+export type CompilerWebpackTypes = 'webpack5' | 'webpack4'
 
 interface IPrebundle {
   enable?: boolean
@@ -17,10 +19,10 @@ interface IPrebundle {
   }
 }
 
-interface ICompiler {
-  type: CompilerTypes
+interface ICompiler<T> {
+  type: T
   prebundle?: IPrebundle
-  vitePlugins?: any[]
+  vitePlugins?: any
 }
 
-export type Compiler = CompilerTypes | ICompiler
+export type Compiler<T extends CompilerTypes = CompilerWebpackTypes> = T | ICompiler<T>

package/types/compile/config/h5.d.ts

@@ -2,51 +2,119 @@ import type Webpack from 'webpack'
 import type Chain from 'webpack-chain'
 import type webpackDevServer from 'webpack-dev-server'
 import type HtmlWebpackPlugin from 'html-webpack-plugin'
-import type { IOption, IPostcssOption } from './util'
+import type { IOption, IPostcssOption, IUrlLoaderOption } from './util'
+import type { OutputOptions as RollupOutputOptions } from 'rollup'
+import type { CompilerTypes, CompilerWebpackTypes } from '../compiler'
 
 export interface IH5RouterConfig {
+  /** 配置路由模式 */
   mode?: 'hash' | 'browser' | 'multi'
+  /** 配置自定义路由 */
   customRoutes?: IOption
+  /** 配置路由基准路径 */
   basename?: string
   lazyload?: boolean | ((pagename: string) => boolean)
   renamePagename?: (pagename: string) => string
   forcePath?: string
 }
 
-export interface IH5Config {
+export interface IH5Config <T extends CompilerTypes = CompilerWebpackTypes> {
+  /** 设置输出解析文件的目录（默认值：'/'）*/
   publicPath?: string
+
+  /** h5 编译后的静态文件目录（默认值：'static'） */
   staticDirectory?: string
+
+  /** 编译后非 entry 的 js 文件的存放目录，主要影响动态引入的 pages 的存放路径（默认值：'chunk'） */
   chunkDirectory?: string
 
   webpack?: ((webpackConfig: Webpack.Configuration, webpack) => Webpack.Configuration) | Webpack.Configuration
 
+  /**
+   * 自定义 Webpack 配置
+   * @param chain  [webpackChain](https://github.com/neutrinojs/webpack-chain) 对象
+   * @param webpack webpack 实例
+   */
   webpackChain?: (chain: Chain, webpack: typeof Webpack) => void
 
-  output?: Webpack.Configuration['output']
+  /** webpack 编译模式下，可用于修改、拓展 Webpack 的 output 选项，配置项参考[官方文档](https://webpack.js.org/configuration/output/)
+  * vite 编译模式下，用于修改、扩展 rollup 的 output，目前仅适配 chunkFileNames 和 assetFileNames 两个配置，修改其他配置请使用 vite 插件进行修改。配置想参考[官方文档](https://rollupjs.org/configuration-options/)
+  */
+  output?: T extends 'vite' ? Pick<RollupOutputOptions, 'chunkFileNames' | 'assetFileNames' > : Webpack.Configuration['output']
+
+  /** 路由相关的配置 */
   router?: IH5RouterConfig
+
+  /** 预览服务的配置，可以更改端口等参数。具体配置参考 [webpack-dev-server](https://webpack.js.org/configuration/dev-server) */
   devServer?: webpackDevServer.Configuration
-  sourceMapType?: 'none' | 'eval' | 'cheap-eval-source-map' | 'cheap-module-eval-source-map' | 'eval-source-map' | 'cheap-source-map' | 'cheap-module-source-map' | 'inline-cheap-source-map' | 'inline-cheap-module-source-map' | 'source-map' | 'inline-source-map' | 'hidden-source-map' | 'nosources-source-map'
+
+  /**  具体配置请参考 [Webpack devtool](https://webpack.js.org/configuration/devtool/#devtool) 配置 (默认值：'cheap-module-eval-source-map')*/
+  sourceMapType?:
+    | 'none'
+    | 'eval'
+    | 'cheap-eval-source-map'
+    | 'cheap-module-eval-source-map'
+    | 'eval-source-map'
+    | 'cheap-source-map'
+    | 'cheap-module-source-map'
+    | 'inline-cheap-source-map'
+    | 'inline-cheap-module-source-map'
+    | 'source-map'
+    | 'inline-source-map'
+    | 'hidden-source-map'
+    | 'nosources-source-map'
+
+  /** extract 功能开关，开启后将使用 mini-css-extract-plugin 分离 css 文件，可通过 h5.miniCssExtractPluginOption 对插件进行配置 (默认值：watch 模式下为 false，否则为 true) */
   enableExtract?: boolean
-  transformOnly?: boolean
 
+  /** [css-loader](https://github.com/webpack-contrib/css-loader) 的附加配置 */
   cssLoaderOption?: IOption
+
+  /** [style-loader](https://github.com/webpack-contrib/style-loader) 的附加配置 */
   styleLoaderOption?: IOption
+
+  /** [sass-loader](https://github.com/webpack-contrib/sass-loader) 的附加配置 */
   sassLoaderOption?: IOption
+
+  /** [less-loader](https://github.com/webpack-contrib/less-loader) 的附加配置 */
   lessLoaderOption?: IOption
+
+  /** [stylus-loader](https://github.com/shama/stylus-loader) 的附加配置 */
   stylusLoaderOption?: IOption
-  mediaUrlLoaderOption?: IOption
-  fontUrlLoaderOption?: IOption
-  imageUrlLoaderOption?: IOption
+
+  /** 针对 mp4 | webm | ogg | mp3 | wav | flac | aac 文件的 [url-loader](https://github.com/webpack-contrib/url-loader) 配置 */
+  mediaUrlLoaderOption?: IUrlLoaderOption
+
+  /** 针对 woff | woff2 | eot | ttf | otf 文件的 [url-loader](https://github.com/webpack-contrib/url-loader) 配置 */
+  fontUrlLoaderOption?: IUrlLoaderOption
+
+  /** 针对 png | jpg | jpeg | gif | bpm | svg 文件的 [url-loader](https://github.com/webpack-contrib/url-loader) 配置 */
+  imageUrlLoaderOption?: IUrlLoaderOption
+
+  /** [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin) 的附加配置 */
   miniCssExtractPluginOption?: IOption
+
+  /** 配置需要额外的经由 Taro 预设的 postcss 编译的模块 */
   esnextModules?: string[]
+
+  /** 用于控制在 H5 端是否使用兼容性组件库，详情请看 [React 兼容性组件库](https://taro-docs.jd.com/docs/next/h5#react-兼容性组件库)。(默认值：false) */
   useHtmlComponents?: boolean
+
+  /** 用于控制在 H5 端是否使用旧版本适配器，旧版本采用全局注册组件，懒加载组件相关依赖；新版本适配器会自动注册相关组件，不再需要引入 @tarojs/components/loader 中的全局 defineCustomElements 方法。(默认值：false) */
   useDeprecatedAdapterComponent?: boolean
 
-  postcss?: IPostcssOption
+  /** 配置 postcss 相关插件 */
+  postcss?: IPostcssOption<'H5'>
+
+  /** html-webpack-plugin 的具体配置 */
   htmlPluginOption?: HtmlWebpackPlugin.Options
 
+  /** Web 编译过程的相关配置 */
   compile?: {
-    exclude?: any[]
-    include?: any[]
+    exclude?: (string | RegExp)[]
+    include?: (string | RegExp)[]
+    filter?: (filename: string) => boolean
   }
+  /** 是否把代码转化为 es5，只在 vite 编译模式下有效 */
+  es5?: T extends 'vite' ? boolean : undefined
 }