weapp-tailwindcss 4.3.2 → 4.4.0-alpha.0

package/dist/types.d.ts

@@ -16,273 +16,311 @@ interface HashMapValue {
 }
 type HashMapKey = string | number;
 type CacheValue = sources.Source | string;
+interface CacheProcessResult<T extends CacheValue> {
+    result: T;
+    cacheValue?: CacheValue;
+}
+interface CacheProcessOptions<T extends CacheValue> {
+    key: string;
+    hashKey?: HashMapKey;
+    rawSource?: string | Buffer;
+    hash?: string;
+    resolveCache?: () => T | undefined;
+    transform: () => Promise<CacheProcessResult<T> | T>;
+    onCacheHit?: (value: T) => void | Promise<void>;
+}
 interface ICreateCacheReturnType {
-    hashMap: Map<HashMapKey, HashMapValue>;
-    instance: LRUCache<string, CacheValue>;
+    readonly hashMap: Map<HashMapKey, HashMapValue>;
+    readonly instance: LRUCache<string, CacheValue>;
     hasHashKey: (key: HashMapKey) => boolean;
     getHashValue: (key: HashMapKey) => HashMapValue | undefined;
-    setHashValue: (key: HashMapKey, value: HashMapValue) => this['hashMap'];
+    setHashValue: (key: HashMapKey, value: HashMapValue) => Map<HashMapKey, HashMapValue>;
     computeHash: (message: string | Buffer) => string;
     get: <V extends CacheValue = sources.Source>(key: string) => V | undefined;
-    set: <V extends CacheValue = sources.Source>(key: string, value: V) => this['instance'];
+    set: <V extends CacheValue = sources.Source>(key: string, value: V) => LRUCache<string, CacheValue>;
     has: (key: string) => boolean;
-    calcHashValueChanged: (key: HashMapKey, hash: string) => this;
-    process: (key: string, callback: () => void | false | Promise<void | false>, fallback: () => void | {
-        key: string;
-        source: CacheValue;
-    } | Promise<void | {
-        key: string;
-        source: CacheValue;
-    }>) => void | Promise<void>;
+    calcHashValueChanged: (key: HashMapKey, hash: string) => ICreateCacheReturnType;
+    process: <T extends CacheValue>(options: CacheProcessOptions<T>) => Promise<T>;
 }
 
 interface UserDefinedOptions {
     /**
+     * 是否禁用此插件。
+     *
      * @group 0.重要配置
-     * @description 是否禁用此插件，一般用于构建到多平台时使用，比如小程序时不传，非小程序环境(h5,app)传入一个 `true`
+     * @remarks
+     * 在多平台构建场景下常用：小程序构建保持默认，非小程序环境（H5、App）传入 `true` 即可跳过转换。
+     * @example
      * ```ts
-     * // 比如 uni-app vue3 vite
+     * // uni-app vue3 vite
      * import process from 'node:process'
-     
-  const isH5 = process.env.UNI_PLATFORM === 'h5'
-  const isApp = process.env.UNI_PLATFORM === 'app'
-  const WeappTailwindcssDisabled = isH5 || isApp
-     
-  import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'
-  // 注册插件
-  // highlight-start
-      uvtw({
-        disabled: WeappTailwindcssDisabled,
-      }),
-  // highlight-end
+     *
+     * const isH5 = process.env.UNI_PLATFORM === 'h5'
+     * const isApp = process.env.UNI_PLATFORM === 'app'
+     * const disabled = isH5 || isApp
+     *
+     * import { UnifiedViteWeappTailwindcssPlugin as uvtw } from 'weapp-tailwindcss/vite'
+     *
+     * uvtw({
+     *   disabled,
+     * })
      * ```
      */
     disabled?: boolean;
     /**
+     * 自定义 `wxml` 标签属性的转换规则。
+     *
      * @group 0.重要配置
-     * @description **这是一个重要的配置!**
-     
-  它可以自定义`wxml`标签上的`attr`转化属性。默认转化所有的`class`和`hover-class`，这个`Map`的 `key`为匹配标签，`value`为属性字符串或者匹配正则数组。
-     
-  如果你想要增加，对于所有标签都生效的转化的属性，你可以添加 `*`: `(string | Regexp)[]` 这样的键值对。(`*` 是一个特殊值，代表所有标签)
-     
-  更复杂的情况，可以传一个 `Map<string | Regex, (string | Regex)[]>`实例。
-     
-  假如你要把 `className` 通过组件的`prop`传递给子组件，又或者想要自定义转化的标签属性时，需要用到此配置，案例详见：[issue#129](https://github.com/sonofmagic/weapp-tailwindcss/issues/129#issuecomment-1340914688),[issue#134](https://github.com/sonofmagic/weapp-tailwindcss/issues/134#issuecomment-1351288238)
-     
-  @example
-     
-  ```js
-  const customAttributes = {
-      // 匹配所有带 Class / class 相关的标签，比如某个组件上的 `a-class`, `testClass` , `custom-class` 里面的值
-      '*': [ /[A-Za-z]?[A-Za-z-]*[Cc]lass/ ],
-      // 额外匹配转化 `van-image` 标签上属性为 `custom-class` 的值
-      'van-image': ['custom-class'],
-      // 转化所有 `ice-button` 标签上属性为 `testClass` 的值
-      'ice-button': ['testClass']
-  }
-  ```
-     
-  当然你可以根据自己的需求，定义单个或者多个正则/字符串。
-     
-  甚至有可能你编写正则表达式，它们匹配的范围，直接包括了插件里自带默认的 `class`/`hover-class`，那么这种情况下，你完全可以取代插件的默认模板转化器，开启 [disabledDefaultTemplateHandler](/docs/api/interfaces/UserDefinedOptions#disableddefaulttemplatehandler) 配置项,禁用默认的模版匹配转化器。
+     * @remarks
+     * 默认会转换所有标签上的 `class` 与 `hover-class`。此配置允许通过 `Map` 或对象为特定标签指定需要转换的属性字符串或正则表达式数组。
+     * - 使用 `'*'` 作为键可为所有标签追加通用规则。
+     * - 支持传入 `Map<string | RegExp, (string | RegExp)[]>` 以满足复杂匹配需求。
+     * - 常见场景包括通过组件 `prop` 传递类名，或对三方组件的自定义属性做匹配，更多讨论见 [issue#129](https://github.com/sonofmagic/weapp-tailwindcss/issues/129#issuecomment-1340914688) 与 [issue#134](https://github.com/sonofmagic/weapp-tailwindcss/issues/134#issuecomment-1351288238)。
+     * 如果自定义规则已经覆盖默认的 `class`/`hover-class`，可开启 [`disabledDefaultTemplateHandler`](/docs/api/interfaces/UserDefinedOptions#disableddefaulttemplatehandler) 以关闭内置模板处理器。
+     * @example
+     * ```js
+     * const customAttributes = {
+     *   '*': [/[A-Za-z]?[A-Za-z-]*[Cc]lass/],
+     *   'van-image': ['custom-class'],
+     *   'ice-button': ['testClass'],
+     * }
+     * ```
      */
     customAttributes?: ICustomAttributes;
     /**
+     * 自定义 class 名称的替换字典。
+     *
      * @group 0.重要配置
-     * @description 自定义转化class名称字典，这个配置项用来自定义转化`class`名称字典,你可以使用这个选项来简化生成的`class`
-  - 默认模式: 把小程序中不允许的字符串，转义为**相等长度**的代替字符串，这种情况不追求转化目标字符串的一比一绝对等价，即无法从生成结果，反推原先的`class`
-     
-  当然，你也可以自定义，传一个 `Record<string, string>` 类型，只需保证转化后 css 中的 `class` 选择器，不会和自己定义的 `class` 产生冲突即可，示例见[dic.ts](https://github.com/sonofmagic/weapp-core/blob/main/packages/escape/src/dic.ts)
+     * @remarks
+     * 默认策略会将小程序不允许的字符映射为等长度的替代字符串，因此无法通过结果反推出原始类名。如需完全自定义，可传入 `Record<string, string>`，只需确保生成的类名不会与已有样式冲突。示例参考 [dic.ts](https://github.com/sonofmagic/weapp-core/blob/main/packages/escape/src/dic.ts)。
      * @default MappingChars2String
      */
     customReplaceDictionary?: Record<string, string>;
     /**
+     * 忽略指定标签模板表达式中的标识符。
+     *
      * @version `^4.0.0`
      * @group 0.重要配置
-     * @description js 忽略标签模板表达式中的标识符，这样使用标识符包裹的模板字符串不会被转义
+     * @remarks
+     * 当模板字符串被这些标识符包裹时，将跳过转义处理。
      * @default ['weappTwIgnore']
      */
     ignoreTaggedTemplateExpressionIdentifiers?: (string | RegExp)[];
     /**
+     * 忽略指定调用表达式中的标识符。
+     *
      * @version `^4.0.0`
      * @group 0.重要配置
-     * @description js 忽略调用表达式中的标识符，这样使用这个方法，包裹的模板字符串和字符串字面量不会被转义，一般用来配合 `@weapp-tailwindcss/merge` 使用，比如设置为 `['twMerge', 'twJoin', 'cva']`
+     * @remarks
+     * 使用这些方法包裹的模板字符串或字符串字面量会跳过转义，常与 `@weapp-tailwindcss/merge` 配合（如 `['twMerge', 'twJoin', 'cva']`）。
      */
     ignoreCallExpressionIdentifiers?: (string | RegExp)[];
     /**
+     * 控制在视图节点上注入的 CSS 预设。
+     *
      * @group 0.重要配置
      * @issue https://github.com/sonofmagic/weapp-tailwindcss/issues/7
-     * @description 在所有 view节点添加的 css 预设，可根据情况自由的禁用原先的规则，或者添加新的规则。默认预置 `css` 同 `tailwindcss` 类似，详细用法如下:
+     * @remarks
+     * 默认会向所有 `view`/`text` 元素注入 Tailwind 风格的基础样式，可通过此配置禁用、调整或补充规则，受 `cssPreflightRange` 影响。
+     * @example
      * ```js
-     * // default 默认，这代表会添加给所有的 view / text 元素, 受到 cssPreflightRange 配置项影响 :
-      cssPreflight: {
-        'box-sizing': 'border-box',
-        'border-width': '0',
-        'border-style': 'solid',
-        'border-color': 'currentColor'
-      }
-      // result
-      // box-sizing: border-box;
-      // border-width: 0;
-      // border-style: solid;
-      // border-color: currentColor
-     
-      // case 禁用所有
-      cssPreflight: false
-      // result
-      // none
-     
-      // case 禁用单个属性
-      cssPreflight: {
-        'box-sizing': false
-      }
-      // border-width: 0;
-      // border-style: solid;
-      // border-color: currentColor
-     
-      // case 更改和添加单个属性
-      cssPreflight: {
-        'box-sizing': 'content-box',
-        'background': 'black'
-      }
-      // result
-      // box-sizing: content-box;
-      // border-width: 0;
-      // border-style: solid;
-      // border-color: currentColor;
-      // background: black
+     * cssPreflight: {
+     *   'box-sizing': 'border-box',
+     *   'border-width': '0',
+     *   'border-style': 'solid',
+     *   'border-color': 'currentColor',
+     * }
+     *
+     * cssPreflight: false
+     *
+     * cssPreflight: {
+     *   'box-sizing': false,
+     *   background: 'black',
+     * }
      * ```
      */
     cssPreflight?: CssPreflightOptions;
     /**
+     * 控制 `cssPreflight` 注入的 DOM 选择器范围。
+     *
      * @group 0.重要配置
      * @issue https://github.com/sonofmagic/weapp-tailwindcss/pull/62
-     * @description 全局`dom`选择器，只有在这个选择器作用范围内的`dom`会被注入 `cssPreflight` 的变量和默认样式。只对所有的 `view`,`text` 和伪元素生效，想要对所有的元素生效，可切换为 `'all'`,此时需要自行处理和客户端默认样式的冲突
+     * @remarks
+     * 仅 `view`、`text` 及其伪元素会受影响。设置为 `'all'` 可以覆盖所有元素，此时需自行处理与宿主默认样式的冲突。
      */
     cssPreflightRange?: 'all';
     /**
+     * 预计算 CSS 变量或 `calc` 表达式的结果。
+     *
      * @group 0.重要配置
      * @version `^4.3.0`
-     * @description css calc 配置项， 用于直接计算 css 变量的结果值，通常用于手机兼容性处理，这个是为了解决 css 中的 calc 函数的表现，在不同手机机型上不一致的问题
+     * @remarks
+     * 解决部分机型对 `calc` 计算不一致的问题，可传入布尔值、选项对象或自定义匹配列表（支持正则）。在启用计算后，可通过 `includeCustomProperties` 指定需要保留的变量。
+     * @example
+     * ```css
+     * // 原始输出
+     * page,
+     * :root {
+     *   --spacing: 8rpx;
+     * }
+     * .h-2 {
+     *   height: calc(var(--spacing) * 2);
+     * }
+     * ```
+     *
+     * ```css
+     * // 启用 cssCalc 后
+     * .h-2 {
+     *   height: 16rpx;
+     *   height: calc(var(--spacing) * 2);
+     * }
+     * ```
+     *
+     * ```js
+     * cssCalc: ['--spacing']
+     * cssCalc: { includeCustomProperties: ['--spacing'] }
+     * ```
      */
     cssCalc?: boolean | CssCalcOptions | (string | RegExp)[];
     /**
+     * 是否额外注入 `tailwindcss css var scope`。
+     *
      * @group 0.重要配置
      * @version `^2.6.0`
-     * @description  是否注入额外的 `tailwindcss css var scope` 区域，这个选项用于这样的场景
-     *
-     * 比如 `taro vue3` 使用 [NutUI](https://nutui.jd.com), 需要使用 `@tarojs/plugin-html`，而这个插件会启用 `postcss-html-transform` 从而移除所有带 `*` 选择器
-     *
-     * 这会导致 `tailwindcss css var scope` 区域被移除导致一些样式，比如渐变等等功能失效
-     *
-     * 这种场景下，启用这个选项会再次重新注入整个 `tailwindcss css var scope`
-     *
+     * @remarks
+     * 当构建链路（例如 `@tarojs/plugin-html`）移除了包含 `*` 的选择器时，可启用该选项重新写入变量作用域，以避免渐变等功能失效。
      * @default false
      */
     injectAdditionalCssVarScope?: boolean;
     /**
+     * 控制 CSS 选择器的替换规则。
+     *
      * @group 0.重要配置
-     * @description 用于处理 css 选择器的替换规则
      */
     cssSelectorReplacement?: {
         /**
+         * 将全局选择器 `:root` 替换为指定值。
+         *
          * @default `'page'` <br/>
-         * @description 把`css`中的全局选择器 **`:root`** 替换为指定值，默认替换为 `'page'`，设置为 `false` 时不进行替换
-         * @example 假如你使用微信小程序的 RootPortal 组件，你需要把此项设置为 ['page','wx-root-content']
+         * @remarks
+         * 设置为 `false` 时不再替换，可根据宿主环境（例如 RootPortal）传入数组值。
+         * @example
+         * root: ['page', 'wx-root-content']
          */
         root?: string | string[] | false;
         /**
+         * 将全局选择器 `*` 替换为指定值。
+         *
          * @issue https://github.com/sonofmagic/weapp-tailwindcss/issues/81 <br/>
          * @default `['view','text']` <br/>
-         * @description 把`css`中的全局选择器 **`*`** 替换为指定值，默认替换为 `'view','text'`，设置为 `false` 时不进行替换，此时小程序会由于不认识`*`选择器而报错
+         * @remarks
+         * 小程序环境不支持 `*`，因此默认转换为 `view`、`text`；设置为 `false` 会留下原始选择器。
          */
         universal?: string | string[] | false;
     };
     /**
+     * rem 到 rpx 的转换配置。
+     *
      * @version `^3.0.0`
      * @group 0.重要配置
-     * @description rem 转 rpx 配置，默认为 `undefined` 不开启，可传入 `true` 启用默认配置项，也可传入自定义配置项，配置项列表见 [postcss-rem-to-responsive-pixel](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel)
+     * @remarks
+     * 传入 `true` 使用默认配置，或提供 [postcss-rem-to-responsive-pixel](https://www.npmjs.com/package/postcss-rem-to-responsive-pixel) 支持的完整选项。
      * ```ts
-     * // 默认值
      * {
-     *  rootValue: 32,
-     *  propList: ['*'],
-     *  transformUnit: 'rpx',
+     *   rootValue: 32,
+     *   propList: ['*'],
+     *   transformUnit: 'rpx',
      * }
      * ```
      */
     rem2rpx?: boolean | Rem2rpxOptions;
     /**
+     * px 到 rpx 的转换配置。
+     *
      * @group 0.重要配置
      * @version `^4.3.0`
-     * @description rem 转 rpx 配置，默认为 `undefined` 不开启，可传入 `true` 启用默认配置项 1px = 1rpx
+     * @remarks
+     * 传入 `true` 启用默认映射（`1px = 1rpx`），或通过对象自定义更多行为。
      */
     px2rpx?: boolean | Px2rpxOptions;
     /**
+     * `postcss-preset-env` 的配置项。
+     *
      * @version `^4.0.0`
      * @group 0.重要配置
-     * @description postcss-preset-env 的入参数
-     * 参考文档
-     * https://preset-env.cssdb.org/
-     * https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env#readme
+     * @see https://preset-env.cssdb.org/
+     * @see https://github.com/csstools/postcss-plugins/tree/main/plugin-packs/postcss-preset-env#readme
      */
     cssPresetEnv?: PresetEnvOptions;
     /**
+     * 为不同版本的 Tailwind 配置行为。
+     *
      * @version `^4.0.0`
      * @group 0.重要配置
-     * @description 配置不同版本 tailwindcss 的行为
      */
     tailwindcss?: PatchOptions['tailwindcss'];
     /**
+     * 指定 tailwindcss@4 的入口 CSS。
+     *
      * @version `^4.2.6`
      * @group 0.重要配置
-     * @description tailwindcss@4 的入口 css 的位置，假如不配置这个选项, 就无法加载自定义插件。等价于传入 tailwindcss.v4.cssEntries
+     * @remarks
+     * 未配置时无法加载自定义插件，等价于设置 `tailwindcss.v4.cssEntries`。
      */
     cssEntries?: string[];
     /**
+     * 配置 uni-app x 场景的行为。
+     *
      * @version `^4.2.0`
      * @group 0.重要配置
      * @ignore
-     * @description uni-app x 的配置
      */
     uniAppX?: boolean;
 }
 interface UserDefinedOptions {
     /**
+     * 匹配需要处理的 `wxml` 等模板文件。
+     *
      * @group 1.文件匹配
-     * @description 匹配 `wxml`等等模板进行处理的方法
      */
     htmlMatcher?: (name: string) => boolean;
     /**
+     * 匹配需要处理的 `wxss` 等样式文件。
+     *
      * @group 1.文件匹配
-     * @description 匹配 `wxss` 等等样式文件的方法
      */
     cssMatcher?: (name: string) => boolean;
     /**
+     * 匹配需要处理的编译后 `js` 文件。
+     *
      * @group 1.文件匹配
-     * @description 匹配编译后 `js` 文件进行处理的方法
      */
     jsMatcher?: (name: string) => boolean;
     /**
-     * @group 1.文件匹配
-     * @description `tailwindcss css var inject scope` 的匹配方法,用于处理原始变量和替换不兼容选择器。可以不传，但是遇到某些 `::before/::after` 选择器注入冲突时，建议传入参数手动指定 css bundle 文件位置
+     * 匹配负责注入 Tailwind CSS 变量作用域的 CSS Bundle。
      *
+     * @group 1.文件匹配
+     * @remarks
+     * 在处理 `::before`/`::after` 等不兼容选择器时，建议手动指定文件位置。
      */
     mainCssChunkMatcher?: (name: string, appType?: AppType) => boolean;
     /**
+     * 匹配各端的 `wxs`/`sjs`/`.filter.js` 文件。
+     *
      * @group 1.文件匹配
      * @experiment 实验性质，有可能会改变
-     * @description 各个平台 `wxs` 文件的匹配方法,可以设置为包括微信的 .wxs,支付宝的 .sjs 和 百度小程序的 .filter.js
-     * > tip: 记得在 `tailwind.config.js` 中，把 `wxs` 这个格式加入 `content` 配置项，不然不会生效
+     * @remarks
+     * 配置前请确保在 `tailwind.config.js` 的 `content` 中包含对应格式。
      * @default ()=>false
      */
     wxsMatcher?: (name: string) => boolean;
     /**
+     * 是否转义 `wxml` 中的内联 `wxs`。
+     *
      * @group 1.文件匹配
      * @experiment 实验性质，有可能会改变
-     * @description 是否转义 `wxml` 中内联的 `wxs`
-     * > tip: 记得在 `tailwind.config.js` 中，把 `wxs` 这个格式加入 `content` 配置项，不然不会生效
+     * @remarks
+     * 使用前同样需要在 `tailwind.config.js` 中声明 `wxs` 格式。
      * @example
      * ```html
      * <!-- index.wxml -->
@@ -303,185 +341,201 @@ interface UserDefinedOptions {
 }
 interface UserDefinedOptions {
     /**
+     * 插件 `apply` 初始调用时触发。
+     *
      * @group 2.生命周期
-     * @description plugin apply 初调用
      */
     onLoad?: () => void;
     /**
+     * 开始处理前触发。
+     *
      * @group 2.生命周期
-     * @description 开始处理时调用
      */
     onStart?: () => void;
     /**
-     * @description 匹配成功并修改文件内容前调用
+     * 匹配并修改文件内容前触发。
+     *
+     * @group 2.生命周期
      */
     /**
+     * 匹配并修改文件后触发。
+     *
      * @group 2.生命周期
-     * @description 匹配成功并修改文件内容后调用
      */
     onUpdate?: (filename: string, oldVal: string, newVal: string) => void;
     /**
+     * 结束处理时触发。
+     *
      * @group 2.生命周期
-     * @description 结束处理时调用
      */
     onEnd?: () => void;
 }
 interface UserDefinedOptions {
     /**
+     * 控制 Tailwind 自定义长度单位补丁。
+     *
      * @group 3.一般配置
      * @issue https://github.com/sonofmagic/weapp-tailwindcss/issues/110
-     * @description 自从`tailwindcss 3.2.0`对任意值添加了长度单位的校验后，小程序中的`rpx`这个`wxss`单位，由于不在长度合法名单中，于是被识别成了颜色，导致与预期不符，详见：[issues/110](https://github.com/sonofmagic/weapp-tailwindcss/issues/110)。所以这个选项是用来给`tailwindcss`运行时，自动打上一个支持`rpx`单位的补丁。默认开启，在绝大部分情况下，你都可以忽略这个配置项，除非你需要更高级的自定义。
-  > 目前自动检索可能存在一定的缺陷，它会在第一次运行的时候不生效，关闭后第二次运行才生效。这是因为 nodejs 运行时先加载好了 `tailwindcss` 模块 ，然后再来运行这个插件，自动给 `tailwindcss` 运行时打上 `patch`。此时由于 `tailwindcss` 模块已经加载，所以 `patch` 在第一次运行时不生效，`ctrl+c` 关闭之后，再次运行才生效。这种情况可以使用:
-     
-  ```diff
-   "scripts": {
-  +  "postinstall": "weapp-tw patch"
-   }
-  ```
-     
-  使用 `npm hooks` 的方式来给 `tailwindcss` 自动打 `patch`
+     * @remarks
+     * TailwindCSS 3.2.0 起对任意值执行长度单位校验，会将未声明的 `rpx` 识别为颜色。本选项默认开启以注入 `rpx` 支持。当 Node.js 在插件执行前已缓存 `tailwindcss` 模块时，首轮运行可能未生效，可通过在 `postinstall` 中执行 `weapp-tw patch` 提前打补丁。
+     * ```diff
+     * "scripts": {
+     * +  "postinstall": "weapp-tw patch"
+     * }
+     * ```
      */
     supportCustomLengthUnitsPatch?: ILengthUnitsPatchOptions | boolean;
     /**
+     * 声明所使用的框架类型。
+     *
      * @group 3.一般配置
-     * @description 使用的框架类型(uni-app,taro...)，用于找到主要的 `css bundle` 进行转化，这个配置会影响默认方法 `mainCssChunkMatcher` 的行为，不传会去猜测 `tailwindcss css var inject scope` (tailwindcss 变量注入的位置) 的位置
+     * @remarks
+     * 用于辅助定位主要的 CSS bundle，以便默认的 `mainCssChunkMatcher` 做出更准确的匹配，未传入时将尝试自动猜测变量注入位置。
      */
     appType?: AppType;
     /**
+     * TailwindCSS 任意值的相关配置。
+     *
      * @group 3.一般配置
-     * @description 针对 tailwindcss arbitrary values 的一些配置
      */
     arbitraryValues?: IArbitraryValues;
     /**
+     * 控制 JS 字面量是否需要保留。
+     *
      * @group 3.一般配置
      * @version `^2.6.1`
-     * @description 当 `tailwindcss` 和 `js` 处理的字面量撞车的时候，配置此选项可以用来保留js字面量，不进行转义处理。返回值中，想要当前js字面量保留，则返回 `true`。想要转义则返回 `false/undefined`
-     * @default 保留所有带 `*` js字符串字面量
+     * @remarks
+     * 当 Tailwind 与 JS 字面量冲突时，可通过回调返回 `true` 保留当前值，返回 `false` 或 `undefined` 则继续转义。默认保留所有带 `*` 的字符串字面量。
      */
     jsPreserveClass?: (keyword: string) => boolean | undefined;
     /**
+     * 禁用默认的 `wxml` 模板替换器。
+     *
      * @group 3.一般配置
      * @version `^2.6.2`
-     * @description 开启此选项，将会禁用默认 `wxml` 模板替换器，此时模板的匹配和转化将完全被 [`customAttributes`](/docs/api/interfaces/UserDefinedOptions#customattributes) 接管，
-     *
-     * 此时你需要自己编写匹配之前默认 `class`/`hover-class`，以及新的标签属性的正则表达式`regex`
+     * @remarks
+     * 启用后模板匹配完全交由 [`customAttributes`](/docs/api/interfaces/UserDefinedOptions#customattributes) 管理，需要自行覆盖默认的 `class` / `hover-class` 等匹配规则。
      * @default false
      */
     disabledDefaultTemplateHandler?: boolean;
     /**
+     * 内部使用的运行时加载器路径。
+     *
      * @ignore
      * @internal
      */
     runtimeLoaderPath?: string;
     /**
+     * 指定用于获取 Tailwind 上下文的路径。
+     *
      * @group 3.一般配置
      * @version `^2.9.3`
-     * @description 用于指定路径来获取 tailwindcss 上下文，一般情况下不用传入，使用 linked / monorepo 可能需要指定具体位置，路径通常是目标项目的 package.json 所在目录
+     * @remarks
+     * 在 linked 或 monorepo 场景下可手动指向目标项目的 `package.json` 所在目录。
      */
     tailwindcssBasedir?: string;
     /**
+     * 控制缓存策略。
+     *
      * @group 3.一般配置
      * @version `^3.0.11`
-     * @description 缓存策略
      */
     cache?: boolean | ICreateCacheReturnType;
     /**
+     * `@babel/parser` 的配置选项。
+     *
      * @version `^3.2.0`
      * @group 3.一般配置
-     * @description 对解析 js 使用的 `@babel/parser` 工具的配置
      */
     babelParserOptions?: ParserOptions & {
         cache?: boolean;
     };
     /**
-     * @group 3.一般配置
-     * @description 用于控制 tailwindcss 子组合器的生效标签范围, 这里我们用一个例子来说明这个配置是干啥用的.
-     *
-     * 我们布局的时候往往会使用 `space-x-4`
-     * 那么实际上会生成这样的css选择器:
-     * ```css
-     * .space-x-4>:not([hidden])~:not([hidden]){}
-     * ```
-     * 然而很不幸，这个选择器在小程序中是不支持的，写了会报错导致编译失败。
-     * 所以出于保守起见，我把它替换为了：
-     * ```css
-     * .space-x-4>view + view{}
-     * ```
-     * 这同时也是默认值, 而这个选项就允许你进行自定义子组合器的行为
+     * 自定义 Tailwind 子组合器的替换值。
      *
-     * 你可以传入一个 字符串，或者字符串数组
-     * 1. 传入字符串数组,比如 `['view','text']` 生成:
+     * @group 3.一般配置
+     * @remarks
+     * 为兼容小程序缺乏 `:not([hidden])~` 支持的限制，默认会将 `.space-x-4` 等选择器替换为 `view + view`。可传入字符串或字符串数组以扩展适用标签。
      * ```css
+     * // 数组示例
      * .space-y-4>view + view,text + text{}
-     * ```
      *
-     * 2. 传入一个字符串，此时行为变成了整个替换，比如 `'view,text,button,input ~ view,text,button,input'` 生成:
-     * ```css
+     * // 字符串示例
      * .space-y-4>view,text,button,input ~ view,text,button,input{}
      * ```
      * @default 'view + view'
      */
     cssChildCombinatorReplaceValue?: string | string[];
     /**
+     * `postcss` 的配置选项。
+     *
      * @version `^3.2.0`
      * @group 3.一般配置
-     * @description 对解析 css 使用的 `postcss` 工具的配置
      */
     postcssOptions?: LoadedPostcssOptions;
     /**
+     * 是否移除 CSS 中的 `:hover` 选择器。
+     *
      * @version `^3.2.1`
      * @group 3.一般配置
      * @issue https://github.com/sonofmagic/weapp-tailwindcss/issues/293
+     * @remarks
+     * 小程序不支持 `:hover`，需要使用组件的 `hover-class`，因此默认删除相关节点。
      * @default `true`
-     * @description 是否删除 css :hover 选择器节点，默认为 `true`, 原因在于，小程序 css :hover 是不生效的，要使用 view 这种标签的 hover-class 属性
      */
     cssRemoveHoverPseudoClass?: boolean;
     /**
+     * 是否移除 `@property` 节点。
+     *
      * @version `^4.1.2`
      * @group 3.一般配置
+     * @remarks
+     * 微信小程序可识别 `@property`，但支付宝暂不支持，默认移除以避免构建失败。
      * @default `true`
-     * @description 是否删除 `@property` 选择器节点，默认为 `true`, 原因在于，现在微信小程序的 `@property` 是生效的，但是支付宝小程序遇到这个会直接挂掉
      */
     cssRemoveProperty?: boolean;
     /**
+     * 自定义 patcher 参数。
+     *
      * @group 3.一般配置
-     * @description 自定义 patcher 参数
      */
     tailwindcssPatcherOptions?: TailwindcssPatcherOptions;
     /**
+     * 控制命令行日志输出级别。
+     *
      * @group 3.一般配置
-     * @description 控制命令行日志的输出，默认为 `info`，可以设置成 `silent` 来禁止所有的命令行输出
+     * @remarks
+     * 默认 `info`，可设置为 `silent` 屏蔽全部输出。
      */
     logLevel?: 'info' | 'warn' | 'error' | 'silent';
 }
 interface UserDefinedOptions {
     /**
+     * 选择用于解析 JS 的 AST 工具。
+     *
      * @group 4.即将废弃配置
-     * @description 对解析 js 使用的 ast 工具，默认情况使用 `babel`，可以通过安装 `@ast-grep/napi`，同时启用 `ast-grep` 配置项，来启用 `ast-grep` 来处理 `js`，速度会是 `babel` 的 `2` 倍左右
+     * @remarks
+     * 默认使用 `babel`，安装 `@ast-grep/napi` 并设置为 `ast-grep` 可获得更快速度。
      * :::danger
-     * 此配置即将在 `5.x` 被弃用
-     *
-     * 废弃原因:
-     *
-     * 虽然 `@ast-grep/napi` 提供了更快的速度，但是 `babel` 有更强的静态分析 `js` 能力，使得后续一些新功能的开发无法使用 `@ast-grep/napi` 实现，所以废弃只保留 `babel` 的方式
+     * 此配置将在 `5.x` 版本移除，后续仅保留 `babel` 实现。
      * :::
      */
     jsAstTool?: 'babel' | 'ast-grep';
     /**
+     * 是否对指定范围的类名执行压缩混淆。
+     *
      * @group 4.即将废弃配置
-     * @description 是否压缩混淆 `wxml`,`js` 和 `wxss` 中指定范围的 `class` 以避免选择器过长问题，默认为`false`不开启，详细配置见 [unplugin-tailwindcss-mangle](https://github.com/sonofmagic/tailwindcss-mangle/tree/main/packages/unplugin-tailwindcss-mangle)
+     * @remarks
+     * 默认关闭，可参考 [unplugin-tailwindcss-mangle](https://github.com/sonofmagic/tailwindcss-mangle/tree/main/packages/unplugin-tailwindcss-mangle) 获取完整配置。
      * :::danger
-     * 此配置即将在 `5.x` 被弃用
-     *
-     * 废弃原因:
-     *
-     * mangle 相关的功能会被迁移到另外一个项目： [`tailwindcss-mangle`](https://github.com/sonofmagic/tailwindcss-mangle) 中去，还想要这个功能可以2个插件结合使用
+     * 此配置将在 `5.x` 中移除，功能已迁移至 [`tailwindcss-mangle`](https://github.com/sonofmagic/tailwindcss-mangle)。
      * :::
      */
     mangle?: boolean | IMangleOptions;
     /**
+     * 自定义 PostCSS 规则的处理回调。
+     *
      * @group 4.即将废弃配置
-     * @description 用于自定义处理 css 的回调函数，可根据 Postcss walk 方法自由定制处理方案的 callback 方法
      */
     customRuleCallback?: CustomRuleCallback;
 }