API 参考

视图与控制器

类型	用途
`MarkdownRenderView`	SwiftUI，单文档。
`MarkdownRenderViewController`	UIKit，单文档。
`MarkdownChatRenderView`	SwiftUI，整段会话。
`MarkdownChatRenderViewController`	UIKit，整段会话。
`MarkdownChatRenderProxy`	命令式控制 SwiftUI 的会话视图。
`MarkdownRenderKit`	`version`、`bridgeVersion`、`licenseDiagnostics()`。

单文档方法

render(_:) · renderStream(_:) · startStreaming() · appendChunk(_:isFinal:) · finishStreaming() · clear() · reload() · contentHeight · licenseStatus

会话方法

setMessages(_:) · appendMessage(_:) · updateMessage(_:) · appendChunk(_:to:isFinal:) · appendReasoningChunk(_:to:isFinal:) · finishReasoning(for:) · setReasoningExpanded(_:for:) · finishMessage(_:) · removeMessage(_:) · clear() · scrollToBottom(animated:) · contentHeight · licenseStatus

MarkdownRenderOptions

选项	默认值	含义
`colorScheme`	`.auto`	`.auto`、`.light`、`.dark`。
`theme`	`.system`	`.system` 或 `.github`，可叠加 token 覆盖。
`extensions`	`[]`	自定义行内语法。
`interaction`	`.automatic`	链接与图片点击归谁处理。
`isScrollEnabled`	`true`	嵌进自己的滚动视图时关掉。
`backgroundColor`	`.clear`	渲染器背景。
`contentPadding`	四周 16pt	内容与边缘的间距。
`bottomGap`	`0`	最后一块下方的额外空间，给覆盖的输入框预留。
`markdown`	见下	解析能力开关。
`streamingMode`	`.incremental`	`.fullRerender` 每次刷新都全量重渲染。
`longBlockStreaming`	`.throttled`	`.deferred` 会等长块完成后一次画出。
`longBlockThreshold`	`512`	超过多少字符启用上面的策略。
`baseFontSize`	`16`	Dynamic Type 缩放前的基准字号。
`respectsDynamicType`	`true`	跟随系统字号。
`minFontScale` / `maxFontScale`	`0.85` / `1.6`	Dynamic Type 倍率的上下限。
`heightChangeDebounceInterval`	`0.08`	流式期间高度上报的防抖间隔。
`copyText` / `copiedText` / `copyFailedText`	`"Copy"` …	代码块复制按钮的文案。

MarkdownRenderLocalization

SDK 自身文案的语言开关与文案本身。详见多语言。

成员	含义
`language`	`.automatic`（默认，跟随设备）、`.english`、`.simplifiedChinese`、`.custom(_:)`。
`availableLanguages`	本次构建提供的语言代码，例如 `["en", "zh-Hans"]`。
`codeCopy` / `codeCopied` / `codeCopyFailed`	解析后的代码块复制按钮文案。
`messageCopy` / `messageCopied` / `messageRetry` / `messageEdit`	解析后的消息操作辅助功能标签。
`reasoningThinking` / `reasoningCompleted` / `reasoningDuration`	解析后的推理折叠区标题。

MarkdownRenderOptions.MarkdownConfig

选项	默认值
`allowRawHTML`	`false`
`linkify`	`true`
`typographer`	`true`
`breaks`	`false`
`taskLists`	`true`
`emoji`	`true`
`math`	`true`
`reasoning`	已启用

MarkdownChatRenderOptions

选项	默认值	含义
`renderOptions`	——	上面那套单文档选项，作用于每一条消息。
`interaction`	`.automatic`	`renderOptions.interaction` 的快捷入口。
`reasoning`	已启用	推理折叠。
`messageActions`	仅复制	每条消息的操作条。
`streamingPresentation`	`.smooth`	`.immediate` 来一个 chunk 显示一个。
`autoScrollBehavior`	`.nearBottom`	还有 `.always`、`.never`。
`preservesUserScroll`	`true`	读者往上翻后停止跟随。
`bottomThreshold`	`96`	距底部多少点仍算「在底部」。
`messageSpacing`	`14`	消息之间的间距（点）。
`maxMessageWidth`	`.full`	阅读栏宽度。
`userMessageMaxWidth`	`.fraction(0.82)`	用户自己气泡的宽度。
`chunkCoalescingInterval`	`1/30` 秒	送进 WebView 前的 token 聚合时长，`0` 表示不聚合。

事件

单文档是 MarkdownRenderEvent，会话是 MarkdownChatRenderEvent。会话版多了 viewportChanged 和 messageAction，并且会给每个 action 附上它来自哪条消息。

事件	触发时机
`.ready`	渲染器加载完成，排队的命令开始执行。
`.rendered(height:)`	每个内容周期恰好两次：首帧上屏，以及最终 flush。
`.heightChanged(_)`	期间的高度变化 —— 流式、图片加载、Dynamic Type。流式中会防抖。
`.viewportChanged(_)`	滚动位置与是否接近底部。
`.messageAction(_)`	消息上的复制、重试或编辑被点击。
`.action(_)`	下面全部。
`.error(_)`	结构化失败，带稳定的 `code`。

Actions

请求 —— 你不处理就没有任何反应：

Action	含义
`.linkTapped(URL)`	链接被点击，且 `interaction.links` 为 `.handledByHost`。
`.imageTapped(URL?)`	图片被点击，且 `interaction.images` 为 `.handledByHost`。
`.extensionTapped(name:action:value:)`	自定义行内扩展被点击。
`.custom(name:payload:)`	无法识别的 bridge 消息。

通知 —— SDK 已经做完了：

Action	含义
`.didOpenLink(URL)`	已在应用内浏览器打开；`mailto`/`tel` 交给系统。
`.didPresentImage(URL)`	已弹出内置预览器。
`.linkBlocked(url:scheme:)`	scheme 不在 `allowedLinkSchemes` 内，没有打开任何东西。
`.codeCopied(text:language:)`	已复制到剪贴板。
`.codeCopyFailed(text:language:error:)`	复制失败。
`.reasoningToggled(isExpanded:)`	读者展开或收起了推理折叠。
`.taskToggled(isChecked:text:)`	任务列表的勾选状态变化。

错误码

MarkdownRenderError 带有 reason、可读的 message，以及适合打点的稳定 code。

code	含义
`licenseMissing`	Copy Bundle Resources 里没有 `.smklicense`。
`licenseInvalid`	信封格式不对、签名错误，或 payload 非法。
`licenseUnknownSigningKey`	由本 SDK 不信任的密钥签发 —— 最常见的是测试环境签发的授权配了生产 SDK。
`licenseWrongIssuerEnvironment`	由 sandbox 签发方签发，生产 SDK 只接受 production。
`licenseUnauthorizedTeamId`	App 的签名团队与授权不一致。
`licenseTeamIdentifierUnavailable`	读不到 Team ID —— 在模拟器上属于预期。
`licenseUnauthorizedBundleId`	当前 bundle identifier 不在授权覆盖范围内。
`expiredTrialLicense`	试用授权已超过 `validUntil`。
`sdkReleaseNotCovered`	这个 SDK 构建的发布时间晚于授权的 `updatesUntil`，需要续期才能使用。
`releaseMetadataMissing`	Framework 缺少发布时间元数据 —— 构建本身有问题。
`resourceMissing` / `resourceInvalid` / `resourceKeyInvalid` / `resourceDecryptionFailed`	内置渲染核心加载失败。
`webViewLoadFailed`	WebView 加载渲染器失败。
`webContentProcessTerminated`	WebKit 回收了内容进程；SDK 会自动重载并回放。
`renderFailed` / `serializationFailed` / `copyFailed`	某次运行时操作失败。

所有 license* 都是诊断，不是故障。渲染继续进行，只是构建被打上角标。见授权。

版本

MarkdownRenderKit.version        // SDK 版本，例如 "0.0.10"
MarkdownRenderKit.bridgeVersion  // 原生 ↔ Web 的消息契约版本

Framework 开启了 library evolution。同一大版本内，公开声明只增不改 —— 用旧构建编译的 App，链接新构建时不需要重新编译。