# uni-webview-framework

**Repository Path**: xueyanjun/uni-webview-framework

## Basic Information

- **Project Name**: uni-webview-framework
- **Description**: uniapp webview 功能封装框架
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2023-06-12
- **Last Updated**: 2025-10-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# 🌐 uni-webview-framework

这是一个基于 [uni-app](https://uniapp.dcloud.io/) 的 Webview 框架项目，旨在为开发者提供一套**高效、稳定、可扩展**的 Webview 操作与管理方案。该项目解决了 uni-app 原生 Webview 组件在实际使用中的诸多痛点，如生命周期不透明、消息通信不稳定、页面加载体验差等。

> **我们的目标是让开发者既能享受到 Web 环境中丰富的类库和 UI 库（如 Vant、NutUI），又能无缝调用 uni-app 提供的强大 API，实现接近原生 App 的用户体验。**

---

## 📌 背景与初衷

在我们公司内部，长期使用 **uni-app** 开发跨平台 App。然而，随着项目的规模逐渐增大，遇到了以下挑战：

- **HBuilderX 编辑器性能瓶颈**：随着项目变得越来越庞大，热更新时 HBuilderX 编辑器卡顿严重，导致开发效率低下。
- **启动问题频发**：手机端经常出现“白屏”或“一直 loading”的启动问题，严重影响了用户体验。
- **官方组件库功能有限**：官方提供的组件库功能有限，社区开源组件库（如 uView）存在较多 bug，导致开发过程不畅，频繁报错但难以定位原因。
- **Webview 功能限制**：虽然 uni-app 官方提供了 `<web-view>` 组件，但它仅支持调用部分 uni 接口（如 `navigateTo` 和 `redirectTo`），无法满足复杂业务需求。
- **

针对这些问题，我进行业务调研后发现uniapp本身能够解决多品牌版本手机的运行环境一致问题，但我司业务线项目运行环境良好，用户基本没有使用老旧手机的情况。
后续我个人开发了 **uni-webview-framework**这个项目，它不仅突破了官方 Webview 组件的功能限制，还提供了丰富的 Web 开发环境支持，极大提升了开发效率。

---

## ✨ 核心特性

### 1. **全面的 Webview 功能封装**

- **页面加载与历史管理**：简化页面加载逻辑，支持页面前进、后退等操作。
- **消息通信机制**：实现 WebView 与原生应用之间的双向消息传递，确保数据同步无误。
- **生命周期事件监听**：监听 WebView 显示、隐藏、销毁等关键生命周期事件，方便开发者进行精细化控制。

### 2. **突破官方 Webview 组件的功能限制**

- **99%以上的 uni 方法支持**：uni-webview-framework 允许你在 Web 环境中调用几乎所有的 uni 方法，使你能够充分利用 uni-app 提供的强大 API。
- **丰富的 Web 生态集成**：支持使用流行的 Vue2/Vue3 UI 库，如 Vant、NutUI 等，享受 Web 生态系统的便利。

### 3. **近似原生的 UI 体验**

- **自动适配页面高度**：无需开发者手动调整，框架会自动计算并适配页面高度，确保最佳显示效果。
- **记录滚动位置**：自动记录滚动组件的高度，用户返回页面时能保持之前的滚动位置。
- **栈式页面导航**：模拟原生 App 的页面前进后退行为，提供流畅的用户体验。
- **页面切换动画**：模仿原生 App 的页面切换动画，提升整体视觉效果。

### 4. **插件扩展支持**

- **灵活的插件系统**：支持通过插件安装扩展更多功能，满足不同业务场景的需求。

### 5. **跨平台兼容性**

- **完全兼容 uni-app 环境**：适用于 iOS 和 Android 平台，确保一致的用户体验。

---

## ⚙️ 安装

确保你已安装 [Node.js](https://nodejs.org) 和 [npm](https://www.npmjs.com/)，然后运行以下命令安装依赖：

```bash
npm install
```

---

## 🧪 使用指南

### 创建 Webview 实例

```javascript
import { XWebview } from 'xwebview';

const webview = XWebview.create('https://example.com', {
  // 配置项
});
```

### 页面跳转与加载

```javascript
webview.loadURL('https://another-page.com');
webview.pageHistoryBack();
```

### 显示与隐藏

```javascript
webview.show();
webview.hide();
```

### 消息通信

```javascript
webview.onMessage((msg) => {
  console.log('收到消息:', msg);
});

webview.postMessage({ text: 'Hello Webview!' });
```

### 销毁 Webview

```javascript
webview.destroy();
```

---

## 🛠 架构设计

uni-webview-framework 分为两大部分：

1. **uni-app 项目**：提供 Web 运行的核心环境，使得 Web 页面能够调用 uni-app 提供的 API。
2. **Web 项目**：可以基于 Vue2 或 Vue3，集成了丰富的 UI 组件库，并封装了多种模仿原生 App 行为的基本 UI 功能，如：
   - 自动计算并适配页面高度
   - 记录滚动组件的高度
   - 栈式的 App 页面前进后退
   - 类似原生 App 的页面切换动画

---

## 🤝 贡献代码

我们欢迎社区贡献！请遵循以下步骤：

1. Fork 本项目
2. 创建新分支 (`git checkout -b feature/new-feature`)
3. 提交你的更改 (`git commit -am 'Add some feature'`)
4. 推送分支 (`git push origin feature/new-feature`)
5. 提交 Pull Request

---

## 📜 协议

本项目遵循 MIT 协议。详见 [LICENSE](LICENSE) 文件。

---

## 📬 联系方式 & 社区支持

如果你有任何疑问或建议，欢迎通过以下方式联系作者交流：
- GitHub/Gitee Issues
- 邮箱：15024702174@163.com

---

### **为什么选择 uni-webview-framework？**

1. **解决 HBuilderX 编辑器的性能瓶颈**：对于大型项目，HBuilderX 编辑器在热更新时容易卡顿，影响开发效率。uni-webview-framework 提供了一种新的解决方案，避免了这些问题。
   
2. **提高开发效率**：通过支持几乎所有 uni 方法，uni-webview-framework 让开发者能够在 Web 环境中使用 uni-app 的强大功能，同时还能利用 Web 生态系统中的丰富资源，如 Vant、NutUI 等流行 UI 库。

3. **增强用户体验**：uni-webview-framework 提供了自动适配页面高度、记录滚动位置、栈式页面导航等功能，使得 Web 页面看起来像原生 App，提升了用户体验。

4. **强大的消息通信机制**：uni-webview-framework 实现了 WebView 与原生应用之间的双向消息传递，确保数据同步无误，增强了应用的稳定性。

---

## 声明
uniapp本身已经很优秀，但如果您遇到了与我一样的痛点，您不妨可以尝试

---