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

+79 -86
View File
@@ -1,20 +1,18 @@
import { createElement } from "../functions";
import { isPositive, nullOrEmpty } from "../utility";
import { isPositive, isTag, nullOrEmpty } from "../utility";
/**
* 创建或转换日期选择框
* @param {string} [min] - 最小可选日期
* @param {string} [max] - 最大可选日期
* @param {HTMLInputElement | string} [element] - 转换该元素为日期选择框
* @param {string | null} [min] 最小可选日期
* @param {string | null} [max] 最大可选日期
* @param {HTMLInputElement | string} [element] 转换该元素为日期选择框
* @returns {HTMLInputElement} 返回创建或转换的日期选择框
*/
export function createDateInput(min, max, element) {
let date;
if (typeof element === 'string') {
element = document.querySelector(element);
}
if (element instanceof HTMLInputElement) {
date = element;
const e = typeof element === 'string' ? document.querySelector(element) : element;
if (e instanceof HTMLInputElement) {
date = e;
date.classList.add('ui-date-cell');
} else {
date = createElement('input', 'ui-date-cell');
@@ -41,7 +39,7 @@ export function createDateInput(min, max, element) {
* @returns 返回 `yyyy-MM-dd` 格式的字符串
*/
export function toDateValue(dt, local) {
if (isNaN(dt)) {
if (!(dt instanceof Date) || isNaN(dt.getTime())) {
return '';
}
const year = local ? dt.getFullYear() : dt.getUTCFullYear();
@@ -52,8 +50,8 @@ export function toDateValue(dt, local) {
/**
* 获取日期格式器
* @param {Date} date - 待格式的日期
* @param {boolean} [utc=true] - 是否按 UTC 时间格式化
* @param {Date} date 待格式的日期
* @param {boolean} [utc=true] 是否按 UTC 时间格式化
* @returns {any} 返回格式化工具对象
*/
export function getFormatter(date, utc) {
@@ -96,11 +94,11 @@ export function getFormatter(date, utc) {
t: () => new Date(r.Y(), r.n(), 0).getDate(),
/**
* @private
* @returns {('1' | '0')} 返回是否为闰年
* @returns {(1 | 0)} 返回是否为闰年
*/
L() {
const y = r.Y();
return t % 4 === 0 && t % 100 !== 0 || t % 400 === 0 ? 1 : 0;
return y % 4 === 0 && y % 100 !== 0 || y % 400 === 0 ? 1 : 0;
},
/**
* @private
@@ -151,7 +149,7 @@ export function getFormatter(date, utc) {
* @private
* @returns {string} 返回时区描述字符串
*/
e: () => /\((.*)\)/.exec(String(date))[1] || 'Coordinated Universal Time',
e: () => /\((.*)\)/.exec(String(date))?.[1] || 'Coordinated Universal Time',
/**
* @private
* @returns {string} 返回时区偏移字符串
@@ -175,7 +173,7 @@ export function getFormatter(date, utc) {
/**
* 格式化日期为 M/d/yyyy 格式的字符串
* @param {Date | number | string} date - 需要格式化的日期值,支持的格式如下:
* @param {Date | number | string} date 需要格式化的日期值,支持的格式如下:
*
* * `"2024-01-26"`
* * `"2024/1/26"`
@@ -183,7 +181,7 @@ export function getFormatter(date, utc) {
* * `"1/26/2024"`
* * `"638418240000000000"`
* * `new Date('2024-01-26')`
* @param {string} [formatter] - 格式化格式,默认为 `"m/d/Y"`
* @param {string} [formatter] 格式化格式,默认为 `"m/d/Y"`
*
* * Y - 年,例如 `2024`
* * y - 年的后两位,例如 `"24"`
@@ -212,17 +210,17 @@ export function formatDate(date, formatter) {
if (date === '') {
return '';
}
if (isNaN(date)) {
if (typeof date === 'string') {
let e = /^(\d{4})-(\d{2})-(\d{2})/.exec(date);
if (e == null) {
e = /^(\d{4})\/(\d{1,2})\/(\d{1,2})/.exec(date);
}
if (e != null) {
date = new Date(e[1], parseInt(e[2]) - 1, e[3]);
date = new Date(parseInt(e[1]), parseInt(e[2]) - 1, parseInt(e[3]));
} else {
e = /^(\d{1,2})\/(\d{1,2})\/(\d{4})$/.exec(date);
if (e != null) {
date = new Date(e[3], parseInt(e[1]) - 1, e[2]);
date = new Date(parseInt(e[3]), parseInt(e[1]) - 1, parseInt(e[2]));
} else {
return date;
}
@@ -238,20 +236,23 @@ export function formatDate(date, formatter) {
const f = getFormatter(date);
return formatter.replace(/\\?(.?)/gi, (k, v) => f[k] ? f[k]() : v);
}
return date;
return String(date);
}
/**
* 设置显示日期
* @param {HTMLElement} element - 要设置显示日期的元素
* @param {HTMLElement | undefined} element - 要设置显示日期的元素
* @param {Date | number | string} val - 日期值,支持格式参见 {@linkcode formatDate}
* @param {string} [formatter] - 日期格式化字符串(仅设置显示元素时调用)
*/
export function setDateValue(element, val, formatter) {
if (element.tagName === 'INPUT') {
if (element == null) {
return;
}
if (isTag(element, 'input')) {
if (val === '') {
element.value = '';
} else if (isNaN(val)) {
} else if (typeof val === 'string') {
if (/^\d{4}-\d{2}-\d{2}/.test(val)) {
element.value = String(val).substring(0, 10);
} else if (/^\d{4}\/\d{2}\/\d{2}/.test(val)) {
@@ -299,7 +300,7 @@ export function setDateValue(element, val, formatter) {
*/
export function getDateValue(element, formatter) {
const date = element?.valueAsDate;
if (date instanceof Date && !isNaN(date)) {
if (date instanceof Date && !isNaN(date.getTime())) {
const year = date.getUTCFullYear();
if (year < 1900 || year > 9999) {
return '';
@@ -319,6 +320,16 @@ export function getDateValue(element, formatter) {
return '';
}
/**
* @typedef DateOptions
* @property {boolean} [enabled=true] 是否可用
* @property {string | null} [minDate] 最小可选择日期
* @property {string | null} [maxDate] 最大可选择日期
* @property {number} [tabIndex] 索引
* @property {string} [className] 类型名
* @property {DateFormatterCallback} [valueFormatter] 自定义格式化函数
*/
/**
* 日期选择框类
* @class
@@ -326,48 +337,22 @@ export function getDateValue(element, formatter) {
export class DateSelector {
_var = {
/**
* @type {HTMLInputElement}
* @type {HTMLInputElement | undefined}
* @private
*/
el: null,
options: {
/**
* @type {boolean?}
* @private
*/
enabled: true,
/**
* @type {string?}
* @private
*/
minDate: null,
/**
* @type {string?}
* @private
*/
maxDate: null,
/**
* @type {number?}
* @private
*/
tabIndex: null,
/**
* @type {string?}
* @private
*/
className: null,
/**
* @type {DateFormatterCallback?}
* @private
*/
valueFormatter: null
}
el: undefined,
/**
* @type {DateOptions}
* @private
*/
options: {}
};
/**
* 日期发生变化时触发的事件
* @type {((date?: Date) => void) | undefined}
* @event
* @param {Date} date - 修改后的日期值
* @param {Date} [date] - 修改后的日期值
* @this DateSelector
*/
onDateChanged;
@@ -375,11 +360,7 @@ export class DateSelector {
/**
* 日期选择框构造函数
* @constructor
* @param {object} [opts] - 日期选择框初始化参数
* @param {boolean} [opts.enabled] - 是否可用
* @param {string} [opts.minDate] - 最小可选择日期
* @param {string} [opts.maxDate] - 最大可选择日期
* @param {DateFormatterCallback} [opts.valueFormatter] - 自定义格式化函数
* @param {DateOptions} [opts] 日期选择框初始化参数
* @example <caption>创建一个 DateSelector 并插入到元素中</caption>
* <div id="dateFrom"></div>
* @example
@@ -400,7 +381,9 @@ export class DateSelector {
* dateSelectorTo.create('#dateTo');
*/
constructor(opts) {
this._var.options = opts ?? {};
if (opts != null) {
this._var.options = opts;
}
}
/**
@@ -411,7 +394,7 @@ export class DateSelector {
create(element) {
const opts = this._var.options;
const el = createDateInput(opts.minDate, opts.maxDate, element);
isPositive(opts.tabIndex) && el.setAttribute('tabindex', opts.tabIndex);
isPositive(opts.tabIndex) && el.setAttribute('tabindex', String(opts.tabIndex));
if (!nullOrEmpty(opts.className)) {
el.classList.add(opts.className);
}
@@ -419,6 +402,9 @@ export class DateSelector {
el.disabled = opts.enabled === false;
}
el.addEventListener('blur', e => {
if (!(e.target instanceof HTMLInputElement)) {
return;
}
const date = this._getDate(e.target.valueAsDate);
if (date == null) {
e.target.value = '';
@@ -434,7 +420,7 @@ export class DateSelector {
/**
* 获取日期选择框元素
* @readonly
* @type {HTMLInputElement}
* @type {HTMLInputElement | undefined}
*/
get element() { return this._var.el }
@@ -442,57 +428,63 @@ export class DateSelector {
* 获取或设置日期选择框是否启用
* @type {boolean}
*/
get enabled() { return !this._var.el.disabled }
get enabled() { return this._var.el?.disabled === false }
set enabled(flag) {
this._var.el.disabled = flag === false;
if (this._var.el != null) {
this._var.el.disabled = flag === false;
}
}
/**
* 获取格式化的日期值,或设置日期值,支持的格式参见 {@linkcode formatDate}
* @type {string | any}
* @type {Date | undefined}
*/
get value() { return this._getDate(this._var.el.valueAsDate) }
get value() { return this._getDate(this._var.el?.valueAsDate) }
/** @param {string | number | Date} val */
set value(val) {
setDateValue(this._var.el, val);
}
/**
* 获取或设置最小可选择日期
* @type {string}
* @type {string | undefined}
*/
get minDate() { return this._var.el.min }
get minDate() { return this._var.el?.min }
set minDate(date) {
this._var.el.min = date;
if (this._var.el != null && !nullOrEmpty(date)) {
this._var.el.min = date;
}
this._var.options.minDate = date;
}
/**
* 获取或设置最大可选择日期
* @type {string}
* @type {string | undefined}
*/
get maxDate() { return this._var.el.max }
get maxDate() { return this._var.el?.max }
set maxDate(date) {
this._var.el.max = date;
if (this._var.el != null && !nullOrEmpty(date)) {
this._var.el.max = date;
}
this._var.options.maxDate = date;
}
/**
* @private
* @param {Date} date
* @returns {Date | any}
* @param {Date | null | undefined} date
* @returns {Date | undefined}
*/
_getDate(date) {
if (date instanceof Date && !isNaN(date)) {
if (date instanceof Date && !isNaN(date.getTime())) {
const year = date.getUTCFullYear();
if (year < 1900 || year > 9999) {
return null;
return;
}
if (typeof this._var.options.valueFormatter === 'function') {
return this._var.options.valueFormatter(date);
}
return date;
}
return null;
}
/**
@@ -500,9 +492,7 @@ export class DateSelector {
* 解析的属性为 `id`, `class`, `data-min`, `data-max`, `disabled`
* @static
* @param {HTMLElement} [dom=document.body] 父元素
* @param {Function} [trigger] 日期设置事件触发函数
* @param {Date} trigger.{this} - 上下文为触发设置日期的 `DateSelector` 实例
* @param {Date} trigger.date - 修改后的日期值
* @param {(this: DateSelector, date?: Date) => void} [trigger] 日期设置事件触发函数, 上下文为触发设置日期的 `DateSelector` 实例
* @example <caption>HTML</caption>
* <input id="dateFrom" data-type="date" data-min="1980-01-01"/>
* @example <caption>解析父容器</caption>
@@ -519,6 +509,9 @@ export class DateSelector {
static resolve(dom = document.body, trigger) {
const dates = dom.querySelectorAll('input[data-type="date"]');
for (let dat of dates) {
if (!(dat instanceof HTMLInputElement)) {
continue;
}
const val = dat.value;
const dateSelector = new DateSelector({
minDate: dat.getAttribute('data-min'),