@eternalheart/react-file-preview 1.1.2 → 1.1.3

package/README.md

@@ -10,6 +10,7 @@ A modern, feature-rich file preview component for React with support for images,
 
 - 🎨 **Modern UI** - Apple-inspired minimalist design with glassmorphism effects
 - 📁 **Multi-format Support** - Supports 20+ file formats
+- 🪟 **Two Display Modes** - Full-screen modal **or** inline embedded preview
 - 🖼️ **Powerful Image Viewer** - Zoom, rotate, drag, mouse wheel zoom
 - 🎬 **Custom Video Player** - Built on Video.js, supports multiple video formats
 - 🎵 **Custom Audio Player** - Beautiful audio control interface
@@ -188,6 +189,48 @@ function App() {
 }
 ```
 
+### Embedded Mode (`FilePreviewEmbed`)
+
+Besides the full-screen modal, the library also ships an **embedded** variant that renders the preview inline inside any container. Useful for detail panels, side-by-side layouts, dashboards, etc.
+
+```tsx
+import { FilePreviewEmbed } from '@eternalheart/react-file-preview';
+import '@eternalheart/react-file-preview/style.css';
+import { useState } from 'react';
+
+function InlinePreview() {
+  const [index, setIndex] = useState(0);
+
+  const files = [
+    'https://example.com/image.jpg',
+    { name: 'document.pdf', type: 'application/pdf', url: '/doc.pdf' },
+  ];
+
+  return (
+    // The embedded preview fills its parent container by default.
+    <div style={{ width: '100%', height: 520 }}>
+      <FilePreviewEmbed
+        files={files}
+        currentIndex={index}
+        onNavigate={setIndex}
+      />
+    </div>
+  );
+}
+```
+
+Differences from `FilePreviewModal`:
+
+- No portal, no full-screen overlay, no `isOpen` / `onClose`
+- Does **not** show the close button in the toolbar
+- Keyboard navigation (←/→) is scoped to the embed container (focus-based)
+- Size defaults to `width: 100%; height: 100%`; override via `width` / `height` props
+
+```tsx
+// Explicit size
+<FilePreviewEmbed files={files} width={800} height={500} />
+```
+
 ## 💡 Usage Examples
 
 ### Preview PowerPoint Files
@@ -277,6 +320,37 @@ const files = [
 | `isOpen` | `boolean` | ✅ | Whether the modal is open |
 | `onClose` | `() => void` | ✅ | Close callback |
 | `onNavigate` | `(index: number) => void` | ❌ | Navigation callback |
+| `customRenderers` | `CustomRenderer[]` | ❌ | Custom renderers for specific file types |
+
+### FilePreviewEmbed Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `files` | `PreviewFileInput[]` | ✅ | - | Array of files |
+| `currentIndex` | `number` | ❌ | `0` | Current file index |
+| `onNavigate` | `(index: number) => void` | ❌ | - | Navigation callback |
+| `customRenderers` | `CustomRenderer[]` | ❌ | - | Custom renderers |
+| `width` | `number \| string` | ❌ | `'100%'` | Container width |
+| `height` | `number \| string` | ❌ | `'100%'` | Container height |
+| `className` | `string` | ❌ | - | Extra class on the root wrapper |
+| `style` | `CSSProperties` | ❌ | - | Extra inline style on the root wrapper |
+
+> `FilePreviewEmbed` has no `isOpen` / `onClose`. To hide/show it, conditionally render it from the parent. It also hides the close button in the toolbar.
+
+### FilePreviewContent (advanced)
+
+Both `FilePreviewModal` and `FilePreviewEmbed` are thin wrappers around the exported lower-level `FilePreviewContent` component. Use it directly when building a fully custom wrapper:
+
+```tsx
+import { FilePreviewContent } from '@eternalheart/react-file-preview';
+
+<FilePreviewContent
+  mode="embed"       // or "modal"
+  files={files}
+  currentIndex={index}
+  onNavigate={setIndex}
+/>
+```
 
 ### File Type Definitions
 

package/README.zh-CN.md

@@ -8,6 +8,7 @@
 
 - 🎨 **现代化 UI** - Apple 风格的简约设计,毛玻璃效果
 - 📁 **多格式支持** - 支持 20+ 种文件格式
+- 🪟 **两种展示模式** - 全屏弹窗 **或** 嵌入式内联预览
 - 🖼️ **强大的图片查看器** - 缩放、旋转、拖拽、滚轮缩放
 - 🎬 **自定义视频播放器** - 基于 Video.js,支持多种视频格式
 - 🎵 **自定义音频播放器** - 精美的音频控制界面
@@ -186,6 +187,48 @@ function App() {
 }
 ```
 
+### 嵌入模式 (`FilePreviewEmbed`)
+
+除了全屏弹窗,组件库还提供了**嵌入式**变体,可以将预览内联渲染到任意 div 容器中,适合详情面板、左右分栏布局、仪表盘等场景。
+
+```tsx
+import { FilePreviewEmbed } from '@eternalheart/react-file-preview';
+import '@eternalheart/react-file-preview/style.css';
+import { useState } from 'react';
+
+function InlinePreview() {
+  const [index, setIndex] = useState(0);
+
+  const files = [
+    'https://example.com/image.jpg',
+    { name: 'document.pdf', type: 'application/pdf', url: '/doc.pdf' },
+  ];
+
+  return (
+    // 嵌入式预览默认填充父容器
+    <div style={{ width: '100%', height: 520 }}>
+      <FilePreviewEmbed
+        files={files}
+        currentIndex={index}
+        onNavigate={setIndex}
+      />
+    </div>
+  );
+}
+```
+
+与 `FilePreviewModal` 的区别:
+
+- 不使用 Portal、无全屏遮罩、没有 `isOpen` / `onClose`
+- **不显示关闭按钮**
+- 键盘导航 (←/→) 作用域限定在嵌入容器内 (基于 focus)
+- 尺寸默认 `width: 100%; height: 100%`,可通过 `width` / `height` props 覆盖
+
+```tsx
+// 显式指定尺寸
+<FilePreviewEmbed files={files} width={800} height={500} />
+```
+
 ## 💡 使用示例
 
 ### 预览 PowerPoint 文件
@@ -275,6 +318,37 @@ const files = [
 | `isOpen` | `boolean` | ✅ | 是否打开预览 |
 | `onClose` | `() => void` | ✅ | 关闭回调 |
 | `onNavigate` | `(index: number) => void` | ❌ | 导航回调 |
+| `customRenderers` | `CustomRenderer[]` | ❌ | 自定义渲染器 |
+
+### FilePreviewEmbed Props
+
+| 属性 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `files` | `PreviewFileInput[]` | ✅ | - | 文件列表 |
+| `currentIndex` | `number` | ❌ | `0` | 当前文件索引 |
+| `onNavigate` | `(index: number) => void` | ❌ | - | 导航回调 |
+| `customRenderers` | `CustomRenderer[]` | ❌ | - | 自定义渲染器 |
+| `width` | `number \| string` | ❌ | `'100%'` | 容器宽度 |
+| `height` | `number \| string` | ❌ | `'100%'` | 容器高度 |
+| `className` | `string` | ❌ | - | 根节点额外 className |
+| `style` | `CSSProperties` | ❌ | - | 根节点额外内联样式 |
+
+> `FilePreviewEmbed` 没有 `isOpen` / `onClose`,若要显示/隐藏,请在父组件中条件渲染。同时它不会显示工具栏上的关闭按钮。
+
+### FilePreviewContent（高级用法）
+
+`FilePreviewModal` 和 `FilePreviewEmbed` 都是基于底层 `FilePreviewContent` 组件的薄包装。当你需要构建完全自定义的容器时,可以直接使用它:
+
+```tsx
+import { FilePreviewContent } from '@eternalheart/react-file-preview';
+
+<FilePreviewContent
+  mode="embed"       // 或 "modal"
+  files={files}
+  currentIndex={index}
+  onNavigate={setIndex}
+/>
+```
 
 ### 文件类型定义
 

package/lib/FilePreviewContent.d.ts

@@ -0,0 +1,13 @@
+import { PreviewFileInput, CustomRenderer } from './types';
+export interface FilePreviewContentProps {
+    files: PreviewFileInput[];
+    currentIndex: number;
+    onNavigate?: (index: number) => void;
+    customRenderers?: CustomRenderer[];
+    /** 运行模式:modal(弹窗) 或 embed(嵌入) */
+    mode?: 'modal' | 'embed';
+    /** 关闭回调,仅 modal 模式使用 */
+    onClose?: () => void;
+}
+export declare const FilePreviewContent: React.FC<FilePreviewContentProps>;
+//# sourceMappingURL=FilePreviewContent.d.ts.map

package/lib/FilePreviewContent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilePreviewContent.d.ts","sourceRoot":"","sources":["../src/FilePreviewContent.tsx"],"names":[],"mappings":"AAgCA,OAAO,EAAe,gBAAgB,EAAY,cAAc,EAAE,MAAM,SAAS,CAAC;AAclF,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,iCAAiC;IACjC,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IACzB,wBAAwB;IACxB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AA+CD,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAAE,CAAC,uBAAuB,CAichE,CAAC"}

package/lib/FilePreviewEmbed.d.ts

@@ -0,0 +1,16 @@
+import { PreviewFileInput, CustomRenderer } from './types';
+interface FilePreviewEmbedProps {
+    files: PreviewFileInput[];
+    currentIndex?: number;
+    onNavigate?: (index: number) => void;
+    customRenderers?: CustomRenderer[];
+    /** 宽度,默认 100% 填充父容器 */
+    width?: number | string;
+    /** 高度,默认 100% 填充父容器 */
+    height?: number | string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare const FilePreviewEmbed: React.FC<FilePreviewEmbedProps>;
+export {};
+//# sourceMappingURL=FilePreviewEmbed.d.ts.map

package/lib/FilePreviewEmbed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FilePreviewEmbed.d.ts","sourceRoot":"","sources":["../src/FilePreviewEmbed.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG3D,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;CAC7B;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CA0B5D,CAAC"}

package/lib/FilePreviewModal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FilePreviewModal.d.ts","sourceRoot":"","sources":["../src/FilePreviewModal.tsx"],"names":[],"mappings":"AAgCA,OAAO,EAAe,gBAAgB,EAAY,cAAc,EAAE,MAAM,SAAS,CAAC;AAclF,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;CACpC;AAgDD,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CA+d5D,CAAC"}
+{"version":3,"file":"FilePreviewModal.d.ts","sourceRoot":"","sources":["../src/FilePreviewModal.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG3D,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;CACpC;AAED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CA8D5D,CAAC"}