AI 驱动的 Vue3 应用开发平台 入门指南（五）：创建 H5 移动应用

创建 H5 移动应用

本指南将引导你使用 VTJ 低代码平台创建移动端友好的 H5 应用程序。H5 应用程序针对移动浏览器进行了优化，具备触摸交互、响应式布局以及 Vant 等移动端专用组件库。

H5 平台架构概览

VTJ 中的 H5 平台专为移动 Web 应用程序设计，它提供了将 Vue 3、TypeScript、Vite 和 Vant UI 组件与 VTJ 低代码引擎相结合的基础。该架构将设计时（低代码设计器）和运行时（渲染器）的关注点分离，确保了生成的代码清晰且易于维护。

flowchart TD A["CLI: npm create vtj@latest -t h5"] --> B[H5 模板生成器] B --> C[项目结构] C --> D[main.ts - Provider 设置] C --> E[vite.config.ts - 构建配置] C --> F[router/index.ts - 路由配置] D --> G["@vtj/h5 平台"] G --> H[Vant UI 组件] G --> I["@vtj/renderer"] I --> J[低代码运行时] J --> K[生成的 Vue 页面] D --> L[LocalService - 数据层] E --> M[带代理的开发服务器]

快速开始：创建你的第一个 H5 项目

分步创建项目

flowchart TD A[开始] --> B["执行 CLI 命令"] B --> C{"已选择模板？"} C -- 是 --> D[输入项目名称] C -- 否 --> E[交互式提示词] E --> F["选择 H5 模板"] F --> D D --> G{"目录已存在？"} G -- 否 --> H[创建项目结构] G -- 是 --> I[确认覆盖] I -- 是 --> H I -- 否 --> J[取消] H --> K[安装依赖] K --> L[启动开发服务器] L --> M[打开浏览器]

创建过程始于 create-vtj CLI 工具，它为项目脚手架提供了交互式界面。你可以直接指定 H5 模板，也可以使用交互式菜单从可用模板中进行选择。

安装命令

执行以下任一命令以创建新的 H5 项目：

交互模式（推荐给初学者）：

npm create vtj@latest --registry=https://registry.npmmirror.com

直接选择模板：

npm create vtj@latest --registry=https://registry.npmmirror.com -- -t h5

CLI 会提示你输入项目名称。默认名称是 vtj-project，但你应该为你的应用程序提供一个有意义的名称。然后，该工具将生成包含所有必要依赖的完整项目结构。

开发工作流

项目创建完成后，导航到你的项目目录并启动开发服务器：

cd your-project-name
npm install
npm run dev

对于生产环境构建：

npm run build:prod

开发服务器启动时带有热模块替换（HMR）和用于 API 请求的代理配置。生产环境构建通过代码分割和资源优化进行了性能优化。

项目结构与组织

生成的 H5 项目遵循标准的 Vue 3 应用程序结构，并包含 VTJ 特定的配置：

h5-project/
├── .vtj/                 
├── public/
│   └── favicon.ico      # 静态资源
├── src/
│   ├── App.vue          # 包含 ConfigProvider 的根组件
│   ├── main.ts          # 应用程序入口
│   ├── router/
│   │   └── index.ts     # Vue Router 配置
│   ├── views/
│   │   ├── page.vue     # 示例页面组件
│   │   └── not-found.vue # 404 页面
│   ├── style/
│   │   └── index.scss   # 全局样式
│   └── components/
│       └── HelloWorld.vue
├── env.json             # 环境配置
├── index.html           # 移动端优化的 HTML 模板
├── vite.config.ts       # Vite 构建配置
├── proxy.config.ts      # API 代理配置
├── package.json         # 项目依赖
└── tsconfig.json        # TypeScript 配置

H5 平台架构

核心依赖

H5 平台使用了一套针对移动开发优化的特定包：

包	版本	用途
@vtj/h5	latest	包含移动端适配器和模块的 H5 平台
@vtj/renderer	latest	低代码组件的运行时渲染器
vue	~3.5.5	核心框架
vue-router	~4.6.0	路由库
pinia	~3.0.2	状态管理
vue-i18n	~11.2.2	国际化支持
vant	bundled	移动端 UI 组件库

H5 和 Web（PC）模板之间的主要区别在于使用 @vtj/h5 而不是 @vtj/web，它提供了使用 Vant UI 组件的加载状态、通知和对话框的移动端专用适配器。

应用程序初始化

main.ts 文件使用 VTJ 的 provider 系统来设置应用程序：

const adapter = createAdapter({ loading, notify, Startup });
const service = new LocalService(createServiceRequest(notify));
const { provider, onReady } = createProvider({
  nodeEnv: process.env.NODE_ENV as NodeEnv,
  mode: ContextMode.Raw,
  modules: createModules(),
  adapter,
  service,
  router,
  dependencies: {
    Vue: () => import("vue"),
    VueRouter: () => import("vue-router"),
    Pinia: () => import("pinia"),
    VueI18n: () => import("vue-i18n"),
  },
  project: { id: name },
  enableStaticRoute: true,
});

适配器模式为以下内容提供了移动端专用实现：

• 加载状态 ：使用 Vant 的 showLoadingToast 进行视觉反馈
• 通知 ：使用 Vant 的 showNotify 进行警报和消息提示
• 对话框 ：使用 Vant 的 showDialog 进行确认操作

根组件结构

App.vue 组件使用 Vant 的 ConfigProvider 将应用程序包装在一致的主题和配置中：

<template>
  <ConfigProvider>
    <Suspense>
      <RouterView :key="route.fullPath"></RouterView>
    </Suspense>
  </ConfigProvider>
</template>

Suspense 组件启用异步组件加载，而带有 route.fullPath key 的 RouterView 确保正确的路由转换和组件重新渲染。

移动端优化配置

HTML 模板

index.html 文件包含移动端专用的 meta 标签，以便在移动设备上正确渲染：

<meta
  name="viewport"
  content="width=device-width, initial-scale=1.0, 
       maximum-scale=1.0, minimum-scale=1.0, viewport-fit=cover"
/>
<meta
  http-equiv="Cache-Control"
  content="no-cache, no-store, must-revalidate"
/>
<meta http-equiv="Pragma" content="no-cache" />
<meta http-equiv="Expires" content="0" />

这些配置确保：

• 正确的视口缩放，无缩放
• 支持刘海屏设备的安全区域
• 不缓存动态内容更新

路由配置

路由器使用基于哈希（Hash）的路由，以更好地兼容移动 Web 容器和历史记录管理：

const router = createRouter({
  history: createWebHashHistory(),
  routes: [
    {
      path: "/:pathMatch(.*)*",
      name: "NotFound",
      component: () => import("@/views/not-found.vue"),
    },
  ],
});

哈希路由是 H5 应用程序的首选，因为它不需要服务器端路由配置，并且可以在嵌入式 Web 视图中无缝工作。

模块系统

H5 平台使用动态加载低代码项目文件的模块系统：

export function createModules(mode: ContextMode = ContextMode.Runtime) {
  if (mode === ContextMode.Runtime || process.env.NODE_ENV === "development") {
    return import.meta.glob([
      "/.vtj/projects/*.json",
      "/.vtj/files/*.json",
      "/.vtj/vue/*.vue",
    ]);
  } else {
    return import.meta.glob(["/.vtj/projects/*.json", "/.vtj/vue/*.vue"]);
  }
}

在开发模式下，加载包括原始 DSL 文件在内的所有项目文件。在生产环境中，仅加载生成的 Vue 组件以进行优化。

开发工具和配置

构建配置

Vite 配置使用 @vtj/cli 的 createViteConfig 进行标准化构建设置，并包含开发工具插件：

import { createViteConfig } from "@vtj/cli";
import { createDevTools } from "@vtj/pro/vite";
import proxy from "./proxy.config";

export default createViteConfig({
  proxy,
  plugins: [createDevTools()],
});

此配置提供：

• 带有 HMR 的优化开发服务器
• 使用 vue-tsc 进行类型检查
• 特定环境的构建
• 开发期间的 API 请求代理配置

代理配置

开发期间的 API 请求被代理以避免 CORS 问题：

export default {
  "/api": {
    target: "http://localhost:3000",
    changeOrigin: true,
    ws: true,
  },
};

修改 target URL 以匹配你的后端服务器。changeOrigin 选项确保正确的 host 头部，ws: true 启用 WebSocket 支持。

提示 ：H5 平台在生产模式下使用 autoUpdate() 函数自动检查应用程序更新。这确保用户始终拥有最新版本，而无需手动刷新。

对比：H5 与 Web 模板

了解 H5 和 Web（PC）模板之间的差异有助于你选择合适的平台：

特性	H5 模板	Web (app) 模板
包	@vtj/h5	@vtj/web
UI 库	Vant（移动端优先）	Element Plus（桌面端优先）
视口	移动端优化的 meta 标签	桌面端视口设置
路由	哈希历史记录	Web History API
触摸支持	原生触摸事件	基于鼠标的交互
组件	移动端专用	桌面端专用

后续步骤

成功创建 H5 项目后，探索这些高级主题：

1. 创建 Web 应用程序 - 了解用于桌面应用程序的 PC 平台
2. 快速开始 - 熟悉 VTJ 的基本概念和工作流程
3. DSL 模式和数据模型 - 了解低代码 DSL 结构
4. 内置组件库 - 探索可用于移动 UI 的 Vant 组件