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

+195 -52
View File
@@ -26,10 +26,11 @@ if (dropdownGlobal == null) {
continue;
}
panel.classList.remove('active');
const dropId = panel.parentElement.dataset.dropId;
const dropId = panel.parentElement?.dataset.dropId;
if (dropId == null) {
continue;
}
/** @type {Dropdown | undefined} */
const dropdown = this[dropId];
if (dropdown?.multiSelect && typeof dropdown.onCollapsed === 'function') {
dropdown.onCollapsed();
@@ -52,7 +53,16 @@ if (dropdownGlobal == null) {
});
}
function selectItems(label, itemlist, template, htmlkey, textkey) {
/**
* @private
* @this Dropdown
* @param {DropdownItem[]} itemlist
*/
function selectItems(itemlist) {
const label = this._var.label;
const template = this._var.options.htmlTemplate;
const htmlkey = this._var.options.htmlKey;
const textkey = this._var.options.textKey;
let htmls;
if (typeof template === 'function') {
htmls = itemlist.map(it => template.call(this, it));
@@ -62,7 +72,7 @@ function selectItems(label, itemlist, template, htmlkey, textkey) {
if (htmls.some(it => it instanceof HTMLElement)) {
label.replaceChildren(...htmls.filter(it => it != null).map(it => it.cloneNode(true)));
} else {
let text = itemlist.map(it => it[textkey]).join(', ');
let text = itemlist.map(it => String(it[textkey])).join(', ');
if (nullOrEmpty(text)) {
text = r('noneItem', '( None )');
}
@@ -70,6 +80,13 @@ function selectItems(label, itemlist, template, htmlkey, textkey) {
}
}
/**
* @private
* @param {string[]} searchkeys
* @param {string} textkey
* @param {string} key
* @param {DropdownItem[]} source
*/
function filterSource(searchkeys, textkey, key, source) {
if (!Array.isArray(searchkeys) || searchkeys.length === 0) {
searchkeys = [textkey];
@@ -87,6 +104,12 @@ function filterSource(searchkeys, textkey, key, source) {
return source;
}
/**
* @private
* @param {DropdownItem} it
* @param {string} valuekey
* @param {string} textkey
*/
function getValue(it, valuekey, textkey) {
if (it == null) {
return null;
@@ -105,7 +128,7 @@ function getValue(it, valuekey, textkey) {
* @property {string} [valueKey=value] - 值关键字
* @property {string} [htmlKey=html] - 源码显示的关键字
* @property {string} [childKey=children] - 子集合的关键字
* @property {Function} [htmlTemplate] - 模板创建函数
* @property {(this: Dropdown, it: DropdownItem) => string} [htmlTemplate] - 模板创建函数
* @property {number} [maxLength=500] - 最大输入长度
* @property {boolean} [multiSelect] - 是否允许多选
* @property {string} [selected] - 选中值
@@ -119,28 +142,62 @@ function getValue(it, valuekey, textkey) {
* @property {string} [placeholder] - 输入框的提示文本
* @property {boolean} [slideFixed] - 是否固定为向下展开
* @property {HTMLElement} [wrapper] - 父元素,默认添加到头元素之后
* @property {boolean} [ignoreAll] - 是否忽略 All 选项
*/
/**
* 数据项基础类型
* @typedef DropdownItemBase
* @property {0 | 1 | 2 | undefined} [__checked] 是否选中
* @property {string} [__p] 父节点 Id
* @property {number} [__level] 层级
* @interface
*/
/**
* 数据项类型
* @typedef {DropdownItemBase & Object.<string, any>} DropdownItem
*/
export class Dropdown {
_var = {};
// _var.options;
// _var.wrapper;
// _var.container;
// _var.label;
// _var.allChecked;
// _var.source;
// _var.lastSelected;
// _var.selected;
// _var.selectedList;
_var = {
/** @type {DropdownOptions} */
options: undefined,
/** @type {HTMLDivElement} */
wrapper: undefined,
/** @type {HTMLDivElement} */
container: undefined,
/** @type {HTMLInputElement | HTMLLabelElement} */
label: undefined,
allChecked: false,
/** @type {DropdownItem[]} */
source: undefined,
/** @type {DropdownItem[]} */
currentSource: undefined,
/** @type {string | undefined} */
lastSelected: undefined,
/** @type {DropdownItem | undefined} */
selected: undefined,
/** @type {DropdownItem[] | undefined} */
selectedList: undefined,
dropTop: 0,
dropHeight: 0
};
/** @type {(() => DropdownItem[]) | undefined} */
sourceFilter;
/** @type {((list: DropdownItem[]) => void) | undefined} */
onSelectedList;
/** @type {((it: DropdownItem) => void) | undefined} */
onSelected;
/** @type {((this: Dropdown) => void) | undefined} */
onExpanded;
/** @type {((this: Dropdown) => void) | undefined} */
onCollapsed;
/**
* @param {DropdownOptions} options
*/
constructor(options = {}) {
options.textKey ??= 'text';
options.valueKey ??= 'value';
@@ -284,6 +341,11 @@ export class Dropdown {
} else {
this._var.wrapper.querySelector('.ui-drop-header').classList.remove('disabled');
}
/** @type {HTMLInputElement} */
const input = this._var.wrapper.querySelector('.ui-drop-text');
if (input != null) {
input.disabled = flag;
}
}
get source() {
@@ -306,6 +368,13 @@ export class Dropdown {
}
const valuekey = this._var.options.valueKey;
const childkey = this._var.options.childKey;
/**
* @private
* @param {DropdownItem[]} list
* @param {string} [id]
* @param {number} [level]
* @returns {DropdownItem[]}
*/
function reduceItems(list, id, level = 0) {
if (!Array.isArray(list)) {
return [];
@@ -326,6 +395,13 @@ export class Dropdown {
get selectedList() { return this._var.selectedList || [] }
/**
*
* @param {string} selected
* @param {boolean} [silence]
* @param {boolean} [ignoreCase]
* @returns {boolean | undefined}
*/
select(selected, silence, ignoreCase) {
if (typeof selected !== 'string') {
selected = String(selected);
@@ -395,12 +471,16 @@ export class Dropdown {
return true;
}
/**
*
* @param {string[]} selectedlist
* @param {boolean} silence
* @returns {boolean | undefined}
*/
selectlist(selectedlist, silence) {
const source = this.source;
const valuekey = this._var.options.valueKey;
const textkey = this._var.options.textKey;
const template = this._var.options.htmlTemplate;
const htmlkey = this._var.options.htmlKey;
const itemlist = selectedlist.map(a => {
const v = typeof a === 'string' ? a : String(a);
let item = source.find(it => String(getValue(it, valuekey, textkey)) === v);
@@ -415,15 +495,11 @@ export class Dropdown {
this._var.allChecked = false;
source.forEach(it => delete it.__checked);
if (itemlist.length === 0) {
this._var.selectedList = null;
delete this._var.selectedList;
this._var.label.innerText = r('none', '( None )');
return false;
}
selectItems(this._var.label, itemlist, template, htmlkey, textkey);
this._var.selectedList = itemlist;
if (!silence && typeof this.onSelectedList === 'function') {
this.onSelectedList(itemlist);
}
this._selectList(list, silence);
}
get _expanded() { return this._var.container?.classList?.contains('active') }
@@ -445,7 +521,14 @@ export class Dropdown {
const key = e.target.value.toLowerCase();
const source = filterSource(options.searchKeys, options.textKey, key, this.source);
this._filllist(source);
})
});
input.addEventListener('blur', e => {
const key = e.target.value.toLowerCase();
if (!nullOrEmpty(key)) {
const list = this._getSelectedList(this._var.currentSource);
this._selectList(list);
}
});
search.append(input, createIcon('fa-light', 'search'));
panel.appendChild(search);
}
@@ -530,6 +613,11 @@ export class Dropdown {
}
}
/**
*
* @param {HTMLDivElement} list
* @param {number} top
*/
_onlistscroll(list, top) {
const offset = (this.multiSelect && !this.ignoreAll) ? DropdownItemHeight : 0;
top -= (top % (DropdownItemHeight * 2)) + offset;
@@ -553,6 +641,7 @@ export class Dropdown {
} else {
array = array.slice(-20);
}
/** @type {HTMLDivElement} */
const content = list.querySelector('.drop-content');
content.replaceChildren();
this._dofilllist(content, array);
@@ -560,6 +649,10 @@ export class Dropdown {
}
}
/**
*
* @param {DropdownItem[]} source
*/
_filllist(source) {
const list = this._var.container.querySelector('.ui-drop-list');
list.replaceChildren();
@@ -571,7 +664,7 @@ export class Dropdown {
const content = createElement('div', 'drop-content');
if (this.multiSelect && !this.ignoreAll) {
list.appendChild(
createElement('li', null,
createElement('li', undefined,
createCheckbox({
label: r('allItem', '( All )'),
checked: this._var.allChecked,
@@ -615,7 +708,19 @@ export class Dropdown {
}
}
/**
*
* @param {string} it
* @param {DropdownItem} item
* @param {string} valuekey
* @param {string} textkey
* @param {string} [childkey]
* @returns {boolean}
*/
_contains(it, item, valuekey, textkey, childkey) {
if (childkey == null) {
return false;
}
if (Array.isArray(item[childkey])) {
for (let t of item[childkey]) {
if (it === String(getValue(t, valuekey, textkey))) {
@@ -629,13 +734,19 @@ export class Dropdown {
return false;
}
/**
*
* @param {HTMLDivElement} content
* @param {DropdownItem[]} array
* @returns {number | undefined}
*/
_dofilllist(content, array) {
const multiselect = this.multiSelect;
const valuekey = this._var.options.valueKey;
const textkey = this._var.options.textKey;
const template = this._var.options.htmlTemplate;
const htmlkey = this._var.options.htmlKey;
const childkey = this._var.options.childKey;
// const childkey = this._var.options.childKey;
const selected = this.selected;
let scrolled;
array.forEach((item, i) => {
@@ -698,7 +809,7 @@ export class Dropdown {
} else {
if (label == null) {
label = createElement('span');
label.innerHTML = item[textkey];
label.innerText = item[textkey];
}
wrapper.appendChild(label);
if (selected != null && String(selected[valuekey]) === val) {
@@ -711,38 +822,51 @@ export class Dropdown {
return scrolled;
}
/**
* @param {DropdownItem[]} [source]
* @returns {DropdownItem[]}
*/
_getSelectedList(source) {
const valuekey = this._var.options.valueKey;
const textkey = this._var.options.textKey;
const list = [];
source ??= this.source;
source.filter(it => it.__p == null).forEach(it => {
const key = String(getValue(it, valuekey, textkey));
if (it.__checked === 1) {
list.push(it);
} else if (it.__checked === 2) {
const children = source.filter(c => c.__checked === 1 && c.__p === key);
if (children.length > 0) {
Array.prototype.push.apply(list, children);
}
}
});
return list;
}
/**
*
* @param {HTMLInputElement} checkbox
* @param {DropdownItem} item
*/
_triggerselect(checkbox, item) {
let list;
const valuekey = this._var.options.valueKey;
const textkey = this._var.options.textKey;
const template = this._var.options.htmlTemplate;
const htmlkey = this._var.options.htmlKey;
const childkey = this._var.options.childKey;
const source = this.source;
if (checkbox.getAttribute('isall') === '1') {
const allchecked = this._var.allChecked = checkbox.checked;
/** @type {NodeListOf<HTMLInputElement>} */
const boxes = this._var.container.querySelectorAll('input.dataitem');
boxes.forEach(box => box.checked = allchecked);
source.forEach(it => it.__checked = allchecked ? 1 : 0);
list = [];
} else {
/** @type {HTMLInputElement | null} */
const all = this._var.container.querySelector('input[isall="1"]');
const val = checkbox.dataset.value;
const getSelectedList = () => {
const list = [];
source.filter(it => it.__p == null).forEach(it => {
const key = String(getValue(it, valuekey, textkey));
if (it.__checked === 1) {
list.push(it);
} else if (it.__checked === 2) {
const children = source.filter(c => c.__checked === 1 && c.__p === key);
if (children.length > 0) {
Array.prototype.push.apply(list, children);
}
}
});
return list;
};
if (checkbox.checked) {
item.__checked = 1;
if (item.__p != null) {
@@ -766,7 +890,7 @@ export class Dropdown {
}
list = [];
} else {
list = getSelectedList();
list = this._getSelectedList();
}
} else {
if (item[childkey]?.length > 0) {
@@ -793,10 +917,11 @@ export class Dropdown {
all.checked = false;
}
}
list = getSelectedList();
list = this._getSelectedList();
}
}
// refresh selection
/** @type {NodeListOf<HTMLInputElement>} */
const checkboxes = this._var.container.querySelectorAll('input.dataitem');
checkboxes.forEach(c => {
const val = c.dataset.value;
@@ -807,23 +932,41 @@ export class Dropdown {
}
});
this._selectList(list);
}
/**
* @private
* @param {DropdownItem[]} list
* @param {boolean} [silence]
*/
_selectList(list, silence) {
if (this._var.allChecked) {
this._var.label.innerText = r('allItem', '( All )');
} else {
selectItems(this._var.label, list, template, htmlkey, textkey);
selectItems.call(this, list);
}
this._var.selectedList = list;
if (typeof this.onSelectedList === 'function') {
if (!silence && typeof this.onSelectedList === 'function') {
this.onSelectedList(list);
}
}
/**
*
* @param {HTMLElement} dom
* @param {(this: Dropdown, item: DropdownItem) => void} [trigger]
* @returns
*/
static resolve(dom = document.body, trigger) {
const selects = dom.querySelectorAll('select');
for (let sel of selects) {
const source = [...sel.children].map(it => {
return { value: it.value, text: it.innerText }
});
const source = [...sel.children].map(
/**
* @param {HTMLOptionElement} it
* @returns {DropdownItem}
*/
it => ({ value: it.value, text: it.innerText }));
const drop = new Dropdown({
selected: sel.value,
disabled: sel.disabled,