vitepress-plugin-filelist 0.5.0 → 0.6.0

package/README.md

@@ -6,7 +6,8 @@
 
 - 📁 树形目录，文件夹按需加载
 - ✅ 勾选文件；选中文件夹会自动加载并选中其下所有层级的文件
-- 📦 批量打包 ZIP（基于 `fflate`），带进度；保留目录结构，不同目录的同名文件不会互相覆盖
+- 📦 批量打包 ZIP（基于 `client-zip`），带进度、可取消；Chrome / Edge 边下载边写入磁盘，不受大小限制；保留目录结构，不同目录的同名文件不会互相覆盖
+- 📄 大目录每个文件夹先显示 200 条，可“显示更多 / 全部显示”
 - ⬇️ 单文件下载（`fs/get` 的 `raw_url`，回退 `/d/`）
 - 👁️ 弹窗预览（不跳转）：图片、音视频、文本、PDF；Office 等其它类型显示文件信息与下载
 - 🔐 目录密码输入，可选只读 token
@@ -81,6 +82,9 @@ export default {
 | `token` | `string` | `''` | 可选只读 token；不传则以游客身份请求 |
 | `password` | `string` | `''` | 目录密码，也可以在运行时输入 |
 | `rememberPassword` | `boolean` | `true` | 输入密码时是否提供“在此标签页中记住”开关；`false` 时不写入 sessionStorage |
+| `pageSize` | `number` | `200` | 每个文件夹先显示的条数，之后显示“显示更多 / 全部显示”；`0` 全部显示 |
+| `zipWarnSize` | `number` | `500`（触屏 `200`） | 需在内存中打包的浏览器（Firefox、Safari）超过该大小（MB）先确认；`0` 不提示 |
+| `zipMaxSize` | `number` | `2048`（触屏 `1024`） | 同上，超过该大小（MB）不打包；`0` 不限制 |
 | `title` | `string` | `''` | 工具栏标题；为空时回退到 OpenList 的 `site_title` |
 | `locale` | `'zh-CN' \| 'en-US'` | `'zh-CN'` | 内置文案预设 |
 | `labels` | `Partial<FileListLabels>` | `undefined` | 按 key 覆盖单条文案 |
@@ -126,6 +130,19 @@ interface FileListSource {
   - 勾选后操作条吸附在组件顶部，位于 VitePress 导航栏 / “On this page” 栏下方，只在本组件范围内吸附
 - 颜色全部取自 VitePress 主题变量，暗色模式自动适配
 
+## 批量下载
+
+- Chrome / Edge（含较新的 Android Chrome）：点“下载 ZIP”先弹出系统“另存为”窗口，之后边下载边写入，内存占用很小，不受大小限制
+- Firefox、Safari、iPhone：浏览器只能先把文件放进内存再打包。按已选总大小判断：超过 `zipWarnSize` 先确认，超过 `zipMaxSize` 不打包并建议分批
+- 打包期间操作条显示进度（大小与文件数），可随时取消；勾选暂时锁定。任一文件失败会整体取消并提示文件名
+- ZIP 只存储不压缩（网盘文件多为已压缩格式），支持超过 4 GB（Zip64）
+
+## 大目录
+
+- 每个文件夹（以及单路径模式的顶层列表）先显示 `pageSize` 条，末尾一行“还有 X 项 · 显示更多 · 全部显示”；剩余不足一页时只显示“显示剩余 X 项”
+- 数据一次全部取回，只减少渲染：排序后再截取，勾选文件夹 / 全选包含未显示的文件，输入筛选词时显示全部匹配
+- 刷新后保留已展开的条数
+
 ## 刷新与目录密码
 
 - **刷新**：保留当前列表并调暗，表头下方显示进度条；完成后整体替换，已展开的目录和仍存在的勾选会保留。刷新失败时保留旧数据并提示。刷新只重新读取 OpenList 的目录缓存（游客没有写权限，无法强制刷新存储）
@@ -203,7 +220,7 @@ import { fileListLocales, formatLabel, resolveLabels } from 'vitepress-plugin-fi
 | 入口 | 内容 |
 | --- | --- |
 | `vitepress-plugin-filelist` | `fileList` 插件（默认导出） |
-| `vitepress-plugin-filelist/client` | `FileList`、`VPFileList`、`enhanceAppWithFileList`、类型 |
+| `vitepress-plugin-filelist/client` | `FileList`、`VPFileList`、`enhanceAppWithFileList`、文案工具（`fileListLocales`、`formatLabel`、`resolveLabels`）、格式与文件类型工具（`formatSize`、`formatDate`、`fileKind`、`previewKind` 等）、类型 |
 | `vitepress-plugin-filelist/style.css` | 组件样式 |
 
 ## 兼容性
@@ -237,11 +254,25 @@ Deno 可以安装 npm 依赖，但目前用 Deno 构建 VitePress 会在 rolldow
 ```bash
 pnpm install
 pnpm run build       # 生成 dist/node、dist/client/ssr、dist/client/browser、style.css
-pnpm run typecheck
-pnpm test            # Vitest：utils、locale helpers、FileList 组件
+pnpm run typecheck   # vue-tsc，包含 .vue 模板与测试
+pnpm test            # Vitest：工具函数、密码、下载、FileList 组件
 pnpm run pack:check
 ```
 
+源码结构（`src/client`）：
+
+| 文件 | 职责 |
+| --- | --- |
+| `FileList.vue` | 组件：把下列模块接到界面 |
+| `api.ts` | OpenList 接口、文件地址缓存、错误判断 |
+| `demo.ts` | 演示数据（与 `api.ts` 同一接口） |
+| `tree.ts` | 树节点、排序、目录统计 |
+| `usePasswords.ts` / `passwords.ts` | 目录密码的选择顺序 / 标签页内记住 |
+| `download.ts` | 单文件下载、批量 ZIP |
+| `PreviewDialog.vue` | 预览弹窗 |
+| `Icon.vue` / `icons.ts` | 图标 |
+| `utils.ts` | 路径、格式化、文件类型表 |
+
 仓库统一使用 pnpm（`pnpm-lock.yaml`），CI 与发布流程执行 `pnpm install --frozen-lockfile`。
 
 `demo/` 下的演示站通过 `file:..` 安装本地包：

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

@@ -18,6 +18,8 @@ interface FileListLabels {
   loading: string;
   loadFailed: string;
   guestHint: string;
+  /** Shown (and appended to toasts) for browser network errors, usually CORS. */
+  /** Shown (and appended to toasts) for browser network errors, usually CORS. */
   corsHint: string;
   retry: string;
   empty: string;
@@ -75,7 +77,7 @@ interface FileListLabels {
   /** Refresh failed; the old rows stay. `{message}` */
   refreshFailed: string;
   cancel: string;
-  /** Placeholder / accessible name of a folder's password input. `{name}` */
+  /** Accessible name of a folder's password input. `{name}` */
   passwordFor: string;
   /** OpenList cannot tell a wrong password from missing permission. */
   passwordWrong: string;
@@ -88,8 +90,31 @@ interface FileListLabels {
   forgetPassword: string;
   /** Lock button on a folder that needs a password. `{name}` */
   unlockFolder: string;
-  /** Appended to failure toasts for browser network errors (usually CORS). */
+  /** @deprecated Network failures now append `corsHint`. */
   networkHint: string;
+  /** Batch progress detail. `{done}` `{total}` sizes, `{files}` `{count}` file counts */
+  batchProgress: string;
+  /** Batch finished. `{name}` `{count}` `{size}` */
+  batchDone: string;
+  batchCanceled: string;
+  /** In-memory ZIP over `zipWarnSize`. `{size}` */
+  zipWarnTitle: string;
+  /** `{limit}` */
+  zipWarnText: string;
+  /** Desktop browsers that cannot stream: point to one that can. */
+  zipStreamTip: string;
+  zipContinue: string;
+  /** In-memory ZIP over `zipMaxSize`. `{size}` */
+  zipBlockTitle: string;
+  /** `{limit}` */
+  zipBlockText: string;
+  gotIt: string;
+  /** Last row of a long folder. `{count}` */
+  moreRemaining: string;
+  showMore: string;
+  showAll: string;
+  /** Fewer than a page left. `{count}` */
+  showRest: string;
 }
 interface FileListSource {
   /** OpenList path, directory or single file. */
@@ -121,6 +146,21 @@ interface FileListProps {
    * cleared when the tab closes). Defaults to `true`; `false` hides the option.
    */
   rememberPassword?: boolean;
+  /**
+   * Rows shown per folder before “Show more”. Defaults to `200`; `0` shows
+   * everything. Data is still loaded in full; only rendering is limited.
+   */
+  pageSize?: number;
+  /**
+   * Browsers that must build the ZIP in memory (Firefox, Safari) ask first above
+   * this many MB. Defaults to 500 (200 on touch devices); `0` never asks.
+   */
+  zipWarnSize?: number;
+  /**
+   * …and refuse above this many MB. Defaults to 2048 (1024 on touch devices);
+   * `0` means no limit. Chrome and Edge stream to disk and skip both checks.
+   */
+  zipMaxSize?: number;
   /** Built-in locale. Defaults to `zh-CN`. */
   locale?: FileListLocale;
   /** Per-key label overrides on top of the locale preset. */
@@ -146,6 +186,7 @@ declare const _default: import("vue").DefineComponent<FileListProps, {}, {}, {},
   password: string;
   title: string;
   rememberPassword: boolean;
+  pageSize: number;
   locale: FileListLocale;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
 declare global {
@@ -225,13 +266,13 @@ declare global {
 export declare const fileListLocales: Record<FileListLocale, FileListLabels>;
 export declare function formatLabel(template: string, values?: Record<string, string | number>): string;
 export declare function resolveLabels(locale?: FileListLocale, overrides?: Partial<FileListLabels>): FileListLabels;
-export interface SortableNode {
+interface SortableNode {
   name: string;
   size: number;
   is_dir: boolean;
   modified: string;
 }
-export type SortKey = 'name' | 'size' | 'modified';
+type SortKey = 'name' | 'size' | 'modified';
 export declare function joinPath(parent: string, name: string): string;
 export declare function encodePath(path: string): string;
 /**
@@ -246,24 +287,26 @@ export declare function zipEntryName(segments: string[]): string;
  * The suffix goes before the extension of the last segment. Adds the result to `used`.
  */
 export declare function uniqueEntryName(name: string, used: Set<string>): string;
+/** Human-readable size. `0` reads `0 B`; missing, negative or invalid sizes read `-`. */
 export declare function formatSize(size: number): string;
 export declare function formatDate(iso: string): string;
+/** Upper-case extension for the type badge, e.g. `PDF`. */
 export declare function extOf(name: string): string;
-export type FileKind = 'doc' | 'sheet' | 'slide' | 'pdf' | 'image' | 'media' | 'archive' | 'code' | 'other';
+type FileKind = 'doc' | 'sheet' | 'slide' | 'pdf' | 'image' | 'media' | 'archive' | 'code' | 'other';
+type PreviewKind = 'image' | 'video' | 'audio' | 'text' | 'pdf' | 'none';
 /** Rough file family, used to colour the type badge. */
 export declare function fileKind(name: string): FileKind;
-/** Sum of the `size` of the given entries, ignoring missing or invalid sizes. */
-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 {
+/** Sum of the `size` of the given entries, ignoring missing or invalid sizes. */
+export declare function totalSize(items: Array<{
+  size?: number;
+}>): number;
+export declare function compareNodes(a: SortableNode, b: SortableNode, key: SortKey, ascending?: boolean): number;
+interface IframePreview {
   label: string;
   scheme: string;
 }
@@ -300,4 +343,4 @@ export declare function fillPreviewUrl(scheme: string, args: {
  * ```
  */
 export declare function enhanceAppWithFileList({ app }: EnhanceAppContext): void;
-export { _default as FileList, _default as VPFileList, type FileListLabels, type FileListLocale, type FileListProps, type FileListSource, type OpenListEntry };
+export { type FileKind, _default as FileList, _default as VPFileList, type FileListLabels, type FileListLocale, type FileListProps, type FileListSource, type IframePreview, type OpenListEntry, type PreviewKind, type SortKey, type SortableNode };