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

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

@@ -1,75 +1,186 @@
 import type Webpack from 'webpack'
 import type Chain from 'webpack-chain'
+import { type Input } from 'postcss'
 import type { Compiler } from '../compiler'
 import type { IModifyWebpackChain } from '../hooks'
-import type { ICopyOptions, IOption, ISassOptions, TogglableOptions } from "./util"
+import type { ICopyOptions, IOption, ISassOptions, TogglableOptions } from './util'
 import type { IH5Config } from './h5'
 import type { IMiniAppConfig } from './mini'
+import { IRNConfig } from './rn'
 
-export type PluginItem = string | [string, object]
+export type PluginItem = string | [string, object] | [string, () => object | Promise<object>]
 
 interface ICache {
+  /**
+   * 是否开启持久化缓存 (默认值 false)
+   * @description ```
+   * 值为 false 时：开发模式下 WebpackConfig.cache.type = 'memory'，而生产模式下 WebpackConfig.cache = false;
+   * 值为 true 时：开发模式和生产模式下均为 WebpackConfig.cache.type = 'filesystem'
+   * ```
+   */
   enable?: boolean
+
+  /**
+   * 当依赖的文件或该文件的依赖改变时，使缓存失效。
+   * @description  详详情请参考 [WebpackConfig.cache.buildDependencies](https://webpack.js.org/configuration/cache/#cachebuilddependencies)。
+   */
   buildDependencies?: Record<string, any>
+
+  /**
+   * 缓存子目录的名称 (默认值 process.env.NODE_ENV-process.env.TARO_ENV)
+   * @description  详情请参考 [WebpackConfig.cache.name](https://webpack.js.org/configuration/cache/#cachename)
+   */
   name?: string
 }
 
 interface ILogger {
+  /** 是否简化输出日志 (默认值 true)*/
   quiet: boolean
+  /** 是否输出 Webpack Stats 信息 (默认值 false) */
   stats: boolean
 }
 
 export interface IProjectBaseConfig {
   isWatch?: boolean
   port?: number
+  /** 项目名称 */
   projectName?: string
+
+  /** 项目创建日期 */
   date?: string
-  designWidth?: number | ((size: number) => number)
+
+  /** 设计稿尺寸 */
+  designWidth?: number | ((size?: string | number | Input) => number)
+
+  /** 设计稿尺寸换算规则 */
   deviceRatio?: TaroGeneral.TDeviceRatio
+
   watcher?: any[]
+
+  /** 源码存放目录 (默认值：'src') */
   sourceRoot?: string
+
+  /** 代码编译后的生产目录 (默认值：'dist') */
   outputRoot?: string
+
+  /**
+   * 用于配置`process.env.xxxx`相关的环境变量
+   * @deprecated 建议使用根目录下的 .env 文件替代
+   * @description 注意：这里的环境变量只能在业务代码中使用，编译时的 node 环境中无法使用
+   * @example
+   * ```ts
+   * // config/index.ts
+   * export default defineConfig({
+   *    env: {
+   *      xxxx: '"测试"'
+   *    }
+   * })
+   *
+   * // src/app.ts
+   * onShow() {
+   *   console.log(process.env.xxxx) // 打印 "测试"
+   * }
+   * ```
+   */
   env?: IOption
+
+  /** 用于配置目录别名，从而方便书写代码引用路径 */
   alias?: IOption
+
+  /**
+   * 用于配置一些常量供代码中进行全局替换使用
+   * @description 注意：这里的环境变量只能在业务代码中使用，编译时的 node 环境中无法使用
+   * @example
+   * ```ts
+   * // config/index.ts
+   * export default defineConfig({
+   *    defineConstants: {
+   *        __TEST__: JSON.stringify('test')
+   *    }
+   * })
+   *
+   * // src/app.ts
+   * onShow() {
+   *   console.log(__TEST__) // 打印 "test"
+   * }
+   * ```
+   */
   defineConstants?: IOption
+
+  /** 用于把文件从源码目录直接拷贝到编译后的生产目录 */
   copy?: ICopyOptions
+
+  /** 配置 JS 压缩工具 (默认 terser) */
   jsMinimizer?: 'terser' | 'esbuild'
+
+  /** 配置 CSS 压缩工具 (默认 csso) */
   cssMinimizer?: 'csso' | 'esbuild' | 'parcelCss'
+
+  /** 配置 csso 工具以压缩 CSS 代码 */
   csso?: TogglableOptions
+
+  /** 配置 terser 工具以压缩 JS 代码 */
   terser?: TogglableOptions
+
   esbuild?: Record<'minify', TogglableOptions>
+
   uglify?: TogglableOptions
+
+  /** 用于控制对 scss 代码的编译行为，默认使用 dart-sass，具体配置可以参考 https://www.npmjs.com/package/sass */
   sass?: ISassOptions
+
+  /** 配置 Taro 插件 */
   plugins?: PluginItem[]
+
+  /** 一个 preset 是一系列 Taro 插件的集合，配置语法同 plugins */
   presets?: PluginItem[]
+
+  /** 模板循环次数 */
   baseLevel?: number
-  framework?: string
+
+  /** 使用的开发框架。可选值：react、preact、nerv、vue、vue3 */
+  framework?: 'react' | 'preact' | 'nerv' | 'vue' | 'vue3'
   frameworkExts?: string[]
+
+  /** 使用的编译工具。可选值：webpack4、webpack5 */
   compiler?: Compiler
+
+  /** Webpack5 持久化缓存配置。具体配置请参考 [WebpackConfig.cache](https://webpack.js.org/configuration/cache/#cache) */
   cache?: ICache
+
+  /** 控制 Taro 编译日志的输出方式 */
   logger?: ILogger
+
+  /** 用于控制是否生成 js、css 对应的 sourceMap */
   enableSourceMap?: boolean
+
   /**
    * 编译开始
    */
   onBuildStart?: (...args: any[]) => Promise<any>
+
   /**
    * 编译完成（启动项目后首次编译结束后会触发一次）
    */
   onBuildComplete?: (...args: any[]) => Promise<any>
+
   /**
    * 编译结束（保存代码每次编译结束后都会触发）
    */
-  onBuildFinish?: (res: { error, stats, isWatch }) => Promise<any>
+  onBuildFinish?: (res: { error; stats; isWatch }) => Promise<any>
+
   /**
    * 修改编译过程中的页面组件配置
    */
   onCompilerMake?: (compilation: Webpack.Compilation, compiler: Webpack.Compiler, plugin: any) => Promise<any>
+
   onWebpackChainReady?: (webpackChain: Chain) => Promise<any>
+
   /**
    * 编译中修改 webpack 配置，在这个钩子中，你可以对 webpackChain 作出想要的调整，等同于配置 [`webpackChain`](./config-detail#miniwebpackchain)
    */
   modifyWebpackChain?: (chain: Chain, webpack: typeof Webpack, data: IModifyWebpackChain) => Promise<any>
+
   /**
    * 编译中修改 vite 配置
    */
@@ -78,18 +189,123 @@ export interface IProjectBaseConfig {
    * 修改编译过程中的页面组件配置
    */
   modifyMiniConfigs?: (configMap: any) => Promise<any>
+
   /**
    * 修改编译后的结果
    */
   modifyBuildAssets?: (assets: any, miniPlugin?: any) => Promise<any>
 }
 
-export interface IProjectConfig extends IProjectBaseConfig {
-  ui?: {
-    extraWatchFiles?: any[]
-  }
+/** 暴露出来给 config/index 使用的配置类型，参考 https://github.com/NervJS/taro-doctor/blob/main/assets/config_schema.json */
+export interface IProjectConfig {
+  /** 项目名称 */
+  projectName?: string
+
+  /** 项目创建日期 */
+  date?: string
+
+  /** 设计稿尺寸 */
+  designWidth?: number | ((size?: string | number | Input) => number)
+
+  /** 设计稿尺寸换算规则 */
+  deviceRatio?: TaroGeneral.TDeviceRatio
+
+  /** 源码存放目录 (默认值：'src') */
+  sourceRoot?: string
+
+  /** 代码编译后的生产目录 (默认值：'dist') */
+  outputRoot?: string
+
+  /**
+   * 用于配置`process.env.xxxx`相关的环境变量
+   * @deprecated 建议使用根目录下的 .env 文件替代
+   * @description 注意：这里的环境变量只能在业务代码中使用，编译时的 node 环境中无法使用
+   * @example
+   * ```ts
+   * // config/index.ts
+   * export default defineConfig({
+   *    env: {
+   *      xxxx: '"测试"'
+   *    }
+   * })
+   *
+   * // src/app.ts
+   * onShow() {
+   *   console.log(process.env.xxxx) // 打印 "测试"
+   * }
+   * ```
+   */
+  env?: IOption
+
+  /** 用于配置目录别名，从而方便书写代码引用路径 */
+  alias?: IOption
+
+  /**
+   * 用于配置一些常量供代码中进行全局替换使用
+   * @description 注意：这里的环境变量只能在业务代码中使用，编译时的 node 环境中无法使用
+   * @example
+   * ```ts
+   * // config/index.ts
+   * export default defineConfig({
+   *    defineConstants: {
+   *        __TEST__: JSON.stringify('test')
+   *    }
+   * })
+   *
+   * // src/app.ts
+   * onShow() {
+   *   console.log(__TEST__) // 打印 "test"
+   * }
+   * ```
+   */
+  defineConstants?: IOption
+
+  /** 用于把文件从源码目录直接拷贝到编译后的生产目录 */
+  copy?: ICopyOptions
+
+  /** 配置 JS 压缩工具 (默认 terser) */
+  jsMinimizer?: 'terser' | 'esbuild'
+
+  /** 配置 CSS 压缩工具 (默认 csso) */
+  cssMinimizer?: 'csso' | 'esbuild' | 'parcelCss'
+
+  /** 配置 csso 工具以压缩 CSS 代码 */
+  csso?: TogglableOptions
+
+  /** 配置 terser 工具以压缩 JS 代码 */
+  terser?: TogglableOptions
+
+  esbuild?: Record<'minify', TogglableOptions>
+
+  /** 用于控制对 scss 代码的编译行为，默认使用 dart-sass，具体配置可以参考 https://www.npmjs.com/package/sass */
+  sass?: ISassOptions
+
+  /** 配置 Taro 插件 */
+  plugins?: PluginItem[]
+
+  /** 一个 preset 是一系列 Taro 插件的集合，配置语法同 plugins */
+  presets?: PluginItem[]
+
+  /** 使用的开发框架。可选值：react、preact、nerv、vue、vue3 */
+  framework?: 'react' | 'preact' | 'nerv' | 'vue' | 'vue3'
+
+  /** 使用的编译工具。可选值：webpack4、webpack5 */
+  compiler?: Compiler
+
+  /** Webpack5 持久化缓存配置。具体配置请参考 [WebpackConfig.cache](https://webpack.js.org/configuration/cache/#cache) */
+  cache?: ICache
+
+  /** 控制 Taro 编译日志的输出方式 */
+  logger?: ILogger
+
+  /** 专属于小程序的配置 */
   mini?: IMiniAppConfig
+
+  /** 专属于 H5 的配置 */
   h5?: IH5Config
-  rn?: IH5Config
+
+  /** 专属于 RN 的配置 */
+  rn?: IRNConfig
+
   [key: string]: any
 }

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

@@ -0,0 +1,56 @@
+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'
+
+export interface IRNConfig {
+  /** 设置 RN bundle 中注册应用的名称 */
+  appName: string
+
+  /** entry 利用模块查找规则{name}.{platform}.{ext}自动区分平台 */
+  entry?: string
+
+  /** 设置 Metro 打包生成 bundle 的输出路径，默认 dist 目录下 */
+  output?: any
+
+  /** [sass](https://github.com/sass/node-sass#options) 相关配置 */
+  sass?: IOption
+
+  /** [less](https://lesscss.org/usage/#less-options) 相关配置 */
+  less?: IOption
+
+  /** [stylus](https://github.com/NervJS/taro/blob/next/packages/taro-rn-style-transformer/README.md#rnstylus) 相关配置 */
+  stylus?: IOption
+
+  /** 配置 postcss 相关插件 */
+  postcss?: {
+    /** postcss 配置，参考 https://github.com/postcss/postcss#options */
+    options?: any
+    /** 默认true，控制是否对 css value 进行 scalePx2dp 转换，pxtransform配置 enable 才生效 */
+    scalable?: boolean
+    pxtransform?: {
+      enable?: boolean
+      /** 插件 pxtransform 配置项 */
+      config?: {
+        additionalProperties?: boolean
+        [key: string]: any
+      }
+    },
+    cssModules?: {
+      enable: boolean
+    },
+    [key: string]: any
+  }
+
+  resolve?: any
+
+  /** 支持多 className 转换，以 classname 或 style 结尾的， 提取前缀， 然后根据前缀，再生成对应的 xxxStyle。如：barClassName -> barStyle。默认值 false，不开启 */
+  enableMultipleClassName?: boolean
+
+  /** 当标签 style 属性值是数组时转换成对象。默认值 false，不开启 */
+  enableMergeStyle?: boolean
+
+  /** 将 svg 文件转换为组件引入。默认值 false，不开启 */
+  enableSvgTransform?: boolean
+}

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

@@ -1,3 +1,5 @@
+import { type Input } from 'postcss'
+
 export type Func = (...args: any[]) => any
 
 export type IOption = Record<string, any>
@@ -9,7 +11,9 @@ export type TogglableOptions<T = IOption> = {
 
 export namespace PostcssOption {
   export type cssModules = TogglableOptions<{
+    /** 转换模式，取值为 global/module */
     namingPattern: 'global' | string
+    /** 自定义生成的class名称规则 */
     generateScopedName: string | ((localName: string, absoluteFilePath: string) => string)
   }>
   export type url = TogglableOptions<{
@@ -18,11 +22,65 @@ export namespace PostcssOption {
   }>
 }
 
+export interface IHtmlTransformOption {
+  /** 是否启用 postcss-html-transform 插件 */
+  enable?: boolean
+  config?: {
+    /** 当前编译平台 (此选项插件内部根据编译平台自行生成，无需传入) */
+    readonly platform?: string
+    /** 设置是否去除 cursor 相关样式 (h5默认值：true) */
+    removeCursorStyle: boolean
+  }
+}
+
+export interface IPxTransformOption {
+  /** 设置 1px 是否需要被转换 */
+  onePxTransform?: boolean
+  /** REM 单位允许的小数位 */
+  unitPrecision?: number
+  /** 允许转换的属性列表 (默认 [*]) */
+  propList?: string[]
+  /** 黑名单里的选择器将会被忽略 */
+  selectorBlackList?: Array<string | RegExp>
+  /** 直接替换而不是追加一条进行覆盖 */
+  replace?: boolean
+  /** 允许媒体查询里的 px 单位转换 */
+  mediaQuery?: boolean
+  /** 设置一个可被转换的最小 px 值 */
+  minPixelValue?: number
+  /**
+   * 转换后的单位，可选值为 rpx、vw、rem，当前仅支持小程序 (默认 rpx) 和 Web 端 (默认 rem)
+   * @description Web 端使用 rem 单位时会注入脚本用于设置 body 上的 font-size 属性，其他单位无该操作
+   */
+  targetUnit?: 'rpx' | 'vw' | 'rem'
+  /**
+   * H5 字体尺寸大小基准值，开发者可以自行调整单位换算的基准值(默认20)
+   * @supported h5
+   */
+  baseFontSize?: number
+  /**
+   * H5 根节点 font-size 的最大值 (默认 40)
+   * @supported h5
+   */
+  maxRootSize?: number
+  /**
+   * H5 根节点 font-size 的最小值(默认 20)
+   * @supported h5
+   */
+  minRootSize?: number
+  /** 设计稿尺寸 */
+  designWidth?: number | ((size?: string | number | Input) => number)
+  /** 设计稿尺寸换算规则 */
+  deviceRatio?: TaroGeneral.TDeviceRatio
+}
+
 export interface IPostcssOption {
   autoprefixer?: TogglableOptions
-  pxtransform?: TogglableOptions
+  pxtransform?: TogglableOptions<IPxTransformOption>
   cssModules?: PostcssOption.cssModules
   url?: PostcssOption.url
+  /** 插件 postcss-html-transform 相关配置, 一般启用了 @tarojs/plugin-html 插件才配置 */
+  htmltransform?: IHtmlTransformOption
   [key: string]: any
 }
 
@@ -96,9 +154,9 @@ export const enum CONFIG_TYPES {
 }
 
 export type IMINI_APP_FILE_TYPE = {
-  TEMPL: TEMPLATE_TYPES,
-  STYLE: STYLE_TYPES,
-  SCRIPT: SCRIPT_TYPES,
+  TEMPL: TEMPLATE_TYPES
+  STYLE: STYLE_TYPES
+  SCRIPT: SCRIPT_TYPES
   CONFIG: CONFIG_TYPES
 }
 

package/types/global.d.ts

@@ -6,7 +6,7 @@ declare namespace TaroGeneral {
   type EventCallback = (
     /** 触发事件参数 */
     ...args: any
-    ) => void
+  ) => void
   /** 通用错误 */
   interface CallbackResult {
     /** 错误信息 */
@@ -35,7 +35,7 @@ declare namespace TaroGeneral {
     /** 阻止事件冒泡到父元素,阻止任何父事件处理程序被执行 */
     stopPropagation: () => void
   }
-  interface currentTarget extends Target {}
+  interface currentTarget extends Target { }
   interface Target {
     /** 事件源组件的id */
     id: string
@@ -378,33 +378,33 @@ declare namespace TaroGeneral {
      */
     13024
   }
-
+  type EventName = string | symbol
   // Events
   class Events {
     /**
      * 监听一个事件，接受参数
      */
-    on(eventName: string, listener: (...args: any[]) => void): this
+    on (eventName: EventName, listener: (...args: any[]) => void): this
 
     /**
      * 添加一个事件监听，并在事件触发完成之后移除Callbacks链
      */
-    once(eventName: string, listener: (...args: any[]) => void): this
+    once (eventName: EventName, listener: (...args: any[]) => void): this
 
     /**
      * 取消监听一个事件
      */
-    off(eventName: string, listener?: (...args: any[]) => void): this
+    off (eventName: EventName, listener?: (...args: any[]) => void): this
 
     /**
      * 取消监听的所有事件
      */
-    off(): this
+    off (): this
 
     /**
      * 触发一个事件，传参
      */
-    trigger(eventName: string, ...args: any[]): boolean
+    trigger (eventName: EventName, ...args: any[]): this
   }
 
   // ENV_TYPE

package/types/index.d.ts

@@ -108,13 +108,13 @@
  * │   │   └── interaction.d.ts             界面 -> 交互 API
  * │   ├── worker
  * │   │   └── index.d.ts                   Worker API
- * │   └── wxml
- * │       └── index.d.ts                   WXML API
+ * │   ├── wxml
+ * │   │   └── index.d.ts                   WXML API
+ * │   ├── taro.extend.d.ts                 Taro 扩展 API 类型定义
+ * │   └── taro.hooks.d.ts                  Taro Hooks 类型定义
  * ├── index.d.ts                           此文件
  * ├── taro.component.d.ts                  Taro Component 类型定义
- * ├── taro.config.d.ts                     Taro 小程序 App 与 Window 设置类型定义
- * ├── taro.extend.d.ts                     Taro 扩展 API 类型定义
- * ├── taro.hooks.d.ts                      Taro Hooks 类型定义
+ * ├── taro.config.d.ts                      Taro 小程序 App 与 Window 设置类型定义
  * └── taro.lifecycle.d.ts                  Taro 生命周期类型定义
  */
 
@@ -123,8 +123,6 @@
 /// <reference path="taro.api.d.ts" />
 /// <reference path="taro.component.d.ts" />
 /// <reference path="taro.config.d.ts" />
-/// <reference path="taro.extend.d.ts" />
-/// <reference path="taro.hooks.d.ts" />
 /// <reference path="taro.lifecycle.d.ts" />
 
 /// <reference types="@tarojs/plugin-platform-alipay/types/shims-alipay" />
@@ -132,6 +130,8 @@
 /// <reference types="@tarojs/plugin-platform-swan/types/shims-swan" />
 /// <reference types="@tarojs/plugin-platform-tt/types/shims-tt" />
 /// <reference types="@tarojs/plugin-platform-weapp/types/shims-weapp" />
+/// <reference types="@tarojs/taro-h5/types/overlay" />
+/// <reference types="@tarojs/taro-rn/types/overlay" />
 
 export = Taro
 export as namespace Taro

package/types/taro.api.d.ts

@@ -2,7 +2,7 @@
  *
  * 微信端能力
  * original code from: https://github.com/wx-minapp/minapp-wx/blob/master/typing/wx.d.ts
- * Lincenced under MIT license: https://github.com/qiu8310/minapp/issues/69
+ * Licensed under MIT license: https://github.com/qiu8310/minapp/issues/69
  * thanks for the great work by @qiu8310 👍👍👍
  *
  */
@@ -41,6 +41,7 @@
 /// <reference path="api/payment/index.d.ts" />
 /// <reference path="api/storage/index.d.ts" />
 /// <reference path="api/storage/background-fetch.d.ts" />
+/// <reference path="api/storage/cache-manager.d.ts" />
 /// <reference path="api/data-analysis/index.d.ts" />
 /// <reference path="api/canvas/index.d.ts" />
 /// <reference path="api/media/map.d.ts" />
@@ -73,6 +74,7 @@
 /// <reference path="api/open-api/favorites.d.ts" />
 /// <reference path="api/open-api/license-plate.d.ts" />
 /// <reference path="api/open-api/channels.d.ts" />
+/// <reference path="api/open-api/device-voip.d.ts" />
 /// <reference path="api/open-api/group.d.ts" />
 /// <reference path="api/open-api/customer-service.d.ts" />
 /// <reference path="api/device/bluetooth.d.ts" />
@@ -88,6 +90,7 @@
 /// <reference path="api/device/clipboard.d.ts" />
 /// <reference path="api/device/network.d.ts" />
 /// <reference path="api/device/screen.d.ts" />
+/// <reference path="api/device/sms.d.ts" />
 /// <reference path="api/device/keyboard.d.ts" />
 /// <reference path="api/device/phone.d.ts" />
 /// <reference path="api/device/accelerometer.d.ts" />
@@ -99,6 +102,7 @@
 /// <reference path="api/device/vibrate.d.ts" />
 /// <reference path="api/ai/visionkit.d.ts" />
 /// <reference path="api/ai/face.d.ts" />
+/// <reference path="api/ai/inference.d.ts" />
 /// <reference path="api/worker/index.d.ts" />
 /// <reference path="api/wxml/index.d.ts" />
 /// <reference path="api/ext/index.d.ts" />
@@ -110,3 +114,6 @@
 /// <reference path="api/alipay/index.d.ts" />
 /// <reference path="api/qq/index.d.ts" />
 /// <reference path="api/swan/index.d.ts" />
+
+/// <reference path="api/taro.extend.d.ts" />
+/// <reference path="api/taro.hooks.d.ts" />

package/types/taro.component.d.ts

@@ -1,7 +1,7 @@
 import React from 'react'
 import Vue from 'vue'
 
-import Taro, { Config } from './index'
+import Taro from './index'
 
 declare module './index' {
   // ref: packages/taro-runtime/src/current.ts
@@ -51,6 +51,7 @@ declare module './index' {
     onReachBottom?(): void
     onResize?(opt: PageResizeObject): void
     onShareAppMessage?(opt: ShareAppMessageObject): ShareAppMessageReturn
+    onShareTimeline?(): ShareTimelineReturnObject
     onTabItemTap?(opt: TabItemTapObject): void
     onTitleClick?(): void
     onUnload(): void

package/types/taro.config.d.ts

@@ -154,6 +154,11 @@ declare module './index' {
      * @default: false
      */
     disableScroll?: boolean
+    /** 是否使用页面全局滚动，MPA下默认为全局滚动，SPA默认为局部滚动
+     * 只在H5生效
+     * @default: MPA:true  SPA:false
+     */
+    usingWindowScroll?: boolean
     /** 禁止页面右滑手势返回
      *
      * **注意** 自微信客户端 7.0.5 开始，页面配置中的 disableSwipeBack 属性将不再生效，
@@ -360,7 +365,9 @@ declare module './index' {
      * @default false
      * @since 2.1.0
      */
-    functionalPages?: boolean
+    functionalPages?: boolean | {
+      independent?: boolean
+    }
     /** 分包结构配置
      * @example
      * ```json