one-screen-scale 1.0.0 → 1.3.0

package/src/index.js

@@ -4,11 +4,30 @@ export {
   applyScale,
   getPageScale,
   getInverseScale,
-  createScaler
+  createScaler,
+  applyBaseStyles,
+  removeBaseStyles,
+  applyCompensateStyles,
+  removeCompensateStyles,
+  ensureBaseStyleSheet,
+  BASE_CLASS,
+  SCALE_CHANGE_EVENT,
 } from './core.js'
 
+// ---- 组件反缩放补偿（仅抵消页面 scale） ----
+export {
+  resolvePageScale,
+  applyCompensateTransform,
+  clearCompensateTransform,
+  resizeCanvasUnder,
+  resizeEchartsUnder,
+  createCompensate,
+  setCompensateEcharts,
+  CANVAS_RESIZE_EVENT,
+} from './compensate.js'
+
 // ---- Vue 指令 ----
-export { vFitScreen } from './directives.js'
+export { vFitScreen, vCompensate, vFitCompensate } from './directives.js'
 
 // ---- Vue Composable ----
 export { useFitScreen } from './composables.js'

package/src/react.d.ts

@@ -7,6 +7,25 @@ export interface ScalerOptions {
   visualWidth?: number
   origin?: string
   autoResize?: boolean
+  /**
+   * 是否自动注入模式所需基础样式（默认 true）
+   * - contain: width:100vw; min-height:100vh/100dvh
+   * - fixed-width: 暂不注入（宽高由 refresh 行内补偿）
+   */
+  injectBaseStyles?: boolean
+  /**
+   * 内容尺寸变化时自动重算（默认 true）
+   */
+  observeContent?: boolean
+}
+
+export interface CompensateOptions {
+  /** 补偿后通知子树 canvas 重绘（ECharts / Chart.js / 自定义事件） */
+  resizeCanvas?: boolean
+  /** @deprecated 请用 resizeCanvas */
+  echarts?: boolean | { getInstanceByDom?: (el: Element) => { resize: (opts?: object) => void } | undefined }
+  echartsLib?: { getInstanceByDom?: (el: Element) => { resize: (opts?: object) => void } | undefined }
+  onRefresh?: (detail: { scale: number; inverseScale: number; el: HTMLElement }) => void
 }
 
 export function useFitScreen(
@@ -17,3 +36,14 @@ export function useFitScreen(
   inverseScale: number
   refresh: () => void
 }
+
+/**
+ * 对应 Vue `v-compensate`：抵消页面 scale 的组件反缩放。
+ * 节点晚于首次 effect 出现时会自动补挂；`resizeCanvas` 变化会重建监听。
+ */
+export function useCompensate(
+  targetRef: RefObject<HTMLElement | null> | HTMLElement,
+  options?: CompensateOptions
+): {
+  refresh: () => void
+}

package/src/react.js

@@ -1,36 +1,86 @@
 /**
- * React hook
+ * React hooks
  *   useFitScreen(ref, options) → { scale, inverseScale, refresh }
+ *   useCompensate(ref, options) → { refresh }   // 对应 Vue v-compensate
  */
 import { useRef, useState, useEffect, useCallback } from 'react'
-import { createScaler } from './core.js'
+import { createScaler, SCALE_CHANGE_EVENT } from './core.js'
+import { createCompensate } from './compensate.js'
+
+function resolveElement(targetRef) {
+  if (!targetRef) return null
+  if (typeof HTMLElement !== 'undefined' && targetRef instanceof HTMLElement) return targetRef
+  if (targetRef.current instanceof HTMLElement) return targetRef.current
+  if (targetRef.value instanceof HTMLElement) return targetRef.value
+  return null
+}
+
+/** ref 第一次 effect 时可能还是空的，等到节点出现再挂。卸载时停掉等待 */
+function waitForElement(targetRef, onReady) {
+  let raf = 0
+  let timer = 0
+  let frames = 0
+  let settled = false
+
+  const finish = () => {
+    settled = true
+    cancelAnimationFrame(raf)
+    clearInterval(timer)
+  }
+
+  const tick = () => {
+    if (settled) return
+    const el = resolveElement(targetRef)
+    if (el) {
+      finish()
+      onReady(el)
+      return
+    }
+    frames += 1
+    if (frames < 60) raf = requestAnimationFrame(tick)
+    else if (!timer) timer = setInterval(tick, 200)
+  }
+
+  tick()
+  return finish
+}
 
 export function useFitScreen(targetRef, options = {}) {
   const [scale, setScale] = useState(1)
   const [inverseScale, setInverseScale] = useState(1)
   const scalerRef = useRef(null)
+  const optionsRef = useRef(options)
+  optionsRef.current = options
 
   useEffect(() => {
-    const el = targetRef?.current ?? targetRef
-    if (!el) return
+    let detach = () => {}
+    let disposed = false
 
-    const scaler = createScaler(el, options)
-    scalerRef.current = scaler
-    const s = scaler.start()
-    setScale(s)
-    setInverseScale(s > 0 ? 1 / s : 1)
-
-    const onResize = () => {
-      const s = scaler.getScale()
+    const cancelWait = waitForElement(targetRef, (el) => {
+      if (disposed) return
+      const scaler = createScaler(el, optionsRef.current)
+      scalerRef.current = scaler
+      const s = scaler.start()
       setScale(s)
       setInverseScale(s > 0 ? 1 / s : 1)
-    }
-    window.addEventListener('resize', onResize)
+
+      const onScale = (event) => {
+        if (event.detail?.el !== el) return
+        setScale(event.detail.scale)
+        setInverseScale(event.detail.inverseScale)
+      }
+      window.addEventListener(SCALE_CHANGE_EVENT, onScale)
+      detach = () => {
+        window.removeEventListener(SCALE_CHANGE_EVENT, onScale)
+        scaler.stop()
+        scalerRef.current = null
+      }
+    })
 
     return () => {
-      window.removeEventListener('resize', onResize)
-      scaler.stop()
-      scalerRef.current = null
+      disposed = true
+      cancelWait()
+      detach()
     }
   }, [targetRef])
 
@@ -44,3 +94,46 @@ export function useFitScreen(targetRef, options = {}) {
 
   return { scale, inverseScale, refresh }
 }
+
+/**
+ * 第三方组件反缩放补偿（对应 Vue `v-compensate`）。
+ * 挂在槽位内层 ref 上；父槽位需有明确宽高。
+ *
+ * @example
+ *   const innerRef = useRef(null)
+ *   useCompensate(innerRef, { resizeCanvas: true })
+ */
+export function useCompensate(targetRef, options = {}) {
+  const apiRef = useRef(null)
+  const optionsRef = useRef(options)
+  optionsRef.current = options
+  const resizeFlag = Boolean(options?.resizeCanvas || options?.echarts || options?.echartsLib)
+  const lib =
+    (options && typeof options.echarts === 'object' && options.echarts) ||
+    options?.echartsLib ||
+    null
+
+  useEffect(() => {
+    let api = null
+    let disposed = false
+
+    const cancelWait = waitForElement(targetRef, (el) => {
+      if (disposed) return
+      api = createCompensate(el, () => optionsRef.current || {})
+      apiRef.current = api
+    })
+
+    return () => {
+      disposed = true
+      cancelWait()
+      api?.stop()
+      apiRef.current = null
+    }
+  }, [targetRef, resizeFlag, lib])
+
+  const refresh = useCallback(() => {
+    apiRef.current?.refresh()
+  }, [])
+
+  return { refresh }
+}