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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tarojs/taro",
-  "version": "3.6.9-alpha.2",
+  "version": "3.6.9-alpha.4",
   "description": "Taro framework",
   "homepage": "https://github.com/nervjs/taro/tree/master/packages/taro#readme",
   "main": "index.js",
@@ -21,15 +21,11 @@
   "author": "O2Team",
   "license": "MIT",
   "dependencies": {
-    "@tarojs/api": "3.6.9-alpha.2",
-    "@tarojs/runtime": "3.6.9-alpha.2"
+    "@tarojs/api": "3.6.9-alpha.4",
+    "@tarojs/runtime": "3.6.9-alpha.4"
   },
   "devDependencies": {
-    "postcss": "^8.4.18",
-    "@tarojs/helper": "3.6.9-alpha.2"
-  },
-  "peerDependencies": {
-    "postcss": "^8.4.18"
+    "@tarojs/helper": "3.6.9-alpha.4"
   },
   "peerDependenciesMeta": {
     "@types/react": {
@@ -41,6 +37,9 @@
     "@types/webpack-dev-server": {
       "optional": true
     },
+    "postcss": {
+      "optional": true
+    },
     "vue": {
       "optional": true
     }

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

@@ -5,8 +5,11 @@ import type HtmlWebpackPlugin from 'html-webpack-plugin'
 import type { IOption, IPostcssOption } from './util'
 
 export interface IH5RouterConfig {
+  /** 配置路由模式 */
   mode?: 'hash' | 'browser' | 'multi'
+  /** 配置自定义路由 */
   customRoutes?: IOption
+  /** 配置路由基准路径 */
   basename?: string
   lazyload?: boolean | ((pagename: string) => boolean)
   renamePagename?: (pagename: string) => string
@@ -14,37 +17,95 @@ export interface IH5RouterConfig {
 }
 
 export interface IH5Config {
+  /** 设置输出解析文件的目录（默认值：'/'）*/
   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
 
+  /** 可用于修改、拓展 Webpack 的 output 选项，配置项参考[官方文档](https://webpack.js.org/configuration/output/) */
   output?: 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
+
+  /** 针对 mp4 | webm | ogg | mp3 | wav | flac | aac 文件的 [url-loader](https://github.com/webpack-contrib/url-loader) 配置 */
   mediaUrlLoaderOption?: IOption
+
+  /** 针对 woff | woff2 | eot | ttf | otf 文件的 [url-loader](https://github.com/webpack-contrib/url-loader) 配置 */
   fontUrlLoaderOption?: IOption
+
+  /** 针对 png | jpg | jpeg | gif | bpm | svg 文件的 [url-loader](https://github.com/webpack-contrib/url-loader) 配置 */
   imageUrlLoaderOption?: IOption
+
+  /** [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 相关插件 */
   postcss?: IPostcssOption
+
+  /** html-webpack-plugin 的具体配置 */
   htmlPluginOption?: HtmlWebpackPlugin.Options
 
+  /** Web 编译过程的相关配置 */
   compile?: {
     exclude?: any[]
     include?: any[]

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

@@ -1,6 +1,6 @@
 import type Webpack from 'webpack'
 import type Chain from 'webpack-chain'
-import type { IMINI_APP_FILE_TYPE, IOption, IPostcssOption } from './util'
+import type { IOption, IPostcssOption } from './util'
 
 interface Runtime {
   enableInnerHTML: boolean
@@ -13,36 +13,75 @@ interface Runtime {
 }
 
 export interface IMiniAppConfig {
-  appOutput?: boolean
+  /** 默认值：'cheap-module-source-map'， 具体参考[Webpack devtool 配置](https://webpack.js.org/configuration/devtool/#devtool) */
   sourceMapType?: string
+
+  /** 指定 React 框架相关的代码是否使用开发环境（未压缩）代码，默认使用生产环境（压缩后）代码 */
   debugReact?: boolean
+
+  /** 压缩小程序 xml 文件的相关配置 */
   minifyXML?: {
+    /** 是否合并 xml 文件中的空格 (默认false) */
     collapseWhitespace?: boolean
   }
 
+  /**
+   * 自定义 Webpack 配置
+   * @param chain  [webpackChain](https://github.com/neutrinojs/webpack-chain) 对象
+   * @param webpack webpack 实例
+   * @param PARSE_AST_TYPE 小程序编译时的文件类型集合
+   * @returns
+   */
   webpackChain?: (chain: Chain, webpack: typeof Webpack, PARSE_AST_TYPE: any) => void
+
+  /** 可用于修改、拓展 Webpack 的 [output](https://webpack.js.org/configuration/output/) 选项 */
   output?: Webpack.Configuration['output']
+
+  /** 配置 postcss 相关插件 */
   postcss?: IPostcssOption
+
+  /** [css-loader](https://github.com/webpack-contrib/css-loader) 的附加配置 */
   cssLoaderOption?: 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
+
+  /** 针对 mp4 | webm | ogg | mp3 | wav | flac | aac 文件的 [url-loader](https://github.com/webpack-contrib/url-loader) 配置 */
   mediaUrlLoaderOption?: IOption
+
+  /** 针对 woff | woff2 | eot | ttf | otf 文件的 [url-loader](https://github.com/webpack-contrib/url-loader) 配置 */
   fontUrlLoaderOption?: IOption
+
+  /** 针对 png | jpg | jpeg | gif | bpm | svg 文件的 [url-loader](https://github.com/webpack-contrib/url-loader) 配置 */
   imageUrlLoaderOption?: IOption
+
+  /** [mini-css-extract-plugin](https://github.com/webpack-contrib/mini-css-extract-plugin) 的附加配置 */
   miniCssExtractPluginOption?: IOption
 
-  customFilesTypes?: IMINI_APP_FILE_TYPE
+  /** 用于告诉 Taro 编译器需要抽取的公共文件 */
   commonChunks?: string[] | ((commonChunks: string[]) => string[])
-  addChunkPages?: ((pages: Map<string, string[]>, pagesNames?: string[]) => void)
+
+  /** 为某些页面单独指定需要引用的公共文件 */
+  addChunkPages?: (pages: Map<string, string[]>, pagesNames?: string[]) => void
+
+  /** 优化主包的体积大小 */
   optimizeMainPackage?: {
     enable?: boolean
     exclude?: any[]
   }
 
+  /** 小程序编译过程的相关配置 */
   compile?: {
     exclude?: any[]
     include?: any[]
   }
+
+  /** 插件内部使用 */
   runtime?: Runtime
 }

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

@@ -6,17 +6,37 @@ import type { IModifyWebpackChain } from '../hooks'
 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
 }
 
@@ -137,7 +157,73 @@ export interface IProjectBaseConfig {
   modifyBuildAssets?: (assets: any, miniPlugin?: any) => Promise<any>
 }
 
-export interface IProjectConfig extends IProjectBaseConfig {
+/** 暴露出来给 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
+
+  /** 用于设置环境变量 (除了NODE_ENV以外，其他环境变量建议在根目录下的.env文件中) */
+  env?: IOption
+
+  /** 用于配置目录别名，从而方便书写代码引用路径 */
+  alias?: IOption
+
+  /** 用于配置一些全局变量供代码中进行使用（建议放在根目录下的.env文件中） */
+  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
 
@@ -145,7 +231,7 @@ export interface IProjectConfig extends IProjectBaseConfig {
   h5?: IH5Config
 
   /** 专属于 RN 的配置 */
-  rn?: IH5Config
+  rn?: IRNConfig
 
   [key: string]: any
 }

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

@@ -0,0 +1,52 @@
+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
+      }
+    }
+  }
+
+  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
 }