AIFF Capacitor WebView 插件

一个功能强大的 Capacitor 插件，用于在移动应用和 Web 应用中打开 WebView 窗口，特别优化了与 AIFF (Aile Frontend Framework) 的集成。

特性

• 🚀 跨平台支持: 支持 iOS、Android 和 Web 平台
• 🔗 AIFF 框架集成: 专为 Aile Frontend Framework 优化
• 📱 原生体验: 在移动设备上提供原生 WebView 体验
• 🎨 可定制化: 支持多种主题、工具栏类型和样式
• 🔒 安全通信: 安全的 JavaScript 消息传递机制
• 🧪 完整测试: 包含单元测试、集成测试和 E2E 测试
• 📖 详细文档: 完整的 API 文档和示例代码

安装

npm install aile-capacitor-aiff

iOS 平台

npx cap sync ios

Android 平台

npx cap sync android

快速开始

基本用法

import { AiffWebView } from 'aile-capacitor-aiff';

// 打开 WebView
await AiffWebView.openWebView({
  url: 'https://example.com',
  title: '示例页面',
  toolbarType: 'navigation'
});

// 关闭 WebView
await AiffWebView.closeWebView();

AIFF 框架集成

// 打开包含 AIFF 框架的页面
await AiffWebView.openWebView({
  url: 'https://your-aiff-app.com',
  title: 'AIFF 应用',
  toolbarType: 'activity'
});

// 监听来自 AIFF 框架的消息
AiffWebView.addListener('messageFromWebview', (data) => {
  console.log('收到 AIFF 消息:', data);
});

// 向 AIFF 框架发送消息
await AiffWebView.postMessage({
  detail: {
    type: 'aiff-event',
    data: { action: 'update-data' }
  }
});

API 参考

openWebView(options)

打开一个新的 WebView 窗口。

参数：

interface WebViewOptions {
  url: string;                    // 要打开的 URL
  title?: string;                 // 页面标题
  toolbarType?: ToolBarType;      // 工具栏类型
  showReloadButton?: boolean;     // 显示刷新按钮
  headers?: Record<string, string>; // 自定义请求头
  toolbarColor?: string;          // 工具栏颜色
  theme?: 'light' | 'dark' | 'auto'; // 主题
  closeModal?: boolean;           // 点击外部关闭
}

示例：

// 基础用法
await AiffWebView.openWebView({ url: 'https://example.com' });

// 完整配置
await AiffWebView.openWebView({
  url: 'https://api.example.com/dashboard',
  title: '管理面板',
  toolbarType: 'navigation',
  showReloadButton: true,
  headers: {
    'Authorization': 'Bearer your-token-here',
    'X-API-Key': 'your-api-key'
  },
  toolbarColor: '#007bff',
  theme: 'dark',
  closeModal: true
});

closeWebView()

关闭当前打开的 WebView。

await AiffWebView.closeWebView();

executeScript(options)

在 WebView 中执行 JavaScript 代码。

await AiffWebView.executeScript({
  code: 'document.body.style.backgroundColor = "lightblue";'
});

postMessage(options)

向 WebView 发送消息。

await AiffWebView.postMessage({
  detail: {
    type: 'notification',
    data: { message: 'Hello from native app!' }
  }
});

setUrl(options)

更改当前 WebView 的 URL。

await AiffWebView.setUrl({ url: 'https://new-url.com' });

reload()

重新加载当前页面。

await AiffWebView.reload();

addListener(eventName, callback)

添加事件监听器。

// 监听页面加载完成
AiffWebView.addListener('pageLoaded', (data) => {
  console.log('页面加载完成:', data);
});

// 监听 URL 变化
AiffWebView.addListener('urlChangeEvent', (data) => {
  console.log('URL 变化:', data.url);
});

// 监听来自 WebView 的消息
AiffWebView.addListener('messageFromWebview', (data) => {
  console.log('收到消息:', data);
});

// 监听关闭事件
AiffWebView.addListener('closeEvent', () => {
  console.log('WebView 已关闭');
});

AIFF 框架集成

JavaScript 注入

插件会自动在 WebView 中注入以下对象，供 AIFF 框架使用：

window.mobileApp

// 在 AIFF 应用中使用
window.mobileApp.postMessage(JSON.stringify({
  type: 'user-action',
  data: { action: 'login', userId: 123 }
}));

// 监听原生消息
window.mobileApp.onMessage = function(message) {
  const data = JSON.parse(message);
  console.log('收到原生消息:', data);
};

postMessageToJS

// 向原生应用发送消息
postMessageToJS({
  type: 'aiff-event',
  data: { 
    action: 'update-title',
    title: '新标题'
  }
});

消息格式

从 WebView 到原生应用

window.mobileApp.postMessage(JSON.stringify({
  type: 'event-type',
  data: {
    // 事件数据
  }
}));

从原生应用到 WebView

// 使用 postMessage
await AiffWebView.postMessage({
  detail: {
    type: 'native-event',
    data: { /* 数据 */ }
  }
});

// 使用 executeScript
await AiffWebView.executeScript({
  code: `
    if (window.aiffApp) {
      window.aiffApp.handleNativeMessage(${JSON.stringify(data)});
    }
  `
});

配置选项

ToolBarType

enum ToolBarType {
  DEFAULT = 'default',      // 默认工具栏
  NAVIGATION = 'navigation', // 导航工具栏（前进、后退、刷新）
  ACTIVITY = 'activity',    // 活动工具栏（标题、关闭按钮）
  BLANK = 'blank'          // 无工具栏
}

主题选项

• light: 浅色主题
• dark: 深色主题
• auto: 自动跟随系统主题

平台特定说明

iOS

• 使用 WKWebView 实现
• 支持 iOS 11.0+
• 需要在 Info.plist 中配置相关权限

Android

• 使用 WebView 实现
• 支持 Android API 21+
• 需要在 AndroidManifest.xml 中配置相关权限

Web

• 使用 iframe 模拟 WebView 行为
• 支持所有现代浏览器
• 提供与原生平台一致的 API

示例应用

查看 example/ 目录获取完整的示例应用代码。

React 示例

import React, { useEffect } from 'react';
import { AiffWebView } from 'aile-capacitor-aiff';

const WebViewExample: React.FC = () => {
  const openDashboard = async () => {
    await AiffWebView.openWebView({
      url: 'https://dashboard.example.com',
      title: '管理面板',
      toolbarType: 'navigation'
    });
  };

  useEffect(() => {
    // 监听来自 AIFF 框架的消息
    const listener = AiffWebView.addListener('messageFromWebview', (data) => {
      if (data.type === 'login-success') {
        console.log('用户登录成功:', data.user);
      }
    });

    return () => {
      listener.remove();
    };
  }, []);

  return (
    <div>
      <button onClick={openDashboard}>打开管理面板</button>
    </div>
  );
};

Vue 示例

<template>
  <div>
    <button @click="openWebView">打开 WebView</button>
    <div v-if="messages.length">
      <h3>收到的消息:</h3>
      <ul>
        <li v-for="msg in messages" :key="msg.id">{{ msg.text }}</li>
      </ul>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue';
import { AiffWebView } from 'aile-capacitor-aiff';

const messages = ref([]);
let listener: any = null;

const openWebView = async () => {
  await AiffWebView.openWebView({
    url: 'https://your-aiff-app.com',
    title: 'AIFF 应用'
  });
};

onMounted(() => {
  listener = AiffWebView.addListener('messageFromWebview', (data) => {
    messages.value.push({
      id: Date.now(),
      text: JSON.stringify(data)
    });
  });
});

onUnmounted(() => {
  if (listener) {
    listener.remove();
  }
});
</script>

开发

环境要求

• Node.js 16+
• npm 或 yarn
• Capacitor 6+

本地开发

# 克隆项目
git clone https://github.com/your-org/aile-capacitor-aiff.git
cd aile-capacitor-aiff

# 安装依赖
npm install

# 运行测试
npm run test
npm run test:e2e

# 构建项目
npm run build

测试

# 运行所有测试
npm test

# 运行单元测试
npm run test:unit

# 运行集成测试
npm run test:integration

# 运行 E2E 测试
npm run test:e2e

# 运行特定平台测试
npm run test:ios
npm run test:android
npm run test:web

贡献

欢迎提交 Issue 和 Pull Request！

开发流程

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

许可证

MIT License - 查看 LICENSE 文件了解详情。

支持

• 📧 邮箱: [email protected]
• 💬 讨论区: GitHub Discussions
• 🐛 Bug 报告: GitHub Issues

更新日志

查看 CHANGELOG.md 了解版本更新详情。