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

+50 -44
View File
@@ -14,72 +14,77 @@ import { validation, convertCssStyle } from './ui/extension';
import { createDateInput, toDateValue, getFormatter, formatDate, setDateValue, getDateValue, DateSelector } from './ui/date';
import * as utility from './utility';
/** @typedef {import('./global')} */
/**
* @param {FrameRequestCallback | TimerHandler} callback
* @returns {number}
*/
function requestAnimationFrame(callback) {
if (typeof utility.global.requestAnimationFrame === 'function') {
utility.global.requestAnimationFrame(callback);
} else {
setTimeout(callback, 0);
return utility.global.requestAnimationFrame(/** @type {FrameRequestCallback} */(callback));
}
return setTimeout(callback, 0);
}
/**
* @private
* @returns {number}
*/
function scrollLeft() {
const n = document.documentElement;
return (utility.global.scrollX || n.scrollLeft) - (n.clientLeft || 0);
}
/**
* @private
* @returns {number}
*/
function scrollTop() {
const n = document.documentElement;
return (utility.global.scrollY || n.scrollTop) - (n.clientTop || 0);
}
/**
* @private
* @param {HTMLElement} e
* @returns {DOMRectReadOnly}
*/
function offset(e) {
const rect = e.getBoundingClientRect();
return {
top: rect.top + scrollTop(),
left: rect.left + scrollLeft(),
height: rect.height,
width: rect.width
};
return new DOMRectReadOnly(
rect.left + scrollLeft(),
rect.top + scrollTop(),
rect.width,
rect.height
);
}
class OptionBase {
_option;
/** @type {import('./types').GetTextCallback} */
r;
/**
* @param {import('./types').OptionParamBase} opt
*/
constructor(opt) {
this._option = opt;
const getText = opt.getText;
if (typeof getText === 'function') {
this.r = getText;
} else if (typeof GetTextByKey === 'function') {
this.r = GetTextByKey;
} else if (typeof utility.global.GetTextByKey === 'function') {
this.r = utility.global.GetTextByKey;
} else {
this.r = utility.r;
}
}
}
/**
* 通知选项
* @typedef NotifyOption
* @property {string | HTMLElement} message - 内容,支持自定义元素
* @property {HTMLElement} [parent] - 目标父元素
* @property {string} [title] - 标题
* @property {"success" | "warning" | "error"} [type] - 提示类型
* @property {boolean} [persistent] - 是否持续显示,默认为 `false`,3 秒后自动关闭
* @property {number} [timeout] - 超时时间,默认 3 秒
* @property {(auto: boolean) => void} [onDismissed] - 关闭时触发的函数
*/
/**
* @private
* @param {HTMLDivElement} wrapper
* @param {(auto: boolean) => void} [onDismissed]
* @param {(auto?: boolean) => void} [onDismissed]
* @param {boolean} [auto]
*/
function closeNotify(wrapper, onDismissed, auto) {
@@ -93,22 +98,26 @@ function closeNotify(wrapper, onDismissed, auto) {
}
/**
*
* @param {NotifyOption} opts
* @param {import('./types').NotifyOption} [opts]
* @returns {HTMLDivElement | undefined}
*/
function notify(opts) {
opts ||= {};
const message = opts?.message;
if (message == null) {
return;
}
/** @type {number} */
let timer;
const close = createIcon('fa-light', 'times');
close.classList.add('ui-notify-close');
close.addEventListener('click', () => {
timer && clearTimeout(timer);
closeNotify(wrapper, opts.onDismissed);
closeNotify(wrapper, opts?.onDismissed);
});
let type;
let typeClass;
opts.type ||= 'success';
switch (opts.type) {
switch (opts?.type) {
case 'warning':
type = 'exclamation-circle';
typeClass = 'warning';
@@ -117,39 +126,36 @@ function notify(opts) {
type = 'times-circle';
typeClass = 'error';
break;
case 'success':
type = 'check-circle';
typeClass = 'success';
break;
default:
type = opts.type;
type = opts?.type ?? 'check-circle';
typeClass = 'success';
break;
}
const icon = createIcon('fa-solid', type);
icon.classList.add('ui-notify-type', typeClass);
const title = opts?.title;
const wrapper = createElement('div', 'ui-notify',
utility.nullOrEmpty(opts.title) ?
utility.nullOrEmpty(title) ?
createElement('div', 'ui-notify-single',
icon,
createElement('span', 'ui-notify-message', opts.message),
createElement('span', 'ui-notify-message', message),
close
) :
createElement('div', 'ui-notify-content',
createElement('div', 'ui-notify-header',
icon,
createElement('h2', 'ui-notify-title', opts.title),
createElement('h2', 'ui-notify-title', title),
close
),
createElement('span', 'ui-notify-message', opts.message)
createElement('span', 'ui-notify-message', message)
)
);
if (!opts.persistent) {
if (opts?.persistent !== true) {
timer = setTimeout(() => {
closeNotify(wrapper, opts.onDismissed, true);
}, opts.timeout || 3000);
closeNotify(wrapper, opts?.onDismissed, true);
}, opts?.timeout || 3000);
}
(opts.parent ?? document.body).appendChild(wrapper);
(opts?.parent ?? document.body).appendChild(wrapper);
setTimeout(() => wrapper.classList.add('active'), 10);
return wrapper;
}