one-screen-scale 1.0.0 → 1.3.0

package/src/composables.js

@@ -1,67 +1,69 @@
-/**
- * Vue 3 Composable
- *   useFitScreen(ref, options) → { scale, inverseScale, refresh }
- */
-import { ref, onMounted, onUnmounted, watch } from 'vue'
-import { createScaler, getInverseScale } from './core.js'
-
-export function useFitScreen(targetRef, options = {}) {
-  const scale = ref(1)
-  const inverseScale = ref(1)
-
-  let scaler = null
-  let onResize = null
-
-  function setup(el) {
-    if (!el) return
-    scaler = createScaler(el, options)
-    const s = scaler.start()
-    scale.value = s
-    inverseScale.value = getInverseScale(el)
-
-    onResize = () => {
-      scale.value = scaler?.getScale?.() ?? 1
-      inverseScale.value = getInverseScale(el)
-    }
-    window.addEventListener('resize', onResize)
-  }
-
-  function teardown() {
-    if (onResize) {
-      window.removeEventListener('resize', onResize)
-      onResize = null
-    }
-    scaler?.stop()
-    scaler = null
-  }
-
-  // 处理 ref 初始有值的情况
-  onMounted(() => {
-    const el = targetRef?.value ?? targetRef
-    setup(el)
-  })
-
-  // 处理 ref 延迟赋值的情况（异步挂载）
-  if (targetRef && typeof targetRef === 'object' && 'value' in targetRef) {
-    watch(
-      () => targetRef.value,
-      (el) => {
-        if (el && !scaler) setup(el)
-      }
-    )
-  }
-
-  onUnmounted(() => {
-    teardown()
-  })
-
-  const refresh = () => {
-    const el = targetRef?.value ?? targetRef
-    if (!el || !scaler) return
-    const s = scaler.refresh()
-    scale.value = s
-    inverseScale.value = getInverseScale(el)
-  }
-
-  return { scale, inverseScale, refresh }
-}
+/**
+ * Vue 3 Composable
+ *   useFitScreen(ref, options) → { scale, inverseScale, refresh }
+ */
+import { ref, onMounted, onUnmounted, watch } from 'vue'
+import { createScaler, SCALE_CHANGE_EVENT } from './core.js'
+
+export function useFitScreen(targetRef, options = {}) {
+  const scale = ref(1)
+  const inverseScale = ref(1)
+
+  let scaler = null
+  let onScale = null
+
+  function setup(el) {
+    if (!el) return
+    scaler = createScaler(el, options)
+    const s = scaler.start()
+    scale.value = s
+    inverseScale.value = s > 0 ? 1 / s : 1
+
+    // 图片加载等导致的重算不经过 window.resize，跟页面缩放事件走
+    onScale = (event) => {
+      if (event.detail?.el !== el) return
+      scale.value = event.detail.scale
+      inverseScale.value = event.detail.inverseScale
+    }
+    window.addEventListener(SCALE_CHANGE_EVENT, onScale)
+  }
+
+  function teardown() {
+    if (onScale) {
+      window.removeEventListener(SCALE_CHANGE_EVENT, onScale)
+      onScale = null
+    }
+    scaler?.stop()
+    scaler = null
+  }
+
+  // 处理 ref 初始有值的情况
+  onMounted(() => {
+    const el = targetRef?.value ?? targetRef
+    setup(el)
+  })
+
+  // 处理 ref 延迟赋值的情况（异步挂载）
+  if (targetRef && typeof targetRef === 'object' && 'value' in targetRef) {
+    watch(
+      () => targetRef.value,
+      (el) => {
+        if (el && !scaler) setup(el)
+      }
+    )
+  }
+
+  onUnmounted(() => {
+    teardown()
+  })
+
+  const refresh = () => {
+    const el = targetRef?.value ?? targetRef
+    if (!el || !scaler) return
+    const s = scaler.refresh()
+    scale.value = s
+    inverseScale.value = s > 0 ? 1 / s : 1
+  }
+
+  return { scale, inverseScale, refresh }
+}

package/src/core.js

@@ -4,8 +4,16 @@
  * 两种模式：
  *   'contain'     一屏展示，内容不溢出，用 min(scaleX, scaleY)
  *   'fixed-width' 固定视觉宽度，内容可滚动，反向补高
+ *
+ * 配套前提：H5 使用 postcss-px-to-viewport（或同类）做移动端适配。
+ * createScaler / 指令默认会注入基础宽高样式，保证测量与缩放生效。
+ *
+ * 图片等异步内容会改变 offsetHeight：默认用 ResizeObserver / 图片 load
+ * 在尺寸稳定后再 refresh，避免首屏偶发「量矮了 → scale 偏大」。
  */
 
+import { applyBaseStyles, removeBaseStyles } from './baseStyles.js'
+
 // ---------- helpers ----------
 
 function resolveEl(el) {
@@ -27,18 +35,14 @@ export function calculateScale({
   targetHeight = (typeof window !== 'undefined' ? window.innerHeight : 1080),
   mode = 'contain',
   visualWidth = 450,     // fixed-width 模式下的目标视觉宽度
-  screenWidth = (typeof window !== 'undefined' ? window.screen.width : 1920),     // fixed-width 模式下的设备屏幕宽度
 }) {
   if (!sourceWidth || !sourceHeight || sourceWidth <= 0 || sourceHeight <= 0) return 1
 
   let scale
 
   if (mode === 'fixed-width') {
-    if(screenWidth < visualWidth){
-      scale = 1
-    }else{
-      scale = visualWidth / Math.max(targetWidth, screenWidth)
-    }
+    // 只用视口宽：视口比目标宽才缩小，否则 1:1（保持清晰）
+    scale = targetWidth > visualWidth ? visualWidth / targetWidth : 1
   } else {
     const sx = targetWidth / sourceWidth
     const sy = targetHeight / sourceHeight
@@ -50,11 +54,23 @@ export function calculateScale({
 
 // ---------- apply / read ----------
 
+/** 页面 scale 变化时抛出，供 ECharts.resize / 业务监听 */
+export const SCALE_CHANGE_EVENT = 'one-screen-scale-change'
+
 export function applyScale(el, scale, origin = 'top center') {
   const target = resolveEl(el)
   if (!target) return
   target.style.transform = `scale(${scale})`
   target.style.transformOrigin = origin
+  // 供业务 / v-compensate 做反缩放（继承到子树）
+  const inv = scale > 0 ? 1 / scale : 1
+  target.style.setProperty('--one-screen-scale', String(scale))
+  target.style.setProperty('--one-screen-inverse-scale', String(inv))
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(
+      new CustomEvent(SCALE_CHANGE_EVENT, { detail: { scale, inverseScale: inv, el: target } })
+    )
+  }
 }
 
 export function getPageScale(el) {
@@ -98,18 +114,44 @@ export function createScaler(el, options = {}) {
     mode = 'contain',
     visualWidth = 450,
     origin = 'top center',
-    autoResize = true
+    autoResize = true,
+    /** 是否自动注入模式所需的宽高基础样式，默认 true */
+    injectBaseStyles = true,
+    /**
+     * 内容尺寸变化时自动重算（图片 load、字体、DOM 撑高）。
+     * 解决刷新偶发「图未加载完就测量 → scale 偏大」。
+     */
+    observeContent = true,
   } = options
 
   let currentScale = 1
-  let handler = null
+  let resizeHandler = null
+  let loadHandler = null
+  let windowLoadHandler = null
+  let rafId = 0
+  let unlockRaf = 0
+  let ro = null
+  let refreshing = false
+  let lastMeasured = { w: 0, h: 0 }
+  // start / stop 各加一，用来丢掉停掉之后才回来的字体、帧回调
+  let session = 0
+
+  // fixed-width 会改 inline width/height，stop 时还原
+  const savedInline = {
+    width: target.style.width,
+    height: target.style.height,
+    transform: target.style.transform,
+    transformOrigin: target.style.transformOrigin,
+  }
 
   function compute() {
     const sw = target.offsetWidth
     const sh = target.offsetHeight
-    const tw = window.innerWidth
+    const tw = document.documentElement.clientWidth || window.innerWidth
     const th = window.innerHeight
 
+    lastMeasured = { w: sw, h: sh }
+
     return calculateScale({
       sourceWidth: sw,
       sourceHeight: sh,
@@ -117,40 +159,159 @@ export function createScaler(el, options = {}) {
       targetHeight: th,
       mode,
       visualWidth,
-      screenWidth: window.screen.width
     })
   }
 
   function refresh() {
+    refreshing = true
     const next = compute()
-    if (next !== currentScale) {
-      currentScale = next
-      applyScale(target, next, origin)
-
-      // fixed-width 模式：反向补偿高度
-      if (mode === 'fixed-width' && next > 0) {
-        target.style.width = `${Math.max(window.innerWidth, window.screen.width)}px`
-        target.style.height = `${Math.round(window.innerHeight / next)}px`
-      }
+    currentScale = next
+    // 始终写入，保证首次 scale=1 时也带上 transform-origin
+    applyScale(target, next, origin)
+
+    // fixed-width 模式：反向补偿高度（视觉宽固定，布局宽仍用视口宽再缩小）
+    if (mode === 'fixed-width' && next > 0) {
+      const viewportWidth = document.documentElement.clientWidth || window.innerWidth
+      const nextW = `${viewportWidth}px`
+      const nextH = `${Math.round(window.innerHeight / next)}px`
+      // 值不变不写，避免 ResizeObserver 死循环
+      if (target.style.width !== nextW) target.style.width = nextW
+      if (target.style.height !== nextH) target.style.height = nextH
     }
+    // 等布局提交后再放开，避免 RO 回调里立刻重入
+    const token = session
+    cancelAnimationFrame(unlockRaf)
+    unlockRaf = requestAnimationFrame(() => {
+      if (token !== session) return
+      refreshing = false
+    })
     return currentScale
   }
 
+  function scheduleRefresh() {
+    if (refreshing) return
+    cancelAnimationFrame(rafId)
+    const token = session
+    rafId = requestAnimationFrame(() => {
+      if (token !== session) return
+      // 尺寸没变就跳过（fixed-width 改 height 触发的 RO）
+      const w = target.offsetWidth
+      const h = target.offsetHeight
+      if (w === lastMeasured.w && h === lastMeasured.h && target.style.transform) {
+        // 视口变化仍需算：由 window.resize 路径直接 refresh
+        return
+      }
+      refresh()
+    })
+  }
+
+  function onWindowResize() {
+    refresh()
+  }
+
   function start() {
+    session += 1
+    const token = session
+    // 复用同一实例 start 时，上一次 stop 之后留下的锁要清掉
+    refreshing = false
+    if (injectBaseStyles) {
+      applyBaseStyles(target, mode)
+    }
+    // 注入样式后再量尺寸
     refresh()
+
     if (autoResize) {
-      handler = () => refresh()
-      window.addEventListener('resize', handler)
+      resizeHandler = onWindowResize
+      window.addEventListener('resize', resizeHandler)
     }
+
+    if (observeContent && typeof window !== 'undefined') {
+      // 1) 子树布局尺寸变化（图片解码后撑高最常见）
+      if (typeof ResizeObserver !== 'undefined') {
+        ro = new ResizeObserver(() => scheduleRefresh())
+        ro.observe(target)
+      }
+
+      // 2) 捕获阶段听内部 img/video 的 load（含后插入的节点）
+      loadHandler = (e) => {
+        const t = e.target
+        if (t && (t.tagName === 'IMG' || t.tagName === 'VIDEO' || t.tagName === 'IFRAME')) {
+          scheduleRefresh()
+        }
+      }
+      target.addEventListener('load', loadHandler, true)
+      target.addEventListener('error', loadHandler, true)
+
+      // 3) 字体就绪。stop 之后 session 变了，这次回调直接丢掉
+      if (document.fonts && document.fonts.ready) {
+        document.fonts.ready
+          .then(() => {
+            if (token !== session) return
+            scheduleRefresh()
+          })
+          .catch(() => {})
+      }
+
+      // 4) 整页资源 load（缓存命中时可能已 complete）
+      if (document.readyState === 'complete') {
+        scheduleRefresh()
+      } else {
+        windowLoadHandler = () => scheduleRefresh()
+        window.addEventListener('load', windowLoadHandler, { once: true })
+      }
+
+      // 5) 再等两帧，覆盖首屏同步布局抖动
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => scheduleRefresh())
+      })
+    }
+
     return currentScale
   }
 
   function stop() {
-    if (handler) {
-      window.removeEventListener('resize', handler)
-      handler = null
+    session += 1
+    if (resizeHandler) {
+      window.removeEventListener('resize', resizeHandler)
+      resizeHandler = null
+    }
+    if (loadHandler) {
+      target.removeEventListener('load', loadHandler, true)
+      target.removeEventListener('error', loadHandler, true)
+      loadHandler = null
+    }
+    if (windowLoadHandler) {
+      window.removeEventListener('load', windowLoadHandler)
+      windowLoadHandler = null
     }
+    if (ro) {
+      ro.disconnect()
+      ro = null
+    }
+    cancelAnimationFrame(rafId)
+    cancelAnimationFrame(unlockRaf)
+    rafId = 0
+    unlockRaf = 0
+
+    if (injectBaseStyles) {
+      removeBaseStyles(target)
+    }
+    target.style.width = savedInline.width
+    target.style.height = savedInline.height
+    target.style.transform = savedInline.transform
+    target.style.transformOrigin = savedInline.transformOrigin
+    target.style.removeProperty('--one-screen-scale')
+    target.style.removeProperty('--one-screen-inverse-scale')
   }
 
   return { start, stop, refresh, getScale: () => currentScale }
 }
+
+export {
+  applyBaseStyles,
+  removeBaseStyles,
+  applyCompensateStyles,
+  removeCompensateStyles,
+  ensureBaseStyleSheet,
+  BASE_CLASS,
+} from './baseStyles.js'

package/src/directives.js

@@ -1,34 +1,144 @@
 /**
  * Vue 3 指令
- *   v-fit-screen   页面级缩放
- *   v-compensate   组件级反缩放补偿
+ *   v-fit-screen    页面级缩放
+ *   v-compensate    组件级反缩放补偿（ECharts / Element Plus 等）
  */
 import { createScaler } from './core.js'
+import { createCompensate } from './compensate.js'
+
+function readOptions(binding) {
+  return binding.value && typeof binding.value === 'object' ? binding.value : {}
+}
+
+function mountScaler(el, binding) {
+  const options = readOptions(binding)
+  const scaler = createScaler(el, options)
+  scaler.start()
+  el.__fitScreenScaler = scaler
+  el.__fitScreenOptionsKey = JSON.stringify({
+    mode: options.mode || 'contain',
+    visualWidth: options.visualWidth,
+    origin: options.origin,
+    autoResize: options.autoResize,
+    injectBaseStyles: options.injectBaseStyles,
+    observeContent: options.observeContent,
+  })
+}
+
+function unmountScaler(el) {
+  const scaler = el.__fitScreenScaler
+  if (scaler) {
+    scaler.stop()
+    delete el.__fitScreenScaler
+    delete el.__fitScreenOptionsKey
+  }
+}
 
 // ---- v-fit-screen ----
 
 export const vFitScreen = {
   mounted(el, binding) {
-    const options = binding.value || {}
-    const scaler = createScaler(el, options)
-    scaler.start()
-    el.__fitScreenScaler = scaler
+    mountScaler(el, binding)
   },
 
   updated(el, binding) {
-    const scaler = el.__fitScreenScaler
-    if (scaler) {
-      const options = binding.value || {}
-      // 简单处理：重新 refresh
-      scaler.refresh()
+    const options = readOptions(binding)
+    const key = JSON.stringify({
+      mode: options.mode || 'contain',
+      visualWidth: options.visualWidth,
+      origin: options.origin,
+      autoResize: options.autoResize,
+      injectBaseStyles: options.injectBaseStyles,
+      observeContent: options.observeContent,
+    })
+
+    if (el.__fitScreenOptionsKey !== key) {
+      unmountScaler(el)
+      mountScaler(el, binding)
+      return
     }
+
+    el.__fitScreenScaler?.refresh()
   },
 
   unmounted(el) {
-    const scaler = el.__fitScreenScaler
-    if (scaler) {
-      scaler.stop()
-      delete el.__fitScreenScaler
-    }
+    unmountScaler(el)
+  },
+}
+
+function readCompensateOptions(binding) {
+  const value = binding?.value
+  const modifiers = binding?.modifiers || {}
+  const options = value && typeof value === 'object' ? { ...value } : {}
+  // v-compensate.resize-canvas / .resizeCanvas / 旧名 .echarts
+  if (
+    modifiers.resizeCanvas ||
+    modifiers['resize-canvas'] ||
+    modifiers.echarts ||
+    value === 'resize-canvas' ||
+    value === 'resizeCanvas' ||
+    value === 'echarts'
+  ) {
+    options.resizeCanvas = options.resizeCanvas || true
   }
+  return options
+}
+
+function compensateOptionsKey(options) {
+  return JSON.stringify({
+    resizeCanvas: Boolean(options.resizeCanvas || options.echarts || options.echartsLib),
+    hasLib: Boolean(
+      (options.echarts && typeof options.echarts === 'object') || options.echartsLib
+    ),
+    hasOnRefresh: typeof options.onRefresh === 'function',
+  })
 }
+
+/**
+ * v-compensate — 挂在「被页面 scale 搞坏」的第三方组件外包一层。
+ *
+ * 原理与业务 WinRateChart 手写一致（JS 行内，非纯 CSS）：
+ *   transform: scale(inverse); width/height: 100% * pageScale; origin: top left
+ *
+ * 用法：
+ *   <div class="slot"><div v-compensate><Whatever /></div></div>
+ *   <div class="slot"><div v-compensate.resize-canvas><Chart /></div></div>
+ *
+ * `.resize-canvas` / `{ resizeCanvas: true }`：补偿后通知子树 canvas 重绘
+ * （探测 ECharts / Chart.js，并派发 one-screen-scale-canvas-resize）。
+ */
+function mountCompensate(el) {
+  const api = createCompensate(el, () => el.__oneScreenCompensateOptions || {})
+  el.__oneScreenCompensateApi = api
+  el.__oneScreenCompensateKey = compensateOptionsKey(el.__oneScreenCompensateOptions || {})
+}
+
+export const vCompensate = {
+  mounted(el, binding) {
+    el.__oneScreenCompensateOptions = readCompensateOptions(binding)
+    mountCompensate(el)
+  },
+
+  updated(el, binding) {
+    const options = readCompensateOptions(binding)
+    const key = compensateOptionsKey(options)
+    el.__oneScreenCompensateOptions = options
+    // resizeCanvas / 图表库变了才重建监听；onRefresh 每次 refresh 现读
+    if (el.__oneScreenCompensateKey !== key) {
+      el.__oneScreenCompensateApi?.stop()
+      mountCompensate(el)
+      return
+    }
+    el.__oneScreenCompensateApi?.refresh()
+  },
+
+  unmounted(el) {
+    el.__oneScreenCompensateApi?.stop()
+    delete el.__oneScreenCompensateApi
+    delete el.__oneScreenCompensateKey
+    delete el.__oneScreenCompensateOptions
+  },
+}
+
+/** 别名，与早期注释里的命名一致 */
+export const vFitCompensate = vCompensate

package/src/index.d.ts

@@ -7,7 +7,6 @@ export interface ScaleOptions {
   targetHeight?: number
   mode?: 'contain' | 'fixed-width'
   visualWidth?: number
-  screenWidth?: number
 }
 
 export interface ScalerOptions {
@@ -15,6 +14,17 @@ export interface ScalerOptions {
   visualWidth?: number
   origin?: string
   autoResize?: boolean
+  /**
+   * 是否自动注入模式所需基础样式（默认 true）
+   * - contain: width:100vw; min-height:100vh/100dvh
+   * - fixed-width: 暂不注入（宽高由 refresh 行内补偿）
+   */
+  injectBaseStyles?: boolean
+  /**
+   * 内容尺寸变化时自动重算（默认 true）。
+   * 监听 ResizeObserver / 内部图片 load 等，避免图未加载完就测量导致 scale 偏大。
+   */
+  observeContent?: boolean
 }
 
 export interface ScalerInstance {
@@ -24,17 +34,83 @@ export interface ScalerInstance {
   getScale: () => number
 }
 
+export const BASE_CLASS: {
+  contain: string
+  'fixed-width': string
+  compensate: string
+}
+
+export const SCALE_CHANGE_EVENT: 'one-screen-scale-change'
+export const CANVAS_RESIZE_EVENT: 'one-screen-scale-canvas-resize'
+
 export function calculateScale(options: ScaleOptions): number
 export function applyScale(el: HTMLElement | string, scale: number, origin?: string): void
 export function getPageScale(el?: HTMLElement | string): number
 export function getInverseScale(el?: HTMLElement | string): number
 export function createScaler(el: HTMLElement | string, options?: ScalerOptions): ScalerInstance
+export function ensureBaseStyleSheet(): HTMLStyleElement | null
+export function applyBaseStyles(el: HTMLElement, mode?: 'contain' | 'fixed-width'): string | null
+export function removeBaseStyles(el: HTMLElement): void
+export function applyCompensateStyles(el: HTMLElement): string | null
+export function removeCompensateStyles(el: HTMLElement): void
+
+// ===== 组件反缩放补偿（仅抵消页面 v-fit-screen 的 scale；不处理浏览器 Ctrl+/-） =====
+
+export interface CompensateRefreshDetail {
+  scale: number
+  inverseScale: number
+  el: HTMLElement
+}
+
+export interface CompensateOptions {
+  /**
+   * 补偿后通知子树 canvas 重绘：探测 ECharts / Chart.js，
+   * 并对每个 <canvas> 派发 CANVAS_RESIZE_EVENT。
+   */
+  resizeCanvas?: boolean
+  /** @deprecated 请用 resizeCanvas；传入 echarts 模块时仍表示开启 + 注入库 */
+  echarts?: boolean | { getInstanceByDom?: (el: Element) => { resize: (opts?: object) => void } | undefined }
+  echartsLib?: { getInstanceByDom?: (el: Element) => { resize: (opts?: object) => void } | undefined }
+  onRefresh?: (detail: CompensateRefreshDetail) => void
+}
+
+export interface CompensateInstance {
+  refresh: () => void
+  stop: () => void
+}
+
+export function resolvePageScale(fromEl?: HTMLElement | null): number
+export function applyCompensateTransform(el: HTMLElement): {
+  scale: number
+  inverseScale: number
+}
+export function clearCompensateTransform(el: HTMLElement): void
+export function resizeCanvasUnder(el: HTMLElement, echartsLib?: CompensateOptions['echartsLib']): number
+/** @deprecated 请用 resizeCanvasUnder */
+export function resizeEchartsUnder(el: HTMLElement, echartsLib?: CompensateOptions['echartsLib']): number
+export function createCompensate(
+  el: HTMLElement,
+  options?: CompensateOptions | (() => CompensateOptions)
+): CompensateInstance
+/** 全局注入 echarts，供 resizeCanvas 探测（无需每个调用传模块） */
+export function setCompensateEcharts(echarts: CompensateOptions['echartsLib'] | null): void
 
 // ===== Vue =====
 
 import type { Ref, Directive } from 'vue'
 
-export const vFitScreen: Directive<HTMLElement, ScalerOptions>
+export const vFitScreen: Directive<HTMLElement, ScalerOptions | undefined>
+/**
+ * 第三方组件反缩放。修饰符 `.resize-canvas` 或 `{ resizeCanvas: true }` 通知子树 canvas 重绘。
+ */
+export const vCompensate: Directive<
+  HTMLElement,
+  CompensateOptions | 'resize-canvas' | 'resizeCanvas' | 'echarts' | undefined
+>
+export const vFitCompensate: Directive<
+  HTMLElement,
+  CompensateOptions | 'resize-canvas' | 'resizeCanvas' | 'echarts' | undefined
+>
 
 export function useFitScreen(
   targetRef: Ref<HTMLElement | null> | HTMLElement,