` 校正 `getBoundingClientRect()` 失真指南)
在 Remotion 中测量 DOM 节点尺寸useCurrentScale()校正getBoundingClientRect()失真指南【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotionRemotion 基于 React 以编程方式生成视频。当你在 Studio 预览中缩放画布、或在 Player 中让视频自适应容器时视频内容所在的容器会被施加一个scale()CSS 变换导致浏览器原生getBoundingClientRect()返回的尺寸与像素坐标随之缩放而失真。本文以 Remotion 官方技能文档 measuring-dom-nodes.md 为骨架结合仓库源码讲解失真成因、useCurrentScale()的精确校正方案、边界行为与配套最佳实践。读完你将能在任何 Remotion 环境下稳定测量任意 DOM 元素如文字块、图片、容器的真实逻辑尺寸供后续布局计算使用。为什么在 Remotion 中测量 DOM 会遇到问题在普通 Web 应用中测量元素尺寸的标准做法是为元素绑定 React Ref然后在生命周期中调用浏览器原生 APIgetBoundingClientRect()读取width、height等属性。但在 Remotion 中这套做法并不直接成立。Remotion 渲染视频时会把你的组合内容放进一个画布容器而这个容器上被施加了 CSS 变换。例如在 Player 端return { position: absolute, width: config.width, height: config.height, display: flex, transform: scale(${scale}), ... };在 Studio 预览端同样如此return { transform: scale(${options.scale}), willChange: transform, ... };transform: scale()会在视觉上放大或缩小容器及其全部后代而这会连带影响getBoundingClientRect()的返回值——它返回的是被变换之后的屏幕坐标系数值而不是组合在逻辑坐标系中的真实尺寸。要拿到元素的真实设计尺寸必须把测量结果除以当前的缩放系数。这里缩放系数在不同场景下含义不同但都由同一个calculateScale()函数计算得出见 packages/core/src/use-current-scale.tsPlayer 中为了把宽高比为固定值的组合完整塞进任意尺寸的播放器容器缩放系数约等于Math.min(容器宽 / 组合宽, 容器高 / 组合高)Studio 中缩放系数即用户界面上的缩放级别Zoom100% 时等于1200% 时等于2最终渲染时视频以原始分辨率输出不存在缩放系数为1。用useCurrentScale()校正测量值从 v4.0.125 起Remotion 提供了useCurrentScale()Hook见 官方 API 文档。它返回当前画布实际生效的缩放系数正好用来还原元素的真实尺寸。技能文档给出的标准校正模式如下原样继承自 measuring-dom-nodes.mdimport { useCurrentScale } from remotion; import { useRef, useEffect, useState } from react; export const MyComponent () { const ref useRefHTMLDivElement(null); const scale useCurrentScale(); const [dimensions, setDimensions] useState({ width: 0, height: 0 }); useEffect(() { if (!ref.current) return; const rect ref.current.getBoundingClientRect(); setDimensions({ width: rect.width / scale, height: rect.height / scale, }); }, [scale]); return ( div ref{ref} Content to measure /div ); };这段代码的关键设计getBoundingClientRect()返回的是屏幕像素除以scale后得到的是逻辑像素即你的组合在 1920×1080 这类坐标系下期望的数值useEffect的依赖数组包含scale——缩放级别变化比如用户在 Studio 中滚动滚轮缩放或 Player 尺寸变化时测量会自动重跑并刷新状态初始状态给0作占位布局阶段务必做ref.current空值保护。官方测量指南 measuring.mdx 提供的写法在此基础上补充说明从 v4.0.103 起首轮useEffect中不会因为组件已挂载但尚未显示而拿到全 0 的矩形可以依赖非零测量结果。钩子的返回值语义与边界行为从源码看useCurrentScale()use-current-scale.ts的返回值来自三个来源的优先级合并若处于CurrentScaleContext类型为scale中直接返回上下文中保存的缩放值Studio 会先把组合渲染进一个未缩放的离屏 portaloffscreen portal见 portal-node.tsHook 通过subscribeToPortalNodeCurrentScale订阅 portal 的当前实际缩放返回 预览真正提交给 portal 的缩放值从而保证测量精确到像素级别渲染环境serverless、headless、服务端渲染或浏览器之外的环境下则返回1。值得注意的是几个容易踩坑的边界行为1. 在 Remotion 上下文之外调用会抛错。源码中如果组件不在 Remotion 渲染上下文内且不是渲染环境会抛出如下明确错误useCurrentScale() was called outside of a Remotion context. This hook can only be called in a component that is being rendered by Remotion.2. 可通过选项让它在上下文外安静地返回 1。若你的组件可能同时被 Remotion 渲染和普通 React 应用复用可传入{ dontThrowIfOutsideOfRemotion: true }此时外部环境一律返回1——这也符合语义因为外部没有缩放测量不需要校正。import { useCurrentScale } from remotion; const MyRegularReactComponent () { const scale useCurrentScale({ dontThrowIfOutsideOfRemotion: true }); return divThe current scale is {scale}/div; };3. 各运行环境的返回值约定。依据官方文档与源码逻辑在 Node.js、Bun、服务端渲染等非浏览器环境中该 Hook 一律返回1在 Player 与 Studio 中返回实时缩放值。若 Hook 调用时发现 Remotion 各包版本不一致源码还会提示检查版本对齐。动手验证在真实场景中复现缩放失真你可以用仓库中的 Player 示例快速复现整个测量链路。给 Player 设置一个与组合宽高比不同的父容器例如把 1920×1080 的组合放进一个近似方形的div再在组合内渲染一个需要精确测量的元素。此时播放器依据calculateCanvasTransformationpackages/player/src/calculate-scale.ts算出scale并把transform: scale(scale)施加到视频容器上不加校正直接读取getBoundingClientRect().width得到的值会被缩放放大或缩小通过useCurrentScale()读取到与容器变换完全一致的系数并做除法就能在任意播放器尺寸下得到恒定的逻辑尺寸——这恰好是 Remotion Player 内建拖拽、吸附等交互组件可参考 packages/docs/docs/player/drag-and-drop/SelectionOutline.tsx 中的真实用法之所以能在缩放画布上精准定位元素的原因。在 Studio 中验证同样直观把预览缩放从 50% 切换到 100% 再到 200%配合上述代码观察dimensions——依赖scale的useEffect会随缩放变化自动重新测量状态始终保持在正确的逻辑尺寸附近。旧版本的替代方案与配套最佳实践版本早于 v4.0.110比例尺元素法若你使用的是 v4.0.110 之前的 Remotion官方曾建议渲染一个固定宽度例如10px的辅助比例尺元素通过测量它的实际宽度反推缩放系数再对目标元素做除法。相关实现可参考 measuring.mdximport { useRef, useState, useEffect } from react; const MEASURER_SIZE 10; export const MyComponent () { const ref useRefHTMLDivElement(null); const measurer useRefHTMLDivElement(null); const [dimensions, setDimensions] useState({ correctedHeight: 0, correctedWidth: 0, }); useEffect(() { if (!ref.current || !measurer.current) return; const rect ref.current.getBoundingClientRect(); const measurerRect measurer.current.getBoundingClientRect(); const scale measurerRect.width / MEASURER_SIZE; setDimensions({ correctedHeight: rect.height * scale, correctedWidth: rect.width * scale, }); }, []); return ( div div ref{ref}Hello World!/div div ref{measurer} style{{ width: MEASURER_SIZE, position: fixed, top: -99999, }} / /div ); };这种方式依赖辅助 DOM 且多一次测量正是官方随后推出useCurrentScale()的原因——新环境请优先使用 Hook 方案。文字测量等同类场景DOM 测量属于更广泛的测量主题。若你测量的对象是文本Remotion 还提供独立于 DOM 的纯计算方案remotion/layout-utilsmeasureText/fitText/fillTextBox详见 measuring-text.md且必须在字体加载完成后再测量以保证测量精度。小结与决策速查在 Remotion 中测量 DOM 元素请遵循以下判断路径确认自己是否处于 Remotion 缩放画布内Studio 预览或 Player不在其中时无需校正直接测量即可处于画布内优先用useCurrentScale()读取实时缩放系数把getBoundingClientRect()的结果除以scale把测量放进依赖scale的useEffect以响应 Studio 缩放级别或 Player 尺寸的实时变化若组件会被复用到 Remotion 之外给useCurrentScale()传{ dontThrowIfOutsideOfRemotion: true }避免抛错若项目停留于 v4.0.110 之前的历史版本退回固定宽度比例尺法反推缩放系数。原文核心要素问题成因、标准校正代码与相关源码证据use-current-scale.ts、portal-node.ts、calculate-scale.ts、Preview.tsx均已在本指南中完整覆盖并深入展开。正确理解并校正scale()变换对测量的影响是编写自适应布局与交互组件的前置条件——现在你的测量结果在任何预览模式下都能保持真实可靠。【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
在 Remotion 中测量 DOM 节点尺寸useCurrentScale()校正getBoundingClientRect()失真指南【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotionRemotion 基于 React 以编程方式生成视频。当你在 Studio 预览中缩放画布、或在 Player 中让视频自适应容器时视频内容所在的容器会被施加一个scale()CSS 变换导致浏览器原生getBoundingClientRect()返回的尺寸与像素坐标随之缩放而失真。本文以 Remotion 官方技能文档 measuring-dom-nodes.md 为骨架结合仓库源码讲解失真成因、useCurrentScale()的精确校正方案、边界行为与配套最佳实践。读完你将能在任何 Remotion 环境下稳定测量任意 DOM 元素如文字块、图片、容器的真实逻辑尺寸供后续布局计算使用。为什么在 Remotion 中测量 DOM 会遇到问题在普通 Web 应用中测量元素尺寸的标准做法是为元素绑定 React Ref然后在生命周期中调用浏览器原生 APIgetBoundingClientRect()读取width、height等属性。但在 Remotion 中这套做法并不直接成立。Remotion 渲染视频时会把你的组合内容放进一个画布容器而这个容器上被施加了 CSS 变换。例如在 Player 端return { position: absolute, width: config.width, height: config.height, display: flex, transform: scale(${scale}), ... };在 Studio 预览端同样如此return { transform: scale(${options.scale}), willChange: transform, ... };transform: scale()会在视觉上放大或缩小容器及其全部后代而这会连带影响getBoundingClientRect()的返回值——它返回的是被变换之后的屏幕坐标系数值而不是组合在逻辑坐标系中的真实尺寸。要拿到元素的真实设计尺寸必须把测量结果除以当前的缩放系数。这里缩放系数在不同场景下含义不同但都由同一个calculateScale()函数计算得出见 packages/core/src/use-current-scale.tsPlayer 中为了把宽高比为固定值的组合完整塞进任意尺寸的播放器容器缩放系数约等于Math.min(容器宽 / 组合宽, 容器高 / 组合高)Studio 中缩放系数即用户界面上的缩放级别Zoom100% 时等于1200% 时等于2最终渲染时视频以原始分辨率输出不存在缩放系数为1。用useCurrentScale()校正测量值从 v4.0.125 起Remotion 提供了useCurrentScale()Hook见 官方 API 文档。它返回当前画布实际生效的缩放系数正好用来还原元素的真实尺寸。技能文档给出的标准校正模式如下原样继承自 measuring-dom-nodes.mdimport { useCurrentScale } from remotion; import { useRef, useEffect, useState } from react; export const MyComponent () { const ref useRefHTMLDivElement(null); const scale useCurrentScale(); const [dimensions, setDimensions] useState({ width: 0, height: 0 }); useEffect(() { if (!ref.current) return; const rect ref.current.getBoundingClientRect(); setDimensions({ width: rect.width / scale, height: rect.height / scale, }); }, [scale]); return ( div ref{ref} Content to measure /div ); };这段代码的关键设计getBoundingClientRect()返回的是屏幕像素除以scale后得到的是逻辑像素即你的组合在 1920×1080 这类坐标系下期望的数值useEffect的依赖数组包含scale——缩放级别变化比如用户在 Studio 中滚动滚轮缩放或 Player 尺寸变化时测量会自动重跑并刷新状态初始状态给0作占位布局阶段务必做ref.current空值保护。官方测量指南 measuring.mdx 提供的写法在此基础上补充说明从 v4.0.103 起首轮useEffect中不会因为组件已挂载但尚未显示而拿到全 0 的矩形可以依赖非零测量结果。钩子的返回值语义与边界行为从源码看useCurrentScale()use-current-scale.ts的返回值来自三个来源的优先级合并若处于CurrentScaleContext类型为scale中直接返回上下文中保存的缩放值Studio 会先把组合渲染进一个未缩放的离屏 portaloffscreen portal见 portal-node.tsHook 通过subscribeToPortalNodeCurrentScale订阅 portal 的当前实际缩放返回 预览真正提交给 portal 的缩放值从而保证测量精确到像素级别渲染环境serverless、headless、服务端渲染或浏览器之外的环境下则返回1。值得注意的是几个容易踩坑的边界行为1. 在 Remotion 上下文之外调用会抛错。源码中如果组件不在 Remotion 渲染上下文内且不是渲染环境会抛出如下明确错误useCurrentScale() was called outside of a Remotion context. This hook can only be called in a component that is being rendered by Remotion.2. 可通过选项让它在上下文外安静地返回 1。若你的组件可能同时被 Remotion 渲染和普通 React 应用复用可传入{ dontThrowIfOutsideOfRemotion: true }此时外部环境一律返回1——这也符合语义因为外部没有缩放测量不需要校正。import { useCurrentScale } from remotion; const MyRegularReactComponent () { const scale useCurrentScale({ dontThrowIfOutsideOfRemotion: true }); return divThe current scale is {scale}/div; };3. 各运行环境的返回值约定。依据官方文档与源码逻辑在 Node.js、Bun、服务端渲染等非浏览器环境中该 Hook 一律返回1在 Player 与 Studio 中返回实时缩放值。若 Hook 调用时发现 Remotion 各包版本不一致源码还会提示检查版本对齐。动手验证在真实场景中复现缩放失真你可以用仓库中的 Player 示例快速复现整个测量链路。给 Player 设置一个与组合宽高比不同的父容器例如把 1920×1080 的组合放进一个近似方形的div再在组合内渲染一个需要精确测量的元素。此时播放器依据calculateCanvasTransformationpackages/player/src/calculate-scale.ts算出scale并把transform: scale(scale)施加到视频容器上不加校正直接读取getBoundingClientRect().width得到的值会被缩放放大或缩小通过useCurrentScale()读取到与容器变换完全一致的系数并做除法就能在任意播放器尺寸下得到恒定的逻辑尺寸——这恰好是 Remotion Player 内建拖拽、吸附等交互组件可参考 packages/docs/docs/player/drag-and-drop/SelectionOutline.tsx 中的真实用法之所以能在缩放画布上精准定位元素的原因。在 Studio 中验证同样直观把预览缩放从 50% 切换到 100% 再到 200%配合上述代码观察dimensions——依赖scale的useEffect会随缩放变化自动重新测量状态始终保持在正确的逻辑尺寸附近。旧版本的替代方案与配套最佳实践版本早于 v4.0.110比例尺元素法若你使用的是 v4.0.110 之前的 Remotion官方曾建议渲染一个固定宽度例如10px的辅助比例尺元素通过测量它的实际宽度反推缩放系数再对目标元素做除法。相关实现可参考 measuring.mdximport { useRef, useState, useEffect } from react; const MEASURER_SIZE 10; export const MyComponent () { const ref useRefHTMLDivElement(null); const measurer useRefHTMLDivElement(null); const [dimensions, setDimensions] useState({ correctedHeight: 0, correctedWidth: 0, }); useEffect(() { if (!ref.current || !measurer.current) return; const rect ref.current.getBoundingClientRect(); const measurerRect measurer.current.getBoundingClientRect(); const scale measurerRect.width / MEASURER_SIZE; setDimensions({ correctedHeight: rect.height * scale, correctedWidth: rect.width * scale, }); }, []); return ( div div ref{ref}Hello World!/div div ref{measurer} style{{ width: MEASURER_SIZE, position: fixed, top: -99999, }} / /div ); };这种方式依赖辅助 DOM 且多一次测量正是官方随后推出useCurrentScale()的原因——新环境请优先使用 Hook 方案。文字测量等同类场景DOM 测量属于更广泛的测量主题。若你测量的对象是文本Remotion 还提供独立于 DOM 的纯计算方案remotion/layout-utilsmeasureText/fitText/fillTextBox详见 measuring-text.md且必须在字体加载完成后再测量以保证测量精度。小结与决策速查在 Remotion 中测量 DOM 元素请遵循以下判断路径确认自己是否处于 Remotion 缩放画布内Studio 预览或 Player不在其中时无需校正直接测量即可处于画布内优先用useCurrentScale()读取实时缩放系数把getBoundingClientRect()的结果除以scale把测量放进依赖scale的useEffect以响应 Studio 缩放级别或 Player 尺寸的实时变化若组件会被复用到 Remotion 之外给useCurrentScale()传{ dontThrowIfOutsideOfRemotion: true }避免抛错若项目停留于 v4.0.110 之前的历史版本退回固定宽度比例尺法反推缩放系数。原文核心要素问题成因、标准校正代码与相关源码证据use-current-scale.ts、portal-node.ts、calculate-scale.ts、Preview.tsx均已在本指南中完整覆盖并深入展开。正确理解并校正scale()变换对测量的影响是编写自适应布局与交互组件的前置条件——现在你的测量结果在任何预览模式下都能保持真实可靠。【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
