zhixi-document-runtime/docs/ios-integration.md

iOS Integration Guide

概述

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

构建 Rust 库

# 安装 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

# 通过 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

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

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

引入 XCFramework

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

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