wsemi 1.9.4 → 1.9.6

package/docs/domDetect.mjs.html

@@ -46,141 +46,21 @@
     <section>
         <article>
             <pre class="prettyprint source linenums"><code>import get from 'lodash-es/get.js'
+import throttle from 'lodash-es/throttle.js'
 import ispint from './ispint.mjs'
 import isp0int from './isp0int.mjs'
+import isnum from './isnum.mjs'
+import cdbl from './cdbl.mjs'
 import evem from './evem.mjs'
 import isfun from './isfun.mjs'
 
 
-//2020年曾以IntersectionObserver與ResizeObserver實作(即下方註解舊碼), 因下列實作缺陷致WTextSelect下拉選單不穩而改為輪詢:
+//2020年曾以IntersectionObserver與ResizeObserver實作(詳細請查git紀錄), 因實作缺陷致WTextSelect下拉選單不穩而改為輪詢:
 //1.元素尺寸為0(隱藏或移出DOM)時仍發出resize, 使用端讀到高度0而算錯版面
 //2.clear未防空值, 元素尚未取得即clear時拋錯, 且已建立之觀察器與已排定之事件未解除
 //3.觀察器只綁首次取得之元素, 元素被換成新節點後即失去偵測
-//現以ResizeObserver偵測尺寸, 並以共用MutationObserver於[元素取不到、不在頁面中或尺寸為0]時重新取得元素, 逐一對應上述缺陷; 無ResizeObserver或MutationObserver時退回輪詢
 
-
-// function domDetect(f, opt = {}) {
-
-//使用IntersectionObserver與ResizeObserver時, 當顯隱頻繁導致元素尚未出現需等待與過快清除時, 會導致WTextSelect下拉選單無法穩定出現內容問題
-
-//     let ele = null
-//     let obInts = null
-//     let obRes = null
-
-//     //tolerancePixel
-//     let tolerancePixel = get(opt, 'tolerancePixel', null)
-//     if (!ispint(tolerancePixel)) {
-//         tolerancePixel = 1
-//     }
-
-//     //ev
-//     let ev = evem()
-
-//     //timer, sold
-//     let timer
-//     let sold = {
-//         offsetWidth: 0,
-//         offsetHeight: 0,
-//     }
-
-//     //check
-//     if (!isfun(f)) {
-//         console.log('invalid f', f)
-//         return ev
-//     }
-
-//     //check
-//     if (!window.IntersectionObserver) {
-//         console.log('invalid IntersectionObserver')
-//         return ev
-//     }
-
-//     //check
-//     if (!window.ResizeObserver) {
-//         console.log('invalid ResizeObserver')
-//         return ev
-//     }
-
-//     //setInterval
-//     timer = setInterval(() => {
-
-//         //execute
-//         let eleTemp = f()
-
-//         //check
-//         if (eleTemp) {
-
-//             //save
-//             ele = eleTemp
-
-//             //obInts
-//             if (!obInts) {
-//                 obInts = new window.IntersectionObserver((entries) => {
-//                     let entry = entries[0]
-
-//                     setTimeout(() => { //emit觸發事件為同步, 用setTimeout脫勾
-//                         ev.emit('display', { mode: entry.isIntersecting ? 'show' : 'hide', ele })
-//                     }, 1)
-
-//                 })
-//                 obInts.observe(ele)
-//             }
-
-//             //obRes
-//             if (!obRes) {
-//                 obRes = new window.ResizeObserver((entries) => {
-//                     // let entry = entries[0]
-
-//                     //new size
-//                     let snew = {
-//                         offsetWidth: ele.offsetWidth,
-//                         offsetHeight: ele.offsetHeight,
-//                     }
-
-//                     //save sold
-//                     let soldt = { ...sold }
-
-//                     //tolerancePixel
-//                     let bw = Math.abs(sold.offsetWidth - snew.offsetWidth) > tolerancePixel
-//                     let bh = Math.abs(sold.offsetHeight - snew.offsetHeight) > tolerancePixel
-
-//                     if (bw || bh) {
-//                         setTimeout(() => { //emit觸發事件為同步, 用setTimeout脫勾
-//                             ev.emit('resize', { sold: soldt, snew, ele })
-//                             ev.emit('resizeWithWindow', { sold: soldt, snew, ele, from: 'dom' })
-//                         }, 1)
-//                     }
-
-//                     //save
-//                     sold = snew
-
-//                 })
-//                 obRes.observe(ele)
-//             }
-
-//             //clearInterval
-//             clearInterval(timer)
-
-//         }
-
-//     }, 10)
-
-//     //fWindowResize
-//     let fWindowResize = (e) => {
-//         ev.emit('resizeWithWindow', { snew: sold, from: 'window' })
-//     }
-//     window.addEventListener('resize', fWindowResize)
-
-//     //clear
-//     ev.clear = () => {
-//         obInts.unobserve(ele)
-//         obRes.unobserve(ele)
-//         clearInterval(timer) //若一直沒偵測到元素故也需要強制中止timer
-//         window.removeEventListener('resize', fWindowResize)
-//     }
-
-//     return ev
-// }
+//現已恢復並用以ResizeObserver偵測尺寸, 並以共用MutationObserver於[元素取不到、不在頁面中或尺寸為0]時重新取得元素, 逐一對應上述缺陷; 無ResizeObserver或MutationObserver時退回輪詢
 
 
 //waiting, 等待重新取得元素之偵測器; mo, 共用之MutationObserver, 僅於有偵測器等待時啟用
@@ -228,6 +108,21 @@ function getTolerancePixel(opt) {
 }
 
 
+function getThrottle(opt) {
+    let t = get(opt, 'throttle', null)
+    if (!ispint(t)) { //未給或0表示不節流
+        t = 0
+    }
+    return t
+}
+
+
+function getFun(opt, key) {
+    let f = get(opt, key, null)
+    return isfun(f) ? f : null
+}
+
+
 //getEle, f()拋錯或回傳非元素時視為取不到, 不中斷偵測
 function getEle(f) {
     let p = null
@@ -241,6 +136,12 @@ function getEle(f) {
 }
 
 
+//toNum, 非數字(含拋錯、未給)者為null
+function toNum(v) {
+    return isnum(v) ? cdbl(v) : null
+}
+
+
 function sizeZero() {
     return {
         offsetWidth: 0,
@@ -249,26 +150,79 @@ function sizeZero() {
         clientHeight: 0,
         windowWidth: 0,
         windowHeight: 0,
+        width: 0,
+        height: 0,
     }
 }
 
 
-function measure(p) {
-    return {
+//measure, width與height為比較用尺寸: 預設同offsetWidth與offsetHeight(border-box), 有給getSize時取其回傳(例如使用端依內容區繪製者)
+function measure(p, getSize) {
+    let r = {
         offsetWidth: p.offsetWidth,
         offsetHeight: p.offsetHeight,
         clientWidth: p.clientWidth,
         clientHeight: p.clientHeight,
         windowWidth: window.innerWidth,
         windowHeight: window.innerHeight,
+        width: p.offsetWidth,
+        height: p.offsetHeight,
     }
+    if (getSize) {
+        let s = null
+        try {
+            s = getSize(p)
+        }
+        catch (err) {
+            s = null
+        }
+        r.width = toNum(get(s, 'width', null)) || 0
+        r.height = toNum(get(s, 'height', null)) || 0
+    }
+    return r
+}
+
+
+//isShown, 量測時元素可見(外框非0)且比較用尺寸非0
+function isShown(s) {
+    return s.offsetWidth > 0 &amp;&amp; s.offsetHeight > 0 &amp;&amp; s.width > 0 &amp;&amp; s.height > 0
+}
+
+
+//isRendered, 元素當下是否被繪製: 在頁面中且自身與祖先皆非display:none
+//  只需計算樣式不需排版: 若讀外框(offsetWidth)確認, 前一個監聽器改動DOM後(同步寫入或Vue於microtask更新)之每次確認皆強制重排, N個偵測器即N次排版
+//  有checkVisibility時以其判定(另涵蓋content-visibility:hidden等), 否則逐層檢查display; 不讀外框, 故元素仍被繪製而尺寸縮為0者視為被繪製
+function isRendered(p) {
+    if (!p || !p.isConnected) {
+        return false
+    }
+    if (isfun(p.checkVisibility)) {
+        return p.checkVisibility()
+    }
+    let e = p
+    while (e &amp;&amp; e.nodeType === 1) {
+        let display = ''
+        try {
+            display = window.getComputedStyle(e).display
+        }
+        catch (err) {
+            display = ''
+        }
+        if (display === 'none') {
+            return false
+        }
+        e = e.parentElement || (e.parentNode &amp;&amp; e.parentNode.host) || null //Shadow DOM內之頂層節點改查其宿主
+    }
+    return true
 }
 
 
 //createCore, 輪詢與ResizeObserver兩種模式共用之比較、發出、視窗事件與清除, 使兩者之規則只寫一處
-//  比較基準sb為上次發出事件時之尺寸, 差值超過容許誤差才更新; 若每次量測皆更新基準, 緩慢之連續小變化(如逐px拖曳或縮放視窗)永遠不會超過容許誤差, 累積再大也不發出
+//  比較基準預設為上次判定變化時之尺寸sb, 差值超過容許誤差才更新; 若每次量測皆更新基準, 緩慢之連續小變化(如逐px拖曳或縮放視窗)永遠不會超過容許誤差, 累積再大也不發出
 //  尺寸為0時差值必超過容許誤差而使基準歸0, 故由隱藏恢復顯示時必發出
-function createCore(ev, opt) {
+//  有給getBase時比較基準改為使用端目前套用之尺寸(例如圖表目前寬高), 故掛載時尺寸已一致者不發出, 且與偵測器之回報次序無關
+//  onReobserve為延後發出因元素已不被繪製而略過時, 請觀察層重新觀察目前元素並登記等待之函數(輪詢模式不需要, 下一次取樣即重新比較)
+function createCore(ev, opt, onReobserve) {
 
     //tolerancePixel
     let tolerancePixel = getTolerancePixel(opt)
@@ -276,101 +230,221 @@ function createCore(ev, opt) {
     //sync, 於ResizeObserver回呼內同步發出事件(繪製前), 供須於同一幀更新版面之使用端(例如圖表重繪); 預設以setTimeout脫勾
     let sync = get(opt, 'sync', false) === true
 
-    //cleared, st, sd, sb, smode, timers
+    //getSize, getBase, throttleTime
+    let getSize = getFun(opt, 'getSize')
+    let getBase = getFun(opt, 'getBase')
+    let throttleTime = getThrottle(opt)
+
+    //cleared, sd, sb, pLast, timers, seqCheck, seqPost
     let cleared = false
-    let st = sizeZero() //前次量測
     let sd = sizeZero() //最新量測
-    let sb = sizeZero() //比較基準, 上次發出事件時之尺寸
-    let smode = {
-        width: '',
-        height: '',
-    }
+    let sb = sizeZero() //上次判定變化時之尺寸
+    let pLast = null //最新量測之元素, 供視窗事件確認其當下是否被繪製
     let timers = new Set()
+    let seqCheck = 0 //判定變化之序號
+    let seqPost = 0 //已處理(發出, 或因尺寸0、不被繪製、使用端已同步而不發出)之最新序號
+
+    //readBase, 比較基準: 有給getBase時取其回傳(該軸非數字表示該軸不比較, 例如固定寬度), 否則為sb
+    //  pending為判定變化時: 有給getBase且尚有未處理之延後發出者, 使用端尺寸將被其更新, 故比較之軸改以其量測(sb)比較;
+    //  否則之後量得與使用端當下相近之尺寸會被判為未變化, 待延後發出套用後使用端即停在過期尺寸; 發出前之再比較(pending為false)則以使用端當下之尺寸比較
+    let readBase = (pending) => {
+        if (!getBase) {
+            return {
+                width: sb.width,
+                height: sb.height,
+            }
+        }
+        let b = null
+        try {
+            b = getBase()
+        }
+        catch (err) {
+            b = null
+        }
+        let width = toNum(get(b, 'width', null))
+        let height = toNum(get(b, 'height', null))
+        if (pending &amp;&amp; seqPost &lt; seqCheck) {
+            return {
+                width: width === null ? null : sb.width,
+                height: height === null ? null : sb.height,
+            }
+        }
+        return {
+            width,
+            height,
+        }
+    }
+
+    //diff, 各軸相對比較基準之差與是否超過容許誤差
+    let diff = (snew, pending) => {
+        let base = readBase(pending)
+        let dw = base.width === null ? 0 : base.width - snew.width
+        let dh = base.height === null ? 0 : base.height - snew.height
+        return {
+            dw,
+            dh,
+            bw: Math.abs(dw) > tolerancePixel,
+            bh: Math.abs(dh) > tolerancePixel,
+        }
+    }
+
+    //mode, 方向只於該軸超過容許誤差時給: 容許誤差內之差值視同未變化(不發事件), 若仍給方向, 另一軸觸發之事件會帶出該軸之殘餘方向
+    let mode = (d) => {
+        return {
+            width: d.bw ? (d.dw > 0 ? 'smaller' : 'larger') : '',
+            height: d.bh ? (d.dh > 0 ? 'smaller' : 'larger') : '',
+        }
+    }
 
-    //emit
-    let emit = (sold, snew, sm, p) => {
+    //skip, 延後發出前元素已不被繪製而不發出:
+    //  若此為最近一次判定之變化(之後未再判定), 比較基準與最新量測歸0, 並請觀察層重新觀察目前元素; 否則元素於下一幀前恢復顯示且尺寸與隱藏前相同時ResizeObserver不再回報(上次回報之尺寸未變), 此次變化即永不發出
+    //  之後已再判定變化者由該次發出處理, 不得歸0, 否則覆蓋較新之比較基準
+    let skip = (snew) => {
+        if (sb !== snew) {
+            return
+        }
+        sb = sizeZero()
+        sd = sizeZero()
+        if (onReobserve) {
+            onReobserve()
+        }
+    }
+
+    //post, 發出事件
+    //  deferred為延後發出(setTimeout、節流之後續呼叫或refresh): 自量測至發出之間元素可能已隱藏或移出頁面, 若照發則使用端讀到尺寸0而算錯版面(即上方2020年缺陷1), 故發出前確認元素當下仍被繪製;
+    //  有給getBase者亦再比較一次, 期間使用端已自行同步尺寸時不發出, 方向亦依當下比較重給
+    let post = (sold, snew, sm, p, seq, deferred) => {
 
         //cleared, clear後不再發出已排定之事件
         if (cleared) {
             return
         }
 
-        //detect resize, 尺寸為0(隱藏或移出DOM)不發出
-        if (snew.offsetWidth > 0 &amp;&amp; snew.offsetHeight > 0) {
-            ev.emit('resize', {
-                sold,
-                snew,
-                smode: sm,
-                ele: p,
-            })
+        //seq, 已處理較新之量測者不發出較舊者: sync時refresh或節流之後續發出為延後發出, 可能晚於其後已同步發出之事件, 照發則使用端最後收到過期尺寸
+        if (seq &lt; seqPost) {
+            return
+        }
+        seqPost = seq
 
-            //cleared, resize之監聽器內可能呼叫clear
-            if (cleared) {
+        //尺寸為0(隱藏或移出DOM)不發出
+        if (!isShown(snew)) {
+            return
+        }
+
+        //deferred
+        if (deferred) {
+            if (!isRendered(p)) {
+                skip(snew)
                 return
             }
+            if (getBase) {
+                let d = diff(snew, false)
+                if (!d.bw &amp;&amp; !d.bh) {
+                    return
+                }
+                sm = mode(d)
+            }
+        }
+
+        ev.emit('resize', {
+            sold,
+            snew,
+            smode: sm,
+            ele: p,
+        })
 
-            ev.emit('resizeWithWindow', {
-                sold,
-                snew,
-                smode: sm,
-                ele: p,
-                from: 'dom',
-            })
+        //cleared, resize之監聽器內可能呼叫clear
+        if (cleared) {
+            return
         }
 
+        ev.emit('resizeWithWindow', {
+            sold,
+            snew,
+            smode: sm,
+            ele: p,
+            from: 'dom',
+        })
+
     }
 
-    //check, 量測並與比較基準比較
-    let check = (p, allowSync) => {
-        if (cleared || !p) {
+    //fire, 於ResizeObserver回呼內同步發出(inSync)或延後發出
+    //  延後發出各自一個task: 前一個監聽器於microtask之DOM異動(如Vue之非同步更新)於下一個發出前已套用, 且監聽器不集中於同一個task; 發出前之確認只需樣式(isRendered), 故不因此強制重排
+    let inSync = false
+    let fire = (sold, snew, sm, p, seq) => {
+        if (inSync) {
+            post(sold, snew, sm, p, seq, false)
             return
         }
+        let t = setTimeout(() => { //emit觸發事件為同步, 用setTimeout脫勾
+            timers.delete(t)
+            post(sold, snew, sm, p, seq, true)
+        }, 1)
+        timers.add(t)
+    }
 
-        //new size
-        let snew = measure(p)
+    //fireThrottled, 節流: 首次立即(同步或延後), 其後throttleTime內至多一次並以最後一次之量測延後發出
+    let fireThrottled = null
+    if (throttleTime > 0) {
+        fireThrottled = throttle(fire, throttleTime)
+    }
 
-        //dw, dh
-        let dw = sb.offsetWidth - snew.offsetWidth
-        let dh = sb.offsetHeight - snew.offsetHeight
+    //deliver, now為於ResizeObserver回呼內同步發出
+    let deliver = (sold, snew, sm, p, seq, now) => {
+        inSync = now
+        try {
+            if (fireThrottled) {
+                fireThrottled(sold, snew, sm, p, seq)
+            }
+            else {
+                fire(sold, snew, sm, p, seq)
+            }
+        }
+        finally {
+            inSync = false
+        }
+    }
 
-        //bw, bh
-        let bw = Math.abs(dw) > tolerancePixel
-        let bh = Math.abs(dh) > tolerancePixel
+    //check, 量測並與比較基準比較
+    let check = (p, allowSync) => {
+        if (cleared) {
+            return
+        }
 
-        //smode
-        smode = {
-            width: dw > 0 ? 'smaller' : (dw &lt; 0 ? 'larger' : ''),
-            height: dh > 0 ? 'smaller' : (dh &lt; 0 ? 'larger' : ''),
+        //取不到元素: 最新量測歸0, 視窗事件不發出(同移出頁面); 比較基準不動, 同尺寸之元素再出現時與既有行為相同不發出dom事件
+        if (!p) {
+            sd = sizeZero()
+            pLast = null
+            return
         }
 
+        //new size
+        let snew = measure(p, getSize)
+
         //save
-        st = sd
         sd = snew
+        pLast = p
 
-        //check
-        if (!bw &amp;&amp; !bh) {
+        //diff
+        let d = diff(snew, true)
+        if (!d.bw &amp;&amp; !d.bh) {
             return
         }
 
         //sold, sb
         let sold = sb
         sb = snew
-        let sm = { ...smode }
 
-        //emit
-        if (allowSync &amp;&amp; sync) {
-            emit(sold, snew, sm, p)
-            return
-        }
-        let t = setTimeout(() => { //emit觸發事件為同步, 用setTimeout脫勾
-            timers.delete(t)
-            emit(sold, snew, sm, p)
-        }, 1)
-        timers.add(t)
+        //deliver
+        seqCheck++
+        deliver(sold, snew, mode(d), p, seqCheck, allowSync &amp;&amp; sync)
 
     }
 
     //fWindowResize, 視窗尺寸取當下值, 否則元素尺寸未變時會一直帶著上次量測時之視窗尺寸
+    //  sold為比較基準, 與dom事件同義; 任何超過容許誤差之變化皆已立即更新比較基準, 故最新量測與比較基準之差必在容許誤差內, 方向恆為空
+    //  元素隱藏、移出頁面、取不到或尚未量得尺寸(最新量測為0)時不發出, 與dom事件之規則一致, 否則使用端於視窗改變時讀到尺寸0而算錯版面
+    //  視窗事件於同一幀之ResizeObserver回報前派發, 視窗改變本身使元素隱藏時(如媒體查詢)最新量測仍為隱藏前之尺寸, 故另確認元素當下仍被繪製(只需樣式, 不強制重排)
     let fWindowResize = (e) => {
         if (cleared) {
             return
@@ -380,10 +454,16 @@ function createCore(ev, opt) {
             windowWidth: window.innerWidth,
             windowHeight: window.innerHeight,
         }
+        if (!isShown(sd) || !isRendered(pLast)) {
+            return
+        }
         ev.emit('resizeWithWindow', {
-            sold: st,
+            sold: sb,
             snew: sd,
-            smode,
+            smode: {
+                width: '',
+                height: '',
+            },
             from: 'window',
         })
     }
@@ -396,7 +476,11 @@ function createCore(ev, opt) {
             clearTimeout(t)
         }
         timers.clear()
+        if (fireThrottled) {
+            fireThrottled.cancel()
+        }
         window.removeEventListener('resize', fWindowResize)
+        pLast = null
     }
 
     return {
@@ -420,14 +504,19 @@ function domDetectByPolling(f, opt = {}) {
     let ev = evem()
     let core = createCore(ev, opt)
 
-    //setInterval
+    //setInterval, 取不到元素時亦交check處理(最新量測歸0)
     let timer = setInterval(() => {
-        let p = getEle(f)
-        if (p) {
-            core.check(p, false)
-        }
+        core.check(getEle(f), false)
     }, getTimeInterval(opt))
 
+    //refresh, 立即重新取得元素並比較(延後發出); clear後不再呼叫f, 同ResizeObserver模式
+    ev.refresh = () => {
+        if (core.isCleared()) {
+            return
+        }
+        core.check(getEle(f), false)
+    }
+
     //clear
     ev.clear = () => {
         clearInterval(timer)
@@ -453,26 +542,58 @@ function domDetectByObserver(f, opt = {}) {
     let timeInterval = getTimeInterval(opt)
 
     //ev, core
+    //  延後發出略過時重新觀察目前元素, 並依[尺寸為0時等待DOM變動]登記等待(最新量測已歸0), 不依賴重新觀察之首次回報(舊版Safari對0尺寸之新觀察不回報)
     let ev = evem()
-    let core = createCore(ev, opt)
+    let core = createCore(ev, opt, () => {
+        reobserve()
+        updateWaiting()
+    })
 
-    //ele, timerInline, roBorder, roContent
+    //ele, timerInline, inlineConn, eleInline, roBorder, roContent
     let ele = null
     let timerInline = null
+    let inlineConn = false //上次判定是否為行內時元素是否在頁面中
+    let eleInline = false //目前元素是否曾判定為行內, 換成新節點時歸零
     let roBorder = null
     let roContent = null
 
+    //observe, 同時觀察border-box與content-box: 比較用之offsetWidth即border-box, 只觀察content-box會漏掉只改padding或border之變化; content-box則使捲軸出現或消失時clientWidth保持最新, 且getSize依內容區量測時只改padding之變化亦會回報
+    let observe = () => {
+        roBorder.observe(ele, { box: 'border-box' })
+        roContent.observe(ele)
+    }
+
+    //reobserve, 重新觀察目前元素: 新建之觀察於下一幀回報一次, 供延後發出被略過後重新比較
+    //  須先unobserve: 瀏覽器對已以同一盒觀察之元素再observe直接返回, 不重建觀察(Chromium實測)
+    let reobserve = () => {
+        if (core.isCleared() || !ele) {
+            return
+        }
+        roBorder.unobserve(ele)
+        roContent.unobserve(ele)
+        observe()
+    }
+
     //syncInline, 非替換之行內元素ResizeObserver不回報(規範明定), 取得之元素為display:inline時改以定期量測, 不為inline時停止
+    //  元素自身隱藏(display:none, 如v-show)時看不出顯示後之型別: 曾判定為行內者持續定期量測, 否則顯示時ResizeObserver會回報; 不在頁面中時display為空字串, 停止量測, 待插入頁面時(onDomChange)重判
     let syncInline = () => {
-        let inline = false
+        let display = ''
         if (ele) {
             try {
-                inline = window.getComputedStyle(ele).display === 'inline'
+                display = window.getComputedStyle(ele).display
             }
             catch (err) {
-                inline = false
+                display = ''
             }
         }
+        inlineConn = !!(ele &amp;&amp; ele.isConnected)
+        if (display === 'inline') {
+            eleInline = true
+        }
+        else if (display !== 'none' &amp;&amp; display !== '') {
+            eleInline = false
+        }
+        let inline = display === 'inline' || (display === 'none' &amp;&amp; eleInline)
         if (inline &amp;&amp; timerInline === null) {
             timerInline = setInterval(onResize, timeInterval)
         }
@@ -483,7 +604,6 @@ function domDetectByObserver(f, opt = {}) {
     }
 
     //retarget, 重新取得元素: 換成新節點時改觀察新節點, 新節點之首次回報由check比較
-    //  同時觀察border-box與content-box: 比較用之offsetWidth即border-box, 只觀察content-box會漏掉只改padding或border之變化; content-box則使捲軸出現或消失時clientWidth保持最新
     let retarget = () => {
         if (core.isCleared()) {
             return
@@ -497,9 +617,9 @@ function domDetectByObserver(f, opt = {}) {
             roContent.unobserve(ele)
         }
         ele = p
+        eleInline = false
         if (ele) {
-            roBorder.observe(ele, { box: 'border-box' })
-            roContent.observe(ele)
+            observe()
         }
         syncInline()
     }
@@ -520,8 +640,13 @@ function domDetectByObserver(f, opt = {}) {
     }
 
     //onDomChange, 僅重新取得元素不量測, 避免強制重排版; 換新節點後由ResizeObserver之首次回報觸發check
+    //  元素插入或移出頁面時重判是否為行內: 不在頁面中之元素取不到display而判為非行內(如Vue指令之bind時元素尚未插入, 或行內元素移出後定期量測已停止), 行內元素ResizeObserver又不回報, 不於插入後重判則永不量測
+    //  僅於在頁面與否改變時重判, 等待中之其他DOM變動不重複讀取樣式
     let onDomChange = () => {
         retarget()
+        if (ele &amp;&amp; ele.isConnected !== inlineConn) {
+            syncInline()
+        }
         updateWaiting()
     }
 
@@ -546,6 +671,14 @@ function domDetectByObserver(f, opt = {}) {
     retarget()
     updateWaiting()
 
+    //refresh, 立即重新取得元素並比較(延後發出), 供比較基準因尺寸以外之原因改變時使用(例如getBase之固定寬度被取消)
+    ev.refresh = () => {
+        retarget()
+        core.check(ele, false)
+        syncInline()
+        updateWaiting()
+    }
+
     //clear, 可於任何時點呼叫(含元素尚未取得), 並取消已排定之事件
     ev.clear = () => {
         if (core.isCleared()) {
@@ -569,13 +702,13 @@ function domDetectByObserver(f, opt = {}) {
 /**
  * 前端針對DOM元素監聽resize、resizeWithWindow事件，其中resizeWithWindow為dom resize與window resize皆會觸發的事件
  *
- * 瀏覽器支援ResizeObserver與MutationObserver時以其偵測(即時且閒置時不耗資源)，否則退回定期輪詢，兩者之比較規則與事件相同：以offsetWidth、offsetHeight與比較基準之差超過容許誤差即發出，比較基準為上次發出事件時之尺寸，故緩慢之連續小變化累積超過容許誤差亦會發出；尺寸為0(隱藏或移出DOM)不發出，由隱藏恢復顯示時會發出，首次取得非0尺寸時會發出
+ * 瀏覽器支援ResizeObserver與MutationObserver時以其偵測(即時且閒置時不耗資源)，否則退回定期輪詢，兩者之比較規則與事件相同：以比較用尺寸(預設offsetWidth、offsetHeight)與比較基準之差超過容許誤差即發出，比較基準預設為上次發出事件時之尺寸，故緩慢之連續小變化累積超過容許誤差亦會發出；尺寸為0(隱藏或移出DOM)不發出，由隱藏恢復顯示時會發出，首次取得非0尺寸時會發出；延後發出(非同步、節流或refresh)時，發出前元素已不被繪製(移出頁面，或自身或祖先為display:none)者不發出，待其再顯示時重新比較(同由隱藏恢復顯示，sold為0、smode兩軸為'larger')，此確認只計算樣式而不讀外框，故元素仍被繪製而尺寸於空檔內縮為0者照發；sync為true時refresh與節流之後續發出仍為延後發出，其量測早於已處理之事件者不發出
  *
- * 元素可取不到、中途消失或重建為新節點：取不到、不在頁面中或尺寸為0時，於DOM變動時重新以f取得元素並改觀察之。行內元素(display:inline)ResizeObserver不回報，該偵測器改以定期量測
+ * 元素可取不到、中途消失或重建為新節點：取不到、不在頁面中或尺寸為0時，於DOM變動時重新以f取得元素並改觀察之。行內元素(display:inline)ResizeObserver不回報，該偵測器改以定期量測，元素自身隱藏(display:none，如v-show)期間亦持續，顯示後即可量得；是否為行內於取得元素、ResizeObserver回報、定期量測及元素插入或移出頁面時判定
  *
- * 事件內容：sold為比較基準(上次發出事件時之尺寸)，snew為本次量測，smode為寬與高相對比較基準之變化方向('larger'、'smaller'或'')，ele為元素；from為'window'之事件其snew為最新量測，其中視窗尺寸取事件當下之值
+ * 事件內容：sold為上次判定變化時之量測，snew為本次量測(另含width、height為比較用尺寸)，smode為寬與高相對比較基準之變化方向('larger'、'smaller'或'')，僅該軸之差超過容許誤差時給方向，否則為''，有給getBase者延後發出時依發出當下與使用端尺寸之比較重給，ele為元素；from為'window'之事件無ele，其snew為最新量測，其中視窗尺寸取事件當下之值，其smode寬與高恆為''(視窗事件不代表元素尺寸變化，且最新量測與比較基準之差必在容許誤差內)；視窗事件於最新量測之任一維為0(隱藏、移出頁面、取不到元素、尚未量得尺寸，或寬高其一為0之元素)，或元素當下不被繪製(例如媒體查詢隨視窗改變而隱藏)時不發出，與dom事件之規則一致
  *
- * 已知限制：ResizeObserver模式下，僅屬性變化(如class)使f改指他元素、或Shadow DOM內之節點被替換時不會跟隨，此類使用端請用mode:'polling'；sync為true時監聽器不得使所監聽元素之尺寸於同一幀內再變，否則瀏覽器回報ResizeObserver loop錯誤；Safari 15.4以前不支援觀察border-box，只改padding或border之變化於該處不會發出
+ * 已知限制：ResizeObserver模式下，僅屬性變化(如class)使f改指他元素、或Shadow DOM內之節點被替換時不會跟隨，行內元素自取得起即自身為display:none(未曾以行內顯示過)、之後僅以style或class改為顯示者不會開始量測，此類使用端請用mode:'polling'；sync為true時監聽器不得使所監聽元素之尺寸於同一幀內再變，否則瀏覽器回報ResizeObserver loop錯誤；Safari 15.4以前不支援觀察border-box，只改padding或border之變化於該處不會發出
  *
  * Unit Test: {@link https://github.com/yuda-lyu/wsemi/blob/master/test/domDetect.test.mjs Github}
  * @memberOf wsemi
@@ -586,7 +719,10 @@ function domDetectByObserver(f, opt = {}) {
  * @param {Integer} [opt.tolerancePixel=1] 輸入容許誤差整數，單位px，可給0表示任何變化皆發出，預設1
  * @param {Boolean} [opt.sync=false] 輸入是否於ResizeObserver回呼內同步發出事件布林值，true時使用端可於瀏覽器繪製前更新版面(例如圖表重繪)，僅ResizeObserver模式有效，預設false
  * @param {Boolean} [opt.watchIdentity=false] 輸入元素可見時是否仍於DOM變動時重新取得元素布林值，f可能於舊元素仍可見時改回傳另一元素者給true，僅ResizeObserver模式有效，預設false
- * @returns {Object} 回傳物件，可使用on與clear函數，on可監聽resize與resizeWithWindow事件，clear為釋放監聽，可於任何時點呼叫(含元素尚未取得)，並取消已排定之事件
+ * @param {Function} [opt.getSize=null] 輸入比較用尺寸函數，傳入元素，回傳{width,height}，供依內容區或特定量測方式繪製之使用端(例如圖表依clientWidth扣除padding)，給予時只改padding、元素內出現或消失捲軸等外框不變之變化亦會發出，回傳非數字或拋錯之軸視為0(不發出)，預設null表示使用offsetWidth、offsetHeight
+ * @param {Function} [opt.getBase=null] 輸入比較基準函數，回傳使用端目前套用之尺寸{width,height}，該軸非數字(含拋錯)表示該軸不比較(例如固定寬度)，給予時以其取代上次發出事件時之尺寸，故掛載時尺寸已一致者不發出(其後事件之sold於首次判定變化前為0)，由隱藏恢復顯示時若與使用端尺寸相同亦不發出；使用端須於事件內套用新尺寸(getBase之回傳隨之更新)，否則之後每次回報皆判定為變化而發出，預設null
+ * @param {Integer} [opt.throttle=0] 輸入節流時間整數，單位毫秒，首次立即發出，其後每throttle毫秒至多發出一次並以最後一次之量測發出(其sold為最後一次判定變化前之量測，可能未曾發出)，clear時取消待發出者，僅作用於元素尺寸之事件(resize與from為'dom'之resizeWithWindow)，視窗事件不節流，預設0表示不節流
+ * @returns {Object} 回傳物件，可使用on、refresh與clear函數，on可監聽resize與resizeWithWindow事件，refresh為立即重新量測並比較(延後發出，給throttle時併入節流而至多延後throttle毫秒)，供比較基準因尺寸以外之原因改變時使用，clear為釋放監聽，可於任何時點呼叫(含元素尚未取得)，並取消已排定之事件
  * @example
  * need test in browser
  *
@@ -629,7 +765,7 @@ export default domDetect
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Sep 25 2026 14:59:11 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sat Sep 26 2026 22:05:36 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>