103 lines
2.3 KiB
Markdown
103 lines
2.3 KiB
Markdown
# 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 可能内存占用大，考虑后台线程处理
|