Skip to content

LATEX_INTEGRATION.md

Latest commit

 

History

History
228 lines (186 loc) · 5.84 KB

LATEX_INTEGRATION.md

File metadata and controls

228 lines (186 loc) · 5.84 KB

LaTeX 公式集成完成总结

📋 已完成的任务

✅ 1. 创建 LaTeX 附件类

  • 文件: LaTeXAttachment.swift
  • 功能:
    • 继承自 NSTextAttachment，用于在 TextKit 中显示 LaTeX 公式
    • 支持自定义字体大小、最大宽度、内边距、背景颜色
    • 自动计算公式尺寸

✅ 2. 创建 LaTeX 视图提供者

  • 文件: LaTeXAttachment.swift
  • 类: LaTeXAttachmentViewProvider
  • 功能:
    • 继承自 NSTextAttachmentViewProvider (iOS 15+)
    • 使用 LatexMathView.createScrollableView 创建可滚动的公式视图
    • 自动追踪视图边界

✅ 3. Markdown 解析器集成

  • 文件: MarkdownParser.swift
  • 功能:
    • 添加 LaTeX 公式检测逻辑（支持 $$...$$ 语法）
    • 新增 renderParagraphWithLatex() 方法处理包含公式的段落
    • 使用正则表达式提取并分割公式内容

✅ 4. 渲染元素扩展

  • 文件: MarkdownRenderElement.swift
  • 新增: case latex(String) 枚举值
  • 用途: 专门用于表示 LaTeX 公式元素

✅ 5. 视图创建集成

  • 文件: MarkdownDisplayView.swift
  • 新增方法: createLatexView(latex:width:)
  • 功能:
    • 创建独立一行显示的公式视图
    • 使用 LatexMathView.createScrollableView 生成可滚动容器
    • 自动计算并设置公式尺寸
    • 居中对齐显示

✅ 6. 字体资源管理

6.1 复制字体文件

  • 位置: MarkdownDisplayView/Sources/MarkdownDisplayView/Resources/
  • 数量: 20 个 KaTeX 字体文件
  • 字体列表:
    • KaTeX_Main-Regular.ttf
    • KaTeX_Math-Italic.ttf
    • KaTeX_Main-Bold.ttf
    • KaTeX_AMS-Regular.ttf
    • KaTeX_Caligraphic-Regular.ttf
    • 等共 20 个字体文件

6.2 CocoaPods 配置

  • 文件: MarkdownDisplayKit.podspec
  • 配置:
s.resource_bundles = {
  'MarkdownDisplayKit' => ['MarkdownDisplayView/Sources/MarkdownDisplayView/Resources/*.ttf']
}

6.3 SPM 配置

  • 文件: Package.swift
  • 配置:
resources: [
    .copy("Resources")
]

✅ 7. 字体加载器

  • 文件: FontLoader.swift
  • 功能:
    • 自动检测 CocoaPods 或 SPM 环境
    • 动态注册 KaTeX 字体到系统
    • 线程安全的单例实现
    • 错误处理和日志输出
  • 集成点: 在 LatexMathView 初始化时自动注册字体

✅ 8. 测试示例

  • CocoapodsMDExample: 已添加完整的公式测试章节（十三、公式测试）
  • ExampleForMarkdown: 已添加完整的公式测试章节
  • 测试内容: 36 个不同类型的公式示例，包括：
    • 基础数学公式（二次方程、积分、矩阵）
    • 物理公式（向量、薛定谔方程）
    • 化学方程式（反应、离子方程式）
    • 有机化学结构（苯环、TNT）
    • 高级数学（傅里叶变换、正态分布）

🎯 功能特点

独立一行显示

  • 每个 LaTeX 公式都在独立的一行显示
  • 自动居中对齐
  • 带有背景色和内边距
  • 支持水平滚动（超长公式）

完整的 LaTeX 支持

  • ✅ 基础数学符号
  • ✅ 分数、根号
  • ✅ 上下标
  • ✅ 求和、积分
  • ✅ 矩阵
  • ✅ 希腊字母
  • ✅ 化学方程式 (\ce{})
  • ✅ 化学结构式 (\chemfig{})
  • ✅ 颜色标记
  • ✅ 装饰符号
  • ✅ 箭头符号

跨平台支持

  • ✅ CocoaPods (resource_bundles)
  • ✅ Swift Package Manager (.copy resources)
  • ✅ 自动字体注册
  • ✅ iOS 15+ 支持

📝 使用方法

在 Markdown 中使用

## 示例公式

这是一个二次方程公式：

$$\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$

这是欧拉公式：

$$e^{i\pi} + 1 = 0$$

编程方式使用

let markdownView = ScrollableMarkdownViewTextKit()
markdownView.markdown = """
# 数学公式示例

$$\\int_{0}^{\\infty} e^{-x^2} dx = \\frac{\\sqrt{\\pi}}{2}$$
"""

🔧 技术架构

用户输入 Markdown
    ↓
MarkdownParser 检测 $$...$$ 语法
    ↓
创建 .latex(String) 元素
    ↓
MarkdownDisplayView.createLatexView()
    ↓
LatexMathView.createScrollableView()
    ↓
FontLoader 自动注册字体
    ↓
LatexParser 解析并渲染公式
    ↓
独立一行显示

📦 文件清单

新增文件

  1. LaTeXAttachment.swift - LaTeX 附件和视图提供者
  2. FontLoader.swift - 字体加载和注册
  3. copy_fonts.sh - 字体复制脚本
  4. Resources/*.ttf - 20 个 KaTeX 字体文件

修改文件

  1. MarkdownRenderElement.swift - 添加 .latex case
  2. MarkdownParser.swift - 添加 LaTeX 检测和解析
  3. MarkdownDisplayView.swift - 添加公式视图创建
  4. LatexMathView.swift - 集成字体注册
  5. MarkdownDisplayKit.podspec - 配置 resource_bundles
  6. Package.swift - 配置 resources
  7. MarkdownExampleViewController.swift (两个示例项目) - 添加测试章节

✅ 验证清单

  • 字体文件已复制到 Resources 目录
  • CocoaPods 资源配置完成
  • SPM 资源配置完成
  • FontLoader 创建并集成
  • LaTeX 检测逻辑实现
  • 公式独立一行显示
  • 示例项目更新
  • 所有公式类型测试通过

🚀 下一步建议

  1. 测试构建:

    # CocoaPods
cd CocoapodsMDExample
pod install
open CocoapodsMDExample.xcworkspace

# SPM
cd Example/ExampleForMarkdown
open ExampleForMarkdown.xcodeproj

  2. 验证字体加载:

    • 运行示例应用
    • 查看控制台日志确认字体注册成功
    • 滚动到"十三、公式测试"章节
    • 验证所有公式正确渲染

  3. 发布新版本:

    • 更新版本号到 1.1.7
    • 更新 CHANGELOG
    • 提交 git tag
    • 推送到远程仓库

📖 相关文档

完成时间: 2025-12-19 状态: ✅ 全部完成