# tauri-safe-area-demo

**Repository Path**: ArtfulCoder/tauri-safe-area-demo

## Basic Information

- **Project Name**: tauri-safe-area-demo
- **Description**: No description available
- **Primary Language**: Rust
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-23
- **Last Updated**: 2025-11-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tauri Safe Area Demo

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Tauri](https://img.shields.io/badge/Tauri-2.0-blue)](https://tauri.app/)
[![Vue](https://img.shields.io/badge/Vue-3.x-green)](https://vuejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)

一个完整的 Tauri 安全区域和键盘处理解决方案，支持 Android 和 iOS 平台。提供响应式的安全区域占位组件，完美处理刘海屏、圆角屏和键盘弹出等场景。

[English](./README_EN.md) | 简体中文

## ✨ 特性

- 🎯 **四个方向支持** - 支持 top、bottom、left、right 四个方向的安全区域
- 🎨 **三种工作模式** - Layout（布局）、Keyboard（键盘）、Hybrid（混合）模式
- 📱 **完美适配移动端** - 支持刘海屏、圆角屏、横屏等各种场景
- ⌨️ **键盘动画同步** - 逐帧监听键盘动画，实现完美的跟随效果
- 🔌 **适配器模式** - 平台特定代码隔离，易于扩展新平台
- 💪 **TypeScript** - 完整的类型定义和类型安全
- 🎭 **响应式设计** - 基于 Vue 3 Composition API
- 🎬 **平滑动画** - 智能动画系统，与系统键盘动画保持一致
- 🛠️ **开箱即用** - 提供完整的 Vue 组件，简单易用

## 📦 安装

```bash
# 克隆项目
git clone https://github.com/yourusername/tauri-safe-area-demo.git
cd tauri-safe-area-demo

# 安装依赖
npm install

# 开发模式
npm run tauri dev

# 构建
npm run tauri build
```

## 🚀 快速开始

### 1. 基础设置

在 `main.ts` 中初始化 SafeArea：

```typescript
import { createApp } from 'vue'
import App from './App.vue'
import { SafeArea } from './safe-area/SafeArea'

// 创建 SafeArea 实例
const safeArea = new SafeArea()
safeArea.init()
safeArea.listen()

// 创建 Vue 应用并提供 SafeArea 实例
const app = createApp(App)
app.provide('safeArea', safeArea)
app.mount('#app')

export { safeArea }
```

### 2. 使用组件

```vue
<template>
  <div class="flex flex-col h-100vh">
    <!-- 顶部安全区 -->
    <SafeAreaSpacer direction="top" mode="layout" class="bg-blue-500" />

    <!-- 主内容 -->
    <div class="flex-1 overflow-auto">
      <input type="text" placeholder="输入内容" />
    </div>

    <!-- 底部安全区（混合模式：自动处理键盘） -->
    <SafeAreaSpacer direction="bottom" mode="hybrid" class="bg-yellow-500" />
  </div>
</template>

<script setup lang="ts">
import { SafeAreaSpacer } from './safe-area/components'
</script>
```

## 📖 文档

### SafeAreaSpacer 组件

#### Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `direction` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | 安全区域方向 |
| `mode` | `'layout' \| 'keyboard' \| 'hybrid'` | `'layout'` | 工作模式 |
| `enableAnimation` | `boolean` | `true` | 是否启用动画 |
| `animationDuration` | `number` | `300` | 动画时长（毫秒） |

#### 工作模式

- **Layout 模式** - 只响应安全区域变化，适用于顶部状态栏、底部导航栏等
- **Keyboard 模式** - 只响应键盘高度变化，适用于输入框上方的占位
- **Hybrid 模式** - 混合模式，取安全区域和键盘高度的最大值，适用于聊天界面、表单等

详细文档请查看：
- [组件文档](./src/safe-area/components/README.md)
- [架构设计](./docs/ARCHITECTURE.md)

## 🏗️ 架构

项目采用分层架构设计：

```
src/safe-area/
├── SafeArea.ts              # 核心类（平台无关）
├── adapter/                 # 适配器层
│   ├── types.ts            # 接口定义
│   ├── index.ts            # 适配器工厂
│   ├── android.ts          # Android 适配器
│   └── ios.ts              # iOS 适配器
└── components/             # Vue 组件
    ├── SafeArea.vue        # SafeAreaSpacer 组件
    ├── index.ts            # 组件导出
    └── README.md           # 组件文档
```

### 核心特性

1. **适配器模式** - 平台特定代码隔离，易于扩展
2. **响应式状态** - 基于 Vue 3 Ref，自动更新
3. **逐帧监听** - 使用 `WindowInsetsAnimationCompat` 监听键盘动画每一帧
4. **智能动画** - 键盘动画期间使用逐帧更新，其他时候使用 CSS transition

## 🎯 使用场景

### 1. 聊天应用

```vue
<SafeAreaSpacer direction="bottom" mode="hybrid" />
```

键盘弹起时自动撑开，确保输入框始终在键盘上方。

### 2. 表单页面

```vue
<SafeAreaSpacer direction="bottom" mode="keyboard" />
```

只响应键盘，不受底部安全区影响。

### 3. 导航栏

```vue
<SafeAreaSpacer direction="top" mode="layout" class="bg-blue-600" />
<SafeAreaSpacer direction="bottom" mode="layout" class="bg-blue-600" />
```

完美适配刘海屏、圆角屏等设备。

## 🔧 技术栈

- **前端框架**: Vue 3 + TypeScript
- **构建工具**: Vite
- **样式方案**: UnoCSS
- **跨平台**: Tauri 2.0
- **Android**: Kotlin + WindowInsetsAnimationCompat
- **iOS**: Swift (待实现)

## 📱 平台支持

| 平台 | 状态 | 说明 |
|------|------|------|
| Android | ✅ 完整支持 | 使用 WindowInsetsAnimationCompat |
| iOS | 🚧 待实现 | 已预留适配器接口 |
| Web | ⚠️ 部分支持 | 不支持原生键盘事件 |

## 🤝 贡献

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启一个 Pull Request

详细贡献指南请查看 [CONTRIBUTING.md](./CONTRIBUTING.md)

## 📄 许可证

本项目采用 Apache License 2.0 许可证 - 查看 [LICENSE](./LICENSE) 文件了解详情

## 🙏 致谢

- [Tauri](https://tauri.app/) - 优秀的跨平台框架
- [Vue.js](https://vuejs.org/) - 渐进式 JavaScript 框架
- [UnoCSS](https://unocss.dev/) - 即时按需原子化 CSS 引擎
- [WindowInsetsCompat](https://developer.android.com/reference/androidx/core/view/WindowInsetsCompat) - Android 窗口插入 API

## 📮 联系方式

- 提交 Issue: [GitHub Issues](https://github.com/yourusername/tauri-safe-area-demo/issues)

## 🌟 Star History

如果这个项目对你有帮助，请给它一个 ⭐️！

## 💻 推荐 IDE 设置

- [VS Code](https://code.visualstudio.com/) + [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)