add jsdoc comments

This commit is contained in:
lchen committed 2026-11-18 10:14:21 +08:00
1 parent 6de354ad47
commit 8c1205bc13
24 files changed
+1228 -425

No files matched your search

+68 -14
View File
@@ -3,6 +3,10 @@ import { createElement } from "../functions";
import { createIcon } from "./icon";
import { get } from "../utility/request";
/**
* @param {string} url
* @returns {HTMLAnchorElement}
*/
export function createPicture(url) {
return createElement('a', a => {
a.className = 'ui-media-picture';
@@ -15,18 +19,30 @@ export function createPicture(url) {
);
}
/**
* @private
* @param {Blob} blob
* @returns {Promise<Uint8Array<ArrayBuffer>>}
*/
function readBlob(blob) {
return new Promise((resolve, reject) => {
const reader = new FileReader();
reader.onload = e => {
if (e.target?.result instanceof ArrayBuffer) {
const data = new Uint8Array(e.target.result);
resolve(data);
}
};
reader.onerror = reject;
reader.readAsArrayBuffer(blob);
});
}
/**
*
* @param {Uint8Array<ArrayBuffer>} array
* @returns
*/
function playAmrArray(array) {
return new Promise((resolve, reject) => {
const samples = AMR.decode(array);
@@ -38,6 +54,12 @@ function playAmrArray(array) {
});
}
/**
* @private
* @param {Float32Array<ArrayBuffer>} samples
* @param {(ctx: AudioContext) => void} ended
* @returns {Promise<AudioContext>}
*/
function playPcm(samples, ended) {
return new Promise(resolve => {
const ctx = new AudioContext();
@@ -61,6 +83,11 @@ function playPcm(samples, ended) {
});
}
/**
* @private
* @param {number} time
* @returns {string}
*/
function getTimeLabel(time) {
// time = Math.round(time);
// return String(Math.floor(time / 60)).padStart(2, '0') + ':' + String(time % 60).padStart(2, '0');
@@ -76,11 +103,18 @@ function getTimeLabel(time) {
return m + ':' + String(time % 60).padStart(2, '0');
}
/**
* @param {string} mime
* @param {string} url
* @returns {HTMLAudioElement | HTMLDivElement}
*/
export function createAudio(mime, url) {
if ((mime === 'audio/amr' || mime === '.amr') && typeof AMR !== 'undefined') {
const timestamp = createElement('span', 'ui-media-timestamp');
timestamp.textContent = '0:00 / 0:00';
/** @type {AudioContext | null} */
let context;
/** @type {number} */
let timer;
return createElement('div', 'ui-media-audio',
createElement('button', button => {
@@ -132,6 +166,10 @@ export function createAudio(mime, url) {
});
}
/**
* @param {string} url
* @returns {HTMLVideoElement}
*/
export function createVideo(url) {
return createElement('video', video => {
video.className = 'ui-media-video';
@@ -140,6 +178,11 @@ export function createVideo(url) {
});
}
/**
* @param {string} url
* @param {string} icon
* @returns {HTMLDivElement}
*/
export function createFile(url, icon = 'file-alt') {
return createElement('div', `ui-media-file ${icon}`,
createIcon('fa-solid', icon),
@@ -151,15 +194,19 @@ export function createFile(url, icon = 'file-alt') {
);
}
/**
* @typedef VideoPlayOptions
* @property {boolean} [autoPlay] 是否自动播放
* @property {boolean} [autoFullScreen] 是否自动全屏
* @property {boolean} [autoLoop] 是否循环播放
* @property {Function} [onLoaded] 视频加载完成回调
*/
/**
* 创建联动视频元素
* @param {string[]} urls - 视频 url 数组
* @param {any} [options] - 播放参数
* @param {boolean} options.[autoPlay] - 是否自动播放
* @param {boolean} options.[autoFullScreen] - 是否自动全屏
* @param {boolean} options.[autoLoop] - 是否循环播放
* @param {Function} options.[onLoaded] - 视频加载完成回调
* @param {Function} [callback] - 视频元素处理回调函数
* @param {string[]} urls 视频 url 数组
* @param {VideoPlayOptions} [options] 播放参数
* @param {(wrapper: HTMLDivElement) => void} [callback] 视频元素处理回调函数
* @returns {HTMLDivElement} 返回联动视频元素
*/
export function createVideoList(urls, options, callback) {
@@ -169,10 +216,13 @@ export function createVideoList(urls, options, callback) {
const length = urls.length;
const container = createElement('div', 'ui-media-video-container');
let seekBufferBar;
/** @type {HTMLDivElement} */
let seekProgressBar;
let playIcon;
let timeLabel;
/** @type {HTMLDivElement} */
let volumeProgressBar;
/** @type {HTMLDivElement} */
let volumeIcon;
const videos = Array(length);
@@ -180,10 +230,14 @@ export function createVideoList(urls, options, callback) {
let prepared = 0;
let ended = 0;
/** @type {boolean} */
let playing;
let duration = -1;
/** @type {string} */
let durationLabel;
/** @type {number} */
let seekBarWidth;
/** @type {boolean} */
let mousing;
const controller = createElement('div', 'ui-video-control active',
createElement('div', seek => {
@@ -369,7 +423,7 @@ export function createVideoList(urls, options, callback) {
video.addEventListener('progress', () => {
const buffered = video.buffered;
for (let i = 0; i < buffered.length; ++i) {
let buffer = seekBufferBar.children[i];
let buffer = /** @type {HTMLElement} */ (seekBufferBar.children[i]);
if (buffer == null) {
seekBufferBar.append(buffer = createElement('div', 'ui-video-buffer'));
}
@@ -383,9 +437,9 @@ export function createVideoList(urls, options, callback) {
}
});
video.addEventListener('canplaythrough', () => {
const w = video.parentElement.querySelector('.ui-video-waiting');
if (w != null) {
w.style.opacity = 0;
const w = video.parentElement?.querySelector('.ui-video-waiting');
if (w instanceof HTMLElement) {
w.style.opacity = '0';
}
if (waiting[i]) {
waiting[i] = false;
@@ -406,9 +460,9 @@ export function createVideoList(urls, options, callback) {
});
video.addEventListener('waiting', () => {
waiting[i] = true;
const w = video.parentElement.querySelector('.ui-video-waiting');
if (w != null) {
w.style.opacity = 1;
const w = video.parentElement?.querySelector('.ui-video-waiting');
if (w instanceof HTMLElement) {
w.style.opacity = '1';
}
videos.forEach(v => v.pause());
});