vitepress-plugin-filelist 0.3.1 → 0.5.0

package/README.md

@@ -7,7 +7,8 @@
 - 📁 树形目录，文件夹按需加载
 - ✅ 勾选文件；选中文件夹会自动加载并选中其下所有层级的文件
 - 📦 批量打包 ZIP（基于 `fflate`），带进度；保留目录结构，不同目录的同名文件不会互相覆盖
-- ⬇️ 单文件下载与预览（`/d/`、`/p/`、`fs/get` 的 `raw_url`）
+- ⬇️ 单文件下载（`fs/get` 的 `raw_url`，回退 `/d/`）
+- 👁️ 弹窗预览（不跳转）：图片、音视频、文本、PDF；Office 等其它类型显示文件信息与下载
 - 🔐 目录密码输入，可选只读 token
 - 🔎 当前树过滤，按名称 / 大小 / 日期排序
 - 🎨 紧凑表格：按文件类型着色的扩展名标签、层级引导线，跟随 VitePress 亮 / 暗主题
@@ -79,6 +80,7 @@ export default {
 | `expanded` | `boolean` | `false` | 目录根是否默认展开 |
 | `token` | `string` | `''` | 可选只读 token；不传则以游客身份请求 |
 | `password` | `string` | `''` | 目录密码，也可以在运行时输入 |
+| `rememberPassword` | `boolean` | `true` | 输入密码时是否提供“在此标签页中记住”开关；`false` 时不写入 sessionStorage |
 | `title` | `string` | `''` | 工具栏标题；为空时回退到 OpenList 的 `site_title` |
 | `locale` | `'zh-CN' \| 'en-US'` | `'zh-CN'` | 内置文案预设 |
 | `labels` | `Partial<FileListLabels>` | `undefined` | 按 key 覆盖单条文案 |
@@ -102,7 +104,7 @@ export default {
 - 目录路径挂载为根文件夹，默认折叠；`expanded` 可为全局或单个 source 打开
 - 文件路径挂载为一条文件记录，直接预览/下载
 - 勾选根目录会加载并选中其下所有文件；ZIP 内以根节点名称（`title` 或路径末段）作为顶层文件夹，文件根保留原文件名
-- 每个 source 可单独设置 `title`、`password`；未设置 `password` 的 source 使用组件的 `password` 或运行时输入的密码，遇到需要密码的目录会弹出密码输入框
+- 每个 source 可单独设置 `title`、`password`；未设置 `password` 的 source 使用组件的 `password` 或运行时输入的密码，遇到需要密码的目录会在该行原地显示密码输入框（见下文）
 - 根节点顺序按 `sources` 顺序，子项仍按名称/大小/日期排序
 
 ```ts
@@ -124,6 +126,16 @@ interface FileListSource {
   - 勾选后操作条吸附在组件顶部，位于 VitePress 导航栏 / “On this page” 栏下方，只在本组件范围内吸附
 - 颜色全部取自 VitePress 主题变量，暗色模式自动适配
 
+## 刷新与目录密码
+
+- **刷新**：保留当前列表并调暗，表头下方显示进度条；完成后整体替换，已展开的目录和仍存在的勾选会保留。刷新失败时保留旧数据并提示。刷新只重新读取 OpenList 的目录缓存（游客没有写权限，无法强制刷新存储）
+- **目录密码**：点击加锁目录（或勾选包含它的目录）时，密码输入框直接出现在该行的大小 / 日期位置，行高不变，下方文件不会移动；勾选在遇到加锁子目录时停下并请求密码
+  - Enter 提交，Esc 取消；密码错误时在原位提示“密码不正确或无权访问”（OpenList 无法区分密码错误和无权限）
+  - 钥匙按钮可开启“在此标签页中记住（关闭标签页后失效）”，密码存在 sessionStorage，按 OpenList 地址和目录区分，也覆盖子目录；已记住的目录显示“已记住 · 忘记”
+  - 保存的密码失效时自动删除，并提示重新输入
+  - 本次页面中输入过的密码（即使没有记住）在刷新后仍然有效
+- 单一 `path` 本身需要密码时，在列表位置显示密码输入框
+
 吸顶偏移默认根据 `.VPNav`、`.VPLocalNav` 的实际高度自动计算；自定义主题可手动指定：
 
 ```css
@@ -132,6 +144,22 @@ interface FileListSource {
 }
 ```
 
+## 预览
+
+点击预览按钮在当前页面的弹窗（原生 `<dialog>`）中显示，不跳转、不打开新标签页。只有能在页面内显示的类型才有预览按钮；点击文件名仍是下载。
+
+| 类型 | 扩展名（节选） | 方式 |
+| --- | --- | --- |
+| 图片 | png、jpg、gif、webp、svg、avif | `<img>`，可旋转、切换原始大小 |
+| 视频 / 音频 | mp4、webm、mov / mp3、m4a、flac、wav | 原生播放器（格式以浏览器支持为准） |
+| 文本 | txt、md、json、csv、yaml、日志与常见代码 | 只读取前 1 MB（Range 请求），纯文本显示 |
+| PDF | pdf | 优先使用 OpenList `iframe_previews` 中配置的 PDF 查看器；未配置时用浏览器自带阅读器（下载后以 Blob 显示，上限 50 MB） |
+| 其它（含 Office、压缩包） | — | 弹窗内显示文件信息和下载按钮 |
+
+- 弹窗内 ← / → 切换当前列表中的可预览文件，Esc 或点击遮罩关闭
+- 读取文本和浏览器 PDF 需要文件地址允许跨域：经 OpenList 代理（`/p/`）时由 OpenList 的 CORS 设置决定；网盘直链由网盘决定。失败时显示“无法在页面内预览”和下载按钮
+- `iframe_previews` 来自 `/api/public/settings`，与 OpenList 网页端使用同一配置，占位符 `$url`、`$e_url`、`$b_url`、`$durl`、`$name` 的含义一致
+
 ## 国际化
 
 ```md
@@ -157,7 +185,7 @@ import { fileListLocales, formatLabel, resolveLabels } from 'vitepress-plugin-fi
 ## OpenList 要求
 
 1. **游客只读权限**：开启游客用户，或传入只读 `token`
-2. **CORS**：OpenList 的 `cors.allow_origins` 必须包含站点来源（默认 `*`）
+2. **CORS**：OpenList 的 `cors.allow_origins` 必须包含站点来源（默认 `*`）；使用 OpenList-Worker 时设置 `ALLOW_URLS`（逗号分隔，完整来源，如 `https://docs.example.com,http://localhost:5173`，不支持通配符）。出现“Failed to fetch”时组件会提示检查这两项。GET 请求不带 `Content-Type`，避免多余的预检
 3. **同协议**：HTTPS 页面不能请求 HTTP 的 OpenList（混合内容）
 4. **token 是公开的**：只放可撤销的只读 token，不要放管理 token
 
@@ -167,8 +195,8 @@ import { fileListLocales, formatLabel, resolveLabels } from 'vitepress-plugin-fi
 | --- | --- |
 | `POST /api/fs/list` | 目录列表（`per_page: 0`） |
 | `POST /api/fs/get` | 获取下载 / 预览 / 打包用的 `raw_url`；失败时回退到 `/d/...?sign=` |
-| `GET /api/public/settings` | 获取 `site_title` |
-| `GET /d/...`、`GET /p/...` | OpenList 生成的下载 / 预览链接 |
+| `GET /api/public/settings` | 获取 `site_title`、`iframe_previews` |
+| `GET /d/...`、`GET /p/...` | 下载与预览读取的文件地址 |
 
 ## 导出
 

package/dist/client/browser/index.d.ts

@@ -32,6 +32,7 @@ interface FileListLabels {
   demoPreview: string;
   demoBatch: string;
   downloadFailed: string;
+  /** @deprecated Preview errors are shown in the dialog (`previewUnavailable`). */
   previewFailed: string;
   batchFailed: string;
   defaultZip: string;
@@ -52,6 +53,43 @@ interface FileListLabels {
   expand: string;
   /** Accessible name of the collapse button, `{name}`. */
   collapse: string;
+  /** Preview dialog: close button. */
+  close: string;
+  /** Preview dialog: previous / next previewable file. */
+  previous: string;
+  next: string;
+  /** Preview dialog: rotate image by 90°. */
+  rotate: string;
+  /** Preview dialog: toggle the image between fit-to-window and actual size. */
+  actualSize: string;
+  /** Preview dialog: file type that is not previewed (Office and others). */
+  previewUnsupported: string;
+  /** Preview dialog: preview failed (network, CORS, unsupported codec). */
+  previewUnavailable: string;
+  /** Preview dialog: PDF larger than the in-page limit, `{size}`. */
+  previewTooLarge: string;
+  /** Preview dialog: only the first `{size}` of a text file is shown. */
+  textTruncated: string;
+  /** Refresh button while refreshing. */
+  refreshing: string;
+  /** Refresh failed; the old rows stay. `{message}` */
+  refreshFailed: string;
+  cancel: string;
+  /** Placeholder / accessible name of a folder's password input. `{name}` */
+  passwordFor: string;
+  /** OpenList cannot tell a wrong password from missing permission. */
+  passwordWrong: string;
+  /** A password remembered in this tab no longer works. */
+  passwordStale: string;
+  /** The key toggle next to a password input. */
+  rememberPassword: string;
+  /** Tag on a folder whose password is remembered. */
+  remembered: string;
+  forgetPassword: string;
+  /** Lock button on a folder that needs a password. `{name}` */
+  unlockFolder: string;
+  /** Appended to failure toasts for browser network errors (usually CORS). */
+  networkHint: string;
 }
 interface FileListSource {
   /** OpenList path, directory or single file. */
@@ -78,6 +116,11 @@ interface FileListProps {
   password?: string;
   /** Toolbar title. Falls back to `site_title` from `/api/public/settings`. */
   title?: string;
+  /**
+   * Offer to remember folder passwords in this browser tab (sessionStorage,
+   * cleared when the tab closes). Defaults to `true`; `false` hides the option.
+   */
+  rememberPassword?: boolean;
   /** Built-in locale. Defaults to `zh-CN`. */
   locale?: FileListLocale;
   /** Per-key label overrides on top of the locale preset. */
@@ -102,6 +145,7 @@ declare const _default: import("vue").DefineComponent<FileListProps, {}, {}, {},
   token: string;
   password: string;
   title: string;
+  rememberPassword: boolean;
   locale: FileListLocale;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare global {
@@ -213,6 +257,32 @@ export declare function totalSize(items: Array<{
   size?: number;
 }>): number;
 export declare function compareNodes(a: SortableNode, b: SortableNode, key: SortKey, ascending?: boolean): number;
+export type PreviewKind = 'image' | 'video' | 'audio' | 'text' | 'pdf' | 'none';
+/**
+ * How a file is shown in the preview dialog. Office documents and anything
+ * else the browser cannot render are `none` (info + download).
+ */
+export declare function previewKind(name: string): PreviewKind;
+export interface IframePreview {
+  label: string;
+  scheme: string;
+}
+/**
+ * Viewers from OpenList's public `iframe_previews` setting that match a file,
+ * in the order OpenList lists them. Keys are comma-separated extensions or a
+ * `/regex/flags` tested against the extension, as in OpenList's frontend.
+ */
+export declare function iframePreviewsFor(name: string, setting: string | undefined): IframePreview[];
+/**
+ * Fill an OpenList preview scheme: `$name`, `$url` (raw URL) and `$durl`
+ * (signed download URL), each optionally prefixed with `e` (URI-encode) or
+ * `b` (base64), e.g. `$e_url`, `$b_url`, `$e_durl`.
+ */
+export declare function fillPreviewUrl(scheme: string, args: {
+  name: string;
+  rawUrl: string;
+  downloadUrl: string;
+}): string;
 /**
  * Register `<FileList>` and `<VPFileList>` globally.
  *