# @eternalheart/ngx-file-preview 中文文档
规范地址：https://npmcn.com/package/%40eternalheart/ngx-file-preview/
版本：1\.0\.12
npm 元数据更新时间：2025-05-21T03:24:45.946Z
中文译文更新时间：2026-11-14T06:39:48.917Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40eternalheart/ngx-file-preview
原文对照：https://npmcn.com/package/%40eternalheart/ngx-file-preview/?lang=original
项目主页：https://wh131462.github.io/ngx-file-preview/
源码仓库：https://github.com/wh131462/ngx-file-preview
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：1.3 MB，103 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：docx-preview ^0\.3\.3，highlight\.js ^11\.11\.1，hls\.js ^1\.4\.12，markdown-it ^14\.1\.0，ngx-extended-pdf-viewer ^23\.0\.0-alpha\.6，pptx-preview ^1\.0\.1，xlsx ^0\.18\.5
- 首次发布：2025-01-02T07:58:20.699Z
- 最新版本发布：2025-05-21T03:24:45.737Z
- 近 30 天下载量：2233（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 0 个）
## 中文简介
一个强大的Angular文件预览组件库支持多种文件格式,包括图像,视频,PDF,Office文档,文本文件等.
## 安装
```sh
npm install @eternalheart/ngx-file-preview
```
也可以使用：`pnpm add @eternalheart/ngx-file-preview`、`yarn add @eternalheart/ngx-file-preview`、`bun add @eternalheart/ngx-file-preview`
## README
# NGX 文件预览 [](https://www.npmjs.com/package/@eternalheart/ngx-file-preview) [](https://www.npmjs.com/package/@eternalheart/ngx-file-preview) [](https://wh131462.github.io/ngx-file-preview/) [](https://github.com/wh131462/ngx-file-preview)
[页:1](https://npmcn.com/package/%40eternalheart/ngx-file-preview/README_CN.md) • 妇女 **联合国**
**NGX 文件预览** 是一个强大的Angular文件预览组件库,支持各种文件格式的预览,并提供灵活的定制选项,为开发者提供高效和方便用户的解决方案.
## 预览示例
### 默认列表视图
### 自定义模板( 示例, 完全自定义)
### 不同文件类型的预览效果
| 文件类型 | 预览效果 |
| --- | --- |
| 图像 |   |
| 视频 |   |
| 音频 |   |
| PPT 预览 |   |
| 单词 |   |
| 埃克塞尔 |   |
| 文本 |   |
| 标记 |   |
| 齐普 |   |
| 未知 |   |
## 特征
- **支持多个文件格式**:完全兼容图像,PDF,PPT,Word,Excel,文本,标记下,音频,视频,以及许多其他常见的文件类型.
- **直观用户体验**:为未知文件类型提供清晰的指标,并支持不同文件格式的用户友好互动.
- **黑暗模式和光明模式**: 适应各种对暗模式和光模式都有视觉偏好的各种用例,包括自动模式切换.
- **灵活使用**: 支持基于指令和基于组件的使用,提供灵活性以满足不同的发展需要.
- **轻量级设计**: 优化性能,方便地融入任何项目,确保平稳高效运行.
- **键盘快捷键支持**:通过允许轻松地导航并用键盘快捷键关闭预览来提高效率.
- **国际化支助**: 内建i18n支持,并具有轻松的语言包注册和切换能力.
## 安装
```bash
npm install @eternalheart/ngx-file-preview --save docx-preview hls.js pptx-preview xlsx ngx-extended-pdf-viewer markdown-it highlight.js
```
## 国际化(i18n)
### 语言配置
您可以在使用指令时指定语言 :
```html
Click to preview
```
### 注册新语言包
使用自定义语言包注册 `I18nUtils.register`数字 :
```typescript
import { I18nUtils } from '@eternalheart/ngx-file-preview';
// Register a new language pack
I18nUtils.register('fr', {
preview: {
error: {
noFiles: 'Aucun fichier à afficher'
},
toolbar: {
zoomIn: 'Zoom avant',
zoomOut: 'Zoom arrière'
// ... other translations
}
}
// ... more translation keys
});
```
### 使用 i18n 管道( 对于开发者)
使用模板中的i18n管来翻译文本 :
```html
{{ 'preview.toolbar.zoomIn' | i18n }}
// With parameters
// Use ${0} as a numeric placeholder in the corresponding text. The number of placeholders is unlimited, but you must pass the corresponding number of arguments when using them.
// example: list.total ==> "共${0}个文件"
{{ 'list.total' | i18n:filesCount }}
```
## 配置
### 1\. 字体图标配置和资源
将必要的资产、样式和脚本添加到您的 `angular.json` 文件 :
```json
{
"projects": {
"your-app": {
"architect": {
"build": {
"options": {
"assets": [
{
"glob": "**/*",
"input": "node_modules/ngx-extended-pdf-viewer/assets",
"output": "assets"
}
],
"styles": [
"node_modules/@eternalheart/ngx-file-preview/src/assets/icon/font/nfp.css"
],
"scripts": [
"node_modules/@eternalheart/ngx-file-preview/src/assets/icon/color/nfp.js"
]
}
}
}
}
}
}
```
### 2\. 模块导入
导入您的角模块中所需的组件 :
```typescript
import {
PreviewDirective,
PreviewListComponent,
PreviewModalComponent
} from '@eternalheart/ngx-file-preview';
@Component({
imports: [
PreviewDirective,
PreviewListComponent,
]
})
```
## 使用量
### 1\. 指令方法
最简单的使用方法:将指令直接应用到元素上:
```typescript
import {PreviewDirective, PreviewEvent} from '@eternalheart/ngx-file-preview';
@Component({
imports: [PreviewDirective],
template: `
Click to preview a single file
Click to preview a single file
Click to preview a single file
Click to preview multiple files
`
})
export class YourComponent {
file: PreviewFile = {
name: 'example.jpg',
type: 'image',
url: 'path/to/file.jpg'
};
files: PreviewFile[] = [
// ... file array
];
handlePreviewEvent(event: PreviewEvent) {
const {type, message, event: targetEvent} = event;
if (type === "error") {
console.log(message); // Handle error event
}
if (type === "select") {
console.log(targetEvent); // Handle file selection event
}
}
}
```
### 2\. 构成部分方法
#### 使用默认列表模板 :
```typescript
import {PreviewListComponent} from '@eternalheart/ngx-file-preview';
@Component({
imports: [PreviewListComponent],
template: `
`
})
```
#### 使用自定义模板 :
```typescript
@Component({
template: `
{{ file.name }}
{{ formatFileSize(file.size) }}
`
})
```
## 文件配置
### `PreviewFile` 接口
```typescript
interface PreviewFile {
url: string; // File URL
name: string; // File name
type?: PreviewType; // File type - Not nessary
size?: number; // File size (optional)
lastModified?: number;// Last modified time (optional)
coverUrl?: string; // Cover image URL (for video/audio, optional)
}
```
### 支持的文件类型( E)`PreviewType`(中文(简体) )
```typescript
type PreviewType =
| 'image' // Image
| 'pdf' // PDF Document
| 'ppt' // PPT Presentation
| 'word' // Word Document
| 'txt' // Text File
| 'video' // Video
| 'excel' // Excel Spreadsheet
| 'audio' // Audio
| 'zip' // Compressed File
| 'unknown' // Unknown Type
```
## API 参考
### 预览列表组件
| 财产 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| 文件 | 预览文件 \[\] | \[ | 要预览的文件列表 |
| 主题模式 | '光'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | "自动" | 预览的主题模式 |
| 自动配置 | {黑暗:{开始:数字,结束:}}} | {黑暗:{开始:19,结束:7}}} | 自动主题模式配置 |
| 朗语 | 字符串 | 日语 | 国际化语言设置, “zh” 和 “en” 默认注册 |
| (文件选择) | 事件编辑器 | \- 说吧 | 选中文件时已释放的事件 |
| (审查活动) | 事件编辑器 | \- 说吧 | 预览动作中释放的事件 |
#### 模板上下文变量
| 变量 | 类型 | 说明 |
| --- | --- | --- |
| 文件 | 预览文件 | 当前文件对象 |
| 指数 | 编号 | 当前文件索引 |
| 类型 | 字符串 | 文件类型 |
| 活动 | 布尔 | 是否选中当前项目 |
| 选择 | () 无效 | 选择当前文件的方法 |
| 预览 | () 无效 | 预览当前文件的方法 |
### 预览指令
| 选择器 | 财产 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| \[ngxFilePreview\] (英语) | ngx 文件审查 | 预览文件 QQ 预览文件 \[\] | \- 说吧 | 要预览的文件 |
| | 主题模式 | '光'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' | "自动" | 预览的主题模式 |
| | 自动配置 | {黑暗:{开始:数字,结束:}}} | {黑暗:{开始:19,结束:7}}} | 自动主题模式配置 |
| | 朗语 | 字符串 | 日语 | 国际化语言设置, “zh” 和 “en” 默认注册 |
| | (审查活动) | 事件编辑器 | \- 说吧 | 预览动作中释放的事件 |
### 预览事件类型
| 事件类型 | 说明 | 事件数据 |
| --- | --- | --- |
| 错误 | 错误事件 | { 类型 : “ 错误” , 消息: 字符串 } |
| 选择 | 文件选择事件 | {类型 : “ 选择” , 事件: 鼠标Event} |
## 键盘快捷键
在预览模式中,可以使用以下快捷键:
- `←` 上一个文件
- `→` 下一个文件
- `Esc` 关闭预览
## 发展指南
1. 清除仓库 :
```bash
git clone https://github.com/wh131462/ngx-file-preview.git
```
2. 安装依赖性 :
```bash
npm install
```
3. 启动开发服务器 :
```bash
npm run start
```
4. 构建库 :
```bash
npm run build
```
## 贡献准则
随便你 [问题](https://github.com/wh131462/ngx-file-preview/issues) 财务报告和审定财务报表 [调取请求](https://github.com/wh131462/ngx-file-preview/pulls) 帮助改进这个项目!
## 许可证
麻省理工学院
## 承认
该项目使用以下优秀的开源库:
- [docx 预览](https://github.com/VolodymyrBaydalka/docx-preview) - 文字文档预览
- [pptx 预览](https://github.com/SheetJS/sheetjs) - PPT 演示文稿预览
- [ưμ㼯a](https://github.com/SheetJS/sheetjs) - Excel电子表格预览
- [ngx- extend- pdf- 查看器](https://github.com/stephanrauh/ngx-extended-pdf-viewer) - PDF 文档预览
- [hls.js (英语)](https://github.com/video-dev/hls.js/) - HLS视频流支持
- [缩放](https://github.com/markdown-it/markdown-it) - Markdown支持系统
- [突出显示.js](https://github.com/highlightjs/highlight.js) - Markdown中的代码由Markdown支持突出显示
我们赞赏这些开放源码项目对社区的贡献!
## 常见问题
### @eternalheart/ngx-file-preview 是什么？
一个强大的Angular文件预览组件库支持多种文件格式,包括图像,视频,PDF,Office文档,文本文件等\.
### 如何安装 @eternalheart/ngx-file-preview？
在项目目录运行 npm install @eternalheart/ngx-file-preview，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：docx-preview（^0\.3\.3）、highlight\.js（^11\.11\.1）、hls\.js（^1\.4\.12）、markdown-it（^14\.1\.0）、ngx-extended-pdf-viewer（^23\.0\.0-alpha\.6）、pptx-preview（^1\.0\.1）、xlsx（^0\.18\.5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。
### @eternalheart/ngx-file-preview 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @eternalheart/ngx-file-preview 支持 ESM 还是 CommonJS？
以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。
### @eternalheart/ngx-file-preview 可以商用吗？
@eternalheart/ngx-file-preview 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @eternalheart/ngx-file-preview 的下载量有多少？
根据 npm 官方下载统计，@eternalheart/ngx-file-preview 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,233 次，日均约 74 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @eternalheart/ngx-file-preview 还在维护吗？
最新版本 1\.0\.12 发布于 2025/05/21（1\.5 年前）；至今共发布 13 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/01/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。