Textin OCR Frontend

一个用于展示 Textin 识别结果的 React 组件库，支持文件预览、坐标回显和结果展示。

目前已支持票据类解析结果（key-value）的展示，具体对应 Textin票据文字识别如国内通用票据识别、银行回单识别、电子承兑汇票识别等相关产品识别结果的展示。

组件库使用的数据结构是规范后的前端数据结构，使用时需要将 OCR 识别 API 返回的数据转换为前端使用的结构，具体参见本项目examples，原始数据结构参见 Textin 官网API 文档。

特性

• 📄 支持图片和 PDF 文件预览
• 🎯 支持文本区域坐标回显和高亮
• 🔄 预览区域和识别结果双向联动
• 📊 支持 JSON 格式结果展示
• 🎨 TODO：可自定义样式和主题

安装

拉取项目

git clone https://github.com/intsig-textin/textin-ocr-frontend.git

npm install textin-ocr-frontend
# 或
yarn add textin-ocr-frontend

快速开始

import { FilePreview, ResultView, JsonView } from "textin-ocr-frontend";

function App() {
  return (
    <div style={{ display: "flex" }}>
      <div style={{ flex: 1 }}>
        <FilePreview src="path/to/image.jpg" rects={rects} pages={pages} />
      </div>
      <div style={{ flex: 1 }}>
        <ResultView resultList={resultList} />
      </div>
    </div>
  );
}

组件说明

1. FilePreview 文件预览组件

文件预览组件，支持 PDF 和图片预览，支持缩放、旋转、分页等功能。

Props

参数	说明	类型	默认值
className	自定义类名	string	-
style	自定义样式	React.CSSProperties	-
src	文件源，支持 PDF 和图片数组	PDFSrc | string[]	-
rects	标注框数据	IRectItem[][]	-
pages	页面数据	IPageItem[]	-
getContainerRef	获取容器引用	React.RefObject	-
activeContentId	当前选中的内容 ID	string	-
showMark	是否显示标注	boolean	-
hasPagination	是否显示分页	boolean	-
hasToolbar	是否显示工具栏	boolean	-
toolbarOptions	工具栏配置	ToolbarOptions	-
toolbarStyle	工具栏样式	React.CSSProperties	-
loading	加载中状态	boolean	-
loadingComponent	自定义加载组件	ReactNode	-

2. ResultView 结果展示组件

结果展示组件，支持表格和列表两种展示方式。

Props

参数	说明	类型	默认值
className	自定义类名	string	-
style	自定义样式	React.CSSProperties	-
resultList	结果列表	IResultListItem[]	-
getContainerRef	获取容器引用	React.RefObject	-
activeContentId	当前选中的内容 ID	string	-
activeParentContentId	当前选中的内容所属的上级 ID	string	-
loading	加载中状态	boolean	-
loadingComponent	自定义加载组件	ReactNode	-

3. MarkLayer 标注层组件

标注层组件，用于在图片显示标注框。

Props

参数	说明	类型	默认值
className	自定义类名	string	-
style	自定义样式	React.CSSProperties	-
rects	标注框数据	IRectItem[]	-
rate	渲染比例（渲染宽度/原始宽度）	number	-
activeContentId	当前选中的内容 ID	string	-
getContainer	获取容器元素	() => HTMLElement | null | undefined	-
svgAttr	SVG 属性	SVGProps	-
onMouseDown	鼠标按下事件	(e: any) => void	-

4. JsonView JSON 展示组件

JSON 数据展示组件，用于格式化展示 JSON 数据。 本项目 JSON 数据采用react-json-view库渲染，API 保持一致，详细属性可参考其官方文档。

Props

参数	说明	类型	默认值
style	自定义样式	React.CSSProperties	-
src	JSON 数据	any	-
...rest	其他 react-json-view 属性	ReactJsonViewProps	-

API Interface 定义

PDFSrc

PDF 文件源配置

interface DocumentInitParameters {
  [key: string]: any;
  url?: string | URL;
  data?: TypedArray | ArrayBuffer | Array<number> | string;
  httpHeaders?: Object;
  withCredentials?: boolean;
  password?: string;
  length?: boolean;
}

type PDFSrc = DocumentInitParameters;

IRectItem

标注框数据

interface IRectItem {
  [key: string]: any;
  key?: string;
  type?: string;
  rect_type?: string;
  uid: string;
  parent_uid?: string;
  content_id: string;
  parent_id?: string;
  position: number[];
  angle?: number;
  render_text?: string;
}

IPageItem

页面数据

interface IPageItem {
  page_number: number;
  duration: number;
  ppi: number;
  width: number;
  height: number;
  angle?: number;
}

IResultListItem

结果列表项

interface IResultListItem extends IRectItem {
  type: string;
  description: string;
  no: number;
  list: IFieldItem[];
  flightList: IFieldItem[][];
  page_id?: number;
}

IFieldItem

字段项

interface IFieldItem extends IOriginFieldItem {
  uid: string;
  parent_uid?: string;
}

interface IOriginFieldItem {
  key: string;
  type?: string;
  value: string;
  description: string;
  position: number[];
}

ToolbarOptions

工具栏配置

interface ToolbarOptions {
  tools: PreviewToolItem[];
}

interface PreviewToolItem {
  Icon: React.ComponentType<any>;
  onClick: () => void;
  type: string;
  disabled?: boolean;
}

PreviewToolItem

工具栏配置项

interface PreviewToolItem {
  Icon: React.ComponentType<any>;  // 工具栏图标组件
  onClick: () => void;            // 点击事件处理函数
  type: string;                   // 工具类型
  disabled?: boolean;             // 是否禁用
}

Hooks

useContentLinkage

用于实现预览区域和识别结果的双向联动。

const { activeContentId, activeParentContentId, registerLinkage } =
  useContentLinkage({
    viewContainerRef,
    resultContainerRef,
  });

参数

参数	类型	必填	说明
viewContainerRef	React.RefObject<HTMLElement | null>	是	预览容器引用
resultContainerRef	React.RefObject<HTMLElement | null>	是	结果容器引用

返回值

属性	类型	说明
activeContentId	string	当前选中的内容 ID
activeParentContentId	string	当前选中的内容所属的父级 ID
registerLinkage	() => void	注册联动事件

usePDFMarkLayer

用于在 PDF 文档上实现标注层功能。

const { run } = usePDFMarkLayer({
  containerRef,
  pdfViewerRef,
  rects,
  pages,
  dpi,
  activeContentId,
  showMark,
});

参数

参数	类型	必填	说明
containerRef	React.RefObject	是	PDF 容器引用
pdfViewerRef	React.RefObject	否	PDF 查看器引用
rects	IRectItem[][]	否	标注框数据
pages	IPageItem[]	是	页面数据
dpi	number	否	分辨率
activeContentId	string	否	当前选中的内容 ID
showMark	boolean	否	是否显示标注

返回值

属性	类型	说明
run	() => void	运行标注层

usePreviewTool

用于实现预览工具栏功能，包括缩放、旋转和 1:1 还原。

const { tools, scale, rotate, position, onMouseDown, onWheel, resizeScale } =
  usePreviewTool({
    viewContainerRef,
    viewRef,
    toolbarOptions,
  });

参数

参数	类型	必填	说明
viewContainerRef	React.RefObject	是	预览容器引用
viewRef	React.RefObject	是	预览内容引用
toolbarOptions	ToolbarOptions	否	工具栏配置

返回值

属性	类型	说明
tools	PreviewToolItem[]	工具栏配置项
scale	number	当前缩放比例
rotate	number	当前旋转角度
position	{ x: number; y: number }	当前位移位置
onMouseDown	(event: any) => void	鼠标按下事件处理函数
onWheel	(event: WheelEvent) => void	滚轮事件处理函数
resizeScale	() => void	重置缩放比例函数

示例

图片示例

PDF示例

未来规划

• 组件支持更多自定义配置、样式覆盖等特性
• 支持可编辑、复制、导出结果
• 支持更多复杂类型如通用文档解析识别结果展示

二次开发

项目基于 vite 和 react 构建，您可将该项目 fork 到本地自主扩展：

拉取项目

git clone https://github.com/intsig-textin/textin-ocr-frontend.git

安装依赖

npm install

启动项目

npm run dev

浏览器访问 http://localhost:5173/

贡献

欢迎贡献代码！在开始之前，请阅读 CONTRIBUTING.md 以了解贡献流程和指南。

许可证

本项目采用 CC-NC License。