# webf-app-template

**Repository Path**: nosison/webf-app-template

## Basic Information

- **Project Name**: webf-app-template
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# webf-app-template

> Flutter + webf + Vue3 跨平台应用模板

## 架构

```
┌─────────────────────────────────────┐
│           Vue3 前端 (web/)           │
│   Naive UI · Pinia · vue-router      │
│   i18n · VueUse · Vite              │
└──────────────┬──────────────────────┘
               │  webf methodChannel
               │  (JS ↔ Flutter Bridge)
┌──────────────▼──────────────────────┐
│           webf Widget               │
│   (WebKit/Blink 内核嵌入 Flutter)    │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│         Flutter 原生层               │
│  file_picker · path_provider        │
│  window_manager · system_info2      │
│  flutter_clipboard_manager          │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│      原生系统 (iOS/Android/Desktop)   │
└─────────────────────────────────────┘
```

## 快速开始

### 前置依赖

- Flutter SDK ≥ 3.22
- Node.js ≥ 18
- Dart SDK ≥ 3.0

### 安装依赖

```bash
# Flutter 依赖
flutter pub get

# 前端依赖
cd web && npm install
```

### 开发模式

#### 方式一：纯浏览器开发（最快）

```bash
cd web
npm run dev
# 访问 http://localhost:5173
# Bridge 调用使用 Mock 数据，方便调试 UI
```

#### 方式二：WebF Go 工具预览

```bash
# 安装 webf_cli
dart pub global activate webf_cli

# 启动前端 dev server
cd web && npm run dev

# 在另一个终端，用 WebF Go 打开
webf run -u http://localhost:5173
```

#### 方式三：完整 Flutter 运行

```bash
# 1. 构建前端
cd web && npm run build

# 2. 运行 Flutter（桌面）
cd .. && flutter run -d macos  # 或 windows / linux

# 3. 运行 Flutter（移动端）
flutter run -d android
flutter run -d ios
```

## Bridge API

| 方法 | JS 调用 | Flutter 实现 | 返回值 |
|------|---------|-------------|--------|
| `Bridge.getSystemInfo()` | `system.info` | `SystemBridge.getInfo` | `SystemInfo` |
| `Bridge.openFile(filter?)` | `file.open` | `FileBridge.openFile` | `FileResult \| null` |
| `Bridge.saveFile(content, name)` | `file.save` | `FileBridge.saveFile` | `SaveResult` |
| `Bridge.writeClipboard(text)` | `clipboard.write` | `ClipboardBridge.write` | `boolean` |
| `Bridge.readClipboard()` | `clipboard.read` | `ClipboardBridge.read` | `string` |

### 在 JS 中调用 Bridge

```typescript
import { Bridge } from '@/bridge'

// 获取系统信息
const info = await Bridge.getSystemInfo()
console.log(info.platform, info.totalMemoryMB)

// 打开文件
const file = await Bridge.openFile('.txt,.md')
if (file) console.log(file.name, file.content)

// 剪贴板
await Bridge.writeClipboard('Hello WebF!')
const text = await Bridge.readClipboard()
```

### 添加自定义 Bridge

**1. Dart 端（`lib/bridge/`）：**

```dart
class MyBridge {
  static Future<dynamic> doSomething(dynamic params) async {
    // 调用 Flutter/系统 API
    return {'result': 'ok'};
  }
}
```

**2. 注册（`lib/bridge/bridge_registry.dart`）：**

```dart
WebFJavaScriptChannel.setMethodCallHandler('my.action', MyBridge.doSomething);
```

**3. JS 端（`web/src/bridge/index.ts`）：**

```typescript
export const Bridge = {
  // ...已有方法
  doSomething: () => invoke<{result: string}>('my.action'),
}
```

## 构建流程

```bash
# 完整构建流程
cd web && npm run build   # 前端构建到 ../web/dist/
cd .. && flutter build macos   # 打包桌面应用（含前端 assets）

# 其他平台
flutter build apk         # Android
flutter build ios         # iOS
flutter build windows     # Windows
flutter build linux       # Linux
```

## 目录结构

```
webf-app-template/
├── pubspec.yaml              # Flutter 依赖
├── lib/
│   ├── main.dart             # 入口
│   ├── app.dart              # MaterialApp
│   ├── webf_shell.dart       # WebF widget
│   ├── bridge/
│   │   ├── bridge_registry.dart
│   │   ├── system_bridge.dart
│   │   ├── file_bridge.dart
│   │   └── clipboard_bridge.dart
│   └── services/
│       └── window_service.dart
└── web/                      # Vue3 + Vite 前端
    ├── package.json
    ├── vite.config.ts
    ├── src/
    │   ├── bridge/index.ts   # Bridge 封装 + Mock
    │   ├── layouts/DefaultLayout.vue
    │   ├── views/
    │   │   ├── HomeView.vue
    │   │   ├── FileView.vue
    │   │   ├── SystemView.vue
    │   │   └── AboutView.vue
    │   ├── stores/app.ts
    │   ├── router/index.ts
    │   └── i18n/             # zh + en
    └── dist/                 # 构建输出（Flutter assets）
```

## 与 electron-web-template 对比

| 特性 | electron-web-template | webf-app-template |
|------|----------------------|-------------------|
| 底层运行时 | Electron (Node.js + Chromium) | Flutter + webf |
| 移动端支持 | ❌ 仅桌面 | ✅ iOS / Android / Desktop |
| 包体积 | ~150 MB | ~30-50 MB |
| 原生性能 | 中等（JS 进程间通信） | 高（Flutter 原生渲染） |
| npm 生态 | ✅ 完整 | ✅ 完整（webf 支持） |
| Vue3 支持 | ✅ | ✅ |
| 热更新 | 需 electron-updater | ✅ 支持 OTA（仅更新 web/) |
| 系统托盘 | ✅ | ⚠ 需要自定义 |
| IPC 通信 | contextBridge | WebFJavaScriptChannel |
| 调试工具 | Electron DevTools | Chrome DevTools + WebF |

## 参考资源

- [webf 官方仓库](https://github.com/openwebf/webf)
- [Flutter 文档](https://docs.flutter.dev)
- [Vue3 文档](https://vuejs.org)
- [Naive UI](https://www.naiveui.com)