add jsdoc comments
This commit is contained in:
1 parent
6de354ad47
commit
8c1205bc13
24 files changed
+1228
-425
No files matched your search
+79
-86
@@ -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'),
|
||||
|
||||
Reference in new issue
Block a user