vitepress-plugin-filelist 0.1.2 → 0.1.3

package/README.md

@@ -1,29 +1,27 @@
 # vitepress-plugin-filelist
 
-OpenList file browser for VitePress — tree view, batch ZIP download, folder password and token support.
+面向 VitePress 的 OpenList 文件浏览组件：树形展开、勾选批量打包、目录密码、token，直接调用 OpenList 接口。
 
-VitePress 的 OpenList 文件浏览组件：树形展开、勾选批量打包、目录密码、token，直接调用 OpenList 接口。
+## 功能
 
-## Features
+- 📁 树形目录，文件夹按需加载
+- ✅ 勾选文件；选中文件夹会连带其已加载的子项
+- 📦 批量打包 ZIP（基于 `fflate`），带进度
+- ⬇️ 单文件下载与预览（`/d/`、`/p/`、`fs/get` 的 `raw_url`）
+- 🔐 目录密码输入，可选只读 token
+- 🔎 当前树过滤，按名称 / 大小 / 日期排序
+- 🌐 使用 `/api/fs/list`、`/api/fs/get`、`/api/public/settings`
+- 🧪 `base` 为空时使用内置演示数据
+- SSR 安全（网络请求只在客户端执行）
 
-- 📁 Tree view with lazy-loaded folders
-- ✅ Checkbox selection, folder selects its loaded children
-- 📦 Batch download as ZIP (via `fflate`), with progress
-- ⬇️ Single file download and preview (`/d/`, `/p/`, `fs/get` raw URL)
-- 🔐 Folder password prompt, optional read-only token
-- 🔎 Filter current tree, sortable name / size / date
-- 🌐 Uses `/api/fs/list`, `/api/fs/get`, `/api/public/settings`
-- 🧪 Demo mode with built-in fake data when `base` is empty
-- SSR safe (network requests only run on the client)
-
-## Install
+## 安装
 
 ```bash
 pnpm add -D vitepress-plugin-filelist
-# or: npm i -D vitepress-plugin-filelist
+# 或：npm i -D vitepress-plugin-filelist
 ```
 
-## Usage with vitepress-tuck
+## 在 vitepress-tuck 中使用
 
 ```ts
 // .vitepress/config.ts
@@ -53,7 +51,7 @@ export default {
 <FileList base="https://pan.example.com" path="/课程资料" />
 ```
 
-## Usage with plain VitePress
+## 在普通 VitePress 中使用
 
 ```ts
 // .vitepress/theme/index.ts
@@ -69,27 +67,27 @@ export default {
 }
 ```
 
-## Props
+## 组件属性
 
-| Prop | Type | Default | Description |
+| 属性 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
-| `base` | `string` | `''` | OpenList base URL. Empty = demo mode |
-| `path` | `string` | `'/'` | Initial directory |
-| `token` | `string` | `''` | Optional read-only token (guest when omitted) |
-| `password` | `string` | `''` | Folder password; can also be entered at runtime |
-| `title` | `string` | `''` | Toolbar title; falls back to OpenList `site_title` |
-| `locale` | `'zh-CN' \| 'en-US'` | `'zh-CN'` | Built-in label preset |
-| `labels` | `Partial<FileListLabels>` | `undefined` | Per-key label overrides |
+| `base` | `string` | `''` | OpenList 站点地址；为空时进入演示模式 |
+| `path` | `string` | `'/'` | 初始目录 |
+| `token` | `string` | `''` | 可选只读 token；不传则以游客身份请求 |
+| `password` | `string` | `''` | 目录密码，也可以在运行时输入 |
+| `title` | `string` | `''` | 工具栏标题；为空时回退到 OpenList 的 `site_title` |
+| `locale` | `'zh-CN' \| 'en-US'` | `'zh-CN'` | 内置文案预设 |
+| `labels` | `Partial<FileListLabels>` | `undefined` | 按 key 覆盖单条文案 |
 
-Both `<FileList>` and `<VPFileList>` are registered.
+同时注册了 `<FileList>` 和 `<VPFileList>` 两个组件名。
 
-## i18n
+## 国际化
 
 ```md
 <FileList locale="en-US" base="https://pan.example.com" />
 ```
 
-Override individual labels on top of the preset:
+在预设基础上覆盖单条文案：
 
 ```md
 <FileList
@@ -98,74 +96,76 @@ Override individual labels on top of the preset:
 />
 ```
 
-Available presets: `zh-CN`, `en-US`. Placeholders use `{count}`, `{percent}`, `{message}`, `{name}` and are replaced by `formatLabel()`. The full key list is exported as `FileListLabels`:
+内置预设：`zh-CN`、`en-US`。占位符支持 `{count}`、`{percent}`、`{message}`、`{name}`，由 `formatLabel()` 替换。完整 key 列表通过 `FileListLabels` 导出：
 
 ```ts
 import type { FileListLabels } from 'vitepress-plugin-filelist/client'
 import { fileListLocales, formatLabel, resolveLabels } from 'vitepress-plugin-filelist/client'
 ```
 
-## OpenList requirements
+## OpenList 要求
 
-1. **Guest read access** — enable the guest user, or pass a read-only `token`.
-2. **CORS** — OpenList's `cors.allow_origins` must include your site origin (default `*`).
-3. **Same protocol** — an HTTPS page cannot call an HTTP OpenList (mixed content).
-4. **Token is public** — only ship a read-only token that can be revoked.
+1. **游客只读权限**：开启游客用户，或传入只读 `token`
+2. **CORS**：OpenList 的 `cors.allow_origins` 必须包含站点来源（默认 `*`）
+3. **同协议**：HTTPS 页面不能请求 HTTP 的 OpenList（混合内容）
+4. **token 是公开的**：只放可撤销的只读 token，不要放管理 token
 
-The component calls:
+组件会调用：
 
-| Endpoint | Purpose |
+| 接口 | 用途 |
 | --- | --- |
-| `POST /api/fs/list` | Directory listing (`per_page: 0`) |
-| `POST /api/fs/get` | `raw_url` for download / preview / ZIP; falls back to `/d/...?sign=` |
-| `GET /api/public/settings` | `site_title` fallback |
-| `GET /d/...` `GET /p/...` | Download / preview links generated by OpenList |
+| `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 生成的下载 / 预览链接 |
 
-## Exports
+## 导出
 
-| Entry | Contents |
+| 入口 | 内容 |
 | --- | --- |
-| `vitepress-plugin-filelist` | `fileList` plugin (default export) |
-| `vitepress-plugin-filelist/client` | `FileList`, `VPFileList`, `enhanceAppWithFileList`, types |
-| `vitepress-plugin-filelist/style.css` | Component styles |
+| `vitepress-plugin-filelist` | `fileList` 插件（默认导出） |
+| `vitepress-plugin-filelist/client` | `FileList`、`VPFileList`、`enhanceAppWithFileList`、类型 |
+| `vitepress-plugin-filelist/style.css` | 组件样式 |
 
-## Compatibility
+## 兼容性
 
-Peer dependency allows VitePress 1.x and 2.0 alpha: `^1.0.0 || ^2.0.0-alpha.0`.
+peerDependencies 同时支持 VitePress 1.x 与 2.0 alpha：`^1.0.0 || ^2.0.0-alpha.0`。
 
-Tested locally against VitePress `2.0.0-alpha.21` on Node 22:
+在 Node 22 下针对 VitePress `2.0.0-alpha.21` 本地实测：
 
-| Package manager | Install | Build |
+| 包管理器 | 安装 | 构建 |
 | --- | --- | --- |
 | npm 10 | ✅ | ✅ |
 | pnpm 11.25 | ✅ | ✅ |
-| yarn 1.22 (classic) | ✅ | ✅ |
+| yarn 1.22（classic） | ✅ | ✅ |
 | bun 1.4 | ✅ | ✅ |
-| deno 2.9 | ✅ `deno install` | ❌ fails while Vite/rolldown loads the config |
+| deno 2.9 | ✅ `deno install` | ❌ Vite/rolldown 加载配置时失败 |
 
-Deno can install the npm dependency, but building a VitePress site with Deno currently fails inside rolldown (`stream did not contain valid UTF-8`). Use Node for builds.
+Deno 可以安装 npm 依赖，但目前用 Deno 构建 VitePress 会在 rolldown 里报 `stream did not contain valid UTF-8`；构建请使用 Node。
 
-## Release
+## 发布
 
-Published to npm from GitHub Actions via Trusted Publishing (OIDC) with provenance.
+通过 GitHub Actions 的 Trusted Publishing（OIDC）发布到 npm，带 provenance。
 
-## Notes
+## 说明
 
-- Batch ZIP downloads files through `raw_url` (OpenList `/p/` proxy), which keeps CORS on the OpenList origin.
-- Select-all only counts already-loaded files; the footer reports how many folders are still collapsed.
-- Directory listings are requested with `per_page: 0` (all entries). Very large folders may be slow; pagination is not implemented yet.
+- 批量 ZIP 通过 `raw_url`（OpenList `/p/` 代理）下载，CORS 保持在 OpenList 源上
+- 全选只统计已加载的文件；页脚会显示还有多少文件夹未展开
+- 目录以 `per_page: 0` 请求全部条目；超大目录可能较慢，暂未实现分页
 
-## Development
+## 开发
 
 ```bash
-npm install
-npm run build       # dist/node, dist/client/ssr, dist/client/browser, style.css
-npm run typecheck
-npm test            # Vitest: utils + locale helpers
-npm run pack:check
+pnpm install
+pnpm run build       # 生成 dist/node、dist/client/ssr、dist/client/browser、style.css
+pnpm run typecheck
+pnpm test            # Vitest：utils + locale helpers
+pnpm run pack:check
 ```
 
-The demo site in `demo/` installs the package through `file:..`:
+仓库统一使用 pnpm（`pnpm-lock.yaml`），CI 与发布流程执行 `pnpm install --frozen-lockfile`。
+
+`demo/` 下的演示站通过 `file:..` 安装本地包：
 
 ```bash
 cd demo

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "vitepress-plugin-filelist",
-  "version": "0.1.2",
+  "version": "0.1.3",
+  "packageManager": "pnpm@11.25.0",
   "type": "module",
   "description": "OpenList file browser for VitePress: tree view, batch ZIP download, i18n, password and token support.",
   "author": "nrjycyd",