# Tencent Qian H5 容器 — iOS Quick Start

## 工具链

- **Xcode 15+**(LTS:Xcode 15.4 / 16.x 均可)
- **Swift 5.9+**
- **iOS Deployment Target 14.3**(对齐人脸核身最低支持)
- **XcodeGen**(用于生成 `.xcodeproj`,本仓库**不提交** `.xcodeproj`)

## 1. 安装 XcodeGen(仅一次)

```bash
brew install xcodegen
```

## 2. 生成 Xcode 工程

```bash
cd ios-swift
xcodegen generate
```

执行后会在当前目录生成 `Demo.xcodeproj`(`.xcodeproj` 已在 `.gitignore` 中,不会被误提交)。

## 3. 打开 + 跑 Demo

```bash
open Demo.xcodeproj
```

在 Xcode 中:
1. 选 `Demo` scheme
2. 选目标设备(模拟器或真机)
3. ⌘ + R 运行

Demo 演示三种集成方式（容器 / 组件 / 配置）与兼容性自检页,详见 [../docs/integration-checklist.md](../docs/integration-checklist.md)。

## 4. SPM 集成(替代方案)

若客户走 Swift Package Manager,无需 XcodeGen,直接在仓库根目录使用 [Package.swift](../Package.swift):

```swift
// 客户工程的 Package.swift
.package(url: "<your-git-url>", from: "1.0.0"),
.product(name: "TencentQianWebView", package: "h5-in-app-integration"),
```

## 目录结构

```
ios-swift/
├── project.yml                 # XcodeGen 配置
├── TencentQianWebView/         # SDK Framework target 源码
│   ├── Sources/
│   │   ├── Model/              # 协议数据模型
│   │   ├── Configuration/      # WKWebViewConfiguration 工厂
│   │   ├── Internal/           # navigation/UI delegate / UA 注入
│   │   ├── Permission/         # 媒体权限 grant
│   │   ├── Download/           # 下载处理策略
│   │   ├── Scheme/             # qianapp / external scheme 拦截
│   │   ├── Resources/          # 国际化字符串(Base / zh-Hans)
│   │   ├── TencentQianWebView.swift              # 公共入口（命名空间 enum）
│   │   ├── TencentQianWebViewController.swift    # 容器模式
│   │   ├── TencentQianWebViewConfigurator.swift  # 配置模式
│   │   ├── TencentQianWebViewComponent.swift     # 组件模式（嵌入自定义布局）
│   │   ├── KeyboardAvoidance.swift               # 底部安全区 + 软键盘避让（容器内建 / 宿主一行接入）
│   │   └── TencentQianWebViewShared.swift        # 跨模块共享定义
│   └── Info.plist
├── TencentQianWebViewTests/    # SDK 单测(XCTest)
└── Demo/                       # Demo App target 源码
```
