Global

Methods

createLegendMeasurer(echarts) → {Object}

Description:

  • 建立離屏量測器: 以未掛入DOM之echarts實例, 計算一般式圖例於指定寬度之排版

    量測實例僅含圖例、隱藏之座標軸與同名空系列, 故顯示列表中「文字等於系列名」之元素即圖例項目(不會與軸刻度文字撞名)

Source:
Parameters:
Name Type Description
echarts Object

輸入echarts命名空間物件, 須與圖表同一份(例如w-echarts-vue之iniEcharts()), 字型與版面規則方能一致
Returns:

回傳物件, 含measure(names,width,height)與dispose(); measure回傳{rows,bottom}(bottom為圖例底緣距圖表頂之px), 量不到回null

Type
Object

createLockSave(cst) → {function}

Description:

  • 有副作用之寫入路徑(如清單儲存 updateUsersList / updateTokensList / updateIpsList)之雙擊防護(後端, ADR-025)

    以「操作:操作者 id」於 wsemi cacheSt 原子占位執行 fn, 同一操作者之同一操作處理中再送出即 reject 錯誤 key (預設 'saveInProgress', 可以 opt.errKey 指定; 皆為 i18n key, 見 procLang); 不同操作者、不同操作互不影響; fn 之 reject 原樣 bubble; fn 結束(含失敗)即釋放. 第 2 次不排隊執行: 其內容與第 1 次相同, 排隊後再寫一次會把第 1 次剛建立之列當修改覆寫 (依序重送另由各專案之資料層檢查擋, 如 SSO procCore.updateTabItems 之新增列檢查回 'saveNewRowExists'). operatorId 可為操作者 id 或「操作者 id + 列識別」(只擋同一列之連發, 同批其他列不受影響).

Source:
Parameters:
Name Type Description
cst Object

輸入 wsemi cacheSt 實例
Returns:

回傳 async (op, operatorId, fn, opt = {}) => fn 之結果, opt.errKey 為占位衝突時 reject 之 key

Type
function

decideLegendType(m) → {String}

Description:

  • 依量測結果決定圖例類型

Source:
Parameters:
Name Type Description
m Object | null

輸入量測結果物件{rows,bottom}, 量測失敗為null
Returns:

回傳'plain'或'scroll', 量測失敗回'scroll'(單列, 不會重疊)

Type
String

describeUpstream(err) → {Object}

Description:

  • 描述上游失敗, 供寫入 log: 絕不含上游原文

    • reject 值(字串)或其 message 屬白名單 key → { upstream: key }
    • 其餘 → { upstreamType, upstreamName }: 型別(null / array / typeof)與名稱形狀之 Error.name(無則 '')
Source:
Parameters:
Name Type Description
err *

輸入注入函數拋出或 reject 之值
Returns:

回傳描述物件

Type
Object

(async) fetchJson(url, optopt) → {Promise}

Description:

  • 以瀏覽器與 node(18+) 內建之 fetch 取得 JSON 回應, 取代 axios(2026-09-07 起本套件不再依賴 axios)

    與 axios 之語意對齊:

    • 網路錯誤或非 2xx: axios 會 reject, fetch 只在網路錯誤 reject, 故此處對 !res.ok 亦 reject, 統一為 { kind: 'request', status, message }
    • 回應非 JSON: axios 回原字串(呼叫端判 state 失敗), 此處 res.json() 失敗 reject { kind: 'parse', status, message }
    • 成功: resolve 解析後之 JSON(對應 axios 之 res.data) reject 之 message 只含例外名稱與代碼(如 'TypeError ECONNREFUSED'、'SyntaxError')或 'HTTP ', 不含網址與回應本體(網址常帶權杖) 注意: node 端 fetch(undici) 不讀 HTTP_PROXY / HTTPS_PROXY 環境變數(axios 會), 需走 proxy 之部署須自行以 opt.dispatcher 注入 undici Agent
Source:
Parameters:
Name Type Attributes Default Description
url String

輸入請求網址字串
opt Object <optional>
 {}

輸入 fetch 選項物件(method / headers / body / signal / dispatcher 等原樣傳給 fetch), 預設 {}
Returns:

回傳 Promise, resolve 為 JSON 物件, reject 為 { kind: 'request'|'parse', status, message }

Type
Promise

genLegend(typeopt) → {Object}

Description:

  • 產生圖例設定(單一來源), genOpt 與執行期切換類型共用

    切換類型(plain↔scroll)時 echarts 以新傳入之選項重建圖例模型(Global.js:322-344), 未帶之設定一律回到預設, 故每次都須帶齊

Source:
Parameters:
Name Type Attributes Default Description
type String <optional>
 'plain'

輸入圖例類型字串, 'plain'或'scroll', 預設'plain'
Returns:

回傳echarts之legend設定物件

Type
Object

maskQuery(q) → {Object|String|Array}

Description:

  • 查詢參數遮罩: 淺拷貝, 鍵名小寫為 token 者以 maskTok 處理, 其餘原樣(供印出 req.query) 非物件輸入依 maskTok 處理

Source:
Parameters:
Name Type Description
q *

輸入查詢參數物件(Hapi 之 req.query 為 null-prototype 物件)
Returns:

回傳遮罩後之淺拷貝

Type
Object | String | Array

maskTok(token) → {String|Array}

Description:

  • 權杖遮罩

    • 空值(undefined / null / '')回 ''
    • 陣列逐元素遮罩
    • 字串(長度 n)露出前後各 k=min(4, floor(n/8)) 字: k=0 只回 '(len=n)', 否則 '前k...後k(len=n)'; 36 字元之 session token 為前 4 後 4(與 w-web-sso 格式相同)
    • 其他型別只回 '(typeof)', 絕不輸出原值
Source:
Parameters:
Name Type Description
token *

輸入權杖
Returns:

回傳遮罩後字串, 輸入陣列時回傳陣列

Type
String | Array

maskUrl(u) → {String|Array}

Description:

  • 網址遮罩: http(s) 只留 origin + pathname, 捨棄 query / fragment / userinfo(其內常含權杖, 如 ?token=)

    • 陣列逐元素處理; 空值回 ''; 其他非字串只回 '(typeof)'
    • 非 http(s) 之網址(如 data:、javascript:)路徑即全部內容, 只回 protocol(同 w-web-sso src/maskUrl.mjs)
    • 無法解析回 '(invalid-url)'
Source:
Parameters:
Name Type Description
u *

輸入網址
Returns:

回傳可寫入 log 之字串, 輸入陣列時回傳陣列

Type
String | Array

mergePickKeysOnly(ltdtDb, rowsIn, keyDetect, pickKeys) → {Array}

Description:

  • 僅採納既有列之指定欄位變更, 其餘欄位、新增列、缺列(刪除)與順序一律以資料庫現值為準

    用於 modeEditUsers='for:grups': 使用者身分由外部單一登入系統同步, 本系統只擁有群組指派(cgrups), 故 API 層須與 UI 一致只接受 cgrups 變更

Source:
Parameters:
Name Type Description
ltdtDb Array

資料庫現有列(select 結果, 依 order 排序後為基底)
rowsIn Array

前端/外部送入之整表列
keyDetect String

對應列之鍵欄位(如 'id')
pickKeys Array

允許採納之欄位名陣列(如 ['cgrups'])
Returns:

以資料庫列為基底、僅覆蓋 pickKeys 之新列陣列(順序同資料庫)

Type
Array

reuseDeletedIds(rows, rowsDb) → {Array}

Description:

  • 新增列沿用資料庫既有 id 時之正規化 (標的清單專用, 其 id 為可就地改寫之標的路徑; ADR-025)

    同一次儲存中刪除(或把 id 改掉)某既有列, 又新增一列並把 id 改成該既有列之 id, 淨效果為「修改該列」: 該新增列改為一般列送出(_isNew 設 false), 建立者 / 建立時間沿用資料庫之值(修改者 / 修改時間由後端寫入). 否則後端之「新增列已存在即拒絕」(saveNewRowExists, 擋同一包重送) 會把它當重送擋下, 且重新整理後重做仍被擋; 亦避免以前端佔位字({待自動給予})覆寫建立者 / 建立時間. 只處理 id 於 rows 內唯一者; 重複 id 不處理, 由後端 ckKey 回 saveRowFieldDuplicate. 使用者 / 群組 / 權限清單之 id 為系統產生且不可編輯, 新增列不會與既有列同 id, 不需此處理.

Source:
Parameters:
Name Type Description
rows Array

輸入欲送出之列陣列(清單之 opt.rows), 不修改
rowsDb Array

輸入資料庫之列陣列(前端 store 之同表資料)
Returns:

回傳正規化後之新陣列

Type
Array

submitGuard() → {Object}

Description:

  • 送出類操作之前端雙擊防護核心 (與 Vue / store 無關, 供單元測試; 由 mUI 之 runSubmit 與 updateLoading 使用, ADR-025)

    • run(key, fn, opt): 同 key 之送出流程進行中(自觸發起至流程結束, 含結果訊息框開啟期間)再觸發即略過. 按鈕之滑鼠與鍵盤 Enter、輸入框之 Enter 等入口共用同一狀態. opt.pm 為 WButtonChip / WButtonCircle 之 promiseUnlock 鎖(click 事件之 msg.pm), 於 releaseBtnLocks()(全頁 loading 關閉, 即請求結束) 或流程結束時釋放; 被略過之觸發亦立即釋放其 pm, 否則該按鈕永久鎖住. fn 收到 unlock 函數: 流程需先開確認框者於開框前呼叫, 按鈕鎖只涵蓋請求期間(確認框背後之按鈕不顯示載入圖示), 重入仍由流程狀態擋. opt.hold 為函數, 輸入流程結果, 回傳 true 時保持占位與按鈕鎖(如登入成功轉址, 頁面即將離開).
    • releaseBtnLocks(): 釋放進行中流程所登記之按鈕鎖, 流程狀態不變(結果訊息框開啟期間之重入仍擋).
    • isRunning(key): 查詢 key 是否進行中.

    為何需要: 全頁 loading(WDialog)不搶焦點, 只擋滑鼠, 鍵盤事件仍送達背後之按鈕與輸入框; 按鈕鎖若於 handler 第一行即解除, 鍵盤連按照樣送出(2026-09-29 實測).

Source:
Returns:

回傳 { run, releaseBtnLocks, isRunning }

Type
Object

wrapInjected(fn, optopt) → {function}

Description:

  • 包裝注入函數: 回傳(同步或 Promise)原樣回傳; 同步拋錯或 reject 回 failValue, 並以 describeUpstream(err) 呼叫 onFail 包裝後一律回 Promise(呼叫端既有之 ispm 判斷照常)

Source:
Parameters:
Name Type Attributes Default Description
fn function

輸入注入函數
opt Object <optional>
 {}

輸入設定物件

Properties
Name Type Attributes Default Description
failValue * <optional>
 null

輸入失敗時之回傳值(getUserByToken 為 null 等同查無, verify* 為 false 等同無權限)
onFail function <optional>
 null

輸入失敗時之紀錄函數, 只收到 describeUpstream 之結果(收不到上游原文); 其自身拋錯不影響回傳
Returns:

回傳包裝後之函數

Type
function