自定义组件库

1. 初始化项目

在您想要创建项目的目录下，运行：

mccl init

脚手架会依次询问以下信息：

1. 组件库名称：请输入组件库名称

   • 示例：my-custom-components

   • 说明：这是组件库名称，默认会用于组件在物料面板中的分类目录。

2. 组件库描述：请输入组件库描述

   • 示例：这是一个基于 antd 的自定义组件库

   • 说明：描述您的组件库用途。

3. 组件库全局变量名：请输入组件库全局变量名

   • 示例：MyCustomComponents

   • 说明：请使用大驼峰命名法（PascalCase），首字母大写，后续字母可以是大小写字母、数字。这个名称将作为唯一标识，设置后请勿修改。

初始化完成后，会创建一个新的项目目录，目录名就是您输入的全局变量名。

生成的项目结构：

YourGlobalName/
├── mobi.config.js          # 配置文件
├── package.json            # 项目依赖配置
├── tsconfig.json           # TypeScript 配置
├── tsconfig.node.json      # Node.js 环境中的 TypeScript 配置文件
├── .gitignore              # Git 忽略文件
├── .nvmrc                  # Node.js 版本指定
├── README.md               # 项目说明文档
└── src/                    # 组件源码目录
    └── HelloMobi/          # 示例组件
        ├── index.tsx       # 组件实现
        └── config.ts       # 组件配置

注意事项：

• 全局变量名设置后请勿修改，因为它是组件的唯一标识

• 初始化会在当前目录下创建新文件夹，不会覆盖现有文件

2. 进入项目目录并安装依赖

cd YourGlobalName  # 替换为您的全局变量名
npm install # 或 pnpm install

3. 启动调试模式

mccl dev
# 或
npm run dev

使用场景：

• 开发组件时实时预览效果

• 调试组件配置

• 与 Mobi 平台集成测试

停止服务：

按 Ctrl+C 退出调试模式。

• 注意事项：

  • 调试模式需配合魔笔平台使用，详见下文。

4. 构建生产版本

mccl build
# 或
npm run build

构建产物：

构建完成后，会在项目根目录生成 dist.zip 文件，将该构建产物上传至魔笔控制台进行使用，详见下文。

1. mccl -v / --version - 查看版本

功能：查看当前安装的脚手架版本。

使用方式：

mccl -v
# 或
mccl --version

2. mccl -h / --help - 查看帮助

功能：查看脚手架帮助说明。

使用方式：

mccl -h
# 或
mccl --help

mobi.config.js - 核心配置文件

mobi.config.js 是脚手架的核心配置文件，位于项目根目录。它定义了组件库的基本信息、组件扫描规则和构建配置。

// Mobi 自定义组件库配置文件
export default {
  // === 组件库基本信息 ===
  library: {
    name: "七点组件",
    description: "这是一个自定义组件库",
  },

  // === 组件配置 ===
  components: {
    // 组件目录
    dir: "src",
    // 是否自动扫描组件目录
    autoScan: true,
    // 手动指定组件（当 autoScan 为 false 时使用）
    include: [],
    // 排除的组件
    exclude: [],
  },

  // === 构建配置 ===
  build: {
    // UMD 全局变量名（大驼峰命名法）
    globalName: "MyCompoLib",
    // 输出目录
    outDir: "dist",
    // 外部依赖（不打包）
    external: ["react", "react-dom", "antd", "dayjs", "@ant-design/icons"],
    // 全局变量映射
    globals: {
      react: "React",
      "react-dom": "ReactDOM",
      antd: "antd",
      dayjs: "dayjs",
      "@ant-design/icons": "AntdIcons",
    },
  },
};

library - 组件库基本信息

作用：定义组件库的基本元信息。

配置项：

components - 组件扫描配置

作用：配置组件扫描规则，告诉脚手架如何找到和识别组件。

配置项：

components: {
  dir: 'src',
  autoScan: true,
  exclude: ['_internal', 'utils', 'types'],
}

src/
├── Button/          ✅ 会被识别为 Button 组件
├── Input/           ✅ 会被识别为 Input 组件
├── Card/            ✅ 会被识别为 Card 组件
└── utils/           ❌ 被排除（在 exclude 列表中）

components: {
  dir: 'src',
  autoScan: false,
  include: ['Button', 'Input', 'Card'],
}

build - 构建配置

作用：配置构建相关的参数，包括输出目录、外部依赖、全局变量映射等。

配置项：

outDir: 'dist'  // 构建产物会输出到 dist.zip 目录

external: [
  'react',        // React 库
  'react-dom',    // ReactDOM 库
  'antd',         // Ant Design 组件库
  'dayjs',        // 日期处理库
  '@ant-design/icons',       // Ant Design 图标库
]

globals: {
  'react': 'React',           // npm 包 react 对应全局变量 React
  'react-dom': 'ReactDOM',     // npm 包 react-dom 对应全局变量 ReactDOM
  'antd': 'antd',             // npm 包 antd 对应全局变量 antd
  'dayjs': 'dayjs',           // npm 包 dayjs 对应全局变量 dayjs
}

组件目录结构

每个组件应该创建独立的文件夹，位于 src 目录下：

src/
└── ComponentName/          # 组件目录
    ├── index.tsx          # 组件实现
    └── config.ts          # 组件配置

文件说明：

• index.tsx：组件的 React 实现代码

• config.ts：组件的低代码平台配置

组件实现（index.tsx）

基本结构：

import React from 'react';
import { Button as AntdButton } from 'antd';

export interface ButtonProps {
  text?: string;
  type?: 'primary' | 'default';
  onClick?: () => void;
}

const Button: React.FC<ButtonProps> = ({
  text = '点击',
  type = 'primary',
  onClick,
}) => {
  return (
    <AntdButton type={type} onClick={onClick}>
      {text}
    </AntdButton>
  );
};

export default Button;

导出要求：

• ✅ 必须使用 export default 导出组件

• ✅ 组件名建议与目录名一致

• ❌ 不支持匿名导出

组件配置（config.ts）

作用：定义组件在低代码平台中的配置，包括属性面板、布局配置、元信息等。

基本结构：

const ButtonConfig = {
  // ========== 基本信息 ==========
  title: '自定义按钮',
  description: '这是一个按钮组件',
  icon: 'https://xxx.jpg',
  category: '基础组件',
  
  // ========== 容器相关 ==========
  isContainer: false,
  
  // ========== 属性面板配置 ==========
  inspectorConfig: [
    {
      title: '内容',
      items: [
        {
          type: 'control',
          title: '按钮文字',
          name: 'text',
          defaultValue: '按钮',
          valueType: 'string',
          control: {
            type: 'Code',
            props: {},
          },
        },
      ],
    },
  ],
  
  // ========== 网格布局配置 ==========
  gridConfig: {
    dragRect: {
      w: 4,
      h: 32,
    },
    initHeight: () => ({ type: 'auto' }),
    supportHeightType: ['fixed', 'auto'],
  },
  
  // ========== 暴露配置 ==========
  exposeConfig: {

    methods: [ ],

  },
};

export default ButtonConfig;

详细的配置项说明请参考组件配置项开发规范。

新建组件库

使用 mccl build命令，会在项目根目录下生成dist.zip（如果在 mobi.config.js文件中配置了outDir: 'dist'），将该dist.zip上传至魔笔平台进行管理。

更新组件库

点击待更新组件库右侧操作列的“更新”按钮，输入更新版本和更新说明信息，上传新版组件库后，可更新该组件库版本。

点击操作列“查看”按钮，可在发布历史中看到该组件库各个版本的发布信息。

注意事项：

• 更新组件库时，需保证该组件库的globalName保持不变。

开启调试模式

调试模式支持在开发组件库时进行实时预览，本地代码改动后，画布中的调试组件会自动更新。但调试模式是临时状态，本地组件开发完成后，可关闭调试模式，将组件构建为正式组件库，上传至魔笔控制台进行管理和长期使用。

需先在本地使用mccl dev开启调试模式

再在魔笔应用“设置 -> 组件库”中开启调试模式，当页面下方出现正在调试中的组件库名称时，说明该组件库已处于调试中状态。此时拖入该调试中的组件库，画布中的组件带有“调试中”标识，修改本地组件代码后，画布中组件会自动更新。