API 参考 · React

包名：@mineru-viewer/react（同时发布 @mineru-viewer/react-no-esm 免构建全局版，全局变量 MVReact）。

导出

import {
  MineruViewer,   // 门面组件（forwardRef）
  SourcePane,     // 右栏源面板
  MarkdownPane,   // 左栏 Markdown 面板
  mount,          // 命令式挂载：mount(el, props) -> 句柄
  bus,            // 全局事件总线
  setPdfWorkerSrc,// 指定 pdf.js worker
  loadZipEntries, // 低阶：zip -> entries
  getAdapter,     // 低阶：选择版本适配器
  detectMeta,     // 低阶：探测 MinerU 版本
  adapters,       // 低阶：已注册适配器表
  version         // 当前版本字符串
} from "@mineru-viewer/react";
import "@mineru-viewer/react/style.css";

Props

名称	类型	默认值	说明
zip	File | ArrayBuffer | string	—	要渲染的 MinerU 产物；string 视为 url 会 fetch
version	string	""	手动指定 MinerU 版本（如 "v340"），否则自动探测
highlights	HighlightGroup[]	[]	业务注入高亮组
showMarkdown	boolean	true	是否展示左栏 Markdown 预览
initialPage	number	1	初始页码
theme	'light' | 'dark'	'light'	主题

事件

React 组件不直接向 DOM 冒泡自定义事件，统一通过 bus 暴露（与 Vue 一致）：

事件	payload
ready	{ meta, pages }
block-click	{ blockId, page }
block-select	{ blockIds, page }
copy / star / feedback	{ blockIds, ... }
edit	{ blockIds, page, oldText, newText }
highlight-activate	{ group }
error	{ phase, message }

import { bus } from "@mineru-viewer/react";
bus.on("ready", ({ meta, pages }) => { /* ... */ });

命令式 API（通过 ref）

import { useRef } from "react";
import { MineruViewer } from "@mineru-viewer/react";

function App() {
  const v = useRef(null);
  const onClick = () => {
    v.current.addHighlight({ id: "g1", blockIds: ["b-1"], color: "#ff7875" });
    v.current.focusBlock("b-2");
  };
  return (
    <>
      <button onClick={onClick}>高亮</button>
      <MineruViewer ref={v} zip="/sample.zip" />
    </>
  );
}

方法	签名	说明
setHighlights	(groups: HighlightGroup[]) => void	互斥替换全部高亮，以最后一组为锚点滚动
addHighlight	(group: HighlightGroup) => void	追加/更新一组（按 id 去重），多组共存
clearHighlights	() => void	清空全部高亮
focusBlock	(blockId: string) => void	定位并居中到某块（含左栏联动）
loadZip	(input: File|ArrayBuffer|string) => Promise<void>	重新加载产物

HighlightGroup 结构

interface HighlightGroup {
  id?: string;        // 用于 addHighlight 去重 / 更新
  blockIds: string[]; // 命中的物理块 id（稳定句柄）
  color?: string;
  label?: string;
  meta?: any;
}

mount 命令式挂载

无需 React 工程也能用（返回带 unmount 的句柄）：

import { mount } from "@mineru-viewer/react";
const h = mount("#app", { zip: "/sample.zip" });
h.addHighlight({ id: "x", blockIds: ["b-1"] });
h.focusBlock("b-1");
h.unmount(); // 卸载 React root

返回的 h 提供：setHighlights / addHighlight / clearHighlights / focusBlock / loadZip / unmount。