boos
e0a5f57793
Vendor the rebranded BoosAPI Desktop client (Tauri + Vue) into metapi as a monorepo subdirectory under desktop/. Source only — node_modules, dist, Cargo target and the upstream .git history are excluded. desktop/ keeps its own independent Cargo workspace (desktop/src-tauri with crates/*); it is not part of the backend boosapi crate, so a `cargo check` at the metapi root still compiles only the backend. Build the desktop app from desktop/src-tauri per desktop/README.md. Note: app icons are still placeholder assets pending the final BoosAPI logo. The updater signing keys live outside the repo and are not included.
117 lines
4.4 KiB
Markdown
117 lines
4.4 KiB
Markdown
---
|
||
description: 查阅 markstream-vue 的底层 API，包括解析器工具、渲染流程选择、作用域覆盖与 AST 级接入能力。
|
||
---
|
||
|
||
# API 参考
|
||
|
||
本页聚焦 `markstream-vue` 的底层入口：解析器工具、渲染流程选择，以及作用域覆盖相关钩子。
|
||
|
||
如果你是想查 `MarkdownRender`、`CodeBlockNode`、`ImageNode` 这类导出的 Vue 组件，请优先看 [渲染器与节点组件](/zh/guide/components)。搭配 [使用示例](/zh/guide/usage) 与 [props](/zh/guide/props) 页面一起阅读效果更佳。
|
||
|
||
## 渲染流程速览
|
||
|
||
```
|
||
Markdown 字符串 → getMarkdown() → markdown-it-ts 实例
|
||
↓
|
||
parseMarkdownToStructure(content, md) → AST (BaseNode[])
|
||
↓
|
||
<MarkdownRender> → 节点组件（CodeBlockNode、ImageNode 等）
|
||
```
|
||
|
||
可在任意阶段介入：
|
||
- 直接传 `content`：组件自动解析。
|
||
- 传 `nodes`：自己在服务端/预处理阶段生成 AST 并复用。
|
||
|
||
## 解析器工具
|
||
|
||
| Helper | 作用 | 适用场景 |
|
||
| ------ | ---- | -------- |
|
||
| `getMarkdown(msgId?, options?)` | 返回预配置的 `markdown-it-ts` 实例。 | 需调整 parser 选项（HTML、插件）或复用实例时。 |
|
||
| `parseMarkdownToStructure(content, md)` | 生成渲染器使用的 AST。 | 服务端预解析、静态导出、或需在渲染前做校验时。 |
|
||
|
||
两者均可在 Node/浏览器使用。处理大文档时可复用 `md` 实例避免重复初始化插件。
|
||
|
||
## 自定义组件与作用域
|
||
|
||
通过 `setCustomComponents(customId?, mapping)` 覆盖任意节点渲染器，再在 `MarkdownRender` 上传入匹配的 `custom-id`，即可限定覆盖范围。
|
||
|
||
```ts twoslash
|
||
import type { Component } from 'vue'
|
||
import { setCustomComponents } from 'markstream-vue'
|
||
|
||
declare const CustomImageNode: Component
|
||
|
||
setCustomComponents('docs', {
|
||
image: CustomImageNode,
|
||
})
|
||
```
|
||
|
||
```vue twoslash
|
||
<script setup lang="ts">
|
||
import MarkdownRender from 'markstream-vue'
|
||
|
||
const md = ''
|
||
</script>
|
||
|
||
<template>
|
||
<MarkdownRender custom-id="docs" :content="md" />
|
||
</template>
|
||
```
|
||
|
||
提示：
|
||
- 使用语义化 ID（如 `docs`、`playground`）方便排查。
|
||
- `setCustomComponents(mapping)` 会注册全局映射；更推荐按 ID 作用域隔离。
|
||
- 在 SPA 中按需注册/卸载时，记得在路由切换时清理。
|
||
|
||
## 解析钩子与节点变换
|
||
|
||
当使用 `content` 时，可通过 `parse-options`（组件 prop）或 `parseMarkdownToStructure` 的 `ParseOptions` 拦截解析阶段：
|
||
|
||
- `preTransformTokens(tokens)` — 生成节点前预处理 token。
|
||
- `postTransformTokens(tokens)` — 在默认处理后继续调整。
|
||
|
||
如需改造 AST，可在 `parseMarkdownToStructure` 返回后自行处理，再通过 `MarkdownRender` 的 `nodes` 传入。
|
||
|
||
示例：把 AI “thinking” 标签直接渲染成自定义组件（无需钩子）
|
||
|
||
```ts twoslash
|
||
import type { Component } from 'vue'
|
||
import { setCustomComponents } from 'markstream-vue'
|
||
|
||
declare const ThinkingNode: Component
|
||
|
||
setCustomComponents('docs', { thinking: ThinkingNode })
|
||
```
|
||
|
||
```vue twoslash
|
||
<script setup lang="ts">
|
||
import MarkdownRender from 'markstream-vue'
|
||
|
||
const doc = '<thinking>Need a plan</thinking>'
|
||
</script>
|
||
|
||
<template>
|
||
<MarkdownRender
|
||
custom-id="docs"
|
||
:custom-html-tags="['thinking']"
|
||
:content="doc"
|
||
/>
|
||
</template>
|
||
```
|
||
|
||
如果你需要进一步改造 `thinking` 节点（剥掉包裹、重映射 attrs、合并分段等），可使用上述 hooks，或在解析后自行处理 AST。
|
||
|
||
## 其他导出
|
||
|
||
- 节点组件：`CodeBlockNode`、`MarkdownCodeBlockNode`、`MermaidBlockNode`、`MathBlockNode`、`ImageNode` 等（详见 [组件与节点渲染器](/zh/guide/components)）。
|
||
- 工具：`VueRendererMarkdown`（全局组件插件）与共享类型定义（组件 props/解析器类型；参考 [/zh/guide/parser-api](/zh/guide/parser-api) 或 npm 上的 `stream-markdown-parser` README）。
|
||
|
||
## 样式 & 排障提醒
|
||
|
||
- 先引入 reset，再在 `@layer components` 导入 `markstream-vue/index.css`，防止 Tailwind/UnoCSS 覆盖。参考 [Tailwind 指南](/zh/guide/tailwind)。
|
||
- 同伴依赖中，KaTeX 需要自己的 CSS；Mermaid 不需要。缺失 KaTeX 样式时通常表现为空白公式。
|
||
- 使用 `custom-id` + `[data-custom-id="docs"]` 来局部覆盖样式。
|
||
- 遇到样式异常时，依照 [排查清单](/zh/guide/troubleshooting#css-looks-wrong-start-here) 逐项检查。
|
||
|
||
需要更多示例？打开 [Playground](/zh/guide/playground) 或运行 `pnpm play` 在本地实验解析/渲染组合。
|