# iOS Integration Guide

## 概述

本文档描述如何将 `zhixi-document-runtime` 集成到 iOS App 中。

## 构建 Rust 库

```bash
# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 添加 iOS target
rustup target add aarch64-apple-ios aarch64-apple-ios-sim

# 构建
cargo build --release --target aarch64-apple-ios
cargo build --release --target aarch64-apple-ios-sim
```

## 生成 Swift Binding

```bash
# 通过 xtask 生成
cargo run -p xtask -- generate-bindings

# 或手动通过 UniFFI
uniffi-bindgen generate \
  crates/zx_document_ffi/src/zx_document.udl \
  --language swift \
  --out-dir bindings/ios/generated
```

## XCFramework

```bash
# 通过 scripts 构建
./scripts/build-ios.sh

# 输出
# bindings/ios/ZxDocumentRuntime.xcframework/
```

## 引入 XCFramework

1. 将 `ZxDocumentRuntime.xcframework` 拖入 Xcode 项目
2. 将生成的 Swift 文件添加到项目
3. 确保 `Frameworks, Libraries, and Embedded Content` 中包含 framework

## Swift 调用示例

```swift
import ZxDocumentRuntime

// 文件类型识别
let materialType = try detectMaterialType(filePath: "/path/to/file.md")
print("Type: \(materialType)")

// 打开文档
let doc = try openDocument(filePath: "/path/to/file.md", materialId: "abc123")
let info = try getDocumentInfo(handle: doc)
print("Title: \(info.title)")

// Markdown blocks
let blocks = try getMarkdownBlocks(handle: doc)
for block in blocks {
    print("[\(block.id)] \(block)")
}

// 搜索
let results = try searchDocument(handle: doc, query: "学习")
for r in results {
    print("Found at \(r.blockId): \(r.snippet)")
}

// 更新阅读位置
let position = ReadingPosition.markdown(
    blockId: "heading-3",
    scrollProgress: 0.45
)
try updateReadingPosition(materialId: "abc123", position: position)

// 导出阅读事件
let events = try exportPendingEvents()
for event in events {
    print("Event: \(event)")
}
```

## 常见问题

### 编译错误

- 确保 Rust target 已安装
- 确保 XCFramework 的 `Build Phase` / `Link Binary with Libraries` 已包含
- 检查 `Library Search Paths` 包含 framework 路径

### 运行时崩溃

- 检查文件路径是否存在
- 编码问题：确保文件是 UTF-8（TXT/MD）
- 大文件：PDF/EPUB 可能内存占用大，考虑后台线程处理