预览插件

预览插件（Preview plugins） 是单独安装的小程序，让 tessoa 预览内置预览处理不了的格式，例如视频、音频和多页文档。本页讲插件页在哪、怎么安装、播放和翻页，以及怎么处理预览失败。

插件预览是 Supporter 档的付费功能：管理、安装和卸载在任何档位下都能做，但已装的插件要解锁之后才真正出图。

插件在你的机器上是怎么跑的

每个插件是一个独立的进程，tessoa 只在需要解一张图或播一段视频时把它拉起来，闲下来它自己退出。插件崩溃或卡住不会影响 tessoa 本体：那个文件回落成图标，别的东西照常。

插件页上这句话写的就是这件事：插件在独立进程中运行，崩溃或挂起不会影响 tessoa 本体；启用、禁用与卸载立即生效，无需重启。

插件包解开后放在你的用户目录下，不随配置漫游：

系统	位置
Windows	%LOCALAPPDATA%\tessoa\plugins\<插件 id>\
macOS	~/Library/Application Support/tessoa/plugins/
Linux	$XDG_DATA_HOME/tessoa/plugins/

打开插件页

两个入口通向同一页：

• 单击窗口左上角的菜单按钮，选 插件。
• 打开设置，在 维护 组里单击 预览插件。

维护 组里另有两个开关，它们管的是两件不同的事：

设置项	作用
启用预览插件	要不要加载插件。关掉之后已装的插件全部不生效，表现和没装一样
提示可安装的预览插件	遇到装了插件才能预览的格式时，要不要在预览栏里提一句

从插件源安装

插件页下半部分是 可安装的插件 一节，列着适用于你这台机器的插件。行尾的按钮有五种状态：

按钮	含义
安装	还没装，单击开始下载
更新	装的是旧版本，副信息里写着 有新版 x.y.z
已安装	已经是最新版，不可单击
百分比	正在下载安装，数字走到 100% 为止
需更新宿主	这个插件要求更新的 tessoa，副信息里写着 需要 tessoa x.y.z 或更高版本

安装步骤：

1. 打开插件页，等 正在获取插件列表… 变成条目。
2. 在要装的那一行单击 安装。
3. 第一次安装插件时会先弹出《预览插件条款》，读完单击 同意并继续。选 暂不 就回到插件页，什么都不装。
4. 按钮上的百分比走完，页面上方的 已安装插件 一节里出现这一行。

下载中断后重新单击 安装 会接着上次的进度续传，不必从头再来。

备注

tessoa 不会在后台替你查插件更新。插件列表只在你打开插件页、或者单击 重新扫描 的那一刻去取一次，其余时候不联网。重新扫描 一枚按钮同时做两件事：重新扫描本机已装的插件，以及重新拉取插件源。

从文件安装

拿到一个 .zip 插件包时走这条路：

1. 在插件页右上角单击 从文件安装…。
2. 在弹出的 选择插件包 里选中那个 .zip 文件，单击 安装。
3. 提示条写着 已安装插件 …，插件页上出现这一行。

装同一个插件的新版本不需要先卸载旧的，直接装即可。

安装失败时提示条会写明原因：

提示	含义
这不是一个插件包（包根没有 plugin.toml）	选错了文件
插件清单（plugin.toml）无效	包的描述文件读不出来
解压失败，插件包可能已损坏	下载没下完整，或者文件坏了
旧版本未能移除（文件可能被占用），请稍后再试	旧版本的文件还被占着，稍后重试
插件包校验失败（可能在传输中损坏，或已被篡改），已放弃安装	从插件源下的包与清单里记的校验值对不上

管理已装的插件

已安装插件 一节里每个插件占两行：上一行是名字和版本，下一行是它的 id、认领的扩展名、占用的磁盘空间和当前状态。

行尾的下拉菜单有四项：

菜单项	作用
启用 / 禁用	禁用之后这个插件不再出图，表现和没装一样；重新启用立即恢复
打开所在位置	在文件管理器里打开这个插件的目录
卸载	停掉进程、删掉目录。单击即执行，没有二次确认——重装一次即可

状态那一格平时写 已启用 或 已禁用，出问题时换成具体原因：

状态	含义
连续失败，本次运行内已停用	这个插件连着两次没能解出内容，tessoa 本次运行内不再找它。重启 tessoa，或者禁用再启用一次，都能让它复位
协议版本不兼容	插件是给别的 tessoa 版本写的
缺少本平台的程序文件	这个包里没有适用于你这个系统的程序
版本 x.y.z 安装失败	上一次更新没装成，旧版本还在用

装好之后预览里多了什么

插件认领的格式可以显示图标网格缩略图，并在画廊、分栏的预览栏、侧详情面板和预览标签页中预览。

视频和音频文件的封面中央多出一枚 ▶。单击它开始播放，画面下方常驻一条播控条：

控件	作用
⏯	暂停 / 继续。声音和画面同时停
进度条	单击任意位置跳到那里
时间码	当前位置，mm:ss
♪	静音 / 取消静音。静音不是暂停，画面照走
音量条	单击设置音量，顺手取消静音。音量和静音状态会记住，重启后仍是你设的那档

播放的几条边界：

• 切到别的文件或关掉标签页，播放随即结束。
• 切到别的标签页会自动暂停，切回来停在原处，不自动继续。
• 最小化窗口时声音继续，画面停住。
• 两个窗口各播一个时，只有后开的那个出声，先开的画面照走。

多页文档

支持翻页的插件可以把文档按页显示；只提供一张封面的插件不会出现翻页控件。例如，tessoa-office 0.2.0 及之后版本支持 .docx 和 .pptx 的多页预览，需要与 tessoa 0.24.0 及之后版本配合使用。

1. 在插件页安装或更新支持该格式的插件，并确认它已启用。
2. 选中文档，在画廊、分栏预览栏、侧详情面板或预览标签页中查看。
3. 等待第一页加载，使用预览区的页码和版式控件浏览后面的页面。

操作	怎么做
翻页	在预览画面上滚动鼠标滚轮
跳到指定页	单击页码，例如 1/6，输入目标页数
切换版式	选择 单页（Single page）、连续滚动（Continuous scroll） 或 双页（Two-page）
放大 / 缩小	使用预览区的缩放按钮；放大后可以拖动画面

这些控件与 PDF 预览相同。窗口太窄时版式按钮会收起；文档预览只供查看，不能在页面中编辑文字。

等待与失败提示

插件正在生成预览、等待超过约 0.3 秒时，大预览区会显示转圈指示器。翻到尚未加载的文档页时，指示器位于待显示页面的中央；加载结束后自动消失。图标网格中的缩略图不显示这些指示器。

插件解不出文件时，预览区显示它提供的诊断并带上插件名称，例如 插件 … 无法播放此文件。连续运行失败使插件被暂时停用时，提示条与预览区会写明 插件 … 连续失败，本次运行内已禁用，播放按钮和翻页控件不再可用。

需要重新尝试时，从左上角菜单打开 插件（Plugins），在已安装插件的菜单里先 禁用（Disable），再 启用（Enable）；也可以重启 tessoa。若仍失败，保留提示中的插件名称和诊断内容，再检查插件更新或反馈问题。

没装插件时的那句提示

打开一个需要插件才能预览的视频、音频或文档时，预览栏上写着 安装预览插件后可预览此格式，下面一枚 查看插件 按钮直达插件页。

这句话只在四个条件同时成立时出现：提示可安装的预览插件 开着、启用预览插件 开着、这个扩展名在 tessoa 内置的那张表里（mp4 mkv mov webm m4v avi mp3 flac ogg m4a wav docx pptx），并且没有任何已装的插件认领它——已经装了却把它禁用的情况不算，那时不会劝你再装一次。

不想再看到这句话，在设置的 维护 组里关掉 提示可安装的预览插件 即可。这个开关只管这句提示，不影响插件本身能不能用。

备注

Windows 上打开常见的 mp4 通常看不到这句提示。系统本身就能给这类视频出一张封面，预览栏画的是那张图，没有留给这句话的位置。系统也解不出来的视频（例如 HEVC 编码的那些），以及 macOS 和 Linux 上，提示照常出现。

授权与条款

插件预览属于 Supporter 档。档位不足时：

• 插件页最上方常驻一条提示，写明已装的插件不会生效，缩略图与播放回落成系统默认的呈现；行尾的 解锁 按钮直达 关于 › 授权 页。
• 预览栏上写的是 升级 Supporter 档后可使用插件预览，只对装了插件、且这个格式确实被插件认领的文件出现。
• 安装、卸载、启用、禁用和浏览插件源都不受限制。先装后买是可以的，解锁那一刻已装的插件立即生效。

《预览插件条款》是一份独立的文档，讲的是第三方插件与 tessoa 的责任边界。它在你安装插件时征求一次同意，不拦启动；条款更新之后，下一次安装或更新插件时会再问一次。整份条款在设置的 关于 组里随时可以翻阅。

插件源连不上时

可安装的插件 这一节永远在页面上，连不上时它显示的就是原因：

提示	该做什么
无法连接到插件源。…	检查网络，然后单击 重新扫描
插件源的签名校验未通过，已拒绝使用这份列表。…	稍后重试；一直如此就到官网下载插件包，走 从文件安装…
插件源列表的格式无法识别。…	先把 tessoa 更新到最新版本
插件源上暂时没有适用于本机的插件。	这台机器的系统或架构暂时没有可装的插件

参见

预览总览 · 预览标签页 · 设置一览 · 常见问题