HTML to UniApp 转换工具

一个用于将 HTML 页面转换为 UniApp Vue 页面自动化工具，支持自动处理兼容性问题、生成页面配置和索引页面。

📋 目录

• 功能特性
• 快速开始
• 使用方法
• 转换规则
• 兼容性处理
• 项目结构
• 配置选项

✨ 功能特性

🎯 核心功能

• ✅ HTML 到 Vue 转换 - 自动将 HTML 文件转换为 UniApp Vue 单文件组件
• ✅ 标签映射 - 自动转换 HTML 标签为 UniApp 组件（div→view, span→text 等）
• ✅ Script 提取 - 提取并转换 Vue 3 Composition API 代码为 <script setup> 语法
• ✅ 样式提取 - 提取并保留 CSS 样式
• ✅ pages.json 生成 - 自动生成 UniApp 页面配置文件
• ✅ 索引页面生成 - 自动创建美观的页面索引（pages.vue）

🔄 自动转换

1. 标签转换

• <a> → <text> + @click="$wemt.router.go(path)"
• <button> → <view> + text-center + hover-class="none"
• <i> → <text>
• <img> → <image>
• 自动移除 .html 扩展名

2. Tailwind CSS 处理

• space-y-* → 自动为子元素添加 mb-*（最后一个除外）
• space-x-* → 自动为子元素添加 mr-*（最后一个除外）
• 保留所有伪类前缀 - hover:, focus:, active: 等

3. 生命周期转换

• onMounted → onLoad
• onUnmounted → onUnload
• onActivated → onShow
• onDeactivated → onHide

4. 兼容性自动处理

• window.scrollTo → uni.pageScrollTo()
• URLSearchParams → onLoad(options) 参数
• localStorage → uni.setStorageSync/getStorageSync
• style 操作 → 自动删除并添加警告
• window/document 对象 → 添加警告注释

🚀 快速开始

安装依赖

cd tools/converter
npm install

编译项目

npm run build

运行转换

# 基本用法
node dist/cli.js --input ../html --output ../vue

# 或使用 npm script
npm run convert

📖 使用方法

命令行选项

html-to-uniapp [options]

选项：
  -i, --input <path>    输入目录（包含 HTML 文件）
  -o, --output <path>   输出目录（生成 Vue 文件）
  -c, --config <path>   配置文件路径
  -h, --help            显示帮助信息
  -V, --version         显示版本信息

使用示例

# 使用默认配置
node dist/cli.js

# 指定输入输出目录
node dist/cli.js --input ./html --output ./pages

# 使用自定义配置文件
node dist/cli.js --config ./converter.config.json

# 组合使用
node dist/cli.js -i ./html -o ./pages -c ./config.json

🔧 转换规则

HTML 标签映射

| HTML 标签 | UniApp 组件 | 额外处理 | | ----------- | ----------- | ------------------------------------------ | | <div> | <view> | - | | <span> | <text> | - | | <a> | <text> | 添加 @click="$wemt.router.go(path)" | | <button> | <view> | 添加 text-center 和 hover-class="none" | | <i> | <text> | - | | <img> | <image> | - | | <header> | <view> | - | | <footer> | <view> | - | | <section> | <view> | - |

链接转换示例

<!-- 转换前 -->
<a href="../workbench/merchant.html">返回</a>

<!-- 转换后 -->
<text @click="$wemt.router.go('../workbench/merchant')">返回</text>

按钮转换示例

<!-- 转换前 -->
<button type="submit">提交</button>

<!-- 转换后 -->
<view class="text-center" hover-class="none">提交</view>

Space-y/x 转换示例

<!-- 转换前 -->
<div class="flex-1 p-4 space-y-6">
  <div>项目 1</div>
  <div>项目 2</div>
  <div>项目 3</div>
</div>

<!-- 转换后 -->
<view class="flex-1 p-4">
  <view class="mb-6">项目 1</view>
  <view class="mb-6">项目 2</view>
  <view>项目 3</view>
  <!-- 最后一个不添加 margin -->
</view>

🛠️ 兼容性处理

1. window.scrollTo 自动转换

// 转换前
window.scrollTo(0, 100);
window.scrollTo(0, document.body.scrollHeight);

// 转换后
uni.pageScrollTo({ scrollTop: 100, duration: 0 });
uni.pageScrollTo({ scrollTop: 999999, duration: 0 });

2. URLSearchParams 自动转换

// 转换前
const params = new URLSearchParams(window.location.search);
const id = params.get("id");
const role = params.get("role") || "merchant";

// 转换后（URLSearchParams 代码被删除）
onLoad((options) => {
  const id = options.id;
  const role = options.role || "merchant";
});

3. localStorage 自动转换

// 转换前
localStorage.setItem("user", "test");
const user = localStorage.getItem("user");
localStorage.removeItem("user");
localStorage.clear();

// 转换后
uni.setStorageSync("user", "test");
const user = uni.getStorageSync("user");
uni.removeStorageSync("user");
uni.clearStorageSync();

4. style 操作自动删除

// 转换前
element.style.height = "auto";
element.style.color = "red";

// 转换后（代码被删除，添加警告注释）
// ⚠️ WARNING: 直接操作 style 在 UniApp 中不推荐，已删除相关代码，请使用数据绑定和动态 class

警告注释说明

转换后的代码会包含以下类型的警告注释：

// ⚠️ CONVERTED: window.scrollTo 已自动转换为 uni.pageScrollTo
// ⚠️ WARNING: URLSearchParams 不可用，已自动转换为使用 onLoad(options) 获取页面参数
// ⚠️ CONVERTED: localStorage 已自动转换为 uni.storage API
// ⚠️ WARNING: 直接操作 style 在 UniApp 中不推荐，已删除相关代码，请使用数据绑定和动态 class
// ⚠️ WARNING: window 对象在 UniApp 中不可用，请使用 uni API 替代
// ⚠️ WARNING: document 对象在 UniApp 中不可用

📁 项目结构

tools/
├── converter/              # 转换工具主目录
│   ├── src/               # 源代码
│   │   ├── cli/          # 命令行接口
│   │   ├── config/       # 配置管理
│   │   ├── converter/    # 核心转换器
│   │   ├── extractor/    # Script/Style 提取器
│   │   ├── generator/    # pages.json 生成器
│   │   ├── mapper/       # 标签映射器
│   │   ├── parser/       # HTML 解析器
│   │   ├── processor/    # 属性处理器
│   │   ├── scanner/      # 文件扫描器
│   │   ├── writer/       # Vue 文件写入器
│   │   └── types/        # TypeScript 类型定义
│   ├── tests/            # 测试文件
│   │   ├── config/       # 配置管理测试
│   │   ├── converter/    # 核心转换器测试
│   │   ├── extractor/    # 提取器测试
│   │   ├── generator/    # 生成器测试
│   │   ├── mapper/       # 映射器测试
│   │   ├── parser/       # 解析器测试
│   │   ├── processor/    # 处理器测试
│   │   ├── scanner/      # 扫描器测试
│   │   ├── writer/       # 写入器测试
│   │   └── integration.test.ts  # 集成测试
│   ├── dist/             # 编译输出
│   ├── coverage/         # 测试覆盖率报告
│   ├── package.json      # 项目配置
│   └── README.md         # 本文档
├── html/                  # 输入：HTML 文件
├── vue/                   # 输出：Vue 文件
│   ├── pages.vue         # 自动生成的索引页面
│   └── pages.json        # 自动生成的页面配置
└── README.md             # 本文档

⚙️ 配置选项

默认配置

{
  inputDir: './tools/html',
  outputDir: './src/pages',
  tagMapping: {
    'div': 'view',
    'span': 'text',
    'a': 'text',
    'img': 'image',
    'button': 'view',
    'i': 'text',
    // ... 更多映射
  },
  removeAttributes: [
    'onclick',
    'onload',
    'autofocus',
    // ... 更多属性
  ],
  pagesJsonPath: './src/pages.json'
}

自定义配置

创建 converter.config.json 文件：

{
  "inputDir": "./my-html",
  "outputDir": "./my-pages",
  "tagMapping": {
    "custom-tag": "view"
  },
  "pagesJsonPath": "./custom-pages.json"
}

📊 生成的文件

1. Vue 组件文件

每个 HTML 文件会生成对应的 .vue 文件：

<template>
  <view class="container">
    <!-- 转换后的模板 -->
  </view>
</template>

<script setup lang="ts">
// 转换后的脚本
import { ref } from "vue";
import { onLoad } from "@dcloudio/uni-app";
</script>

<style scoped>
/* 提取的样式 */
</style>

2. pages.json

自动生成的页面配置文件：

{
  "pages": [
    {
      "path": "pages",
      "style": {
        "navigationBarTitleText": "页面索引"
      }
    },
    {
      "path": "internal/exchange/add",
      "style": {
        "navigationBarTitleText": "发起交互"
      }
    }
  ],
  "globalStyle": {}
}

3. pages.vue

自动生成的索引页面，列出所有转换后的页面：

• 渐变色头部，显示总页面数
• 卡片式列表，每个页面一个卡片
• 显示页面标题和路径
• 点击跳转到对应页面
• 响应式设计，适配不同屏幕

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📧 联系方式

如有问题或建议，请通过以下方式联系：

• 提交 Issue
• 发送邮件至：[email protected]