vvvfs 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -102,12 +102,16 @@ const vvvfs = new VVVFS("vvvfs", {
102
102
  // 用法与 vvvfs 相当
103
103
  ```
104
104
 
105
- ### 使用 `<fs-img>` 自定义元素
105
+ ### 使用 `<fs-img>` / `<fs-audio>` / `<fs-video>` 自定义元素
106
106
 
107
- 库加载后会自动注册 `<fs-img>` 元素,可直接显示 vvvfs 中的图片文件:
107
+ 库加载后会自动注册这三个元素,可直接显示 / 播放 vvvfs 中的媒体文件:
108
108
 
109
109
  ```html
110
110
  <fs-img src="/home/user/Pictures/logo.png" alt="Logo" width="120"></fs-img>
111
+ <fs-audio src="/home/user/Music/demo.mp3"></fs-audio>
112
+ <fs-video src="/home/user/Videos/demo.mp4" width="320"></fs-video>
113
+ <!-- src 也支持 http(s) 云端地址,会先下载到本地缓存再显示 -->
114
+ <fs-img src="https://example.com/Pictures/logo.png"></fs-img>
111
115
  ```
112
116
 
113
117
  ```javascript
@@ -117,19 +121,52 @@ img.src = "/home/user/Pictures/logo.png";
117
121
  document.body.appendChild(img);
118
122
  ```
119
123
 
120
- 属性:
124
+ `src` 除了 vvvfs 内的路径,也支持 `http(s)` 云端地址。文件会缓存到 `/home/.cache/cloud/<hostname>/<pathname>`,再从缓存显示 / 播放:
121
125
 
122
- - `src` / `path`:图片在 vvvfs 中的路径(`src` 优先)
126
+ ```html
127
+ <fs-img src="https://example.com/Pictures/logo.png"></fs-img>
128
+ <fs-video src="https://example.com/Videos/demo.mp4" width="320"></fs-video>
129
+ ```
130
+
131
+ - **缓存优先**:已有缓存时先直接展示缓存,再发送 HEAD 校验远端文件大小;大小不一致、HEAD 未返回 Content-Type 或缓存不可显示时,自动重新下载并刷新
132
+ - **多线程下载**:默认使用 4 线程按 Range 分片并行下载(`vvvfs.downloadFile(url, path, { threads })` 可调整,1-8);文件过小、服务器不支持 Range 或分片失败时自动回退单线程
133
+ - `vvvfs.head(url)` 可单独获取远端文件的 `Content-Length` / `Content-Type`,用于自定义校验
134
+ - 下载使用 `fetch`,目标服务器需允许跨域(CORS)
135
+ - 云端文件同样支持 `watch`,监听的是本地缓存路径
136
+
137
+ 三者共有的属性:
138
+
139
+ - `src` / `path`:媒体路径(`src` 优先),支持 vvvfs 内的路径与 `http(s)` 云端地址
123
140
  - `dbname`:数据库名,默认 `vvvfs`;未指定且存在全局 `vvvfs` 实例时直接使用该实例
124
- - `alt` / `width` / `height`:透传到内部 `<img>` 元素
125
- - `watch`:存在时,文件内容发生变化后自动刷新
141
+ - `watch`:`true` 时启用文件监听,`false` 时停止监听;启用后文件内容发生变化会自动刷新(缺省或空值视为 `true`,兼容 `<fs-img watch>` 的写法)
142
+
143
+ 各自的属性:
126
144
 
127
- 事件:`load`(加载完成)、`error`(加载失败),`detail` 中包含 `path` 与 `file`(或 `message`)。元素上还会写入 `data-state` 属性(`loading` / `loaded` / `error`),便于 CSS 定制。
145
+ - `<fs-img>`:`alt` / `width` / `height` 透传到内部 `<img>` 元素
146
+ - `<fs-audio>`:`autoplay` / `loop` / `muted` / `preload` 透传到内部 `<audio>` 元素;`controls` 默认开启,移除该属性即可关闭
147
+ - `<fs-video>`:`autoplay` / `loop` / `muted` / `preload` / `width` / `height` 透传到内部 `<video>` 元素;`controls` 默认开启,移除该属性即可关闭
128
148
 
129
- 内部使用 Shadow DOM 渲染:图片暴露为 `part="img"`,可用 `fs-img::part(img) { ... }` 定制样式;默认插槽内容会在加载失败或未设置路径时显示(如 `<fs-img src="/a.png">加载失败</fs-img>`)。
149
+ 事件:`load`(加载完成)、`error`(加载失败),`detail` 中包含 `path` 与 `file`(或 `message`);`path` 为媒体文件在 vvvfs 中的实际路径,云端文件即本地缓存路径。元素上还会写入 `data-state` 属性(`loading` / `loaded` / `error`),便于 CSS 定制。
150
+
151
+ 此外提供 `data` 属性(JS 属性),返回当前媒体文件的 Blob 对象(未加载或加载失败时为 `null`),可用于上传、二次处理等场景。
152
+
153
+ 内部使用 Shadow DOM 渲染:媒体元素分别暴露为 `part="img"` / `part="audio"` / `part="video"`,可用 `fs-img::part(img) { ... }` 等定制样式;默认插槽内容会在加载失败或未设置路径时显示(如 `<fs-audio src="/a.mp3">加载失败</fs-audio>`)。
130
154
 
131
155
  ## 更新日志
132
156
 
157
+ ### 0.2.4
158
+ - `<fs-img>` / `<fs-audio>` / `<fs-video>` 的 `src` 支持 `http(s)` 云端地址:文件缓存到 `/home/.cache/cloud/<hostname>/<pathname>` 后显示 / 播放
159
+ - 云端文件改为**缓存优先**:先展示已有缓存,再发送 HEAD 校验远端文件大小;大小不一致、HEAD 未返回 Content-Type 或缓存不可显示时自动重新下载并刷新
160
+ - `downloadFile` 支持多线程下载(默认 4 线程,`threads` 可配置 1-8,按 Range 分片并行);文件过小、服务器不支持 Range 或分片失败时自动回退单线程
161
+ - 新增 `vvvfs.head(url)` 方法,返回远端文件的 `Content-Length` / `Content-Type` / `acceptRanges`
162
+
163
+ ### 0.2.3
164
+
165
+ - 新增 `<fs-audio>` 自定义元素,可直接播放 vvvfs 中的音频文件
166
+ - 新增 `<fs-video>` 自定义元素,可直接播放 vvvfs 中的视频文件
167
+ - `<fs-img>` / `<fs-audio>` / `<fs-video>` 新增 `data` 属性,返回当前媒体文件的 Blob 对象(未加载时为 `null`)
168
+ - `<fs-img>` / `<fs-audio>` / `<fs-video>` 的 `watch` 属性支持 `true` / `false`,为 `false` 时停止文件监听
169
+
133
170
  ### 0.2.2
134
171
 
135
172
  - 新增 `<fs-img>` 自定义元素,可直接显示 vvvfs 中的图片文件
@@ -337,34 +374,71 @@ Using the `VVVFS.File` class:
337
374
  // The usage is equivalent to vvvfs
338
375
  ```
339
376
 
340
- ### Using the `<fs-img>` Custom Element
377
+ ### Using the `<fs-img>` / `<fs-audio>` / `<fs-video>` Custom Elements
341
378
 
342
- Once the library is loaded, the `<fs-img>` element is registered automatically and can display image files stored in vvvfs directly:
379
+ Once the library is loaded, these three elements are registered automatically and can display / play media files stored in vvvfs directly:
343
380
 
344
381
  ```html
345
382
  <fs-img src="/home/user/Pictures/logo.png" alt="Logo" width="120"></fs-img>
383
+ <fs-audio src="/home/user/Music/demo.mp3"></fs-audio>
384
+ <fs-video src="/home/user/Videos/demo.mp4" width="320"></fs-video>
385
+ <!-- src also accepts http(s) URLs; the file is downloaded to the local cache first -->
386
+ <fs-img src="https://example.com/Pictures/logo.png"></fs-img>
346
387
  ```
347
388
 
348
389
  ```javascript
349
- // It can also be created dynamically
390
+ // They can also be created dynamically
350
391
  const img = document.createElement("fs-img");
351
392
  img.src = "/home/user/Pictures/logo.png";
352
393
  document.body.appendChild(img);
353
394
  ```
354
395
 
355
- Attributes:
396
+ Besides paths inside vvvfs, `src` also accepts `http(s)` URLs. The file is cached into `/home/.cache/cloud/<hostname>/<pathname>` and then displayed / played from the cache:
356
397
 
357
- - `src` / `path`: path of the image inside vvvfs (`src` takes precedence)
398
+ ```html
399
+ <fs-img src="https://example.com/Pictures/logo.png"></fs-img>
400
+ <fs-video src="https://example.com/Videos/demo.mp4" width="320"></fs-video>
401
+ ```
402
+
403
+ - **Cache first**: when a cache entry exists it is displayed immediately, then a HEAD request validates the remote file size; if the size differs, the HEAD response has no Content-Type, or the cache cannot be displayed, the file is downloaded again and the element refreshes
404
+ - **Multi-threaded download**: downloads run in 4 parallel Range-based chunks by default (configurable via `vvvfs.downloadFile(url, path, { threads })`, 1-8); it falls back to a single thread when the file is too small, the server ignores Range, or a chunk fails
405
+ - `vvvfs.head(url)` returns the remote `Content-Length` / `Content-Type` on its own for custom validation
406
+ - Downloads use `fetch`, so the target server must allow cross-origin requests (CORS)
407
+ - Cloud files support `watch` as well; the local cache path is what gets watched
408
+
409
+ Attributes shared by all three:
410
+
411
+ - `src` / `path`: media path (`src` takes precedence), either inside vvvfs or an `http(s)` URL
358
412
  - `dbname`: database name, defaults to `vvvfs`; when omitted and a global `vvvfs` instance exists, that instance is used directly
359
- - `alt` / `width` / `height`: passed through to the inner `<img>` element
360
- - `watch`: when present, the image is refreshed automatically after the file content changes
413
+ - `watch`: `true` enables file watching and `false` disables it; when enabled, the media is refreshed automatically after the file content changes (a missing or empty value is treated as `true`, for compatibility with `<fs-img watch>`)
414
+
415
+ Element-specific attributes:
361
416
 
362
- Events: `load` (image loaded) and `error` (loading failed); `detail` contains `path` plus `file` (or `message`). A `data-state` attribute (`loading` / `loaded` / `error`) is also written to the element for CSS customization.
417
+ - `<fs-img>`: `alt` / `width` / `height` are passed through to the inner `<img>` element
418
+ - `<fs-audio>`: `autoplay` / `loop` / `muted` / `preload` are passed through to the inner `<audio>` element; `controls` is enabled by default and can be turned off by removing the attribute
419
+ - `<fs-video>`: `autoplay` / `loop` / `muted` / `preload` / `width` / `height` are passed through to the inner `<video>` element; `controls` is enabled by default and can be turned off by removing the attribute
363
420
 
364
- Rendering happens inside a Shadow DOM: the image is exposed as `part="img"`, so it can be styled with `fs-img::part(img) { ... }`; the default slot content is shown when loading fails or no path is set (e.g. `<fs-img src="/a.png">failed</fs-img>`).
421
+ Events: `load` (media loaded) and `error` (loading failed); `detail` contains `path` plus `file` (or `message`), where `path` is the actual vvvfs path of the media file (the local cache path for cloud files). A `data-state` attribute (`loading` / `loaded` / `error`) is also written to the element for CSS customization.
422
+
423
+ A `data` property (JS property) is also available, returning the Blob object of the current media file (`null` before loading or after a failure), which is useful for uploading or further processing.
424
+
425
+ Rendering happens inside a Shadow DOM: the media element is exposed as `part="img"` / `part="audio"` / `part="video"`, so it can be styled with `fs-img::part(img) { ... }` and friends; the default slot content is shown when loading fails or no path is set (e.g. `<fs-audio src="/a.mp3">failed</fs-audio>`).
365
426
 
366
427
  ## Changelog
367
428
 
429
+ ### 0.2.4
430
+ - The `src` attribute of `<fs-img>` / `<fs-audio>` / `<fs-video>` now accepts `http(s)` URLs: the file is cached into `/home/.cache/cloud/<hostname>/<pathname>` and then displayed / played
431
+ - Cloud files are now **cache-first**: the existing cache is shown immediately, then a HEAD request validates the remote file size; a size mismatch, a missing Content-Type, or an undisplayable cache triggers a fresh download and refresh
432
+ - `downloadFile` supports multi-threaded downloads (4 threads by default, configurable via `threads`, 1-8, using parallel Range chunks); it falls back to a single thread when the file is too small, the server ignores Range, or a chunk fails
433
+ - Added `vvvfs.head(url)`, returning the remote `Content-Length` / `Content-Type` / `acceptRanges`
434
+
435
+ ### 0.2.3
436
+
437
+ - Added the `<fs-audio>` custom element to play audio files stored in vvvfs directly
438
+ - Added the `<fs-video>` custom element to play video files stored in vvvfs directly
439
+ - Added the `data` property to `<fs-img>` / `<fs-audio>` / `<fs-video>`, returning the Blob object of the current media file (`null` before loading)
440
+ - The `watch` attribute of `<fs-img>` / `<fs-audio>` / `<fs-video>` now accepts `true` / `false`; `false` stops the file watching
441
+
368
442
  ### 0.2.2
369
443
 
370
444
  - Added the `<fs-img>` custom element to display image files stored in vvvfs directly