vitepress-plugin-filelist 0.1.2 → 0.2.0

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,58 @@ 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` | `'/'` | 初始目录 |
+| `sources` | `FileListSource[]` | `[]` | 多根挂载；设置后忽略 `path` |
+| `expanded` | `boolean` | `false` | 目录根是否默认展开 |
+| `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
+  base="https://pan.example.com"
+  title="课程资料"
+  :sources="[
+    { path: '/课程资料/语文' },
+    { path: '/课程资料/数学', expanded: true },
+    { path: '/课程资料/说明.pdf' }
+  ]"
+/>
+```
+
+- 目录路径挂载为根文件夹，默认折叠；`expanded` 可为全局或单个 source 打开
+- 文件路径挂载为一条文件记录，直接预览/下载
+- 根目录复选框与勾选、全选效果一致：选中根目录会选中其已加载的子项
+- 每个 source 可单独设置 `title`、`password`
+- 根节点顺序按 `sources` 顺序，子项仍按名称/大小/日期排序
+
+```ts
+interface FileListSource {
+  path: string
+  title?: string
+  password?: string
+  expanded?: boolean
+}
+```
+
+## 国际化
 
 ```md
 <FileList locale="en-US" base="https://pan.example.com" />
 ```
 
-Override individual labels on top of the preset:
+在预设基础上覆盖单条文案：
 
 ```md
 <FileList
@@ -98,74 +127,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/dist/client/browser/index.d.ts

@@ -34,11 +34,25 @@ interface FileListLabels {
   batchFailed: string;
   defaultZip: string;
 }
+interface FileListSource {
+  /** OpenList path, directory or single file. */
+  path: string;
+  /** Root label. Defaults to the last path segment. */
+  title?: string;
+  /** Per-source folder password. */
+  password?: string;
+  /** Initial expanded state for a directory source. Overrides the global `expanded` prop. */
+  expanded?: boolean;
+}
 interface FileListProps {
   /** OpenList base URL, e.g. `https://pan.example.com`. Empty string enables demo mode. */
   base?: string;
   /** Initial directory, defaults to `/`. */
   path?: string;
+  /** Mount multiple paths as root nodes. When set, `path` is ignored. */
+  sources?: FileListSource[];
+  /** Expand directory roots initially. Defaults to `false`. */
+  expanded?: boolean;
   /** Optional read-only token. Guest access is used when omitted. */
   token?: string;
   /** Folder password. The component also asks at runtime when OpenList reports one. */
@@ -64,6 +78,8 @@ interface OpenListEntry {
 declare const _default: import("vue").DefineComponent<FileListProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<FileListProps> & Readonly<{}>, {
   base: string;
   path: string;
+  sources: FileListSource[];
+  expanded: boolean;
   token: string;
   password: string;
   title: string;
@@ -176,4 +192,4 @@ export declare function compareNodes(a: SortableNode, b: SortableNode, key: Sort
  * ```
  */
 export declare function enhanceAppWithFileList({ app }: EnhanceAppContext): void;
-export { _default as FileList, _default as VPFileList, type FileListLabels, type FileListLocale, type FileListProps, type OpenListEntry };
+export { _default as FileList, _default as VPFileList, type FileListLabels, type FileListLocale, type FileListProps, type FileListSource, type OpenListEntry };

package/dist/client/browser/index.js

@@ -173,32 +173,33 @@ const _hoisted_23 = [
 	".indeterminate",
 	"onChange"
 ];
-const _hoisted_24 = ["onClick"];
-const _hoisted_25 = {
+const _hoisted_24 = ["title"];
+const _hoisted_25 = ["onClick"];
+const _hoisted_26 = {
 	key: 1,
 	class: "fl-arrow-placeholder"
 };
-const _hoisted_26 = ["onClick"];
-const _hoisted_27 = {
+const _hoisted_27 = ["onClick"];
+const _hoisted_28 = {
 	key: 0,
 	class: "fl-folder-icon"
 };
-const _hoisted_28 = {
+const _hoisted_29 = {
 	key: 1,
 	class: "fl-ext-badge"
 };
-const _hoisted_29 = {
+const _hoisted_30 = {
 	key: 2,
 	class: "fl-loading"
 };
-const _hoisted_30 = { class: "fl-cell fl-cell-size" };
-const _hoisted_31 = { class: "fl-cell fl-cell-date" };
-const _hoisted_32 = { class: "fl-cell fl-cell-op" };
-const _hoisted_33 = ["title", "onClick"];
+const _hoisted_31 = { class: "fl-cell fl-cell-size" };
+const _hoisted_32 = { class: "fl-cell fl-cell-date" };
+const _hoisted_33 = { class: "fl-cell fl-cell-op" };
 const _hoisted_34 = ["title", "onClick"];
-const _hoisted_35 = { class: "fl-foot" };
-const _hoisted_36 = { key: 0 };
-const _hoisted_37 = {
+const _hoisted_35 = ["title", "onClick"];
+const _hoisted_36 = { class: "fl-foot" };
+const _hoisted_37 = { key: 0 };
+const _hoisted_38 = {
 	key: 4,
 	class: "fl-toast"
 };
@@ -207,6 +208,11 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 	props: {
 		base: { default: "" },
 		path: { default: "/" },
+		sources: { default: () => [] },
+		expanded: {
+			type: Boolean,
+			default: false
+		},
 		token: { default: "" },
 		password: { default: "" },
 		title: { default: "" },
@@ -409,14 +415,14 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 			if (payload.code !== 200) throw new ApiError(payload.message || `HTTP ${response.status}`, payload.code ?? response.status);
 			return payload.data;
 		}
-		async function listDir(path) {
+		async function listDir(path, password = activePassword.value) {
 			if (demo.value) {
 				await new Promise((resolve) => setTimeout(resolve, 220));
 				return DEMO_TREE[path] ?? [];
 			}
 			return (await request("/api/fs/list", {
 				path,
-				password: activePassword.value,
+				password,
 				page: 1,
 				per_page: 0,
 				refresh: false
@@ -424,13 +430,14 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 		}
 		async function resolveUrl(node) {
 			if (demo.value) return "";
+			if (node.raw_url) return node.raw_url;
 			const cached = downloadCache.get(node.path);
 			if (cached) return cached;
 			let url = "";
 			try {
 				url = (await request("/api/fs/get", {
 					path: node.path,
-					password: activePassword.value
+					password: node.password || activePassword.value
 				}))?.raw_url ?? "";
 			} catch {
 				url = "";
@@ -455,7 +462,7 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 			nodes.sort((a, b) => compareNodes(a, b, sortKey.value, sortAsc.value));
 			for (const node of nodes) if (node.children.length) sortTree(node.children);
 		}
-		function toNodes(items, parent, depth) {
+		function toNodes(items, parent, depth, password = "") {
 			return items.map((item) => ({
 				...item,
 				path: joinPath(parent, item.name),
@@ -463,7 +470,8 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 				expanded: false,
 				loaded: false,
 				loading: false,
-				children: []
+				children: [],
+				password
 			}));
 		}
 		function setSort(key) {
@@ -472,15 +480,82 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 				sortKey.value = key;
 				sortAsc.value = true;
 			}
-			sortTree(roots.value);
+			if (props.sources.length) {
+				for (const root of roots.value) if (root.children.length) sortTree(root.children);
+			} else sortTree(roots.value);
+		}
+		function sourceName(path) {
+			const parts = path.split("/").filter(Boolean);
+			return parts[parts.length - 1] || path;
+		}
+		async function loadChildren(node) {
+			if (node.loaded) return true;
+			node.loading = true;
+			try {
+				node.children = toNodes(await listDir(node.path, node.password), node.path, node.depth + 1, node.password);
+				sortTree(node.children);
+				node.loaded = true;
+				return true;
+			} catch (error) {
+				showToast(t("folderFailed", { message: errorText(error) }));
+				return false;
+			} finally {
+				node.loading = false;
+			}
+		}
+		async function loadSourceRoot(source) {
+			const path = source.path;
+			const password = source.password ?? "";
+			let item = {
+				name: sourceName(path),
+				size: 0,
+				is_dir: true,
+				modified: ""
+			};
+			if (demo.value) {
+				if (/\/[^/]+\.[^/]+$/.test(path)) item = {
+					...item,
+					is_dir: false,
+					modified: "2026-09-01T08:00:00+08:00"
+				};
+			} else try {
+				const data = await request("/api/fs/get", {
+					path,
+					password
+				});
+				item = {
+					...item,
+					...data
+				};
+			} catch {}
+			return {
+				...item,
+				name: source.title || item.name || sourceName(path),
+				path,
+				depth: 0,
+				expanded: source.expanded ?? props.expanded,
+				loaded: false,
+				loading: false,
+				children: [],
+				password,
+				isRoot: true
+			};
 		}
 		async function loadRoot() {
 			loadingRoot.value = true;
 			errorMsg.value = "";
 			needsPassword.value = false;
 			try {
+				if (props.sources.length) {
+					const nodes = await Promise.all(props.sources.map((source) => loadSourceRoot(source)));
+					roots.value = nodes;
+					for (const node of roots.value) if (node.is_dir && node.expanded) node.expanded = await loadChildren(node);
+					selected.value = /* @__PURE__ */ new Set();
+					downloadCache.clear();
+					return;
+				}
 				const items = await listDir(props.path);
-				roots.value = toNodes(items, props.path, 0);
+				roots.value = toNodes(items, props.path, 0, activePassword.value);
 				sortTree(roots.value);
 				selected.value = /* @__PURE__ */ new Set();
 				downloadCache.clear();
@@ -498,19 +573,7 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 				node.expanded = false;
 				return;
 			}
-			if (!node.loaded) {
-				node.loading = true;
-				try {
-					node.children = toNodes(await listDir(node.path), node.path, node.depth + 1);
-					sortTree(node.children);
-					node.loaded = true;
-				} catch (error) {
-					showToast(t("folderFailed", { message: errorText(error) }));
-					return;
-				} finally {
-					node.loading = false;
-				}
-			}
+			if (!await loadChildren(node)) return;
 			node.expanded = true;
 		}
 		const visible = computed(() => {
@@ -735,6 +798,7 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 						key: node.path,
 						class: normalizeClass(["fl-row", {
 							"fl-row-dir": node.is_dir,
+							"fl-row-root": node.isRoot,
 							"fl-row-selected": selected.value.has(node.path)
 						}])
 					}, [
@@ -746,23 +810,24 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 						}, null, 40, _hoisted_23)]),
 						createElementVNode("span", {
 							class: "fl-cell fl-cell-name",
+							title: node.isRoot ? node.path : void 0,
 							style: normalizeStyle({ paddingLeft: `${node.depth * 22}px` })
 						}, [node.is_dir ? (openBlock(), createElementBlock("button", {
 							key: 0,
 							class: normalizeClass(["fl-arrow", { "fl-arrow-open": node.expanded }]),
 							type: "button",
 							onClick: ($event) => toggleExpand(node)
-						}, "▸", 10, _hoisted_24)) : (openBlock(), createElementBlock("span", _hoisted_25)), createElementVNode("span", {
+						}, "▸", 10, _hoisted_25)) : (openBlock(), createElementBlock("span", _hoisted_26)), createElementVNode("span", {
 							class: normalizeClass(["fl-name", { "fl-name-link": node.is_dir }]),
 							onClick: ($event) => node.is_dir ? toggleExpand(node) : download(node)
 						}, [
-							node.is_dir ? (openBlock(), createElementBlock("span", _hoisted_27, "📁")) : (openBlock(), createElementBlock("span", _hoisted_28, toDisplayString(unref(extOf)(node.name) || "FILE"), 1)),
+							node.is_dir ? (openBlock(), createElementBlock("span", _hoisted_28, "📁")) : (openBlock(), createElementBlock("span", _hoisted_29, toDisplayString(unref(extOf)(node.name) || "FILE"), 1)),
 							createTextVNode(" " + toDisplayString(node.name) + " ", 1),
-							node.loading ? (openBlock(), createElementBlock("span", _hoisted_29, "…")) : createCommentVNode("v-if", true)
-						], 10, _hoisted_26)], 4),
-						createElementVNode("span", _hoisted_30, toDisplayString(node.is_dir ? "-" : unref(formatSize)(node.size)), 1),
-						createElementVNode("span", _hoisted_31, toDisplayString(unref(formatDate)(node.modified)), 1),
-						createElementVNode("span", _hoisted_32, [!node.is_dir ? (openBlock(), createElementBlock(Fragment, { key: 0 }, [canPreview(node) ? (openBlock(), createElementBlock("button", {
+							node.loading ? (openBlock(), createElementBlock("span", _hoisted_30, "…")) : createCommentVNode("v-if", true)
+						], 10, _hoisted_27)], 12, _hoisted_24),
+						createElementVNode("span", _hoisted_31, toDisplayString(node.is_dir ? "-" : unref(formatSize)(node.size)), 1),
+						createElementVNode("span", _hoisted_32, toDisplayString(unref(formatDate)(node.modified)), 1),
+						createElementVNode("span", _hoisted_33, [!node.is_dir ? (openBlock(), createElementBlock(Fragment, { key: 0 }, [canPreview(node) ? (openBlock(), createElementBlock("button", {
 							key: 0,
 							class: "fl-download",
 							type: "button",
@@ -782,7 +847,7 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 							cx: "12",
 							cy: "12",
 							r: "3"
-						})], -1)])], 8, _hoisted_33)) : createCommentVNode("v-if", true), createElementVNode("button", {
+						})], -1)])], 8, _hoisted_34)) : createCommentVNode("v-if", true), createElementVNode("button", {
 							class: "fl-download",
 							type: "button",
 							title: t("download"),
@@ -801,11 +866,11 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 							createElementVNode("path", { d: "M12 3v12" }),
 							createElementVNode("path", { d: "m7 10 5 5 5-5" }),
 							createElementVNode("path", { d: "M5 21h14" })
-						], -1)])], 8, _hoisted_34)], 64)) : createCommentVNode("v-if", true)])
+						], -1)])], 8, _hoisted_35)], 64)) : createCommentVNode("v-if", true)])
 					], 2);
 				}), 128)),
-				createElementVNode("div", _hoisted_35, [createElementVNode("span", null, toDisplayString(t("loaded", { count: allFiles.value.length })) + " · " + toDisplayString(t("selected", { count: selected.value.size })), 1), unloadedFolders.value ? (openBlock(), createElementBlock("span", _hoisted_36, " · " + toDisplayString(t("unloaded", { count: unloadedFolders.value })), 1)) : createCommentVNode("v-if", true)]),
-				toast.value ? (openBlock(), createElementBlock("div", _hoisted_37, toDisplayString(toast.value), 1)) : createCommentVNode("v-if", true)
+				createElementVNode("div", _hoisted_36, [createElementVNode("span", null, toDisplayString(t("loaded", { count: allFiles.value.length })) + " · " + toDisplayString(t("selected", { count: selected.value.size })), 1), unloadedFolders.value ? (openBlock(), createElementBlock("span", _hoisted_37, " · " + toDisplayString(t("unloaded", { count: unloadedFolders.value })), 1)) : createCommentVNode("v-if", true)]),
+				toast.value ? (openBlock(), createElementBlock("div", _hoisted_38, toDisplayString(toast.value), 1)) : createCommentVNode("v-if", true)
 			]);
 		};
 	}

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

@@ -34,11 +34,25 @@ interface FileListLabels {
   batchFailed: string;
   defaultZip: string;
 }
+interface FileListSource {
+  /** OpenList path, directory or single file. */
+  path: string;
+  /** Root label. Defaults to the last path segment. */
+  title?: string;
+  /** Per-source folder password. */
+  password?: string;
+  /** Initial expanded state for a directory source. Overrides the global `expanded` prop. */
+  expanded?: boolean;
+}
 interface FileListProps {
   /** OpenList base URL, e.g. `https://pan.example.com`. Empty string enables demo mode. */
   base?: string;
   /** Initial directory, defaults to `/`. */
   path?: string;
+  /** Mount multiple paths as root nodes. When set, `path` is ignored. */
+  sources?: FileListSource[];
+  /** Expand directory roots initially. Defaults to `false`. */
+  expanded?: boolean;
   /** Optional read-only token. Guest access is used when omitted. */
   token?: string;
   /** Folder password. The component also asks at runtime when OpenList reports one. */
@@ -64,6 +78,8 @@ interface OpenListEntry {
 declare const _default: import("vue").DefineComponent<FileListProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<FileListProps> & Readonly<{}>, {
   base: string;
   path: string;
+  sources: FileListSource[];
+  expanded: boolean;
   token: string;
   password: string;
   title: string;
@@ -176,4 +192,4 @@ export declare function compareNodes(a: SortableNode, b: SortableNode, key: Sort
  * ```
  */
 export declare function enhanceAppWithFileList({ app }: EnhanceAppContext): void;
-export { _default as FileList, _default as VPFileList, type FileListLabels, type FileListLocale, type FileListProps, type OpenListEntry };
+export { _default as FileList, _default as VPFileList, type FileListLabels, type FileListLocale, type FileListProps, type FileListSource, type OpenListEntry };

package/dist/client/ssr/index.js

@@ -131,6 +131,11 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 	props: {
 		base: { default: "" },
 		path: { default: "/" },
+		sources: { default: () => [] },
+		expanded: {
+			type: Boolean,
+			default: false
+		},
 		token: { default: "" },
 		password: { default: "" },
 		title: { default: "" },
@@ -167,6 +172,12 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 		const batchBusy = ref(false);
 		const batchProgress = ref(0);
 		const downloadCache = /* @__PURE__ */ new Map();
+		let toastTimer;
+		function showToast(msg) {
+			toast.value = msg;
+			clearTimeout(toastTimer);
+			toastTimer = setTimeout(() => toast.value = "", 3200);
+		}
 		function errorText(error) {
 			return error instanceof Error ? error.message : String(error);
 		}
@@ -327,14 +338,14 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 			if (payload.code !== 200) throw new ApiError(payload.message || `HTTP ${response.status}`, payload.code ?? response.status);
 			return payload.data;
 		}
-		async function listDir(path) {
+		async function listDir(path, password = activePassword.value) {
 			if (demo.value) {
 				await new Promise((resolve) => setTimeout(resolve, 220));
 				return DEMO_TREE[path] ?? [];
 			}
 			return (await request("/api/fs/list", {
 				path,
-				password: activePassword.value,
+				password,
 				page: 1,
 				per_page: 0,
 				refresh: false
@@ -353,7 +364,7 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 			nodes.sort((a, b) => compareNodes(a, b, sortKey.value, sortAsc.value));
 			for (const node of nodes) if (node.children.length) sortTree(node.children);
 		}
-		function toNodes(items, parent, depth) {
+		function toNodes(items, parent, depth, password = "") {
 			return items.map((item) => ({
 				...item,
 				path: joinPath(parent, item.name),
@@ -361,16 +372,82 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 				expanded: false,
 				loaded: false,
 				loading: false,
-				children: []
+				children: [],
+				password
 			}));
 		}
+		function sourceName(path) {
+			const parts = path.split("/").filter(Boolean);
+			return parts[parts.length - 1] || path;
+		}
+		async function loadChildren(node) {
+			if (node.loaded) return true;
+			node.loading = true;
+			try {
+				node.children = toNodes(await listDir(node.path, node.password), node.path, node.depth + 1, node.password);
+				sortTree(node.children);
+				node.loaded = true;
+				return true;
+			} catch (error) {
+				showToast(t("folderFailed", { message: errorText(error) }));
+				return false;
+			} finally {
+				node.loading = false;
+			}
+		}
+		async function loadSourceRoot(source) {
+			const path = source.path;
+			const password = source.password ?? "";
+			let item = {
+				name: sourceName(path),
+				size: 0,
+				is_dir: true,
+				modified: ""
+			};
+			if (demo.value) {
+				if (/\/[^/]+\.[^/]+$/.test(path)) item = {
+					...item,
+					is_dir: false,
+					modified: "2026-09-01T08:00:00+08:00"
+				};
+			} else try {
+				const data = await request("/api/fs/get", {
+					path,
+					password
+				});
+				item = {
+					...item,
+					...data
+				};
+			} catch {}
+			return {
+				...item,
+				name: source.title || item.name || sourceName(path),
+				path,
+				depth: 0,
+				expanded: source.expanded ?? props.expanded,
+				loaded: false,
+				loading: false,
+				children: [],
+				password,
+				isRoot: true
+			};
+		}
 		async function loadRoot() {
 			loadingRoot.value = true;
 			errorMsg.value = "";
 			needsPassword.value = false;
 			try {
+				if (props.sources.length) {
+					const nodes = await Promise.all(props.sources.map((source) => loadSourceRoot(source)));
+					roots.value = nodes;
+					for (const node of roots.value) if (node.is_dir && node.expanded) node.expanded = await loadChildren(node);
+					selected.value = /* @__PURE__ */ new Set();
+					downloadCache.clear();
+					return;
+				}
 				const items = await listDir(props.path);
-				roots.value = toNodes(items, props.path, 0);
+				roots.value = toNodes(items, props.path, 0, activePassword.value);
 				sortTree(roots.value);
 				selected.value = /* @__PURE__ */ new Set();
 				downloadCache.clear();
@@ -454,8 +531,9 @@ const _sfc_main = /*@__PURE__*/ defineComponent({
 			ssrRenderList(visible.value, (node) => {
 				_push(`<div class="${ssrRenderClass([{
 					"fl-row-dir": node.is_dir,
+					"fl-row-root": node.isRoot,
 					"fl-row-selected": selected.value.has(node.path)
-				}, "fl-row"])}"><span class="fl-cell fl-cell-check"><input type="checkbox"${ssrIncludeBooleanAttr(isChecked(node)) ? " checked" : ""}${ssrRenderAttr("indeterminate", isIndeterminate(node))}></span><span class="fl-cell fl-cell-name" style="${ssrRenderStyle({ paddingLeft: `${node.depth * 22}px` })}">`);
+				}, "fl-row"])}"><span class="fl-cell fl-cell-check"><input type="checkbox"${ssrIncludeBooleanAttr(isChecked(node)) ? " checked" : ""}${ssrRenderAttr("indeterminate", isIndeterminate(node))}></span><span class="fl-cell fl-cell-name"${ssrRenderAttr("title", node.isRoot ? node.path : void 0)} style="${ssrRenderStyle({ paddingLeft: `${node.depth * 22}px` })}">`);
 				if (node.is_dir) _push(`<button type="button" class="${ssrRenderClass([{ "fl-arrow-open": node.expanded }, "fl-arrow"])}">▸</button>`);
 				else _push(`<span class="fl-arrow-placeholder"></span>`);
 				_push(`<span class="${ssrRenderClass([{ "fl-name-link": node.is_dir }, "fl-name"])}">`);

package/dist/client/style.css

@@ -125,6 +125,10 @@
   background: var(--vp-c-bg-soft);
 }
 
+.fl-row-root .fl-name {
+  font-weight: 600;
+}
+
 .fl-row-selected {
   background: var(--vp-c-brand-soft);
 }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "vitepress-plugin-filelist",
-  "version": "0.1.2",
+  "version": "0.2.0",
+  "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",