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/Img.ts +17 -599
- package/Media.ts +880 -0
- package/README.md +91 -17
- package/dist/vvvfs.min.js +22 -10
- package/index.ts +182 -5
- package/package.json +1 -1
- package/types/index.d.ts +150 -10
- package//345/205/261/345/210/233/350/276/211/347/205/214/357/274/210/351/224/241/350/201/214/345/244/247/344/271/213/346/255/214/357/274/211.flac +0 -0
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
|
-
|
|
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
|
-
|
|
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
|
-
- `
|
|
125
|
-
|
|
141
|
+
- `watch`:`true` 时启用文件监听,`false` 时停止监听;启用后文件内容发生变化会自动刷新(缺省或空值视为 `true`,兼容 `<fs-img watch>` 的写法)
|
|
142
|
+
|
|
143
|
+
各自的属性:
|
|
126
144
|
|
|
127
|
-
|
|
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
|
-
|
|
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
|
|
377
|
+
### Using the `<fs-img>` / `<fs-audio>` / `<fs-video>` Custom Elements
|
|
341
378
|
|
|
342
|
-
Once the library is loaded,
|
|
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
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
- `
|
|
360
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|