one-screen-scale 1.1.0 → 1.3.0

package/src/index.d.ts

@@ -1,46 +1,122 @@
-// ===== 核心 =====
-
-export interface ScaleOptions {
-  sourceWidth: number
-  sourceHeight: number
-  targetWidth?: number
-  targetHeight?: number
-  mode?: 'contain' | 'fixed-width'
-  visualWidth?: number
-  // screenWidth?: number
-}
-
-export interface ScalerOptions {
-  mode?: 'contain' | 'fixed-width'
-  visualWidth?: number
-  origin?: string
-  autoResize?: boolean
-}
-
-export interface ScalerInstance {
-  start: () => number
-  stop: () => void
-  refresh: () => number
-  getScale: () => number
-}
-
-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
-
-// ===== Vue =====
-
-import type { Ref, Directive } from 'vue'
-
-export const vFitScreen: Directive<HTMLElement, ScalerOptions>
-
-export function useFitScreen(
-  targetRef: Ref<HTMLElement | null> | HTMLElement,
-  options?: ScalerOptions
-): {
-  scale: Ref<number>
-  inverseScale: Ref<number>
-  refresh: () => void
-}
+// ===== 核心 =====
+
+export interface ScaleOptions {
+  sourceWidth: number
+  sourceHeight: number
+  targetWidth?: number
+  targetHeight?: number
+  mode?: 'contain' | 'fixed-width'
+  visualWidth?: number
+}
+
+export interface ScalerOptions {
+  mode?: 'contain' | 'fixed-width'
+  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 {
+  start: () => number
+  stop: () => void
+  refresh: () => number
+  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，
+   * 并对每个 &lt;canvas&gt; 派发 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 | 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,
+  options?: ScalerOptions
+): {
+  scale: Ref<number>
+  inverseScale: Ref<number>
+  refresh: () => void
+}

package/src/index.js

@@ -1,14 +1,33 @@
-// ---- 核心（框架无关） ----
-export {
-  calculateScale,
-  applyScale,
-  getPageScale,
-  getInverseScale,
-  createScaler
-} from './core.js'
-
-// ---- Vue 指令 ----
-export { vFitScreen } from './directives.js'
-
-// ---- Vue Composable ----
-export { useFitScreen } from './composables.js'
+// ---- 核心（框架无关） ----
+export {
+  calculateScale,
+  applyScale,
+  getPageScale,
+  getInverseScale,
+  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, vCompensate, vFitCompensate } from './directives.js'
+
+// ---- Vue Composable ----
+export { useFitScreen } from './composables.js'

package/src/react.d.ts

@@ -1,19 +1,49 @@
-// ===== React =====
-
-import type { RefObject } from 'react'
-
-export interface ScalerOptions {
-  mode?: 'contain' | 'fixed-width'
-  visualWidth?: number
-  origin?: string
-  autoResize?: boolean
-}
-
-export function useFitScreen(
-  targetRef: RefObject<HTMLElement | null> | HTMLElement,
-  options?: ScalerOptions
-): {
-  scale: number
-  inverseScale: number
-  refresh: () => void
-}
+// ===== React =====
+
+import type { RefObject } from 'react'
+
+export interface ScalerOptions {
+  mode?: 'contain' | 'fixed-width'
+  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(
+  targetRef: RefObject<HTMLElement | null> | HTMLElement,
+  options?: ScalerOptions
+): {
+  scale: number
+  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,46 +1,139 @@
-/**
- * React hook
- *   useFitScreen(ref, options) → { scale, inverseScale, refresh }
- */
-import { useRef, useState, useEffect, useCallback } from 'react'
-import { createScaler } from './core.js'
-
-export function useFitScreen(targetRef, options = {}) {
-  const [scale, setScale] = useState(1)
-  const [inverseScale, setInverseScale] = useState(1)
-  const scalerRef = useRef(null)
-
-  useEffect(() => {
-    const el = targetRef?.current ?? targetRef
-    if (!el) return
-
-    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()
-      setScale(s)
-      setInverseScale(s > 0 ? 1 / s : 1)
-    }
-    window.addEventListener('resize', onResize)
-
-    return () => {
-      window.removeEventListener('resize', onResize)
-      scaler.stop()
-      scalerRef.current = null
-    }
-  }, [targetRef])
-
-  const refresh = useCallback(() => {
-    const el = targetRef?.current ?? targetRef
-    if (!el || !scalerRef.current) return
-    const s = scalerRef.current.refresh()
-    setScale(s)
-    setInverseScale(s > 0 ? 1 / s : 1)
-  }, [targetRef])
-
-  return { scale, inverseScale, refresh }
-}
+/**
+ * React hooks
+ *   useFitScreen(ref, options) → { scale, inverseScale, refresh }
+ *   useCompensate(ref, options) → { refresh }   // 对应 Vue v-compensate
+ */
+import { useRef, useState, useEffect, useCallback } from 'react'
+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(() => {
+    let detach = () => {}
+    let disposed = false
+
+    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)
+
+      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 () => {
+      disposed = true
+      cancelWait()
+      detach()
+    }
+  }, [targetRef])
+
+  const refresh = useCallback(() => {
+    const el = targetRef?.current ?? targetRef
+    if (!el || !scalerRef.current) return
+    const s = scalerRef.current.refresh()
+    setScale(s)
+    setInverseScale(s > 0 ? 1 / s : 1)
+  }, [targetRef])
+
+  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 }
+}