# @file-viewer/core 中文文档 规范地址：https://npmcn.com/package/%40file-viewer/core/ 版本：3\.3\.3 npm 元数据更新时间：2026-10-31T11:07:07.108Z 中文译文更新时间：2026-11-14T17:39:41.083Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40file-viewer/core 原文对照：https://npmcn.com/package/%40file-viewer/core/?lang=original 项目主页：https://github.com/flyfish-dev/file-viewer#readme 源码仓库：https://github.com/flyfish-dev/file-viewer ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.3 MB，135 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：1 个 - 首次发布：2026-06-20T00:41:14.891Z - 最新版本发布：2026-10-31T11:07:06.786Z - 近 30 天下载量：189199（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：68（近 12 个月 68 个） ## 中文简介 框架中性 TypeScript API 用于浏览器-侧文件预览,渲染器预设,搜索,缩放,页面导航,打印和导出. ## 安装 ```sh npm install @file-viewer/core ``` 也可以使用：`pnpm add @file-viewer/core`、`yarn add @file-viewer/core`、`bun add @file-viewer/core` ## README # @ 文件查看器/ 核心 [联合国](https://github.com/flyfish-dev/file-viewer/blob/main/packages/core/README.md) • 妇女 [简体中文](https://github.com/flyfish-dev/file-viewer/blob/main/packages/core/README.zh-CN.md) [![npm version](https://img.shields.io/npm/v/@file-viewer%2Fcore?logo=npm)](https://www.npmjs.com/package/@file-viewer/core) [![npm downloads](https://img.shields.io/npm/dm/@file-viewer%2Fcore?logo=npm)](https://www.npmjs.com/package/@file-viewer/core) [![GitHub stars](https://img.shields.io/github/stars/flyfish-dev/file-viewer?style=flat&logo=github)](https://github.com/flyfish-dev/file-viewer/stargazers) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE) [GitHub 图像](https://github.com/flyfish-dev/file-viewer) • 妇女 [文档](https://doc.file-viewer.app/zh/) • 妇女 [\*\*\* 民主](https://demo.file-viewer.app/) • 妇女 [格式矩阵](https://doc.file-viewer.app/guide/formats) • 妇女 [问题反馈](https://github.com/flyfish-dev/file-viewer/issues) • 妇女 [联合国](https://github.com/flyfish-dev/file-viewer/blob/main/packages/core/README.md) [![File Viewer 在线演示：Word、Excel、PPT、3D 模型、CAD 图纸与二进制检查器](https://raw.githubusercontent.com/flyfish-dev/file-viewer/main/docs/public/_media/file-viewer-demo-v3-zh.webp)](https://demo.file-viewer.app/) > \* \* \* \* \* \* 文件查看器 \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* \* [GitHub 图像](https://github.com/flyfish-dev/file-viewer) 点个星。 Flyfish 文件查看器的框架中立类型Script基础. 此套件是下一个架构的迁移基础: 一个纯 TypeScript 核心套件, 有内部 `headless`, (中文(简体) ), `browser`,以及 `renderers` 层,加上Vue、React、纯JavaScript、jQuery和Svelte等多个本地标准组件包。 核心拥有共享格式矩阵,源检测,渲染器协议,能力计算,生命周期上下文,操作/活动/搜索/位置/zoom/印刷/出品合同,重型渲染器资产清单,选项正常化,纯状态模型,和框架中立浏览器渲染引擎. 浏览器执行只在仍然保持框架中立的TypeScript时才属于核心内部. DOM 安装,标准浏览器外壳和工具栏, `HTMLElement` traversal,搜索亮点,缩放提供者发现,打印窗口,下载触发器,Canvas,Worker和WASM渲染器不得依赖Vue,React,Svelte或任何组件包. 框架组件包在视具体情况而定的同时保留自己的组件生命周期、公共类型表面、兼容性默认和生态系统互动层 `@file-viewer/core` 作为唯一的共享基础. `@file-viewer/core` 是唯一共享的一揽子基础。 它拥有无头合同和浏览器/转发器层 `createViewer(container, options)` 引擎、渲染器登记册、DOM供应商登记册、打印版式帮助器、浏览器资产分辨率以及框架中立的DOM/Canvas/Worker/WASM渲染合同。 核心来源是公开的;私人Gitea总量仍然可用于完整的工作空间、统一发布自动化、赞助和优先支持. 目前仍然在核心内部的框架中立浏览器渲染器仅限于低成本的图像路径. 电子表格渲染已移动到 `@file-viewer/renderer-spreadsheet`; CAD 渲染已移动到 `@file-viewer/renderer-cad`; Typst 渲染已移动到 `@file-viewer/renderer-typst`; OFD 渲染已移动到 `@file-viewer/renderer-ofd`; PDF 渲染已移动到 `@file-viewer/renderer-pdf`; 归档渲染已移动到 `@file-viewer/renderer-archive`; 电子邮件渲染已移动到 `@file-viewer/renderer-email`; EPUB 和 UMD 电子书渲染已移入 `@file-viewer/renderer-epub`; 三维模型渲染已移动到 `@file-viewer/renderer-3d`; Draw.io、Excalidraw、人鱼和PlantUML渲染已移到 `@file-viewer/renderer-drawing`; 音频、 视频、 HLS 和 MIDI 渲染已移至 `@file-viewer/renderer-media`; 代码、 文本、 Markdown、 补丁和 git 捆绑渲染已移动到 `@file-viewer/renderer-text`; Word DOCX/DOC/RTF/ODT渲染已移到 `@file-viewer/renderer-word`; PowerPoint渲染已移动到 `@file-viewer/renderer-presentation`; XMind 渲染已移动到 `@file-viewer/renderer-mindmap`; 地理空间渲染已移动到 `@file-viewer/renderer-geo`; 数据资产渲染已移动到 `@file-viewer/renderer-data`; EDA 渲染和解析已移动到 `@file-viewer/renderer-eda`。现在只使用核心的安装可避免直接OFD、PDF、Word、电子表格、PPTX、CAD、Typst、XMind、Geo、媒体、3D、绘图、存档、电子邮件、EPUB、UMD、数据资产、EDA、, `ofd-xml-parser`, (中文(简体) ), `jszip`, (中文(简体) ), `pdfjs-dist`, (中文(简体) ), `styled-exceljs`, (中文(简体) ), `e-virt-table`, (中文(简体) ), `tinycolor2`, (中文(简体) ), `@flyfish-dev/cad-viewer`, (中文(简体) ), `@myriaddreamin/*`, (中文(简体) ), `highlight.js`, (中文(简体) ), `marked`, (中文(简体) ), `diff2html`, (中文(简体) ), `pako`, (中文(简体) ), `mermaid`, (中文(简体) ), `plantuml-encoder`, (中文(简体) ), `@panzoom/panzoom`, (中文(简体) ), `hls.js`, (中文(简体) ), `@tonejs/midi`, (中文(简体) ), `three`, (中文(简体) ), `@excalidraw/excalidraw`, (中文(简体) ), `roughjs`, (中文(简体) ), `libarchive.js`, (中文(简体) ), `postal-mime`, (中文(简体) ), `@kenjiuno/msgreader`, (中文(简体) ), `epubjs`, (中文(简体) ), `ag-psd`, (中文(简体) ), `sql.js`, (中文(简体) ), `hyparquet`, (中文(简体) ), `avsc` 财务报告和审定财务报表 `cfb` 引擎依赖性. ```bash npm install @file-viewer/core ``` ## 浏览器源加载反馈(未发布) 浏览器 `mountViewer` (原始内容存档于2019-09-21). URL. 文件 : 5 、 缓冲 、 + 、 + 、 +。 ## 渲染前预检 `precheckFileViewerSource()` ===================================================================================================================================================================================。`valid: null` ; 。 ```ts import { precheckFileViewerSource } from '@file-viewer/core/headless' const result = await precheckFileViewerSource(file, { // 可传当前产品实际安装的扩展名列表，避免把未装 preset 的格式报成可预览 supportedExtensions: ['pdf', 'docx', 'xlsx', 'pptx'] }) if (!result.previewable) { console.warn(result.reason, result.missingParts) } ``` ## 入境点 使用 `@file-viewer/core/headless` 当一个组件包,服务器侧帮助器或构建脚本只需要框架中性合同时:格式支持,源正常化,渲染器能力元数据,生命周期/操作背景,选项正常化,状态帮助器和静态资产解析. 本条目有意不暴露DOM取景器引擎或浏览器渲染器. ```ts import { DEFAULT_SUPPORTED_EXTENSIONS, normalizeSource, resolveFileViewerRendererAssets } from '@file-viewer/core/headless' const source = normalizeSource({ url: '/files/report.pdf' }) const pdfAssets = resolveFileViewerRendererAssets('pdf', { baseUrl: '/file-viewer/' }) ``` 使用 `@file-viewer/core/browser` 当一个本地组件包或纯浏览器集成需要共享的浏览器外壳和工具栏,直接DOM引擎,渲染器注册,搜索/分区提供者,打印/出出适配器和框架中性Canvas/Worker/WASM渲染器时. ```ts import { createViewer, coreBrowserRendererHandlers } from '@file-viewer/core/browser' const viewer = createViewer(document.querySelector('#viewer')!, { options: { toolbar: true, styleIsolation: 'shadow' } }) await viewer.load({ url: '/files/report.pdf' }) ``` 缩放按钮在达到边界时保持位置并禁用。使用现有的 `toolbar.items` 配置隐藏重置入口`resetZoom()` API —— —— `pdf.zoomToolbar: false` 校对:SOUP ```ts const options = { toolbar: { items: { 'zoom-reset': false } }, pdf: { zoomToolbar: false } } ``` HTML 文档构建器位于选入导出项中, 所以普通预览会这样做 不下载消毒器。 观众的 `exportHtml()` 财务报告和审定财务报表 `print()` 方法 仅在引用时加载此条目。 v3, 迁移直接建筑商从 软件包根到明确的子路径: ```ts import { buildExportHtmlDocument, buildFileViewerRenderedHtmlDocument } from '@file-viewer/core/export' ``` 3 模板中已弃用的兼容导出在v3中改为异步,以保持这条懒加载边界 旧调用需要使用 `await buildExportHtmlDocument(...)` / 编号 `await collectDocumentStyles()`。直接从 `export` 子路径导入时,返回类型仍 API 页面存档备份,存于互联网档案馆。 `options.styleIsolation` 接受 `auto`, (中文(简体) ), `shadow`, (中文(简体) ), `scoped`,或 `none`启用 `shadow` 当自定义主机或框架包装器需要阴影旋转后置的渲染表面时. 核心通过解决 `surface` 转换器 `load(context)`,所以自定义渲染器应该将样式注入 `context.surface.shadowRoot` 或制造器容器代替 `document.head`,并应尽可能在同一孤立的地表内挂上覆盖物. 词根 `@file-viewer/core` 条目仍然是正常的浏览器兼容条目。 新的组件包应倾向于它们所需要的最狭窄的明确切入点: `headless` 合同和建设时间助手, `browser` 用于真实浏览器预览,以及 `export` 用于消毒的独立 HTML 文档. ```ts import { listFileViewerRendererAssetManifests, resolveFileViewerRendererAssets } from '@file-viewer/core' const manifests = listFileViewerRendererAssetManifests() const cadAssets = resolveFileViewerRendererAssets('cad', { baseUrl: '/file-viewer/', options: { cad: { wasmPath: '/file-viewer/wasm/cad/' } } }) ``` 对于非虚拟主机或自定义的静态目录,配置一个运行时的资产 装入文件前的基数 。 渲染器特定的URL仍然占据优先位置. 这个 Vite 插件自动设置此选项 `copyAssets.baseDir`。 。 。 . ```ts import { setDefaultFileViewerAssetBaseUrl } from '@file-viewer/core' setDefaultFileViewerAssetBaseUrl('/tenant/static/file-viewer/') ``` 显示的API让包装和部署脚本从同一份核心合同中发现存档,DOCX,电子表格,CAD,Typst和数据资产工人/WASM资源,而不是每个框架路径硬编码. 电子表格资产仍然是共用部署合同的一部分 `@file-viewer/renderer-spreadsheet`;CAD资产仍然是共用部署合同的一部分 `@file-viewer/renderer-cad`;档案资产仍然是共享部署合同的一部分 `@file-viewer/renderer-archive`;DOCX资产仍然是共享部署合同的一部分 `@file-viewer/renderer-word`; SQLite WASM 资产解析仍为核心 `@file-viewer/renderer-data` 部署工具共享一条稳定的离线路径. 正式文件: [https://doc.file-viewer.app/ 页面存档备份,存于互联网档案馆](https://doc.file-viewer.app/) 在线演示 : [https://demo.field-viewer.app/ 页面存档备份,存于互联网档案馆](https://demo.file-viewer.app/) 公共来源存储器: - GitHub : (中文(简体) ) [https://github.com/flyfish-dev/files-viewer-core 页面存档备份,存于互联网档案馆](https://github.com/flyfish-dev/file-viewer-core) - 枪: [https://gitee.com/flyfish-dev/file-viewer-core 页面存档备份,存于互联网档案馆](https://gitee.com/flyfish-dev/file-viewer-core) GitHub/Gitee寄存器是分布式公共源码包. 私人Gitea总量对于完整的工作空间、发布自动化、集成历史、赞助和优先支持仍然有用. 许可证: Apache -2.0. 对于第二次开发或商业用途,保持清晰的Flyfish Viewer属性,并在可能的情况下促进共享兼容性改进. ## 格式与相关包 文件查看器 @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ office/PDF/OFD/CAD; 3D% @% @% @% @% [格式矩阵](https://doc.file-viewer.app/guide/formats)键。 - 组件:`@file-viewer/web`, (中文)`@file-viewer/vue3`, (中文)`@file-viewer/vue2.7`, (中文)`@file-viewer/vue2.6`, (中文)`@file-viewer/react`, (中文)`@file-viewer/react-legacy`, (中文)`@file-viewer/svelte`, (中文)`@file-viewer/jquery`时 `-full` 页:1 - 能力组合:`@file-viewer/preset-lite`, (中文)`@file-viewer/preset-office`, (中文)`@file-viewer/preset-engineering`, (中文)`@file-viewer/preset-all` - − :`@file-viewer/vite-plugin`, (中文)`file-viewer-copy-assets` ## 页:1 阿帕奇-2.0。详见 [自由主义](https://github.com/flyfish-dev/file-viewer/blob/main/LICENSE)键。 ## 常见问题 ### @file-viewer/core 是什么？ 框架中性 TypeScript API 用于浏览器-侧文件预览,渲染器预设,搜索,缩放,页面导航,打印和导出\. ### 如何安装 @file-viewer/core？ 在项目目录运行 npm install @file-viewer/core，或使用 pnpm add / yarn add / bun add。 ### @file-viewer/core 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @file-viewer/core 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @file-viewer/core 可以商用吗？ @file-viewer/core 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @file-viewer/core 的下载量有多少？ 根据 npm 官方下载统计，@file-viewer/core 在 2026/10/15 – 2026/11/13 这 30 天内被下载 189,199 次，日均约 6,307 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @file-viewer/core 还在维护吗？ 最新版本 3\.3\.3 发布于 2026/10/31（14 天前）；至今共发布 68 个版本，其中过去 12 个月发布了 68 个；首次发布于 2026/06/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。