AI 驱动的 Vue3 应用开发平台 深入探究（十）：物料系统之内置组件库

内置组件库（Element Plus、Ant Design Vue、Vant）

VTJ 通过其统一的物料系统架构，与三个流行的 Vue 组件库提供了全面的集成。这一抽象层使开发者能够利用熟悉的组件模式，同时保持低代码的可扩展性和跨库的可移植性。该系统将组件库定义转换为物料描述，从而驱动可视化设计器、代码生成器和运行时渲染器。

物料系统架构

内置组件库通过 VTJ 的物料系统实现，该系统作为 UI 组件库和低代码引擎之间的抽象层。每个组件库都表示为一组物料描述，定义了组件元数据、属性配置、事件处理程序和默认模板。

flowchart TD
    subgraph Built-in_Libraries [Built-in Libraries]
        F[Element Plus]
        G[Ant Design Vue]
        H[Vant]
    end
    subgraph VTJ_Material_System [VTJ Material System]
        A[MaterialDescription]
        B[Component Metadata]
        C[Props & Setters]
        D[Events & Slots]
        E[Snippet Template]
    end
    subgraph VTJ_Engine [VTJ Engine]
        I[Visual Designer]
        J[Code Generator]
        K[Runtime Renderer]
    end

    F --> A
    G --> A
    H --> A
    A --> B
    A --> C
    A --> D
    A --> E
    I --> A
    J --> A
    K --> A

物料系统架构遵循声明式模式，其中每个组件通过从 @vtj/core 导出的 MaterialDescription 接口定义。这种方法实现了跨不同 UI 框架的一致组件注册、属性编辑和代码生成。

组件库概述

VTJ 附带了三个完整的组件库实现，每个都针对不同的用例和平台：

Component Library	Target Use Case	Platform	Component Count	Package Name
Element Plus	企业级 Web 应用	Desktop/Web	60+	element-plus
Ant Design Vue	企业级管理系统	Desktop/Web	60+	ant-design-vue
Vant	移动端 H5 应用	Mobile/Web	70+	vant

每个库都作为 @vtj/materials 包中的独立构建目标进行维护，允许有选择地进行 tree-shaking 和优化包体积。构建系统通过特定于环境的构建脚本独立编译每个库。

物料描述结构

VTJ 内置库中的每个组件都通过标准化的物料描述模式定义。该模式提供了可视化编辑、代码生成和运行时渲染所需的元数据。

核心属性

{
  name: 'ElButton',           // 组件名称（库前缀）
  label: '按钮',              // 中文显示标签
  alias: 'Button',            // 可选引用别名
  categoryId: 'base',         // 组件分类
  doc: 'https://...',         // 文档 URL 引用
  package: 'element-plus',     // 源包名称
  props: [...],               // 属性定义
  events: [...],              // 事件定义
  slots: [...],               // 插槽定义
  snippet: {...}              // 默认模板片段
}

属性定义

组件属性通过 setter 配置定义，这些配置决定了它们在可视化设计器中的编辑方式。Setters 将属性类型映射到相应的编辑组件。

共享属性工具

VTJ 为跨组件库的通用模式提供了可重用的属性定义工具，减少了重复并确保了一致性。

尺寸属性：

function size(name: string = "size"): MaterialProp {
  return {
    name,
    title: "尺寸",
    defaultValue: "default",
    setters: "SelectSetter",
    options: ["default", "large", "small"],
  };
}

类型属性：

function type(name: string = "type"): MaterialProp {
  return {
    name,
    title: "类型",
    defaultValue: "default",
    setters: "SelectSetter",
    options: ["default", "primary", "success", "warning", "danger", "info"],
  };
}

这些工具在组件中使用，以保持一致的尺寸和类型选项，同时允许通过参数化进行每个库的定制。

Element Plus 集成

Element Plus 是 VTJ 用于桌面 Web 应用的主要组件库，提供了一套全面的企业级组件，并支持 Vue 3 Composition API。

组件分类

Element Plus 组件按功能分类组织：

• 基础组件：Button, Layout, Space, Link, Text, Scrollbar
• 表单组件：Input, Select, Checkbox, Radio, DatePicker, Upload, Form
• 数据展示：Table, Tree, Card, Calendar, Avatar, Badge, Tag
• 导航：Menu, Tabs, Breadcrumb, Steps, Anchor, PageHeader
• 反馈：Dialog, Drawer, Alert, Tooltip, Popover, Popconfirm
• 其他：Divider, Watermark, ConfigProvider, Splitter

组件示例：Button

const button: MaterialDescription = {
  name: "ElButton",
  label: "按钮",
  categoryId: "base",
  doc: "https://element-plus.org/zh-CN/component/button.html",
  props: [
    size("size"),
    type("type"),
    {
      name: "plain",
      title: "是否为朴素按钮",
      defaultValue: false,
      setters: "BooleanSetter",
    },
    {
      name: "loading",
      title: "是否为加载中状态",
      defaultValue: false,
      setters: "BooleanSetter",
    },
    {
      name: "icon",
      title: "图标组件",
      defaultValue: undefined,
      setters: "IconSetter",
    },
  ],
  events: ["click"],
  slots: ["default", "loading", "icon", "tag"],
  snippet: {
    name: "ElButton",
    children: "按钮",
    props: { type: "primary" },
  },
};

高级组件

Element Plus 包含用于复杂数据场景的复杂组件：

• ElTable：功能齐全的数据表，支持排序、筛选、分页和虚拟滚动
• ElTreeV2：用于大型数据集的高性能虚拟树组件
• ElTransfer：用于数据选择的双面板穿梭组件
• ElVirtualizedTable：用于处理大量行数据的虚拟滚动表

Ant Design Vue 集成

Ant Design Vue 提供了另一个企业级 UI 组件库，其设计系统专注于企业应用程序和丰富的交互组件。

组件组织

Ant Design Vue 遵循与 Element Plus 类似的分类方案，但采用特定于组件的命名约定：

• 基础组件：Button, Typography, Divider, Flex, Grid, Layout, Space
• 输入组件：Form, Input, Select, DatePicker, Upload, Cascader, Rate
• 导航组件：Menu, Breadcrumb, Steps, Anchor, PageHeader, Pagination
• 数据展示：Table, List, Card, Calendar, Avatar, Badge, Tag, Tree
• 反馈组件：Alert, Modal, Drawer, Message, Notification, Progress
• 其他组件：Affix, ConfigProvider, FloatButton, Watermark

组件示例：Button

const components: MaterialDescription[] = [
  {
    name: "AButton",
    alias: "Button",
    label: "按钮",
    categoryId: "base",
    doc: "https://www.antdv.com/components/button-cn",
    props: [
      {
        name: "type",
        label: "type",
        setters: "SelectSetter",
        options: ["primary", "ghost", "dashed", "link", "text", "default"],
        defaultValue: "default",
      },
      {
        name: "shape",
        label: "shape",
        setters: "SelectSetter",
        options: ["default", "circle", "round"],
        defaultValue: "default",
      },
      {
        name: "size",
        label: "size",
        setters: "SelectSetter",
        options: ["large", "middle", "small"],
        defaultValue: "middle",
      },
      {
        name: "danger",
        label: "danger",
        setters: "BooleanSetter",
        defaultValue: false,
      },
    ],
    events: ["click"],
    slots: ["default", "icon"],
    snippet: { children: "Button" },
  },
];

独特组件

Ant Design Vue 包含其他库中未发现的独特组件：

• Comment：用于线程化讨论的评论列表组件
• Descriptions：结构化描述列表组件
• FloatButton：具有定位功能的浮动操作按钮
• QRCode：二维码生成和显示
• Segmented：用于值选择的分段控件

Vant 集成

Vant 是 Vue 3 的 premier 移动端组件库，针对触摸交互和移动优先设计模式进行了优化。VTJ 的 Vant 集成通过低代码生产力实现快速移动 H5 应用程序开发。

移动优化分类

Vant 组件围绕移动用例组织：

• 基础组件：Button, Cell, Icon, Image, Popup, Space, Toast
• 表单组件：Field, Form, Calendar, DatePicker, Picker, Uploader, Stepper
• 反馈组件：Dialog, ActionSheet, Overlay, Loading, Notify, PullRefresh
• 视图组件：Badge, Card, Collapse, List, Steps, Swipe, Progress
• 导航组件：NavBar, Tabbar, Tab, Sidebar, Grid, IndexBar, Pagination
• 业务组件：AddressEdit, ContactCard, CouponList, SubmitBar

组件示例：Button

const Button: MaterialDescription = {
  name: "VanButton",
  alias: "Button",
  label: "按钮",
  categoryId: "base",
  doc: "https://vant-ui.github.io/vant/#/zh-CN/button",
  props: [
    {
      name: "type",
      title: "类型，可选值为 primary success warning danger",
      defaultValue: "default",
      setters: "SelectSetter",
      options: ["primary", "success", "warning", "danger", "default"],
    },
    {
      name: "size",
      title: "尺寸，可选值为 large small mini",
      defaultValue: "normal",
      setters: "SelectSetter",
      options: ["large", "small", "mini", "normal"],
    },
    {
      name: "block",
      title: "是否为块级元素",
      setters: "BooleanSetter",
    },
    {
      name: "loading",
      title: "是否显示为加载状态",
      setters: "BooleanSetter",
    },
    {
      name: "url",
      title: "点击后跳转的链接地址",
      setters: "StringSetter",
    },
  ],
  events: ["click", "touchstart"],
  slots: ["default", "icon", "loading"],
  snippet: { children: "按钮" },
};

移动端特定功能

Vant 包含针对移动交互优化的组件：

• 触摸事件：扩展的事件处理，支持 touchstart, touchmove, touchend
• 手势组件：用于手势操作的 SwipeCell, Swipe, PullRefresh
• NumberKeyboard：用于数字输入的自定义键盘
• FloatingPanel：具有可拖动交互的底部面板
• AddressEdit：完整的地址选择和编辑组件

属性 Setter 系统

VTJ 的属性 setter 系统将组件属性映射到可视化设计器中相应的编辑组件。该系统确保类型安全的属性编辑，同时提供丰富的用户体验。

常见 Setter 类型

Setter Type	Usage	Example Properties
StringSetter	文本输入	title, placeholder
NumberSetter	数字输入	maxlength, min
BooleanSetter	切换开关	disabled, loading
SelectSetter	下拉选择	type, size
IconSetter	图标选择	icon
ArraySetter	数组编辑	data, options
JSONSetter	JSON 对象编辑	columnConfig, formRules
ColorSetter	颜色选择器	color, backgroundColor

Setter 配置示例

{
  name: 'size',
  title: '尺寸',
  defaultValue: 'default',
  setters: 'SelectSetter',
  options: ['default', 'large', 'small']
},
{
  name: 'loading',
  title: '是否为加载中状态',
  defaultValue: false,
  setters: 'BooleanSetter'
},
{
  name: 'icon',
  title: '图标组件',
  defaultValue: undefined,
  setters: 'IconSetter'
}

属性可以通过提供数组来使用多个 setter，从而实现灵活的编辑界面。例如，setters: ['ArraySetter', 'JSONSetter'] 允许在可视化数组编辑和直接 JSON 输入之间切换，用于复杂数据结构。

组件分类系统

VTJ 将组件组织为逻辑分类，以提高在可视化设计器中的可发现性。每个组件都分配有一个 categoryId，用于确定其面板位置。

标准分类

Category ID	Display Name	Typical Components
base	基础组件	Button, Layout, Space, Icon
form	表单组件	Input, Select, Form, DatePicker
data	数据展示	Table, Tree, Card, List
nav	导航	Menu, Tabs, Breadcrumb, Steps
feedback	反馈	Dialog, Alert, Drawer, Tooltip
other	其他	Divider, Watermark, ConfigProvider

分类实现

// Element Plus 分类
import affix from "./affix"; // nav
import alert from "./alert"; // feedback
import avatar from "./avatar"; // data
import button from "./button"; // base
import cascader from "./cascader"; // form

// 每个组件定义其分类
const button: MaterialDescription = {
  name: "ElButton",
  label: "按钮",
  categoryId: "base", // 分类分配
  // ... 其他属性
};

Snippet 模板系统

Snippet 系统提供了默认的模板配置，当通过可视化设计器添加组件时会插入这些配置。Snippets 包括默认属性值、子内容和嵌套组件结构。

简单 Snippet 示例

snippet: {
  name: 'ElButton',
  children: '按钮',
  props: {
    type: 'primary'
  }
}

复杂 Snippet 示例

snippet: {
  name: 'ElButtonGroup',
  children: [
    {
      name: 'ElButton',
      children: 'Button1'
    },
    {
      name: 'ElButton',
      children: 'Button2'
    },
    {
      name: 'ElButton',
      children: 'Button3'
    }
  ]
}

Snippet 优势

• 快速开始：为常见用例提供合理的默认值
• 最佳实践：鼓励正确的组件使用模式
• 一致性：在项目中保持统一的组件结构
• 可扩展性：可以由开发者为项目特定需求进行定制

事件和插槽定义

组件定义其支持的事件和插槽，以便在低代码环境中实现正确的交互处理和内容组合。

事件定义

事件声明为简单的字符串数组，指定哪些组件事件可用于在可视化设计器中绑定。

// Element Plus Button
events: ["click"];

// Vant Button (包括触摸事件)
events: ["click", "touchstart"];

// 复杂组件支持多个事件
events: ["select", "change", "focus", "blur", "clear"];

插槽定义

插槽定义了可以插入自定义内容的位置，实现灵活的组件组合。

// Element Plus Button
slots: ["default", "loading", "icon", "tag"];

// Ant Design Button
slots: ["default", "icon"];

// Vant Button
slots: ["default", "icon", "loading"];

插槽使用模式

插槽定义驱动可视化设计器中的插槽编辑界面，允许开发者：

• 通过拖放添加插槽内容
• 配置插槽特定属性
• 在指定插槽内嵌套组件
• 创建复杂的组件层次结构

库比较

了解 VTJ 内置组件库之间的差异有助于开发者为其用例选择合适的库。

功能比较

Feature	Element Plus	Ant Design Vue	Vant
目标平台	Desktop Web	Desktop Web	Mobile H5
设计系统	Material-inspired	Enterprise-focused	Mobile-first
组件数量	60+	60+	70+
Tree Shaking	Full support	Full support	Full support
TypeScript 支持	Native	Native	Native
Composition API	First-class	First-class	First-class
触摸优化	Limited	Limited	Full
包体积	~500KB gzipped	~600KB gzipped	~400KB gzipped

组件对等性

虽然所有三个库都提供了全面的组件集，但某些组件是特定于库的：

Component Type	Element Plus	Ant Design Vue	Vant
Button	✓	✓	✓
Table	✓ (with virtual scroll)	✓	✗
Form	✓	✓	✓ (mobile optimized)
DatePicker	✓	✓	✓ (mobile picker style)
Upload	✓	✓	✓ (mobile optimized)
Tree	✓	✓	✗
SwipeCell	✗	✗	✓
PullRefresh	✗	✗	✓
FloatingPanel	✗	✗	✓
QRCode	✗	✓	✗
Comment	✗	✓	✗

VTJ 允许在同一项目中混合使用组件库。你可以在桌面视图中使用 Element Plus，在移动视图中使用 Vant，渲染器会根据平台上下文自动处理组件解析。

集成和使用

使用 VTJ 的内置组件库需要最少的配置。这些库在导入时会自动注册到引擎。

基本集成

import { createApp } from "vue";
import { Engine } from "@vtj/engine";
import { ElementMaterials } from "@vtj/materials";

const app = createApp();

const engine = new Engine({
  materials: ElementMaterials,
});

app.use(engine);

多库集成

import { ElementMaterials } from "@vtj/materials/element";
import { AntdVMaterials } from "@vtj/materials/antdv";
import { VantMaterials } from "@vtj/materials/vant";

const engine = new Engine({
  materials: [...ElementMaterials, ...AntdVMaterials, ...VantMaterials],
});

适配器配置

UI 包提供了一个适配器系统，用于注册自定义组件和扩展库功能。

import { AdapterPlugin } from "@vtj/ui";

app.use(AdapterPlugin, {
  components: [
    // 自定义组件注册
    MyCustomComponent,
  ],
  uploader: async (file: File) => {
    // 自定义上传处理程序
    const formData = new FormData();
    formData.append("file", file);
    const response = await uploadApi(formData);
    return response.data;
  },
});

构建系统

VTJ 的构建系统将每个组件库编译为单独的分发包，以实现最佳的 tree-shaking 和模块化使用。

构建目标

每个库都有自己的构建配置，在 package.json 脚本中定义：

• build:element: 编译 Element Plus 物料
• build:antdv: 编译 Ant Design Vue 物料
• build:vant: 编译 Vant 物料
• build:ui: 编译 VTJ 的自定义 UI 组件

构建输出结构

dist/
├── element/
│   ├── index.js
│   ├── index.d.ts
│   └── styles.css
├── antdv/
│   ├── index.js
│   ├── index.d.ts
│   └── styles.css
├── vant/
│   ├── index.js
│   ├── index.d.ts
│   └── styles.css
└── ui/
    ├── index.js
    ├── index.d.ts
    └── styles.css

Tree Shaking 优势

单独的构建输出实现：

• 最小包体积：仅导入所需的组件库
• 快速加载：减少初始下载大小
• 选择性更新：独立更新单个库
• 平台优化：对于仅桌面应用程序排除移动库

自定义组件扩展

虽然 VTJ 提供了全面的内置组件库，但物料系统支持通过自定义组件无缝扩展。自定义组件遵循与内置组件相同的 MaterialDescription 模式。

自定义组件定义

import type { MaterialDescription } from "@vtj/core";

const MyButton: MaterialDescription = {
  name: "MyButton",
  label: "我的按钮",
  categoryId: "base",
  props: [
    {
      name: "text",
      title: "按钮文字",
      defaultValue: "Click me",
      setters: "StringSetter",
    },
    {
      name: "variant",
      title: "变体",
      defaultValue: "primary",
      setters: "SelectSetter",
      options: ["primary", "secondary", "danger"],
    },
  ],
  events: ["click"],
  slots: ["default"],
  snippet: {
    name: "MyButton",
    props: {
      text: "Click me",
    },
  },
};

export default MyButton;

注册自定义组件

import { Engine } from "@vtj/engine";
import myButton from "./materials/my-button";

const engine = new Engine({
  materials: [
    myButton,
    // ... 其他自定义物料
  ],
});

最佳实践

在使用 VTJ 的内置组件库时，遵循这些实践可确保最佳的开发体验和应用程序性能。

库选择

• 桌面应用程序：使用 Element Plus 构建 Material Design 风格的界面
• 管理系统：使用 Ant Design Vue 获取企业级组件
• 移动端 H5：使用 Vant 获取针对触摸优化的移动界面
• 混合平台：根据组件需求战略性地组合库

性能优化

• 仅导入所需的组件库以最小化包体积
• 使用 tree-shaking 排除未使用的组件
• 对复杂组件（如表格和树）利用懒加载
• 对于使用 ElTreeV2 和 ElVirtualizedTable 的大数据集，考虑使用虚拟滚动

组件一致性

• 在自定义组件中保持一致的属性命名
• 遵循特定于库的约定（例如，Element Plus 的 El 前缀）
• 为属性使用适当的 setter 类型
• 提供有意义的 snippet 模板以便快速开始

文档集成

每个物料都包含一个链接到官方组件文档的 doc 属性。使用这些引用来：

• 了解组件行为和限制
• 探索高级组件功能
• 排查组件特定问题
• 从原始库文档中学习最佳实践

后续步骤

了解 VTJ 的内置组件库后，探索这些相关主题：

• 创建自定义物料组件 →：学习如何按照物料描述模式使用你自己的自定义组件扩展 VTJ
• 物料模式配置 →：深入了解物料定义可用的高级配置选项
• 集成第三方库 →：发现如何集成除 Element Plus、Ant Design Vue 和 Vant 之外的其他 Vue 组件库
• 渲染器系统和运行时 →：了解物料如何通过 VTJ 的渲染器架构在运行时渲染

内置组件库为低代码开发提供了坚实的基础，但 VTJ 的真正威力在于其可扩展性。通过掌握物料系统架构，你可以与任何 Vue 3 组件库创建无缝集成。

参考资料

• 开源代码仓库：gitee.com/newgateway/…