@novlan/postcss-plugin-remove-selector 0.1.3 → 0.1.5

package/README.md

@@ -23,11 +23,47 @@
 pnpm add @novlan/postcss-plugin-remove-selector -D
 ```
 
-在 `vite.config.ts` 中使用：
+### 简化模式（推荐）
+
+通过 `mode` 指定预设，只需关注 `used`/`unused`，无需手动配置 `file` 和 `selectorPattern`：
 
 ```ts
 import { defineConfig } from 'vite';
-import { postCssPluginRemoveSelector } from '@novlan/postcss-plugin-remove-selector';
+import { postcssPluginRemoveSelector } from '@novlan/postcss-plugin-remove-selector';
+
+export default defineConfig({
+  css: {
+    postcss: {
+      plugins: [
+        postcssPluginRemoveSelector({
+          mode: 'tdesign',
+          used: ['home', 'chat', 'user', 'add', 'search', 'close'],
+        }),
+      ],
+    },
+  },
+});
+```
+
+使用 `customUsed` / `customUnused` 可在预设基础上增量追加，不会覆盖预设中已有的列表：
+
+```ts
+postcssPluginRemoveSelector({
+  mode: 'tdesign',
+  // 在 tdesign 预设默认的 used 列表上，额外追加 'star' 和 'heart'
+  customUsed: ['star', 'heart'],
+  // 从结果中额外移除 'loading'
+  customUnused: ['loading'],
+})
+```
+
+### 标准模式
+
+通过 `list` 数组传入完整配置，适用于需要匹配多个文件的复杂场景：
+
+```ts
+import { defineConfig } from 'vite';
+import { postcssPluginRemoveSelector } from '@novlan/postcss-plugin-remove-selector';
 import {
   TDESIGN_ICON_REMOVE_SELECTOR
 } from '@novlan/postcss-plugin-remove-selector/lib/tdesign-uniapp-icon';
@@ -36,7 +72,7 @@ import {
 export default defineConfig({
   css: {
     postcss: {
-      plugins: [postCssPluginRemoveSelector(TDESIGN_ICON_REMOVE_SELECTOR)],
+      plugins: [postcssPluginRemoveSelector(TDESIGN_ICON_REMOVE_SELECTOR)],
     },
   },
 });
@@ -44,25 +80,46 @@ export default defineConfig({
 
 ## 3. 类型
 
-```ts
-interface FileConfig {
-  /** 文件匹配规则，可以是字符串或正则表达式 */
-  file: RegExp | string;
-  /** 需要保留的选择器列表（图标名称） */
-  include?: string[];
-  /** 需要移除的选择器列表（图标名称） */
-  exclude?: string[];
-  /** 选择器匹配模式，只处理匹配该模式的选择器 */
-  selectorPattern?: RegExp;
-}
-
-interface Options {
-  /** 配置列表 */
-  list: FileConfig[];
-  /** 是否开启调试模式 */
-  debug?: boolean;
-}
-```
+插件支持两种配置方式，传入 `SimpleOptions`（简化模式）或 `Options`（标准模式）均可。
+
+### SimpleOptions（简化模式）
+
+| 属性 | 类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| `mode` | `'tdesign'` | 否 | 预设模式，设置后自动使用对应的 `file` 和 `selectorPattern` 默认值 |
+| `file` | `RegExp \| string` | 否 | 文件匹配规则。使用 `mode` 时可省略 |
+| `used` | `string[]` | 否 | 正在使用的图标名称列表，这些图标会被保留 |
+| `unused` | `string[]` | 否 | 未使用的图标名称列表，这些图标会被移除 |
+| `customUsed` | `string[]` | 否 | 增量追加到 `used` 列表（不覆盖预设或已有的 `used`） |
+| `customUnused` | `string[]` | 否 | 增量追加到 `unused` 列表（不覆盖预设或已有的 `unused`） |
+| `selectorPattern` | `RegExp` | 否 | 选择器匹配模式。使用 `mode` 时可省略 |
+| `debug` | `boolean` | 否 | 是否开启调试模式 |
+
+> `mode` 和 `file` 至少需要指定一个。当 `mode` 和 `file`/`selectorPattern` 同时指定时，`file`/`selectorPattern` 优先。
+
+### Options（标准模式）
+
+| 属性 | 类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| `list` | `FileConfig[]` | 是 | 配置列表 |
+| `debug` | `boolean` | 否 | 是否开启调试模式 |
+
+### FileConfig
+
+| 属性 | 类型 | 是否必填 | 说明 |
+| --- | --- | --- | --- |
+| `file` | `RegExp \| string` | 是 | 文件匹配规则，可以是字符串或正则表达式 |
+| `used` | `string[]` | 否 | 正在使用的图标名称列表，这些图标会被保留 |
+| `unused` | `string[]` | 否 | 未使用的图标名称列表，这些图标会被移除 |
+| `customUsed` | `string[]` | 否 | 增量追加到 `used` 列表（不覆盖已有的 `used`） |
+| `customUnused` | `string[]` | 否 | 增量追加到 `unused` 列表（不覆盖已有的 `unused`） |
+| `selectorPattern` | `RegExp` | 否 | 选择器匹配模式，只处理匹配该模式的选择器 |
+
+### 内置预设
+
+| mode | 说明 | 默认 file | 默认 selectorPattern |
+| --- | --- | --- | --- |
+| `tdesign` | TDesign UniApp 图标减包 | `/[@/]tdesign[/]uniapp[/]dist[/]icon[/]icon\.[css\|vue]/` | `/^\.t-icon-[\w-]+:before$/` |
 
 ## 4. 更新日志
 

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 export * from './plugin';
-export { TDESIGN_ICON_REMOVE_SELECTOR } from './tdesign-uniapp-icon';
-export { postCssPluginRemoveSelector as default } from './plugin';
+export * from './tdesign-uniapp-icon';
+export * from './presets';
+export { postcssPluginRemoveSelector as default } from './plugin';

package/lib/index.js

@@ -30,25 +30,154 @@ function extractIconName(selector) {
  * @param options 配置项
  */
 function shouldRemoveRule(options) {
-    const { selectorPattern, include, exclude, selector } = options;
+    const { selectorPattern, used, unused, selector } = options;
     // 如果配置了 selectorPattern，只处理匹配的选择器
     if (selectorPattern && !selectorPattern.test(selector)) {
         return false;
     }
     // 提取图标名称进行精确匹配
     const iconName = extractIconName(selector);
-    // 如果有 include 列表，只保留 include 中的图标
-    if (include.length) {
-        return !include.includes(iconName || '');
+    // 如果有 used 列表，只保留 used 中的图标
+    if (used.length) {
+        return !used.includes(iconName || '');
     }
-    // 如果有 exclude 列表，移除 exclude 中的图标
-    if (exclude.length) {
-        return exclude.includes(iconName || '');
+    // 如果有 unused 列表，移除 unused 中的图标
+    if (unused.length) {
+        return unused.includes(iconName || '');
     }
     return false;
 }
 
+const TDESIGN_USED_ICONS = [
+    // custom-tab-bar.vue
+    'home',
+    'chat',
+    'user',
+    // home/index.vue
+    'add',
+    // release/index.vue
+    'location',
+    'file-copy',
+    'upload',
+    // search/index.vue
+    'search',
+    'delete',
+    // data-center/index.vue
+    'info-circle-filled',
+    // my/index.vue - 静态图标
+    'discount',
+    'edit',
+    // my/index.vue - gridList 动态图标
+    'root-list',
+    // my/index.vue - settingList 动态图标
+    'service',
+    'setting',
+    // setting/index.vue - menuData 动态图标
+    'app',
+    'notification',
+    'image',
+    'chart',
+    'sound',
+    'secured',
+    'info-circle',
+    // login/login.vue
+    'logo-wechat-stroke',
+    'logo-qq',
+    'logo-wecom',
+    'caret-down-small',
+    // nav-bar.vue
+    'view-list',
+    // 组件内部可能使用的图标（如 t-navbar left-arrow 等）
+    'chevron-left',
+    'chevron-right',
+    'chevron-up',
+    'chevron-down',
+    'arrow-left',
+    'arrow-right',
+    'arrow-up',
+    'arrow-down',
+    'close',
+    'close-circle-filled',
+    'check',
+    'check-circle-filled',
+    'error-circle-filled',
+    'loading',
+];
+/**
+ * 内置预设配置
+ *
+ * 每个预设包含默认的 file 和 selectorPattern，
+ * 用户只需提供 include/exclude 即可快速使用
+ */
+const PRESETS = {
+    tdesign: {
+        /** 匹配 @tdesign/uniapp 的图标 css 文件 */
+        file: /[@/]tdesign[/]uniapp[/]dist[/]icon[/]icon\.[css|vue]/,
+        /** 只处理 .t-icon-xxx:before 这类图标选择器 */
+        selectorPattern: /^\.t-icon-[\w-]+:before$/,
+        // 保留的图标名称列表
+        used: TDESIGN_USED_ICONS,
+    },
+};
+
 const PLUGIN_NAME = 'postcss-plugin-remove-selector';
+/**
+ * 判断传入的配置是否为简化模式
+ */
+function isSimpleOptions(opts) {
+    return !('list' in opts);
+}
+/**
+ * 将简化配置转换为标准 Options
+ */
+function normalizeOptions(opts) {
+    if (!isSimpleOptions(opts)) {
+        return opts;
+    }
+    const { mode, file, used, unused, customUsed, customUnused, selectorPattern, debug } = opts;
+    let resolvedFile = file;
+    let resolvedSelectorPattern = selectorPattern;
+    let resolvedUsed = used || [];
+    let resolvedUnused = unused || [];
+    // 如果指定了 mode，使用预设的默认值
+    if (mode && PRESETS[mode]) {
+        const preset = PRESETS[mode];
+        if (!resolvedFile) {
+            resolvedFile = preset.file;
+        }
+        if (!resolvedSelectorPattern) {
+            resolvedSelectorPattern = preset.selectorPattern;
+        }
+        // 如果用户没有显式指定 used/unused，使用预设的默认值
+        if (!used && preset.used) {
+            resolvedUsed = [...preset.used];
+        }
+        if (!unused && preset.unused) {
+            resolvedUnused = [...preset.unused];
+        }
+    }
+    // 将 customUsed/customUnused 增量追加（不覆盖）
+    if (customUsed?.length) {
+        resolvedUsed = [...resolvedUsed, ...customUsed];
+    }
+    if (customUnused?.length) {
+        resolvedUnused = [...resolvedUnused, ...customUnused];
+    }
+    if (!resolvedFile) {
+        throw new Error(`[${PLUGIN_NAME}] 必须指定 "file" 或 "mode"，当前均未设置。`);
+    }
+    return {
+        list: [
+            {
+                file: resolvedFile,
+                used: resolvedUsed,
+                unused: resolvedUnused,
+                selectorPattern: resolvedSelectorPattern,
+            },
+        ],
+        debug,
+    };
+}
 /**
  * 核心处理逻辑，PostCSS 7 / 8 共用
  */
@@ -59,7 +188,10 @@ function processRoot(root, result, opts) {
     if (!found) {
         return;
     }
-    const { exclude = [], include = [], selectorPattern } = found;
+    const { used = [], unused = [], customUsed = [], customUnused = [], selectorPattern } = found;
+    // 合并 customUsed/customUnused 到 used/unused
+    const mergedUsed = customUsed.length ? [...used, ...customUsed] : used;
+    const mergedUnused = customUnused.length ? [...unused, ...customUnused] : unused;
     if (debug) {
         console.log('[postcss-plugin-remove-selector] handling:', fileName);
     }
@@ -67,8 +199,8 @@ function processRoot(root, result, opts) {
     root.walkRules((rule) => {
         if (shouldRemoveRule({
             selectorPattern,
-            exclude,
-            include,
+            used: mergedUsed,
+            unused: mergedUnused,
             selector: rule.selector,
         })) {
             rule.remove();
@@ -87,26 +219,32 @@ function processRoot(root, result, opts) {
  * - PostCSS 8：使用标准 Creator 函数格式 + postcss: true 标记
  * - PostCSS 7：回退到 postcss.plugin() 注册方式
  *
+ * 支持两种配置方式：
+ * 1. 标准模式：传入 { list: [...], debug?: boolean }
+ * 2. 简化模式：传入 { mode?, file?, used?, unused?, customUsed?, customUnused?, selectorPattern?, debug? }
+ *
  * @param opts 配置项
  * @returns PostCSS 插件
  */
-const postCssPluginRemoveSelector = (opts = { list: [] }) => 
-// PostCSS 8 格式
-({
-    postcssPlugin: PLUGIN_NAME,
-    Once(root, { result }) {
-        processRoot(root, result, opts);
-    },
-});
+const postcssPluginRemoveSelector = (opts = { list: [] }) => {
+    const normalizedOpts = normalizeOptions(opts);
+    return {
+        postcssPlugin: PLUGIN_NAME,
+        Once(root, { result }) {
+            processRoot(root, result, normalizedOpts);
+        },
+    };
+};
 // 标记为 PostCSS 8 插件
-postCssPluginRemoveSelector.postcss = true;
+postcssPluginRemoveSelector.postcss = true;
 // PostCSS 7 兼容：通过 postcss.plugin() 注册
 try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const postcss = require('postcss');
     if (postcss && typeof postcss.plugin === 'function') {
-        postCssPluginRemoveSelector.postcss7 = postcss.plugin(PLUGIN_NAME, (opts = { list: [] }) => (root, result) => {
-            processRoot(root, result, opts);
+        postcssPluginRemoveSelector.postcss7 = postcss.plugin(PLUGIN_NAME, (opts = { list: [] }) => (root, result) => {
+            const normalizedOpts = normalizeOptions(opts);
+            processRoot(root, result, normalizedOpts);
         });
     }
 }
@@ -118,72 +256,13 @@ catch (e) {
  * TDesign UniApp 图标减包配置
  *
  * 使用说明：
- * 1. 在 USED_ICONS 数组中配置项目中实际使用的图标名称
+ * 1. 在 TDESIGN_USED_ICONS 数组中配置项目中实际使用的图标名称
  * 2. 插件只会处理 .t-icon-xxx:before 这类图标选择器
  * 3. 其他基础样式（如 @font-face、.t-icon 等）会自动保留
  *
  * 如何查找项目中使用的图标：
  * grep -rho 'icon="[^"]*"\|left-icon="[^"]*"\|name="[^"]*"' src --include="*.vue" | sort | uniq
  */
-/**
- * 项目中实际使用的图标列表
- * 根据 src 目录下的 .vue 文件分析得出
- */
-const USED_ICONS = [
-    // custom-tab-bar.vue
-    'home',
-    'chat',
-    'user',
-    // home/index.vue
-    'add',
-    // release/index.vue
-    'location',
-    'file-copy',
-    'upload',
-    // search/index.vue
-    'search',
-    'delete',
-    // data-center/index.vue
-    'info-circle-filled',
-    // my/index.vue - 静态图标
-    'discount',
-    'edit',
-    // my/index.vue - gridList 动态图标
-    'root-list',
-    // my/index.vue - settingList 动态图标
-    'service',
-    'setting',
-    // setting/index.vue - menuData 动态图标
-    'app',
-    'notification',
-    'image',
-    'chart',
-    'sound',
-    'secured',
-    'info-circle',
-    // login/login.vue
-    'logo-wechat-stroke',
-    'logo-qq',
-    'logo-wecom',
-    'caret-down-small',
-    // nav-bar.vue
-    'view-list',
-    // 组件内部可能使用的图标（如 t-navbar left-arrow 等）
-    'chevron-left',
-    'chevron-right',
-    'chevron-up',
-    'chevron-down',
-    'arrow-left',
-    'arrow-right',
-    'arrow-up',
-    'arrow-down',
-    'close',
-    'close-circle-filled',
-    'check',
-    'check-circle-filled',
-    'error-circle-filled',
-    'loading',
-];
 /**
  * TDesign UniApp 图标减包配置
  */
@@ -191,19 +270,19 @@ const TDESIGN_ICON_REMOVE_SELECTOR = {
     list: [
         {
             // 匹配 @tdesign/uniapp 的图标 css 文件
-            file: /[@/]tdesign[/]uniapp[/]dist[/]icon[/]icon\.[css|vue]/,
+            file: PRESETS.tdesign.file,
             // 只处理 .t-icon-xxx:before 这类图标选择器，其他样式自动保留
-            selectorPattern: /^\.t-icon-[\w-]+:before$/,
+            selectorPattern: PRESETS.tdesign.selectorPattern,
             // 保留的图标名称列表
-            include: USED_ICONS,
-            exclude: [],
+            used: PRESETS.tdesign.used,
         },
     ],
 };
 
+exports.PRESETS = PRESETS;
 exports.TDESIGN_ICON_REMOVE_SELECTOR = TDESIGN_ICON_REMOVE_SELECTOR;
-exports["default"] = postCssPluginRemoveSelector;
+exports["default"] = postcssPluginRemoveSelector;
 exports.extractIconName = extractIconName;
-exports.postCssPluginRemoveSelector = postCssPluginRemoveSelector;
+exports.postcssPluginRemoveSelector = postcssPluginRemoveSelector;
 exports.shouldHandleFile = shouldHandleFile;
 exports.shouldRemoveRule = shouldRemoveRule;

package/lib/plugin.d.ts

@@ -1,4 +1,4 @@
-export type { Options, FileConfig, ShouldRemoveRuleOptions } from './types';
+export type { Options, SimpleOptions, FileConfig, ShouldRemoveRuleOptions, PresetMode, Preset } from './types';
 export { shouldHandleFile, shouldRemoveRule, extractIconName } from './helper';
 /**
  * PostCSS 插件：移除指定的 CSS 选择器
@@ -8,8 +8,12 @@ export { shouldHandleFile, shouldRemoveRule, extractIconName } from './helper';
  * - PostCSS 8：使用标准 Creator 函数格式 + postcss: true 标记
  * - PostCSS 7：回退到 postcss.plugin() 注册方式
  *
+ * 支持两种配置方式：
+ * 1. 标准模式：传入 { list: [...], debug?: boolean }
+ * 2. 简化模式：传入 { mode?, file?, used?, unused?, customUsed?, customUnused?, selectorPattern?, debug? }
+ *
  * @param opts 配置项
  * @returns PostCSS 插件
  */
-declare const postCssPluginRemoveSelector: any;
-export { postCssPluginRemoveSelector };
+declare const postcssPluginRemoveSelector: any;
+export { postcssPluginRemoveSelector };

package/lib/presets.d.ts

@@ -0,0 +1,8 @@
+import type { Preset, PresetMode } from './types';
+/**
+ * 内置预设配置
+ *
+ * 每个预设包含默认的 file 和 selectorPattern，
+ * 用户只需提供 include/exclude 即可快速使用
+ */
+export declare const PRESETS: Record<PresetMode, Preset>;

package/lib/tdesign-uniapp-icon.d.ts

@@ -2,7 +2,7 @@
  * TDesign UniApp 图标减包配置
  *
  * 使用说明：
- * 1. 在 USED_ICONS 数组中配置项目中实际使用的图标名称
+ * 1. 在 TDESIGN_USED_ICONS 数组中配置项目中实际使用的图标名称
  * 2. 插件只会处理 .t-icon-xxx:before 这类图标选择器
  * 3. 其他基础样式（如 @font-face、.t-icon 等）会自动保留
  *
@@ -14,9 +14,8 @@
  */
 export declare const TDESIGN_ICON_REMOVE_SELECTOR: {
     list: {
-        file: RegExp;
+        file: string | RegExp;
         selectorPattern: RegExp;
-        include: string[];
-        exclude: never[];
+        used: string[] | undefined;
     }[];
 };

package/lib/types.d.ts

@@ -4,10 +4,14 @@
 export interface FileConfig {
     /** 文件匹配规则，可以是字符串或正则表达式 */
     file: RegExp | string;
-    /** 需要保留的选择器列表（图标名称） */
-    include?: string[];
-    /** 需要移除的选择器列表（图标名称） */
-    exclude?: string[];
+    /** 正在使用的选择器列表（图标名称），这些图标会被保留 */
+    used?: string[];
+    /** 未使用的选择器列表（图标名称），这些图标会被移除 */
+    unused?: string[];
+    /** 增量追加到 used 列表中的图标名称，不会覆盖已有的 used */
+    customUsed?: string[];
+    /** 增量追加到 unused 列表中的图标名称，不会覆盖已有的 unused */
+    customUnused?: string[];
     /** 选择器匹配模式，只处理匹配该模式的选择器 */
     selectorPattern?: RegExp;
 }
@@ -20,16 +24,55 @@ export interface Options {
     /** 是否开启调试模式 */
     debug?: boolean;
 }
+/**
+ * 预设模式名称
+ */
+export type PresetMode = 'tdesign';
+/**
+ * 预设配置，包含默认的 file 和 selectorPattern
+ */
+export interface Preset {
+    /** 文件匹配规则 */
+    file: RegExp | string;
+    /** 选择器匹配模式 */
+    selectorPattern: RegExp;
+    /** 正在使用的选择器列表（图标名称），这些图标会被保留 */
+    used?: string[];
+    /** 未使用的选择器列表（图标名称），这些图标会被移除 */
+    unused?: string[];
+}
+/**
+ * 简化配置项（扁平化形式）
+ * 适用于只需要配置单个文件场景，无需传递 list 数组
+ */
+export interface SimpleOptions {
+    /** 预设模式，如 'tdesign'，设置后自动使用对应的 file 和 selectorPattern 默认值 */
+    mode?: PresetMode;
+    /** 文件匹配规则，可以是字符串或正则表达式。使用 mode 时可省略 */
+    file?: RegExp | string;
+    /** 正在使用的选择器列表（图标名称），这些图标会被保留 */
+    used?: string[];
+    /** 未使用的选择器列表（图标名称），这些图标会被移除 */
+    unused?: string[];
+    /** 增量追加到 used 列表中的图标名称，不会覆盖已有的 used（适用于在预设基础上额外新增） */
+    customUsed?: string[];
+    /** 增量追加到 unused 列表中的图标名称，不会覆盖已有的 unused（适用于在预设基础上额外新增） */
+    customUnused?: string[];
+    /** 选择器匹配模式，只处理匹配该模式的选择器。使用 mode 时可省略 */
+    selectorPattern?: RegExp;
+    /** 是否开启调试模式 */
+    debug?: boolean;
+}
 /**
  * 判断是否移除规则的参数
  */
 export interface ShouldRemoveRuleOptions {
     /** 选择器匹配模式 */
     selectorPattern?: RegExp;
-    /** 需要保留的选择器列表 */
-    include: string[];
-    /** 需要移除的选择器列表 */
-    exclude: string[];
+    /** 正在使用的选择器列表，这些会被保留 */
+    used: string[];
+    /** 未使用的选择器列表，这些会被移除 */
+    unused: string[];
     /** 当前选择器 */
     selector: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novlan/postcss-plugin-remove-selector",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "homepage": "https://novlan1.github.io/plugins/zh/postcss-plugin-remove-selector.html",
   "bugs": {
     "url": "https://github.com/novlan1/plugins/issues"