ratex-react-native

July 16, 2026 · View on GitHub

React Native 原生 LaTeX 数学公式渲染库——无 WebView，无 JavaScript 数学引擎。公式在 Rust 中完成解析和排版（编译为原生库），直接使用 KaTeX 字体绘制到原生 Canvas 上。

English documentation: README.md

特性

在 iOS、Android 与 macOS（React Native macOS）上原生渲染 LaTeX 数学公式
基于新架构（Fabric / JSI / TurboModules）构建 —— React Native ≥ 0.84 仅支持新架构
测量渲染内容尺寸，便于滚动视图和动态布局
提供解析失败的错误回调
内置所有 KaTeX 字体，无需额外配置
通过 alignSelf: 'baseline' 在 flex 行和 <Text> 内实现基线对齐
同步公式度量 API（getTexMetrics），供自定义文本引擎使用
InlineTeX 组件支持文字与 $...$ 公式混排

环境要求

依赖	版本
React Native	≥ 0.84
React	≥ 19.2
iOS	≥ 14.0
macOS	≥ 13.0（使用 React Native macOS 时）
Android	minSdk 21（Android 5.0+）

安装

npm install ratex-react-native

iOS — pod install

cd ios && pod install

macOS（React Native macOS）

在应用的 macos/ 目录执行 pod install，然后 npx react-native run-macos。本 pod 自带的 RaTeX.xcframework 需包含 macOS 切片（见 RaTeX 仓库中的 ./scripts/build-apple-xcframework.sh）。

使用方法

块级公式

import { RaTeXView } from 'ratex-react-native';

function MathFormula() {
  return (
    <RaTeXView
      latex="\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}"
      fontSize={24}
      color="#1E88E5"
      onError={(e) => console.warn('LaTeX 错误:', e.nativeEvent.error)}
    />
  );
}

内联公式（文字与 LaTeX 混排）

import { InlineTeX } from 'ratex-react-native';

function Paragraph() {
  return (
    <InlineTeX
      content="质能等价关系 $E = mc^2$ 是狭义相对论的核心结论。"
      fontSize={16}
      textStyle={{ color: '#333' }}
    />
  );
}

在 content 字符串中用 $...$ 标记公式，支持一段文字中包含多个公式。

共享默认颜色

import { RaTeXProvider, InlineTeX, RaTeXView } from 'ratex-react-native';

function Screen() {
  return (
    <RaTeXProvider color="#1E88E5">
      <RaTeXView latex="x + y" />
      <InlineTeX content="内联公式：$E = mc^2$" />
    </RaTeXProvider>
  );
}

API

`<RaTeXView />`

属性	类型	默认值	说明
`latex`	`string`	—	要渲染的 LaTeX 数学字符串（必填）
`fontSize`	`number`	`24`	字体大小，单位为 dp（密度无关像素）。公式整体等比缩放。
`displayMode`	`boolean`	`true`	`true` = 独立块样式（`$$...$$`）；`false` = 行内样式（ $...$ ）。
`color`	`ColorValue`	—	默认公式颜色。显式 LaTeX 颜色仍然优先。
`style`	`StyleProp<ViewStyle>`	—	标准 React Native 样式。宽高会自动从测量结果设置，也可手动覆盖。
`onError`	`(e: { nativeEvent: { error: string } }) => void`	—	LaTeX 字符串解析失败时调用。
`onContentSizeChange`	`(e: { nativeEvent: { width: number; height: number } }) => void`	—	排版完成后回调，携带公式的固有内容尺寸（未缩放）（dp）。适用于滚动视图或动态容器。

内容尺寸自适应

RaTeXView 会自动将 onContentSizeChange 返回的 width 和 height 应用到自身 style，实现类似 wrap_content 的自适应布局，无需手动指定尺寸：

<ScrollView horizontal>
  <RaTeXView latex="\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}" fontSize={28} />
</ScrollView>

显式指定宽高时的行为

如果你在 style 中显式指定了 width 和/或 height，RaTeXView 不会再用测量结果覆盖这些值；原生视图会在绘制阶段把公式**按比例缩小（不会放大）**以适配给定布局尺寸，并在必要时按边界裁剪。

基线对齐

RaTeXView 可以像普通字符一样落在文字基线上——既支持 flex 行，也支持 <Text> 内嵌：

<View style={{ flexDirection: 'row', alignItems: 'baseline' }}>
  <Text>f(x) =</Text>
  <RaTeXView latex={'\\frac{a}{b}'} fontSize={16} displayMode={false} />
</View>

<Text>
  compare y with{' '}
  <RaTeXView latex="y" fontSize={16} displayMode={false}
             style={{ alignSelf: 'baseline' }} />{' '}
  mid-sentence
</Text>

`<InlineTeX />`

将包含 $...$ 标记的混合字符串渲染为原生内联文本流。公式在 iOS/macOS 上通过 NSTextAttachment 嵌入，在 Android 上通过 ReplacementSpan 嵌入，因此换行、断词和基线对齐都交给平台文本排版引擎处理。

渲染流程：

将 content 解析成文字和公式片段。转义美元符号（\$）保留为普通文本，未闭合或空的 $ 分隔符会回退为普通文本。
公式片段使用原生 text attachment/span 参与内联排版，并上报测量后的内容高度用于动态布局。

属性	类型	默认值	说明
`content`	`string`	—	包含 $...$ 标记的文字字符串（必填）。
`fontSize`	`number`	`16`	传给每个公式渲染器的字体大小（dp）。
`color`	`ColorValue`	—	传给每个行内公式的默认颜色。显式 LaTeX 颜色仍然优先。
`textStyle`	`StyleProp<TextStyle>`	—	普通文字样式来源。支持字段：`color`、`fontSize`、`fontFamily`、`fontStyle: 'italic'`，以及包含 `underline` / `line-through` 的 `textDecorationLine`。
`style`	`StyleProp<ViewStyle>`	—	原生内联容器的标准 React Native 样式。若未显式指定高度，会自动使用测量高度。

InlineTeX 会自动对所有公式传入 displayMode={false}—— $...$ 始终使用行内样式。

`<RaTeXProvider />`

为后代 RaTeXView 和 InlineTeX 提供默认公式颜色。若组件自身传入 color，则会覆盖继承值。

同步获取公式的墨迹度量——即 TeX 盒模型中的 depth：KaTeX 在 Web 端以 vertical-align: -depth 输出，MathML Core 中称为 ink line-descent。适用于需要以数值形式拿到基线偏移的自定义文本引擎（TextKit / Spannable、markdown 渲染器等）。度量与 measure/render 共享同一解析缓存，屏幕上已有的公式不会重复解析。

import { getTexMetrics } from 'ratex-react-native';

// 任意公式的自然（未缩放）度量——无需挂载视图：
const m = getTexMetrics('\\frac{a}{b}', 16, false);
// { width, height, depth } | null —— 单位 dp；基线位于 height - depth 处

// 已挂载视图的实际绘制度量（已应用适配缩放与居中）：
const d = ref.current?.getTexMetrics(); // ref: RaTeXViewRef
// { depth, scale, width, height } | null —— depth 可直接使用

两者都可在 useLayoutEffect 中安全调用。

架构支持

仅支持新架构（Fabric / Codegen / TurboModules），与 React Native 官方支持版本（≥ 0.84）保持一致，新架构在这些版本中默认开启。不再支持旧架构（Bridge/Paper）。

fontSize 说明

fontSize 单位为 dp（密度无关像素），而非 CSS pt$ 或物理像素。在 3 \times 屏幕密度的设备上，$fontSize={24} 的公式渲染高度为 72 物理像素，与 React Native 的标准布局单位一致。

许可证

MIT