@tarojs/taro 3.6.8 → 3.6.9-alpha.10

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

@@ -1,91 +1,307 @@
 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?: string | 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>
+
   /**
    * 修改编译过程中的页面组件配置
    */
   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/index.d.ts

@@ -130,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

@@ -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" />