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

+94 -15
View File
@@ -2,14 +2,19 @@ import { getCookie } from "./cookie";
import { get } from "./request";
import { nullOrEmpty } from "./strings";
/** @typedef {import('../types').LanguageResource} LanguageResource */
const g = typeof window !== 'undefined' ? window : self;
/** @type {LanguageResource} */
let cache;
function getCurrentLgId() {
let lgid;
if (typeof consts !== 'undefined') {
lgid = getCookie(consts.cookie?.lang);
if (typeof g.consts !== 'undefined') {
lgid = getCookie(g.consts.cookie?.lang);
if (nullOrEmpty(lgid)) {
lgid = consts.user?.language;
lgid = g.consts.user?.language;
}
}
if (nullOrEmpty(lgid)) {
@@ -42,13 +47,23 @@ function getCurrentLgId() {
return 'en';
}
/**
* @private
* @param {"en" | "en_au" | "en_ca" | "fr_ca" | "zh_cn" | "es" | "fr" | "pt"} lgid
* @returns {string}
*/
function getStorageKey(lgid) {
if (typeof consts !== 'undefined') {
return (consts.prefix || '') + `res_${lgid}`;
if (typeof g.consts !== 'undefined') {
return (g.consts.prefix || '') + `res_${lgid}`;
}
return `res_${lgid}`;
}
/**
* @private
* @param {string} [template]
* @returns {Promise<LanguageResource>}
*/
async function doRefreshLgres(template = '') {
const lgid = getCurrentLgId();
const url = template.length > 0 ? template.replace('{lgid}', lgid) : `language/${lgid}`;
@@ -58,21 +73,27 @@ async function doRefreshLgres(template = '') {
return dict;
}
/**
*
* @param {string} [template]
* @param {LanguageResource | null} [lgres]
* @returns {Promise<LanguageResource>}
*/
async function refreshLgres(template, lgres) {
if (lgres == null || typeof consts === 'undefined') {
if (lgres == null || typeof g.consts === 'undefined') {
lgres = await doRefreshLgres(template);
}
const ver = Number(consts.resver);
const ver = Number(g.consts?.resver);
const currentVer = Number(lgres.ver);
if (isNaN(currentVer) || isNaN(ver) || ver > currentVer) {
console.log(`found new language res version: ${lgres.ver} => ${consts.resver}`);
console.log(`found new language res version: ${lgres.ver} => ${g.consts?.resver}`);
lgres = await doRefreshLgres(template);
}
Object.defineProperty(lgres, 'r', {
writable: false,
configurable: false,
enumerable: false,
value: function (key, defaultValue) {
value: function (/** @type {string} */ key, /** @type {string | undefined} */ defaultValue) {
return getLanguage(this, key, defaultValue);
}
});
@@ -80,15 +101,47 @@ async function refreshLgres(template, lgres) {
return lgres;
}
/**
* @private
* @param {LanguageResource} lgres
* @param {string} [key]
* @param {string | null} [defaultValue]
* @returns {string}
*/
function getLanguage(lgres, key, defaultValue) {
if (key == null) {
return '';
}
let value = lgres[key];
return value ?? defaultValue;
if (value != null && typeof value !== 'string') {
value = String(value);
}
return value ?? defaultValue ?? '';
}
/**
* @private
* @template {keyof HTMLElementTagNameMap} K
* @param {Element} element
* @param {K} tagName
* @returns {element is HTMLElementTagNameMap[K]}
*/
export function isTag(element, tagName) {
return element.tagName.toLowerCase() === tagName;
}
/**
* @private
* @param {HTMLElement} dom
* @param {LanguageResource} result
*/
function applyLanguage(dom, result) {
for (let text of dom.querySelectorAll('[data-lgid]')) {
if (!(text instanceof HTMLElement)) {
continue;
}
const key = text.dataset.lgid;
if (text.tagName === 'INPUT') {
if (isTag(text, 'input')) {
text.value = getLanguage(result, key, text.value);
} else {
text.innerText = getLanguage(result, key, text.innerText);
@@ -97,12 +150,18 @@ function applyLanguage(dom, result) {
text.dataset.lgid = '';
}
for (let title of dom.querySelectorAll('[data-title-lgid]')) {
if (!(title instanceof HTMLElement)) {
continue;
}
const key = title.dataset.titleLgid;
title.setAttribute('title', getLanguage(result, key, title.getAttribute('title')));
// delete title.dataset.titleLgid;
title.dataset.titleLgid = '';
}
for (let holder of dom.querySelectorAll('[data-placeholder-lgid]')) {
if (!(holder instanceof HTMLElement)) {
continue;
}
const key = holder.dataset.placeholderLgid;
holder.setAttribute('placeholder', getLanguage(result, key, holder.getAttribute('placeholder')));
// delete holder.dataset.placeholderLgid;
@@ -110,9 +169,13 @@ function applyLanguage(dom, result) {
}
}
/**
* @returns {Promise<void>}
*/
export function domLoad() {
if (document.readyState === 'loading') {
return new Promise((resolve, reject) => {
/** @type {number | undefined} */
let tid = setTimeout(() => reject('timeout'), 30000);
document.addEventListener('DOMContentLoaded', () => {
clearTimeout(tid);
@@ -124,13 +187,24 @@ export function domLoad() {
return Promise.resolve();
}
/**
* @typedef LgresOptions
* @property {string} [template]
* @property {(result: LanguageResource) => void} [callback]
*/
/**
* @param {HTMLElement} dom
* @param {LgresOptions} options
* @returns
*/
export async function init(dom = document.body, options = {}) {
const lgid = getCurrentLgId();
let lgres = localStorage.getItem(getStorageKey(lgid));
const json = localStorage.getItem(getStorageKey(lgid));
let result;
if (lgres != null) {
if (json != null) {
try {
lgres = JSON.parse(lgres);
const lgres = JSON.parse(json);
result = await refreshLgres(options.template, lgres);
} catch (e) {
console.error('error while parsing lgres, try refresh ...', e);
@@ -152,11 +226,16 @@ export async function init(dom = document.body, options = {}) {
}
}
/**
* @param {string} key
* @param {string | null} [defaultValue]
* @returns {string}
*/
export function r(key, defaultValue) {
if (cache != null) {
return getLanguage(cache, key, defaultValue);
}
return defaultValue;
return defaultValue ?? '';
}
export const lang = {