@eternalheart/react-file-preview 1.4.0 → 1.5.0

package/README.zh-CN.md

@@ -4,24 +4,23 @@
 
 一个现代化、功能丰富的 React 文件预览组件,支持图片、视频、音频、PDF、Office 文档(Word、Excel、PowerPoint)、Markdown 和代码文件预览。
 
-## ✨ 特性
-
-- 🎨 **现代化 UI** - Apple 风格的简约设计,毛玻璃效果
-- 📁 **多格式支持** - 支持 20+ 种文件格式
-- 🪟 **两种展示模式** - 全屏弹窗 **或** 嵌入式内联预览
-- 🖼️ **强大的图片查看器** - 缩放、旋转、拖拽、滚轮缩放
-- 🎬 **自定义视频播放器** - 基于 Video.js,支持多种视频格式
-- 🎵 **自定义音频播放器** - 精美的音频控制界面
-- 📄 **PDF 查看器** - 支持分页浏览
-- 📊 **Office 文档支持** - Word、Excel、PowerPoint 文件预览
-- 📝 **Markdown 渲染** - 支持 GitHub Flavored Markdown
-- 💻 **代码高亮** - 支持 40+ 种编程语言
-- 🎭 **流畅动画** - 基于 Framer Motion
-- 📱 **响应式设计** - 适配各种屏幕尺寸
-- ⌨️ **键盘导航** - 支持方向键和 ESC 键
-- 🎯 **拖拽上传** - 支持拖拽文件上传
-
-## 📦 安装
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/2728.svg" width="20" height="20" alt="✨" /> 特性
+
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f3a8.svg" width="16" height="16" alt="🎨" style="vertical-align: middle;" /> **现代化 UI** - 简洁现代的界面设计，流畅动画
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f4c1.svg" width="16" height="16" alt="📁" style="vertical-align: middle;" /> **多格式支持** - 支持 20+ 种文件格式
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1fa9f.svg" width="16" height="16" alt="🪟" style="vertical-align: middle;" /> **两种展示模式** - 全屏弹窗 **或** 嵌入式内联预览
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f5bc.svg" width="16" height="16" alt="🖼️" style="vertical-align: middle;" /> **强大的图片查看器** - 缩放、旋转、拖拽、滚轮缩放
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f3ac.svg" width="16" height="16" alt="🎬" style="vertical-align: middle;" /> **自定义视频播放器** - 基于 Video.js,支持多种视频格式
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f3b5.svg" width="16" height="16" alt="🎵" style="vertical-align: middle;" /> **自定义音频播放器** - 精美的音频控制界面
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f4c4.svg" width="16" height="16" alt="📄" style="vertical-align: middle;" /> **PDF 查看器** - 支持分页浏览
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f4ca.svg" width="16" height="16" alt="📊" style="vertical-align: middle;" /> **Office 文档支持** - Word、Excel、PowerPoint 文件预览
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f4dd.svg" width="16" height="16" alt="📝" style="vertical-align: middle;" /> **Markdown 渲染** - 支持 GitHub Flavored Markdown
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f4bb.svg" width="16" height="16" alt="💻" style="vertical-align: middle;" /> **代码高亮** - 支持 40+ 种编程语言
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f3ad.svg" width="16" height="16" alt="🎭" style="vertical-align: middle;" /> **流畅动画** - 基于 Framer Motion
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f4f1.svg" width="16" height="16" alt="📱" style="vertical-align: middle;" /> **响应式设计** - 适配各种屏幕尺寸
+<img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/2328.svg" width="16" height="16" alt="⌨️" style="vertical-align: middle;" /> **键盘导航** - 支持方向键和 ESC 键
+
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f4e6.svg" width="20" height="20" alt="📦" /> 安装
 
 ```bash
 # 使用 npm
@@ -136,7 +135,7 @@ export default defineConfig({
 
 > 说明:`@jsquash/avif` 仅在浏览器不原生支持 AVIF 时作为兜底使用(Chrome 85+、Firefox 93+、Safari 16+ 均已原生支持)。如果你的目标浏览器都覆盖原生支持范围,也可以直接从依赖中移除 `@jsquash/avif`。
 
-## 🚀 快速开始
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f680.svg" width="20" height="20" alt="🚀" /> 快速开始
 
 📖 **第一次使用？** 查看 [快速开始指南](./QUICK_START.md) 获取 5 分钟入门教程！
 
@@ -187,14 +186,18 @@ import { FilePreviewModal, PreviewFileInput } from '@eternalheart/react-file-pre
 import '@eternalheart/react-file-preview/style.css';
 
 function App() {
+  // 假设 file1 来自 File API：<input type="file">、拖拽、
+  // 剪贴板粘贴,或 fetch().then(r => r.blob())
+  const file1 = new File(['content'], 'example.txt', { type: 'text/plain' });
+
   const files: PreviewFileInput[] = [
-    // 1. 原生 File 对象
+    // 1. 原生 File 对象（组件卸载时自动释放）
     file1,
 
-    // 2. HTTP URL 字符串
+    // 2. HTTP URL 字符串（按需加载）
     'https://example.com/image.jpg',
 
-    // 3. 带元数据的文件对象
+    // 3. 带元数据的文件对象（推荐用于远程资源）
     {
       name: 'document.pdf',
       type: 'application/pdf',
@@ -203,6 +206,9 @@ function App() {
     },
   ];
 
+  // 内存提示: 如果你通过 URL.createObjectURL() 生成 URL,
+  // 文件移除时请调用 URL.revokeObjectURL() 避免内存泄漏。
+
   return (
     <FilePreviewModal
       files={files}
@@ -256,7 +262,7 @@ function InlinePreview() {
 <FilePreviewEmbed files={files} width={800} height={500} />
 ```
 
-## 💡 使用示例
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f4a1.svg" width="20" height="20" alt="💡" /> 使用示例
 
 ### 预览 PowerPoint 文件
 
@@ -309,7 +315,7 @@ const files = [
 />
 ```
 
-## 📖 支持的文件格式
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f4d6.svg" width="20" height="20" alt="📖" /> 支持的文件格式
 
 ### 图片
 - **格式**: JPG, PNG, GIF, WebP, SVG, BMP, ICO
@@ -358,7 +364,56 @@ const files = [
 ### 电子书
 - **EPUB**: 章节导航、翻页
 
-## 🎮 API 参考
+## ⚠️ 功能限制与性能说明
+
+### 支持等级
+
+**✅ 完全支持（生产可用）**
+- 图片（JPG, PNG, GIF, WebP, SVG, BMP, ICO）
+- 视频（MP4, WebM, OGG）
+- 音频（MP3, WAV, OGG）
+- PDF
+- Markdown
+- 代码文件（通过 Shiki 支持 40+ 种语言，按需加载）
+- JSON, CSV, XML
+
+**⚠️ 部分支持（仅供预览）**
+- **Office（DOCX, XLSX, PPTX）**: 基础布局和文本渲染。复杂格式（图表、宏、嵌入对象）可能无法准确渲染。
+- **ZIP**: 目录树浏览 + 文本/代码/图片内联预览。大型压缩包（>100MB）可能导致性能问题。
+- **字体（TTF, OTF, WOFF）**: 元数据 + 字符预览。不支持完整字体特性测试。
+
+**🧪 实验性支持**
+- **MSG（Outlook 邮件）**: 邮件头和纯文本正文。复杂 HTML 正文可能无法正确渲染。
+- **EPUB**: 基础章节导航。CSS 样式可能与原生阅读器有差异。不支持 DRM 保护文件。
+- **字幕格式（SRT, ASS, TTML, LRC）**: 仅文本显示。不支持视频同步或高级样式。
+
+### 性能边界
+
+| 文件大小 | 状态 | 说明 |
+|---------|------|------|
+| < 50MB | ✅ 推荐 | 流畅的预览体验 |
+| 50-100MB | ⚠️ 可能卡顿 | 加载时 UI 可能无响应 |
+| > 100MB | ❌ 不推荐 | 可能超出浏览器内存限制 |
+
+**特殊情况：**
+- **ZIP 压缩包**: 性能取决于文件数量，而非仅体积
+- **Office 文档**: 复杂文件（>200 页、大量图片）可能超时
+- **代码高亮**: >5MB 的文件可能需要 3-5 秒高亮时间
+
+### 浏览器兼容性
+
+**最低要求：**
+- Chrome 90+ / Edge 90+
+- Firefox 88+
+- Safari 14+
+
+**已知限制：**
+- **Safari iOS**: 视频自动播放需要用户交互
+- **Firefox**: AVIF 支持需要 Firefox 93+（已包含降级解码器）
+- **Office 格式**: 不同浏览器渲染质量有差异
+- **EPUB**: 旧版浏览器可能不支持某些 CSS 特性
+
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f3ae.svg" width="20" height="20" alt="🎮" /> API 参考
 
 ### FilePreviewModal Props
 
@@ -374,6 +429,7 @@ const files = [
 | `messages` | `Partial<Record<Locale, Partial<Messages>>>` | ❌ | 自定义翻译覆盖 |
 | `headless` | `boolean` | ❌ | 无头模式，隐藏工具栏和导航箭头 |
 | `theme` | `Theme` | ❌ | 主题模式: `'auto' \| 'dark' \| 'light'`（默认 `'dark'`） |
+| `showDownload` | `boolean` | ❌ | 是否显示下载按钮（默认 `true`） |
 
 ### FilePreviewEmbed Props
 
@@ -391,6 +447,7 @@ const files = [
 | `messages` | `Partial<Record<Locale, Partial<Messages>>>` | ❌ | - | 自定义翻译覆盖 |
 | `headless` | `boolean` | ❌ | `false` | 无头模式，隐藏工具栏和导航箭头 |
 | `theme` | `Theme` | ❌ | `'dark'` | 主题模式: `'auto' \| 'dark' \| 'light'` |
+| `showDownload` | `boolean` | ❌ | `true` | 是否显示下载按钮 |
 
 > `FilePreviewEmbed` 没有 `isOpen` / `onClose`,若要显示/隐藏,请在父组件中条件渲染。同时它不会显示工具栏上的关闭按钮。
 
@@ -510,7 +567,7 @@ const files = [
 #### 电子书
 - **EPUB**: `application/epub+zip` (.epub)
 
-## 🌐 国际化（i18n）
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f310.svg" width="20" height="20" alt="🌐" /> 国际化（i18n）
 
 内置中文（默认）和英文，零外部依赖。
 
@@ -528,7 +585,353 @@ const files = [
 
 在自定义渲染器中可通过 `useTranslator()` hook 获取翻译函数。
 
-## 🎨 自定义样式
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f9e9.svg" width="20" height="20" alt="🧩" /> 自定义渲染器
+
+本库支持自定义渲染器以处理内置不支持的文件类型。自定义渲染器可以可选地提供工具栏配置并集成到本库的架构中。
+
+### 事件驱动的工具栏更新
+
+自定义渲染器可以通过事件驱动机制实现实时工具栏更新：
+
+**优势：**
+- **实时更新**：工具栏立即反映状态变化
+- **更好的性能**：无轮询开销或不必要的重新渲染
+- **类型安全**：完整的 TypeScript 接口支持
+
+**实现方式：**
+
+```tsx
+import { forwardRef, useImperativeHandle, useState, useEffect, useMemo, useCallback } from 'react';
+import { ToolbarEventEmitter } from '@eternalheart/react-file-preview';
+import type { RendererHandle, ToolbarGroup } from '@eternalheart/react-file-preview';
+
+interface CustomRendererProps {
+  url: string;
+  onPageChange?: (current: number, total: number) => void;
+}
+
+export const CustomRenderer = forwardRef<RendererHandle, CustomRendererProps>((props, ref) => {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [totalPages, setTotalPages] = useState(10);
+  const emitter = useMemo(() => new ToolbarEventEmitter(), []);
+  
+  // 状态变化时通知工具栏
+  useEffect(() => {
+    emitter.notify();
+    props.onPageChange?.(currentPage, totalPages);
+  }, [currentPage, totalPages, emitter, props]);
+  
+  const getToolbarGroups = useCallback((): ToolbarGroup[] => [
+    {
+      items: [
+        {
+          type: 'button',
+          icon: <ChevronLeft className="w-4 h-4" />,
+          tooltip: '上一页',
+          action: () => setCurrentPage(p => Math.max(1, p - 1)),
+          disabled: currentPage <= 1
+        },
+        {
+          type: 'text',
+          content: `${currentPage} / ${totalPages}`,
+          minWidth: '4rem'
+        },
+        {
+          type: 'button',
+          icon: <ChevronRight className="w-4 h-4" />,
+          tooltip: '下一页',
+          action: () => setCurrentPage(p => Math.min(totalPages, p + 1)),
+          disabled: currentPage >= totalPages
+        }
+      ]
+    }
+  ], [currentPage, totalPages]);
+  
+  useImperativeHandle(ref, () => ({
+    getToolbarGroups,
+    onToolbarChange: (listener) => emitter.subscribe(listener)
+  }), [getToolbarGroups, emitter]);
+  
+  return <div>你的自定义渲染器 UI</div>;
+});
+```
+
+**主组件使用：**
+
+```tsx
+import { CustomRenderer } from './CustomRenderer';
+
+<FilePreviewModal
+  files={files}
+  customRenderers={[
+    {
+      test: (file) => file.type === 'application/custom',
+      component: CustomRenderer
+    }
+  ]}
+/>
+```
+
+主组件会自动检测 `onToolbarChange` 并订阅事件。如果未实现，则回退到轮询以保持向后兼容。
+
+### Renderer 懒加载
+
+所有内置渲染器通过 `React.lazy` 实现代码分割，以最小化主包体积并提升初始加载性能。
+
+**架构：**
+
+- **注册**：渲染器在 `src/renderers/lazy.tsx` 中注册，使用 named export 并通过 `React.lazy` 包装
+- **加载**：每个渲染器是独立的 chunk，按需加载
+- **回退**：`<Suspense>` 配合 `<RendererLoading />` 处理加载状态
+
+**打包体积影响：**
+
+- 主入口：gzip ≤ 80 KB（CI 强制约束）
+- 每个渲染器：独立异步 chunk
+- 整个库：gzip ≤ 800 KB（所有渲染器合计）
+
+**实现示例：**
+
+```tsx
+// src/renderers/lazy.tsx
+import { lazy } from 'react';
+import type { CustomRenderer as CustomRendererImpl } from './Custom';
+
+export const CustomRenderer: Lazy<typeof CustomRendererImpl> = lazy(() =>
+  import('./Custom').then((m) => ({ default: m.CustomRenderer }))
+);
+```
+
+```tsx
+// src/FilePreviewContent.tsx
+import { CustomRenderer } from './renderers/lazy';  // ✅ 懒加载导入
+// 禁止: import { CustomRenderer } from './renderers/Custom';  // ❌ 直接导入会破坏代码分割
+
+<Suspense fallback={<RendererLoading />}>
+  {fileType === 'custom' && <CustomRenderer ref={rendererRef} url={currentFile.url} />}
+</Suspense>
+```
+
+**用于自定义渲染器：**
+
+如果你希望自定义渲染器也享受代码分割，可以使用相同的模式：
+
+```tsx
+import { lazy, Suspense } from 'react';
+
+const MyCustomRenderer = lazy(() => import('./MyCustomRenderer'));
+
+<FilePreviewModal
+  files={files}
+  customRenderers={[
+    {
+      test: (file) => file.type === 'application/custom',
+      component: (props) => (
+        <Suspense fallback={<div>加载中...</div>}>
+          <MyCustomRenderer {...props} />
+        </Suspense>
+      )
+    }
+  ]}
+/>
+```
+
+### i18n 集成
+
+自定义渲染器可以通过 `useTranslator()` hook 访问本库的 i18n 系统，实现一致的多语言支持。
+
+**架构：**
+
+- **字典源**：`file-preview-core/src/i18n/messages/`（zh-CN.ts、en-US.ts）
+- **禁止硬编码**：所有用户可见文案必须使用翻译 key
+- **自动切换语言**：跟随 `FilePreviewModal` 的 `locale` prop
+
+**在自定义渲染器中使用：**
+
+```tsx
+import { useTranslator } from '@eternalheart/react-file-preview';
+
+export const CustomRenderer = forwardRef<RendererHandle, Props>((props, ref) => {
+  const t = useTranslator();
+  const [error, setError] = useState<string | null>(null);
+  
+  if (error) {
+    return (
+      <div className="rfp-text-fg-primary">
+        {t('custom.load_failed')}: {error}
+      </div>
+    );
+  }
+  
+  return (
+    <div>
+      <button>{t('common.download')}</button>
+      <span>{t('custom.loading')}</span>
+    </div>
+  );
+});
+```
+
+**新增自定义翻译键：**
+
+对于自定义渲染器，通过 `messages` prop 扩展翻译（不要修改 `node_modules` 中的源文件）：
+
+```tsx
+<FilePreviewModal
+  files={files}
+  locale="en-US"
+  messages={{
+    'en-US': {
+      'custom.load_failed': 'Failed to load custom file',
+      'custom.file_size': 'File size: {size} KB'
+    },
+    'zh-CN': {
+      'custom.load_failed': '自定义文件加载失败',
+      'custom.file_size': '文件大小: {size} KB'
+    }
+  }}
+  customRenderers={[...]}
+/>
+```
+
+**指南：**
+- 使用 `<scope>.<snake_name>` 格式（如 `custom.load_failed`、`custom.parse_error`）
+- 为所有启用的语言（`zh-CN` 和 `en-US`）提供翻译
+- 已有通用 key：`common.loading`、`common.download`、`common.close`、`toolbar.*`
+
+**参数化翻译：**
+
+```tsx
+// 字典: 'custom.file_size': '文件大小: {size} KB'
+t('custom.file_size', { size: 1024 })  // → "文件大小: 1024 KB"
+```
+
+**工具栏集成：**
+
+工具栏项也应使用翻译字符串：
+
+```tsx
+const getToolbarGroups = useCallback((): ToolbarGroup[] => [
+  {
+    items: [
+      {
+        type: 'button',
+        icon: <Download className="rfp-w-4 rfp-h-4" />,
+        tooltip: t('common.download'),  // ✅ 已翻译
+        action: handleDownload
+      }
+    ]
+  }
+], [t]);
+```
+
+### 主题适配
+
+自定义渲染器必须使用语义化颜色 token 以支持本库的 `'auto' | 'dark' | 'light'` 主题系统。
+
+**语义化 Token 系统：**
+
+所有颜色定义为 CSS 变量（`--fp-*`），通过 Tailwind 类暴露，前缀为 `rfp-`：
+
+| 用途 | 类名 | 说明 |
+|------|------|------|
+| **文字（fg）** | | |
+| 主文本 | `rfp-text-fg-primary` | 最高对比度 |
+| 正文 | `rfp-text-fg-secondary` | 默认文字 |
+| 次要文本 | `rfp-text-fg-tertiary` | 副本、计数器 |
+| 弱化文本 | `rfp-text-fg-muted` | 占位符 |
+| 禁用文本 | `rfp-text-fg-disabled` | 禁用按钮 |
+| **背景（surface）** | | |
+| 表面层 1 | `rfp-bg-surface-1` | 卡片、最弱 |
+| 表面层 2 | `rfp-bg-surface-2` | hover 状态 |
+| 表面层 3 | `rfp-bg-surface-3` | 强调 |
+| 工具栏 | `rfp-bg-surface-toolbar` | 顶部工具栏 |
+| **边框** | | |
+| 弱边框 | `rfp-border-line-weak` | 细线 |
+| 标准边框 | `rfp-border-line` | 默认边框 |
+| 强边框 | `rfp-border-line-strong` | 强调 |
+| **代码** | | |
+| 代码背景 | `rfp-bg-code-bg` | Dark：#1e1e1e / Light：#f6f8fa |
+| 代码文字 | `rfp-text-code-fg` | 跟随主题 |
+| **强调（accent）** | | |
+| 强调背景 | `rfp-bg-accent` | 主按钮 |
+| 强调 hover | `rfp-bg-accent-hover` | hover 状态 |
+
+**✅ 正确用法：**
+
+```tsx
+export const CustomRenderer = forwardRef<RendererHandle, Props>((props, ref) => {
+  return (
+    <div className="rfp-bg-surface-1 rfp-border rfp-border-line-weak rfp-rounded">
+      <h2 className="rfp-text-fg-primary rfp-text-lg">标题</h2>
+      <p className="rfp-text-fg-secondary">正文内容</p>
+      <button className="rfp-bg-surface-2 hover:rfp-bg-surface-3 rfp-text-fg-primary">
+        点击
+      </button>
+      <pre className="rfp-bg-code-bg rfp-text-code-fg">
+        {code}
+      </pre>
+    </div>
+  );
+});
+```
+
+**❌ 错误用法（禁止使用）：**
+
+```tsx
+// ❌ 字面色类 — 会破坏主题切换
+<div className="rfp-text-white/90 rfp-bg-white/10 rfp-border-white/15">
+<div className="rfp-text-gray-700 rfp-bg-gray-100">
+
+// ❌ 内联字面色
+<div style={{ color: '#ffffff', background: '#1f2937' }}>
+
+// ❌ 硬编码暗色
+<div style={{ background: '#1e1e1e' }}>  // 应改用 rfp-bg-code-bg
+```
+
+**支持主题的三方库：**
+
+对于具有 theme prop 的库（如 `react-syntax-highlighter`），使用 `useResolvedTheme()`：
+
+```tsx
+import { useResolvedTheme } from '@eternalheart/react-file-preview';
+import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
+import { vscDarkPlus, vs } from 'react-syntax-highlighter/dist/esm/styles/prism';
+
+export const CodeRenderer = forwardRef<RendererHandle, Props>((props, ref) => {
+  const resolvedTheme = useResolvedTheme();  // 'dark' | 'light'
+  
+  return (
+    <SyntaxHighlighter
+      language="javascript"
+      style={resolvedTheme === 'light' ? vs : vscDarkPlus}
+    >
+      {code}
+    </SyntaxHighlighter>
+  );
+});
+```
+
+**测试：**
+
+务必在 Light 和 Dark 两个主题下测试你的自定义渲染器：
+
+```tsx
+<FilePreviewModal
+  files={files}
+  theme="light"  // 在 'light'、'dark'、'auto' 间切换
+  customRenderers={[...]}
+/>
+```
+
+验证：
+- 文字在两个主题下都可读（无白底白字或黑底黑字）
+- 边框和分隔线清晰可见
+- hover 状态有足够对比度
+- 代码块跟随主题（不固定为暗色）
+
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f3a8.svg" width="20" height="20" alt="🎨" /> 自定义样式
 
 组件使用 Tailwind CSS 构建,您可以通过覆盖 CSS 变量来自定义样式:
 
@@ -540,18 +943,18 @@ const files = [
 }
 ```
 
-## ⌨️ 键盘快捷键
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/2328.svg" width="20" height="20" alt="⌨️" /> 键盘快捷键
 
 - `ESC` - 关闭预览
 - `←` - 上一个文件
 - `→` - 下一个文件
 - `滚轮` - 缩放图片 (仅图片预览)
 
-## 📚 文档
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f4da.svg" width="20" height="20" alt="📚" /> 文档
 
 - [在线演示](https://wh131462.github.io/file-preview) - 在线 Demo
 
-## 🤖 Context7 支持
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f916.svg" width="20" height="20" alt="🤖" /> Context7 支持
 
 本项目支持 [Context7](https://context7.com) MCP Server。如果你正在使用 AI 编程助手（如 Claude Code、Cursor 等），可以配置 Context7 MCP Server 来获取 `@eternalheart/react-file-preview` 的最新文档和代码示例，从而获得更好的 AI 辅助开发体验。
 
@@ -563,33 +966,7 @@ const files = [
 
 > 更多关于 Context7 的配置方式，请访问 [Context7 官方文档](https://github.com/upstash/context7)。
 
-## 📦 包信息
-
-### 打包体积
-
-- **ESM**: ~54 KB (gzipped: ~12 KB)
-- **CJS**: ~37 KB (gzipped: ~11 KB)
-- **CSS**: ~56 KB (gzipped: ~14 KB)
-
-### Peer Dependencies
-
-- `react`: ^18.0.0
-- `react-dom`: ^18.0.0
-
-### 导出
-
-```json
-{
-  ".": {
-    "types": "./lib/index.d.ts",
-    "import": "./lib/index.mjs",
-    "require": "./lib/index.cjs"
-  },
-  "./style.css": "./lib/index.css"
-}
-```
-
-## 🛠️ 开发
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f6e0.svg" width="20" height="20" alt="🛠️" /> 开发
 
 ### 库开发
 
@@ -627,15 +1004,15 @@ react-file-preview/
 └── vite.config.lib.ts        # 库构建配置
 ```
 
-## 📄 许可证
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f4c4.svg" width="20" height="20" alt="📄" /> 许可证
 
 [MIT](./LICENSE) © [EternalHeart](https://github.com/wh131462)
 
-## 🤝 贡献
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f91d.svg" width="20" height="20" alt="🤝" /> 贡献
 
 欢迎提交 Issue 和 Pull Request!
 
-## 🔗 相关链接
+## <img src="https://cdn.jsdelivr.net/gh/twitter/twemoji@latest/assets/svg/1f517.svg" width="20" height="20" alt="🔗" /> 相关链接
 
 - [GitHub](https://github.com/wh131462/file-preview)
 - [npm](https://www.npmjs.com/package/@eternalheart/react-file-preview)

package/lib/FilePreviewContent.d.ts

@@ -20,6 +20,7 @@ export interface FilePreviewContentProps {
     shouldFetchAsBlob?: ShouldFetchAsBlob;
     onDownload?: (file: PreviewFile) => void;
     onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+    showDownload?: boolean;
 }
 export declare const FilePreviewContent: React.FC<FilePreviewContentProps>;
 //# sourceMappingURL=FilePreviewContent.d.ts.map

package/lib/FilePreviewContent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FilePreviewContent.d.ts","sourceRoot":"","sources":["../src/FilePreviewContent.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAuC,MAAM,OAAO,CAAC;AAC5D,OAAO,EAAiC,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAmB,KAAK,KAAK,EAA2B,MAAM,iCAAiC,CAAC;AAGlK,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAyB,MAAM,SAAS,CAAC;AACvF,OAAO,KAAK,EAAE,0BAA0B,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAuCtJ,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC5D,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;IACzC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;CAC9D;AAED,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAAE,CAAC,uBAAuB,CAWhE,CAAC"}
+{"version":3,"file":"FilePreviewContent.d.ts","sourceRoot":"","sources":["../src/FilePreviewContent.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA4D,MAAM,OAAO,CAAC;AACjF,OAAO,EAAiC,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAmB,KAAK,KAAK,EAA2B,MAAM,iCAAiC,CAAC;AAGlK,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAyB,MAAM,SAAS,CAAC;AACvF,OAAO,KAAK,EAAE,0BAA0B,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAetJ,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC5D,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;IACzC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC;IAC7D,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAAE,CAAC,uBAAuB,CAWhE,CAAC"}

package/lib/FilePreviewEmbed.d.ts

@@ -31,6 +31,8 @@ interface FilePreviewEmbedProps {
     onDownload?: (file: PreviewFile) => void | Promise<void>;
     /** 关闭回调：传入后工具栏显示关闭按钮 */
     onClose?: () => void;
+    /** 是否显示下载按钮，默认 true */
+    showDownload?: boolean;
 }
 export declare const FilePreviewEmbed: React.FC<FilePreviewEmbedProps>;
 export {};

package/lib/FilePreviewEmbed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FilePreviewEmbed.d.ts","sourceRoot":"","sources":["../src/FilePreviewEmbed.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,0BAA0B,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAE/K,UAAU,qBAAqB;IAC7B,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtD,sBAAsB;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qBAAqB;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,oBAAoB;IACpB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC5D,mDAAmD;IACnD,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,4BAA4B;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,4CAA4C;IAC5C,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CA+D5D,CAAC"}
+{"version":3,"file":"FilePreviewEmbed.d.ts","sourceRoot":"","sources":["../src/FilePreviewEmbed.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,0BAA0B,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAE/K,UAAU,qBAAqB;IAC7B,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtD,sBAAsB;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qBAAqB;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,oBAAoB;IACpB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC5D,mDAAmD;IACnD,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,4BAA4B;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,4CAA4C;IAC5C,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,uBAAuB;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAiE5D,CAAC"}

package/lib/FilePreviewModal.d.ts

@@ -25,6 +25,8 @@ interface FilePreviewModalProps {
     shouldFetchAsBlob?: ShouldFetchAsBlob;
     /** 自定义下载回调；不传时库内默认通过 fetcher 拉 Blob 触发下载 */
     onDownload?: (file: PreviewFile) => void | Promise<void>;
+    /** 是否显示下载按钮，默认 true */
+    showDownload?: boolean;
 }
 export declare const FilePreviewModal: React.FC<FilePreviewModalProps>;
 export {};

package/lib/FilePreviewModal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FilePreviewModal.d.ts","sourceRoot":"","sources":["../src/FilePreviewModal.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,0BAA0B,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAE/K,UAAU,qBAAqB;IAC7B,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtD,sBAAsB;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qBAAqB;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,oBAAoB;IACpB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC5D,mDAAmD;IACnD,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,4BAA4B;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,4CAA4C;IAC5C,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAgG5D,CAAC"}
+{"version":3,"file":"FilePreviewModal.d.ts","sourceRoot":"","sources":["../src/FilePreviewModal.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE3D,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,0BAA0B,EAAE,WAAW,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAE/K,UAAU,qBAAqB;IAC7B,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACtD,sBAAsB;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qBAAqB;IACrB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,oBAAoB;IACpB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAC5D,mDAAmD;IACnD,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,4BAA4B;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,4CAA4C;IAC5C,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,uBAAuB;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAkG5D,CAAC"}