511 lines
12 KiB
Markdown
511 lines
12 KiB
Markdown
# MeshRay 原生前端开发指南
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
web/
|
||
├── static/
|
||
│ ├── index.html # 主页面（Vue 应用入口）
|
||
│ └── js/
|
||
│ └── app.js # Vue 应用逻辑
|
||
└── embed.go # Go embed 配置
|
||
```
|
||
|
||
---
|
||
|
||
## 📦 技术栈
|
||
|
||
- **Vue 3.4** - 渐进式 JavaScript 框架
|
||
- **Element Plus** - Vue 3 组件库
|
||
- **Tailwind CSS** - 实用优先的 CSS 框架
|
||
- **CDN 加载** - 无需本地安装依赖
|
||
|
||
---
|
||
|
||
## 🎨 开发示例
|
||
|
||
### 1. 添加新页面
|
||
|
||
#### 步骤 1: 在 HTML 中添加页面内容
|
||
|
||
```html
|
||
<!-- 在 index.html 的主内容区添加 -->
|
||
<div v-if="currentPage === 'devices'">
|
||
<h2 class="text-2xl font-bold mb-6">设备管理</h2>
|
||
|
||
<div class="card p-6">
|
||
<el-button type="primary" @click="showCreateDevice = true">
|
||
<el-icon><Plus /></el-icon>
|
||
添加设备
|
||
</el-button>
|
||
|
||
<el-table :data="devices" style="width: 100%; margin-top: 20px;">
|
||
<el-table-column prop="name" label="名称"></el-table-column>
|
||
<el-table-column prop="ip" label="IP 地址"></el-table-column>
|
||
<el-table-column label="操作">
|
||
<template #default="{ row }">
|
||
<el-button size="small" @click="editDevice(row)">编辑</el-button>
|
||
<el-button size="small" type="danger" @click="deleteDevice(row)">删除</el-button>
|
||
</template>
|
||
</el-table-column>
|
||
</el-table>
|
||
</div>
|
||
</div>
|
||
```
|
||
|
||
#### 步骤 2: 在 JS 中添加数据和逻辑
|
||
|
||
```javascript
|
||
// app.js
|
||
const devices = ref([]);
|
||
const showCreateDevice = ref(false);
|
||
|
||
const loadDevices = async () => {
|
||
const response = await fetch(`${API_BASE}/devices`);
|
||
const result = await response.json();
|
||
devices.value = result.data || [];
|
||
};
|
||
|
||
const editDevice = (device) => {
|
||
ElementPlus.ElMessageBox.alert(`编辑设备：${device.name}`);
|
||
};
|
||
|
||
const deleteDevice = async (device) => {
|
||
await ElementPlus.ElMessageBox.confirm('确定删除？', '警告', { type: 'warning' });
|
||
const response = await fetch(`${API_BASE}/devices/${device.id}`, { method: 'DELETE' });
|
||
if (response.ok) {
|
||
ElementPlus.ElMessage.success('删除成功');
|
||
await loadDevices();
|
||
}
|
||
};
|
||
|
||
onMounted(() => {
|
||
loadDevices();
|
||
});
|
||
|
||
return { currentPage, devices, showCreateDevice, loadDevices, editDevice, deleteDevice };
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 调用 API
|
||
|
||
#### GET 请求
|
||
|
||
```javascript
|
||
const loadStats = async () => {
|
||
try {
|
||
const response = await fetch('/api/v1/dashboard/stats');
|
||
const result = await response.json();
|
||
|
||
if (response.ok && result.data) {
|
||
stats.networkCount = result.data.network_count;
|
||
stats.deviceCount = result.data.device_count;
|
||
}
|
||
} catch (error) {
|
||
console.error('加载失败:', error);
|
||
ElementPlus.ElMessage.error('加载数据失败');
|
||
}
|
||
};
|
||
```
|
||
|
||
#### POST 请求
|
||
|
||
```javascript
|
||
const createNetwork = async () => {
|
||
try {
|
||
const response = await fetch('/api/v1/networks', {
|
||
method: 'POST',
|
||
headers: { 'Content-Type': 'application/json' },
|
||
body: JSON.stringify({
|
||
name: newNetwork.name,
|
||
subnet_ipv4: newNetwork.subnet_ipv4,
|
||
listen_port: newNetwork.listen_port,
|
||
mesh_mode: newNetwork.mesh_mode
|
||
})
|
||
});
|
||
|
||
const result = await response.json();
|
||
|
||
if (response.ok) {
|
||
ElementPlus.ElMessage.success('创建成功');
|
||
showCreateNetworkDialog.value = false;
|
||
await loadNetworks();
|
||
} else {
|
||
ElementPlus.ElMessage.error(result.error || '创建失败');
|
||
}
|
||
} catch (error) {
|
||
ElementPlus.ElMessage.error('创建失败');
|
||
}
|
||
};
|
||
```
|
||
|
||
#### DELETE 请求
|
||
|
||
```javascript
|
||
const deleteNetwork = async (network) => {
|
||
try {
|
||
await ElementPlus.ElMessageBox.confirm(
|
||
`确定删除 "${network.name}"？`,
|
||
'警告',
|
||
{ type: 'warning', confirmButtonText: '删除', cancelButtonText: '取消' }
|
||
);
|
||
|
||
const response = await fetch(`/api/v1/networks/${network.id}`, { method: 'DELETE' });
|
||
|
||
if (response.ok) {
|
||
ElementPlus.ElMessage.success('删除成功');
|
||
await loadNetworks();
|
||
} else {
|
||
const result = await response.json();
|
||
ElementPlus.ElMessage.error(result.error);
|
||
}
|
||
} catch (error) {
|
||
if (error !== 'cancel') {
|
||
ElementPlus.ElMessage.error('删除失败');
|
||
}
|
||
}
|
||
};
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 使用 Element Plus 组件
|
||
|
||
#### 对话框 (Dialog)
|
||
|
||
```html
|
||
<el-dialog v-model="showDialog" title="标题" width="500px">
|
||
<el-form :model="formData" label-width="100px">
|
||
<el-form-item label="名称">
|
||
<el-input v-model="formData.name" placeholder="请输入名称"></el-input>
|
||
</el-form-item>
|
||
</el-form>
|
||
<template #footer>
|
||
<el-button @click="showDialog = false">取消</el-button>
|
||
<el-button type="primary" @click="handleSubmit">确定</el-button>
|
||
</template>
|
||
</el-dialog>
|
||
```
|
||
|
||
#### 消息提示
|
||
|
||
```javascript
|
||
// 成功消息
|
||
ElementPlus.ElMessage.success('操作成功');
|
||
|
||
// 错误消息
|
||
ElementPlus.ElMessage.error('操作失败');
|
||
|
||
// 警告消息
|
||
ElementPlus.ElMessage.warning('请注意');
|
||
|
||
// 确认对话框
|
||
await ElementPlus.ElMessageBox.confirm('确定执行？', '提示', {
|
||
confirmButtonText: '确定',
|
||
cancelButtonText: '取消',
|
||
type: 'warning'
|
||
});
|
||
|
||
// 提示框
|
||
ElementPlus.ElMessageBox.alert('这是一段提示信息', '标题', {
|
||
confirmButtonText: '确定'
|
||
});
|
||
```
|
||
|
||
#### 表格 (Table)
|
||
|
||
```html
|
||
<el-table :data="items" style="width: 100%">
|
||
<el-table-column prop="id" label="ID" width="80"></el-table-column>
|
||
<el-table-column prop="name" label="名称"></el-table-column>
|
||
<el-table-column prop="status" label="状态">
|
||
<template #default="{ row }">
|
||
<el-tag :type="row.status === 'active' ? 'success' : 'danger'">
|
||
{{ row.status === 'active' ? '运行中' : '已停止' }}
|
||
</el-tag>
|
||
</template>
|
||
</el-table-column>
|
||
<el-table-column label="操作" width="200">
|
||
<template #default="{ row }">
|
||
<el-button size="small" @click="view(row)">查看</el-button>
|
||
<el-button size="small" type="primary" @click="edit(row)">编辑</el-button>
|
||
</template>
|
||
</el-table-column>
|
||
</el-table>
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 使用 Tailwind CSS
|
||
|
||
#### 布局
|
||
|
||
```html
|
||
<!-- Flexbox 布局 -->
|
||
<div class="flex items-center justify-between">
|
||
<div>左侧内容</div>
|
||
<div>右侧内容</div>
|
||
</div>
|
||
|
||
<!-- Grid 布局 -->
|
||
<div class="grid grid-cols-3 gap-4">
|
||
<div>列 1</div>
|
||
<div>列 2</div>
|
||
<div>列 3</div>
|
||
</div>
|
||
```
|
||
|
||
#### 间距
|
||
|
||
```html
|
||
<!-- 外边距 -->
|
||
<div class="m-4">上下左右 1rem</div>
|
||
<div class="mt-2">上边距 0.5rem</div>
|
||
<div class="mb-4">下边距 1rem</div>
|
||
<div class="mx-auto">水平居中</div>
|
||
|
||
<!-- 内边距 -->
|
||
<div class="p-4">上下左右 1rem</div>
|
||
<div class="px-6">左右 1.5rem</div>
|
||
<div class="py-2">上下 0.5rem</div>
|
||
```
|
||
|
||
#### 颜色
|
||
|
||
```html
|
||
<div class="bg-blue-500 text-white">蓝色背景白字</div>
|
||
<div class="bg-green-100 text-green-800">浅绿背景深绿字</div>
|
||
<div class="hover:bg-red-500">悬停变红</div>
|
||
```
|
||
|
||
#### 响应式
|
||
|
||
```html
|
||
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4">
|
||
<!-- 手机 1 列，平板 2 列，桌面 4 列 -->
|
||
</div>
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 常用工具函数
|
||
|
||
### 格式化日期
|
||
|
||
```javascript
|
||
const formatDate = (dateString) => {
|
||
return new Date(dateString).toLocaleString('zh-CN', {
|
||
year: 'numeric',
|
||
month: '2-digit',
|
||
day: '2-digit',
|
||
hour: '2-digit',
|
||
minute: '2-digit'
|
||
});
|
||
};
|
||
|
||
// 使用
|
||
{{ formatDate(network.created_at) }}
|
||
```
|
||
|
||
### 复制文本
|
||
|
||
```javascript
|
||
const copyToClipboard = async (text) => {
|
||
try {
|
||
await navigator.clipboard.writeText(text);
|
||
ElementPlus.ElMessage.success('已复制到剪贴板');
|
||
} catch (error) {
|
||
ElementPlus.ElMessage.error('复制失败');
|
||
}
|
||
};
|
||
```
|
||
|
||
### 下载文件
|
||
|
||
```javascript
|
||
const downloadFile = (content, filename, mimeType = 'text/plain') => {
|
||
const blob = new Blob([content], { type: mimeType });
|
||
const url = URL.createObjectURL(blob);
|
||
const link = document.createElement('a');
|
||
link.href = url;
|
||
link.download = filename;
|
||
link.click();
|
||
URL.revokeObjectURL(url);
|
||
};
|
||
|
||
// 使用：下载 WireGuard 配置
|
||
downloadFile(configText, 'wg0.conf', 'text/plain');
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 完整页面模板
|
||
|
||
```html
|
||
<!DOCTYPE html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>页面标题</title>
|
||
<script src="https://cdn.tailwindcss.com"></script>
|
||
<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
|
||
<link rel="stylesheet" href="https://unpkg.com/element-plus/dist/index.css">
|
||
<script src="https://unpkg.com/element-plus"></script>
|
||
<script src="https://unpkg.com/@element-plus/icons-vue"></script>
|
||
</head>
|
||
<body>
|
||
<div id="app">
|
||
<h1 class="text-3xl font-bold">{{ title }}</h1>
|
||
<button class="bg-blue-500 text-white px-4 py-2 rounded" @click="handleClick">
|
||
点击我
|
||
</button>
|
||
</div>
|
||
|
||
<script>
|
||
const { createApp, ref } = Vue;
|
||
|
||
createApp({
|
||
setup() {
|
||
const title = ref('我的页面');
|
||
|
||
const handleClick = () => {
|
||
ElementPlus.ElMessage.success('按钮被点击了');
|
||
};
|
||
|
||
return { title, handleClick };
|
||
}
|
||
}).use(ElementPlus).mount('#app');
|
||
</script>
|
||
</body>
|
||
</html>
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 最佳实践
|
||
|
||
### 1. 代码组织
|
||
|
||
```javascript
|
||
// app.js
|
||
const API_BASE = '/api/v1';
|
||
|
||
// 按功能模块组织代码
|
||
const dashboardModule = {
|
||
stats: reactive({...}),
|
||
loadStats: async () => {...}
|
||
};
|
||
|
||
const networkModule = {
|
||
networks: ref([]),
|
||
createNetwork: async () => {...},
|
||
deleteNetwork: async (network) => {...}
|
||
};
|
||
|
||
// 统一导出
|
||
return {
|
||
...dashboardModule,
|
||
...networkModule
|
||
};
|
||
```
|
||
|
||
### 2. 错误处理
|
||
|
||
```javascript
|
||
try {
|
||
const response = await fetch(url);
|
||
if (!response.ok) throw new Error('网络错误');
|
||
const result = await response.json();
|
||
// 处理结果
|
||
} catch (error) {
|
||
console.error('详细错误:', error);
|
||
ElementPlus.ElMessage.error('操作失败：' + error.message);
|
||
}
|
||
```
|
||
|
||
### 3. Loading 状态
|
||
|
||
```javascript
|
||
const loading = ref(false);
|
||
|
||
const loadData = async () => {
|
||
loading.value = true;
|
||
try {
|
||
// API 调用
|
||
} finally {
|
||
loading.value = false;
|
||
}
|
||
};
|
||
|
||
// UI 显示
|
||
<el-button :loading="loading">加载数据</el-button>
|
||
```
|
||
|
||
---
|
||
|
||
## 🐛 调试技巧
|
||
|
||
### 控制台日志
|
||
|
||
```javascript
|
||
console.log('当前状态:', stats);
|
||
console.error('发生错误:', error);
|
||
console.warn('警告信息:', warning);
|
||
```
|
||
|
||
### Vue DevTools
|
||
|
||
安装 [Vue DevTools](https://devtools.vuejs.org/) 浏览器扩展：
|
||
- 查看组件树
|
||
- 检查响应式数据
|
||
- 调试事件
|
||
|
||
### Network 面板
|
||
|
||
浏览器开发者工具 → Network：
|
||
- 查看 API 请求
|
||
- 检查请求参数
|
||
- 分析响应数据
|
||
|
||
---
|
||
|
||
## 📞 常见问题
|
||
|
||
### Q: 如何添加新的 CDN 资源？
|
||
|
||
A: 在 `<head>` 标签中添加：
|
||
|
||
```html
|
||
<script src="https://unpkg.com/axios/dist/axios.min.js"></script>
|
||
```
|
||
|
||
### Q: 如何使用自定义样式？
|
||
|
||
A: 在 `<style>` 标签中添加：
|
||
|
||
```html
|
||
<style>
|
||
.custom-class {
|
||
color: red;
|
||
}
|
||
</style>
|
||
```
|
||
|
||
### Q: 如何访问后端 API？
|
||
|
||
A: 使用相对路径，Gin 会自动代理：
|
||
|
||
```javascript
|
||
fetch('/api/v1/networks') // ✅ 正确
|
||
fetch('http://localhost:8080/api/v1/networks') // ❌ 错误
|
||
```
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-03-20
|
||
**适用版本**: MeshRay 2.0+
|