@guoxianxin/acf2

acf2 是一个用于 Vue 项目的自动配套文件生成工具。 当你在监听目录里新建文件时，它会按规则自动生成同目录下的 .less、types.ts、api.ts 等文件。

安装

npm i @guoxianxin/acf2

快速开始

import { runAcf2, defineAcf2Config } from "@guoxianxin/acf2";

runAcf2(
  defineAcf2Config({
    watchDir: "src/views",
    createEffect: {
      vue: () => ["less", "type.ts", "api"],
    },
    acf2Data: {
      styleLang: "less",
    },
  })
);

对外 API

@guoxianxin/acf2 当前对外暴露以下核心函数：

• runAcf2
• defineAcf2Config
• registerWriteFile
• baseWriteFileFn
• readTemplate
• writeGeneratedFile
• buildTemplateVars
• replaceTemplateContent
• resolveWritePath

1. runAcf2

作用：启动监听与自动生成流程。

函数签名：

runAcf2(config?: Acf2Config): void

使用示例：

import { runAcf2 } from "@guoxianxin/acf2";

runAcf2({
  watchDir: "src/views",
  createEffect: {
    vue: () => ["less", "type.ts", "api"],
  },
  acf2Data: {
    styleLang: "less",
  },
});

说明：

• 不传参数时会使用内置默认配置。
• 传入参数会覆盖默认配置后启动监听。

2. defineAcf2Config

作用：定义并返回带类型提示的配置对象（常用于 ts 项目）。

函数签名：

defineAcf2Config(config: Acf2Config): Acf2Config

使用示例：

import { defineAcf2Config, runAcf2 } from "@guoxianxin/acf2";

const config = defineAcf2Config({
  watchDir: "src/views",
  watchFileType: ["vue", "less", "type.ts"],
  createEffect: {
    vue: () => ["less", "type.ts", "api"],
  },
  acf2Data: {
    styleLang: "less",
  },
});

runAcf2(config);

说明：

• 这个函数本身不启动监听，仅用于定义配置。

3. registerWriteFile

作用：注册或覆盖某个文件类型的“生成函数”。

函数签名（简化）：

registerWriteFile(writeFile: Record<string, (config: Acf2Config) => Promise<any>>): void

使用示例：

import { registerWriteFile } from "@guoxianxin/acf2";

registerWriteFile({
  md: async (config) => {
    // 自定义 md 文件生成逻辑
  },
});

说明：

• key 是你定义的类型名（例如 md、vue_01）。
• 如果 key 与已有类型同名，会被覆盖。
• 常与 baseWriteFileFn 配合使用，减少重复模板替换代码。

4. baseWriteFileFn

作用：读取模板文件，替换 _acf2_ 变量，并写入目标文件。

函数签名：

baseWriteFileFn(options: {
  config: Acf2Config;
  templatePath: string;
  ext: string;
  fileName?: string;
}): Promise<void>

参数说明：

• config：acf2 配置对象。
• templatePath：模板文件绝对路径。
• ext：目标文件扩展名（如 ts、less、vue_01）。
• fileName：可选，覆盖默认输出文件名（默认使用 config.acf2Data.fileName）。

使用示例：

import { fileURLToPath } from "node:url";
import {
  baseWriteFileFn,
  registerWriteFile,
  runAcf2,
  defineAcf2Config,
} from "@guoxianxin/acf2";

registerWriteFile({
  vue_01: async (config) => {
    await baseWriteFileFn({
      config,
      templatePath: fileURLToPath(
        new URL("../template/template.vue", import.meta.url)
      ),
      ext: "vue_01",
    });
  },
});

runAcf2(
  defineAcf2Config({
    watchDir: "src/views",
    createEffect: {
      vue: () => ["less", "type.ts", "api", "vue_01"],
    },
    acf2Data: {
      styleLang: "less",
    },
  })
);

5. 模板处理工具函数（用于自定义写入流程）

当你希望在 registerWriteFile 里自己控制“读取/替换/写入”每一步时，可以使用这些函数：

• readTemplate(templatePath)：读取模板内容
• buildTemplateVars(config)：从 acf2Data 生成变量字典
• replaceTemplateContent(content, vars, options?)：按前缀做替换（默认 _acf2_）
• resolveWritePath({ config, ext, fileName? })：生成目标写入路径
• writeGeneratedFile(writePath, content)：把内容写入文件

示例：

import {
  registerWriteFile,
  readTemplate,
  buildTemplateVars,
  replaceTemplateContent,
  resolveWritePath,
  writeGeneratedFile,
} from "@guoxianxin/acf2";

registerWriteFile({
  md: async (config) => {
    const template = await readTemplate("/abs/template.md");
    const vars = buildTemplateVars(config);
    const content = replaceTemplateContent(template, vars);
    const writePath = resolveWritePath({ config, ext: "md" });
    await writeGeneratedFile(writePath, content);
  },
});

配置字段说明

Acf2Config 常用字段：

• watchDir：监听目录（相对当前执行目录）
• watchFileType：监听的文件类型
• createEffect：联动生成规则
• acf2Data：模板变量上下文

acf2Data 常用字段：

• fileName：文件名（无扩展名）
• ext：当前触发文件扩展名
• snakeName：下划线命名（如 getPopupCom -> get_popup_com）
• styleLang：样式语言（如 less）
• stylePath：样式引入语句
• filePath：当前文件完整路径
• dirPath：当前文件所在目录

模板占位符

内置模板支持以下变量替换：

• _acf2_fileName
• _acf2_ext
• _acf2_snakeName
• _acf2_styleLang
• _acf2_stylePath
• _acf2_filePath
• _acf2_dirPath

注意事项

• 仅在文件新增（add）时触发生成。
• 新建文件如果已经有内容，会跳过生成，避免覆盖。
• 建议仅在本地开发阶段开启监听，批量文件操作前(git 操作)先关闭进程。