@mxmweb/file-viewer v1.7.7

@mxmweb/file-viewer

一个功能强大的 React 文件预览组件，支持 PDF、Excel、CSV、Markdown 等多种文件格式的预览和标注功能。

✨ 特性

• 📄 支持多种文件格式
  • PDF 文件预览和标注
  • Excel/CSV 表格预览和单元格标注
  • Markdown 文档预览和文本标注
• 🎨 现代化 UI 设计，基于 Tailwind CSS
• 📱 响应式布局，完美适配移动端
• 🛠️ 可配置的工具栏
• ⚡️ 自动文件类型检测
• 🎯 支持文件下载
• ✏️ 灵活的标注系统
• 🔍 内置缩放控制
• 📚 支持大文件 PDF 分页懒加载
• 🌐 支持自定义 PDF.js 资源路径
• 🧩 支持 CSV 文件，样式和标注体验与 Excel 完全一致
• 🗂️ 表格标注 sheetName 可选，未传时自动应用于当前 sheet，兼容 csv 单表场景

📦 安装

npm install @mxmweb/file-viewer
# 或者
yarn add @mxmweb/file-viewer
# 或者
pnpm add @mxmweb/file-viewer

🚀 快速开始

PDF 预览

在使用 PDF 预览功能之前，需要先注册 PDF.js worker 和其他资源：

import { registerPDFWorker, registerCMap, registerStandardFonts,registerLuckysheetResources } from '@mxmweb/file-viewer';

//xlsx，csv,xls的渲染工具
registerLuckysheetResources('/your/custom/path/');

// 在应用入口注册 worker
registerPDFWorker('/worker/pdf.worker.min.js');

// 如果需要支持中文等非拉丁字符，注册 cMap
registerCMap('/pdfjs/cmaps/');

// 如果需要支持特殊字体，注册标准字体
registerStandardFonts('/pdfjs/standard_fonts/');

基础使用示例：

import FileViewer from '@mxmweb/file-viewer';
import '@mxmweb/file-viewer/dist/assets/style.css'
function App() {
  return (
    <FileViewer
      content="/example.pdf"
      onClose={() => setIsOpen(false)}
      tools={{
        annotation: true,
        download: true,
        close: true
      }}
    />
  );
}

📖 API

资源注册函数

FileViewer Props

ToolConfig 配置

interface ToolConfig {
  annotation?: boolean; // 是否显示标注工具
  download?: boolean;   // 是否显示下载按钮
  close?: boolean;      // 是否显示关闭按钮
}

const defaultTools = {
  annotation: true,
  download: true,
  close: true
}

标注类型定义

// PDF 标注
interface Annotation {
  id: string;
  pageNumber: number;
  x: number;
  y: number;
  width: number;
  height: number;
  content: string;
  color?: string;
}

// Excel/CSV 标注
interface SheetAnnotation {
  id: string;
  offsets: {
    row: number;
    col: number;
  };
  sheetName?: string; // 可选，未传时自动应用于当前 sheet
  color: string;
  content?: string;
}

// Markdown 标注
interface MDAnnotation {
  start: number;
  end: number;
  color?: string;
}

💡 使用示例

PDF 文件预览

import FileViewer from '@mxmweb/file-viewer';
import type { Annotation } from '@mxmweb/file-viewer';

const mockAnnotations: Annotation[] = [
  {
    id: 'anno-1',
    pageNumber: 1,
    x: 0.1,
    y: 0.2,
    width: 0.3,
    height: 0.1,
    content: '这里是第一页的标注',
    color: '#FFEB3B'
  },
  {
    id: 'anno-2',
    pageNumber: 2,
    x: 0.5,
    y: 0.4,
    width: 0.2,
    height: 0.15,
    content: '第二页的高亮区域',
    color: '#4FC3F7'
  }
];

function PDFWithAnnotations() {
  const [annotations, setAnnotations] = useState<Annotation[]>(mockAnnotations);

  const handleAnnotationChange = (annotation: Annotation) => {
    setAnnotations(prev =>
      prev.some(a => a.id === annotation.id)
        ? prev.map(a => (a.id === annotation.id ? annotation : a))
        : [...prev, annotation]
    );
  };

  const handleAnnotationDelete = (id: string) => {
    setAnnotations(prev => prev.filter(a => a.id !== id));
  };

  return (
    <FileViewer
      content="/example.pdf"
      annotations={annotations}
      onAnnotationChange={handleAnnotationChange}
      onAnnotationDelete={handleAnnotationDelete}
      tools={{
        annotation: true,
        download: true
      }}
    />
  );
}

Excel/CSV 文件预览

import FileViewer from '@mxmweb/file-viewer';
import type { SheetAnnotation } from '@mxmweb/file-viewer';

const mockSheetAnnotations: SheetAnnotation[] = [
  {
    id: 'sheet-anno-1',
    offsets: { row: 2, col: 3 },
    // sheetName 可选，不传时自动应用于当前 sheet
    color: '#FFE599',
    content: '高亮单元格'
  }
];

function SheetWithAnnotations() {
  return (
    <FileViewer
      content="/example.csv"
      annotations={mockSheetAnnotations}
      // 也支持 xlsx
      // content="/example.xlsx"
      tools={{
        annotation: true,
        download: true
      }}
    />
  );
}

initialPage 用法示例

PDF 打开时跳转到第 2 页

<FileViewer
  content="/example.pdf"
  initialPage={2} // 打开时自动跳转到第2页
  ...其他props
/>

Excel/CSV 打开时跳转到 sheetName

<FileViewer
  content="/example.xlsx"
  initialPage="利润表" // 打开时自动跳转到 sheetName 为"利润表"的表
  ...其他props
/>

⚠️ 关于 Tailwind 全局样式

本组件库基于 Tailwind CSS 构建，如需避免全局样式污染，建议只在主项目入口引入 tailwind 样式，不要在组件库入口引入。

如需自定义主题色，建议通过 CSS 变量或主项目全局覆盖，不要直接用 border-border 这类变量色工具类。