easyv-types-x

自动从配置文件生成 TypeScript 类型定义的工具。

功能特性

• 🔄 监听配置文件变化，自动生成对应的 TypeScript 类型
• 📁 支持多组件项目结构
• 🎯 智能类型推断，支持嵌套对象和数组
• 📄 多格式支持: 支持 .json、.js、.mjs 配置文件
• ⚡ 零配置开箱即用
• 👀 自动监听模式: 在开发命令中添加监听功能

安装

npm install easyv-types-x

安装完成后，工具会自动：

1. 将 types-listener.js 脚本复制到你的项目根目录
2. 在你的 package.json 中添加以下脚本命令：
   • "types-listener": "node types-listener.js"
   • "dev:watch": "concurrently \"npm run types-listener\" \"npm run dev\""
   • "start:watch": "concurrently \"npm run types-listener\" \"npm start\""
3. 提供全局命令：
   • types-listener - 项目监听模式
   • easyv-types-x - 单文件模式

如果你想使用 :watch 命令，还需要安装 concurrently：

npm install --save-dev concurrently

使用方法

方式一：项目监听模式（推荐）

适用于有固定项目结构的场景。

1. 确保项目结构

确保你的项目有以下结构：

your-project/
├── src/
│   └── components/
│       ├── component1/
│       │   └── config/
│       │       └── main.js     # 或 main.json, main.mjs
│       ├── component2/
│       │   └── config/
│       │       └── main.json   # 或 main.js, main.mjs
│       └── ...
└── package.json

支持的配置文件格式:

• main.js (CommonJS或ES Module)
• main.mjs (ES Module)
• main.json (JSON格式)

工具会按优先级顺序查找：main.js > main.mjs > main.json

外部依赖支持 🆕：

• 内置 @easyv/config 支持: 工具已集成 @easyv/config 依赖，支持所有导入方式
• 智能兼容性处理: 自动处理 CommonJS 模块的导入兼容性问题
• 零配置体验: 无需修改现有代码，支持标准 ES 模块导入语法

支持的导入方式 🔄

工具完全兼容标准的 ES 模块导入语法，无需修改现有代码：

// ✅ 标准 ES 模块导入（推荐，无需修改）
import { sc, show, showRule } from "@easyv/config";

// ✅ 默认导入方式（也支持）
import pkg from "@easyv/config";
const { sc, show, showRule } = pkg;

JavaScript 配置示例 (main.js)

import { sc, show, showRule } from "@easyv/config";

export default {
  base: {
    name: '3D城市组件',
    module_name: 'smartCity3D',
    version: '1.0.0',
    show: 1
  },
  configuration: [
    {
      name: 'chart',
      displayName: '基础配置',
      value: [
        // 使用 show() 函数生成显示控制
        show(true),
        
        // 使用 sc() 函数生成复杂配置项
        sc("mapLimit", "地图范围限制", "", [
          show(true),
          sc("angles", "旋转限制", "", [
            sc("hRotate", "水平", "range", [-180, 180], {
              min: -180,
              max: 180,
              suffix: "°"
            }),
            sc("vRotate", "垂直", "range", [10, 90], {
              min: 10,
              max: 90,
              suffix: "°"
            })
          ], { defaultOpen: true }, showRule())
        ], { defaultOpen: true })
      ]
    }
  ]
};

说明: 工具内置了 @easyv/config 依赖，并自动处理导入兼容性，你可以使用任何标准的导入方式，无需修改现有代码。

3. 配置文件格式

JSON格式 (main.json)

{
  "configuration": [
    {
      "name": "title",
      "value": "默认标题"
    },
    {
      "name": "style",
      "value": {
        "color": "#ffffff",
        "fontSize": 16
      }
    },
    {
      "name": "data",
      "value": [
        { "name": "item1", "value": "value1" },
        { "name": "item2", "value": "value2" }
      ]
    }
  ]
}

JavaScript格式 (main.js 或 main.mjs)

export default {
  base: {
    name: '组件名称',
    module_name: 'component-name',
    version: '1.0.0',
    show: 1
  },
  width: 520,
  height: 400,
  configuration: [
    {
      name: 'chart',
      displayName: '全局',
      type: 'object',
      value: [
        {
          name: 'textStyle',
          displayName: '文本样式',
          value: [
            {
              name: 'fontFamily',
              displayName: '字体',
              type: 'font',
              value: 'Arial',
            },
            {
              name: 'fontSize',
              displayName: '字体大小',
              type: 'number',
              value: 14,
            }
          ]
        }
      ]
    }
  ]
};

2. 运行类型生成

手动运行

npm run types-listener

或者直接运行：

node types-listener.js

自动监听模式 🆕

工具会自动在你的 package.json 中添加带有监听功能的脚本：

# 开发模式 + 类型监听
npm run dev:watch

# 启动项目 + 类型监听  
npm run start:watch

这些命令会同时运行你的项目和类型生成器，当配置文件发生变化时，TypeScript 类型会自动重新生成！

注意: 使用 :watch 命令需要安装 concurrently 包：

npm install --save-dev concurrently

方式二：单文件模式 🆕

适用于有独立配置文件目录的场景。

使用 easyv-types-x 命令可以为单个配置文件生成类型：

# 基本用法
easyv-types-x <config-name> [output-name] [interface-name]

# 示例
easyv-types-x a                      # 从 a.js/a.json 生成 a.ts
easyv-types-x a myTypes              # 从 a.js/a.json 生成 myTypes.ts
easyv-types-x config component       # 从 config.js/config.json 生成 component.ts  
easyv-types-x data DataTypes MyData  # 生成 DataTypes.ts，接口名为 MyData

# 全局使用（安装后可直接使用）
easyv-types-x a                      # 直接运行，无需 npx

使用场景：

# 假设你有一个 configs 目录
configs/
├── a.json
├── b.js  
├── c.mjs
└── d.json

# 在 configs 目录中运行
cd configs
easyv-types-x a                    # 生成 a.ts（使用默认文件名）
easyv-types-x a types-a            # 生成 types-a.ts
easyv-types-x b types-b MyConfig   # 生成 types-b.ts，接口名为 MyConfig

支持的文件格式：

• .js (CommonJS或ES Module)
• .mjs (ES Module)
• .json (JSON格式)

工具会按优先级搜索：<name>.js > <name>.mjs > <name>.json

4. 生成的类型文件

工具会在每个组件的 config 目录下生成 types.ts 文件（项目监听模式）或在指定位置生成类型文件（单文件模式）：

export interface MyComponentProps {
  left: number;
  top: number;
  width: number;
  height: number;
  id: string;
  configuration: {
    title: string;
    style: {
      color: string;
      fontSize: number;
    };
    data: any[];
  };
}

export default MyComponentProps;

工作原理

1. 扫描 src/components 目录下的所有组件文件夹
2. 监听每个组件的 config/main.json 文件变化
3. 解析 JSON 配置，推断 TypeScript 类型
4. 生成对应的 types.ts 文件

支持的类型推断

• string → string
• number → number
• boolean → boolean
• null → null
• Array → any[]
• Object → 推断具体对象结构

许可证

ISC

贡献

欢迎提交 Issue 和 Pull Request！