ArkTS transform实战指南：从CSS迁移到3D透视动效

最近在 HarmonyOS 6 上做应用，我把一批原先靠硬改布局数值来实现的动效，全部换成了 ArkTS transform 来做，代码结构干净了很多，效果也直观多了。经常会看到有人在问 ArkTS transform 怎么用，尤其是类似“css 中 rotateY(60deg) translateZ(300px) 出来是什么效果”这一类问题，说明大家对“变换”能产生什么样子的视觉结果，心里并没有太明确的画面感。

这篇博客不打算写成一个 API 文档，而是把我实际使用 transform 的过程、参数含义、踩坑经验都拿出来聊。它解决的是 ArkUI 里组件旋转、缩放、平移、倾斜以及 3D 透视这些几何变化的问题，适合从 CSS、Flutter 转到鸿蒙开发的同学，也适合正在写鸿蒙应用但拿捏不准 transform 细节的开发者。

1. 认识 ArkTS 里 transform：它跟 CSS 的 transform 有什么区别

做过 Web 开发的人对 CSS transform 应该很熟，写起来就是一行样式字符串，例如translateY(20px) rotate(45deg)。在 ArkTS 里，transform 对应的是一种对象形式的配置，传给.transform()这个通用属性方法。写法不一样，但解决的视觉问题基本是同一类：在不打乱布局的前提下，让组件在画布上发生几何变换。

ArkTS 的 transform 设计风格比较“显式”。举个例子，CSS 里写旋转要带单位rotate(45deg)，ArkTS 则直接给一个角度数值，再把旋转轴通过 x、y、z 三个分量指定清楚。这种设计一开始可能会让人觉得啰嗦，但真正做 3D 变换的时候就会体会到它的好处——CSS 里虽然也支持 rotateY、rotateX 这种函数，但如果你要轴角度组合组合，ArkTS 这边反而更直观。

transform 之所以值得单独写一篇，是因为它和 ArkUI 的状态驱动模型绑定得很深。你在@State数据里改变角度、位移值，页面会跟着刷新，如果再叠加上动画，就是很自然的一组动效。相比起用margin或position去挪组件位置，transform 不参与布局计算，性能优势非常明显。

1.1 transform 对象里的每个参数干什么用

我直接贴一段我在项目里经常用的写法：

.transform({ rotate: { x: 0, y: 0, z: 1, angle: 45 }, translate: { x: 100, y: 50 }, scale: { x: 1.2, y: 1.2 }, skew: { xAngle: 0, yAngle: 15 }, centerX: '50%', centerY: '50%' })

这是同时设置多个变换参数的样子。逐个拆开看：

• rotate：旋转。x、y、z 表示旋转轴，angle是角度。{ x: 0, y: 0, z: 1, angle: 45 }的意思是绕 z 轴旋转 45 度，z 轴就是正对着屏幕往外的那条轴，视觉上就是平面旋转。
• translate：平移。x、y 对应横向和纵向位移，还可以设置 z。x、y 接受数值或者百分比，z 需要先配合透视才看得出来。
• scale：缩放。x 是水平缩放比例，y 是垂直缩放比例，1 就是原始大小，0.5 缩小一半，2 放大一倍。
• skew：倾斜。xAngle 让组件沿 x 轴方向倾斜，yAngle 沿 y 轴方向倾斜。这个做标签、徽章、平行四边形按钮很常用。
• centerX、centerY：变换中心点。默认是组件的几何中心，也就是 50% 50%。如果想让某个元素绕着左上角转，就把 centerX 和 centerY 都设成 0%。

注意：centerX 和 centerY 控制的是整个变换的基准点，而不是单个 rotate 或者 scale 的锚点。实际使用中，我习惯把它放在所有变换参数之后，逻辑更清楚。

1.2 CSS transform 到 ArkTS transform 的快速对照

直接看对照表，理解起来会很快：

当然，具体到不同 HarmonyOS 版本，接口名称和类型定义可能有细微差别，以你项目对应的 SDK 文档为准。但大方向是对的，ArkTS transform 基本覆盖了 CSS transform 里你会用到的绝大多数场景。

1.3 为什么我不用改布局去代替 transform

有朋友会问：我要把某个按钮往下移 20 像素，直接改 margin 不就行了？何必用 transform？

我在实际项目里摸爬滚打后的答案是：大部分普通静态界面，改 margin、padding 确实没问题。但一旦涉及“动态、频繁、可交互”的视觉变化，直接改布局参数就是给自己挖坑。

第一个原因是性能。改布局属性会触发组件重新测量和布局，严重点会波及父容器和兄弟组件。而 transform 是在绘制层完成的几何变换，不会引起重新布局，帧率表现完全不一样。我做过一个列表项的滑动删除效果，起初用 offset 和 margin 来做，低端机型上明显顿挫，后来全部改成 translate，画面丝滑了非常多。

第二个原因是状态管理。ArkUI 的页面刷新逻辑和@State绑定很紧密，transform 的值可以直接由变量驱动，和动画系统配合非常自然。如果我去改 margin，那动画过程中每帧都得改一个布局属性，调试起来看到的是布局系统频繁“重排”，很难受。

第三个原因是 3D。布局系统根本做不了绕 Y 轴翻转这种透视效果，这不是“改改坐标”能实现的事，必须走 transform 体系，配合了 perspective 才有立体感。后面我会专门用一节来说 3D 效果。

2. 基础变换实操：rotate / scale / translate / skew 一个都不能漏

很多教程会把每个属性单独贴一段 API，看起来像词典，看完了还是不知道用在哪。我这节换个思路，每个变换都给一个实际场景，顺便把我观察到的“屏幕上到底会变成什么样子”说出来。

2.1 rotate：让按钮或卡片带出旋转角度

要做一个点击按钮就转 45 度的效果，代码可以这么写：

@State angle: number = 0; Button('点我旋转') .width(120) .height(48) .transform({ rotate: { x: 0, y: 0, z: 1, angle: this.angle }, centerX: '50%', centerY: '50%' }) .onClick(() => { this.angle = this.angle === 0 ? 45 : 0; })

这个按钮会从中心点开始顺时针旋转 45 度，再点一下转回 0 度。可能有人觉得这里写centerX: '50%', centerY: '50%'是多余的，因为默认就是中心。其实对新手来说，把中心点显式写出来是有好处的，能帮助你建立“旋转是绕谁转”的空间意识。

如果你把 centerX 改成 0，就变成了绕左边缘转动，整体视觉效果像一扇门被推开；把 centerY 改成 0，则像翻盖手机翻开盖子。这个区别在写侧滑菜单、折叠面板、翻页效果时特别重要。

实操心得：我做一个抽奖转盘时，把 centerX 和 centerY 设成圆心，再把每个奖品项绕中心点做 rotate 排列。这个需求如果不用 transform，光靠计算每个子项的位置，那代码量直接起飞，而且屏幕旋转一变全乱套。

2.2 scale：缩放时别把中心点给忘了

缩放最经典的使用场景是按压反馈。手指按下按钮，按钮微微缩小，松手恢复。我通常配合状态变量来做：

@State isPressed: boolean = false; Button('确认支付') .width(200) .height(56) .scale({ x: this.isPressed ? 0.94 : 1, y: this.isPressed ? 0.94 : 1 }) .gesture( GestureGroup(GestureMode.Exclusive, TapGesture().onAction(() => { this.isPressed = true; setTimeout(() => { this.isPressed = false; }, 80); })) )

这里我没写 centerX、centerY，默认就是从中心缩放，视觉上很自然。假如想做一个“图片从左上角放大展开”的效果，必须把中心点设成左上：

.scale({ x: this.isPressed ? 1.5 : 1, y: this.isPressed ? 1.5 : 1, centerX: '0%', centerY: '0%' })

我早期犯过一个错，以为缩放比例成比例就完事了，结果放大之后的图片位置偏了，看起来像被“甩”出去了。后来才意识到，缩放中心点决定了一个元素放大之后会往哪个方向“扩展”。这点非常重要。

scale 还有一个隐藏用途：配合透明度做“元素由小变大出现”的效果。新进页面的弹窗、通知条都很适合，比单纯的 opacity 动画要更有层次感。

2.3 translate：位移里除了 x/y 还有 z

translate 可能是上手最容易的，毕竟就是移动位置。但这里有个概念需要提前说清楚——z 轴的位移如果没有透视配合，在屏幕上就是看不见的。

先看二维位移：

.translate({ x: 80, y: -40 })

这就是把组件向右移动 80vp、向上移动 40vp。注意，这里的数值指的是视觉位移，不是重新摆放后的布局位置，组件原来的位子不会占着空档。也就是说，transform 里的 translate 不会把兄弟组件挤开。

这点用来做“提示条从上方滑入”这种动态效果特别合适。以前我习惯修改 margin-top 来腾位置，整个布局都会被干扰；改成 translate 之后，就只有这个组件自己在动，其余元素纹丝不动。

z 轴平移为什么值得提？因为它经常是 3D 效果中“纵向深度”变化的关键。只有设置 perspective 之后，z 的移动才会呈现出近大远小的透视变化。如果没有透视，组件在 z 方向移动对你来说是不可见的，所以看到“translateZ 没效果”时，第一反应就该是去查有没有设置 perspective。

2.4 skew：被很多人忽略了倾斜效果

skew 在基础变换里存在感最低，因为它不像旋转、缩放那么常用，但真到用的时候特别好使。比如做一个“斜角标签”，如果用图片素材或者重新画 shape，工作量不小；用 skew 一行就能搞定：

Text('HOT') .fontColor('#fff') .fontSize(14) .backgroundColor('#FF3B30') .padding({ left: 20, right: 20, top: 6, bottom: 6 }) .transform({ skew: { xAngle: -12, yAngle: 0 } })

xAngle 为负时，组件上部会向右倾斜，下部向左倾斜，看起来就是平行四边形。这个用在商品角标、促销标签、按钮上，会比普通矩形更有设计感。

不过要提醒一句：skew 会同时影响内部文字，如果文字也跟着形状歪掉，通常不是你想要的效果。我在做这类标签的时候，会在外层容器上做 skew，在内层用反向 skew 抵消，保证文字是正的。这个方法在做 Web 时也是通用的，放到 ArkTS 里一样有效。

3. 3D 变换拆解：rotateY(60deg) translateZ(300px) 到底长什么样

因为很多人问 CSS 里那句transform: rotateY(60deg) translateZ(300px)到底出来是什么样子，这里单独拿出来拆一下，顺便讲清楚 ArkTS 怎么实现同款效果。

3.1 先拆 CSS 那行 transform 的计算逻辑

先建立坐标系。屏幕内，x 轴从左到右，y 轴从上到下，z 轴是垂直屏幕指向你。组件默认摆在一个和屏幕平行的平面上。

rotateY(60deg)的意思就是让组件绕着 y 轴旋转 60 度。y 轴是一条竖直轴，所以旋转之后，原本正对你的组件会变成侧着的样子——水平方向会明显变窄，像一扇正在合上的门。此时组件的左边或右边会朝你靠近，另一边会远离。

紧接着translateZ(300px)，是把组件沿着 z 轴方向移动 300 像素。不过要注意，此时组件已经不是正对着你了，它自有坐标系的 z 轴也被旋转过了。所以这个“往前推”不是简单地从屏幕往外挪，而是沿着它旋转后的朝向移动。

如果在父容器上设置了 perspective（比如 800px），视觉效果就很明显：组件旋转后水平宽度被压缩，同时又朝你面前推进，会产生“一张立体卡片斜着朝你飞过来”的感觉。没有 perspective 时，效果更像是水平方向被压缩或者拉伸，缺少深度感。

我再用生活例子类比一下：想象手里拿着一张扑克牌，先沿垂直方向转 60 度，让牌面斜对着你，然后把整张牌朝你眼睛方向推近 300 像素。你最终看到的，就是一张斜着、变窄、但离你更近的牌。

3.2 在 ArkTS 中实现同款 3D 效果

ArkTS 中要复刻这个效果，代码长这样：

Column() .width(200) .height(120) .backgroundColor('#FF5C7A') .borderRadius(12) .perspective(800) .transform({ rotate: { x: 0, y: 1, z: 0, angle: 60 }, translate: { x: 0, y: 0, z: 300 } })

rotate里的 x、y、z 是轴向量。{ x: 0, y: 1, z: 0, angle: 60 }表示绕 y 轴旋转，等价于 CSS 里的rotateY(60deg)。translate里指定 z 为 300，就对应了 CSS 的translateZ(300px)。

这里的关键点是.perspective(800)不能漏。perspective 的值可以理解成“观察者离屏幕的距离”，数值越小，透视感越强；数值越大，透视感越弱，越来越接近正交投影。我常用 800 到 1000 之间，既能看出明显深度，又不会让变形太夸张。

实操心得：给单个组件直接设 perspective，通常只作用于它自身的变换。但 3D 卡片翻转这类效果里，我更喜欢把 perspective 放在父容器上，让所有子组件的 3D 变换共用同一个视场，这样多个卡片同时做旋转时，透视透视关系才一致，看起来更真实。

3.3 用 transform 做 3D 卡片翻转

卡片翻转是 transform 3D 能力最典型的应用，我很建议动手写一遍。思路是：放一个 Stack，里面叠两张卡片，一张正面，一张背面。通过一个布尔变量控制两张卡分别旋转到哪个角度。

@State flipped: boolean = false; build() { Stack({ alignContent: Alignment.Center }) { Text('正面内容') .width(200) .height(120) .backgroundColor('#FF5C7A') .borderRadius(12) .rotate({ x: 0, y: 1, z: 0, angle: this.flipped ? 180 : 0 }) Text('背面内容') .width(200) .height(120) .backgroundColor('#3A86FF') .borderRadius(12) .rotate({ x: 0, y: 1, z: 0, angle: this.flipped ? 0 : 180 }) } .perspective(900) .onClick(() => { animateTo({ duration: 400, curve: Curve.EaseInOut }, () => { this.flipped = !this.flipped; }); }) }

初始状态下，背面卡片的 Y 轴旋转是 180 度，正好背对着用户，所以看不见；点击后，背面转回 0 度，正面转到 180 度，背面就被翻了出来。加上 perspective 后，这个翻转过程会有明显的厚度感和立体感，而不是简单地在二维平面上缩放。

第一次跑这个示例时，我有同事问为什么没看到背面内容“提前露出来”。原因是中间状态虽然两张卡都介于半转状态，但卡片没有厚度，所以只能看到当前面向自己的那张卡的渐变缩小。如果希望有厚度感，可以给卡片中间再加一个“厚度层”或者把背景换成接近的颜色，看起来会更像一张立体卡牌。

4. 配合动画才算完整：animateTo 和状态驱动的 transform

单纯静态地设置 transform 很容易，但要实现“动起来”才是大多数业务场景的刚需。HarmonyOS 里最常见的方式是animateTo包裹状态变化，让页面在状态更新时产生平滑动画。

4.1 为什么状态驱动天然适合 transform

ArkUI 的状态驱动模型，意思是你不需要手动“每帧去改坐标”，只需要在animateTo里改变状态值，系统会自动插值计算中间过程。transform 的值正好是数值、角度、比例这一类可以插值的量，所以和动画是天然搭档。

举个例子，一个实现点赞的爱心从无到弹出的效果，我可以让它的 scale 从 0 到 1，同时 opacity 从 0 到 1。如果不用 transform，我需要写一堆组件重建逻辑；用了 transform，只要改两个变量就行。

另一点是 transform 的动画过程不会打断布局。列表项上滑删除、弹窗展开、按钮按压，这些效果在动画过程中，其他 UI 元素不会因为某个组件变换而被迫让位。这种“低侵犯”特性，让 transform 在复杂布局中特别安全。

4.2 一个完整入场动效示例

还是不放概念，直接放代码。比如页面上有一个面板，要从下方滑入并轻微放大：

@State entered: boolean = false; aboutToAppear() { setTimeout(() => { animateTo({ duration: 420, curve: Curve.EaseOutBack }, () => { this.entered = true; }); }, 30); } build() { Column() .width(300) .height(160) .borderRadius(16) .backgroundColor('#FFFFFF') .translate({ y: this.entered ? 0 : 80 }) .scale({ x: this.entered ? 1 : 0.85, y: this.entered ? 1 : 0.85 }) .opacity(this.entered ? 1 : 0) }

刚进页面时，这个面板在下方 80vp、缩小到 85%、完全透明；animateTo触发后，它滑上来、放大、显示出来。curve 选择EaseOutBack会有一种轻微回弹的视觉效果，比线性运动更容易让人觉得“有质感”。

我对这套组合的体会是：opacity 负责“出现感”，translate 负责“方向感”，scale 负责“大小感”，三者叠加起来，比单纯一个 transform 参数丰富得多。你可以把这套模板直接用到悬浮按钮、广告弹层、通知条的入场动效上。

4.3 动效编排时的三个注意点

第一，把状态变化放在animateTo回调里，而不是在回调外先改状态再调用。这个顺序很关键。很多人写完动画发现没效果，多半就是因为状态变化没有落在 animateTo 的闭包内。

第二，多个 transform 参数同时变化，要保证它们的初始值和目标值类型一致。例如 scale 用数值，translate 也用数值，动画系统才能正确插值。如果你一会传'50%'一会传100，就可能出现跳变或者干脆不执行动画。

第三，不要在动画过程中频繁改变父容器尺寸。如果动态内容高度引起父容器 reflow，transform 组件的视觉位置就会叠加出错，甚至出现闪动。我的经验是，动画涉及到的容器最好提前给一个合理高度，给内部 transform 一个稳定环境。

5. 实测最容易踩的 6 个坑，附排查思路

这部分来自我自己的 debug 记录，希望能帮你看完少走弯路。

5.1 常见问题速查表

5.2 几个值得细说的排查实录

第一个典型的坑是角度回绕。做转盘或者旋转图标时，如果当前角度是 350 度，目标角度是 10 度，动画系统如果直接插值，会从 350 度倒退一大圈到 10 度。视觉上就是“反方向转了一圈”。解决方式是把目标角度改成 370 度，这样差值只有 20 度，动画就沿着正向最短路径走。

第二个坑是 transform 和原有布局属性叠加。假如一个组件既设置了marginTop，又设置了translate，视觉位置会叠加成“布局挤出来的一份 + 变换移出来的一份”。调试时经常看到组件偏偏往一个方向偏，排查时很容易漏掉 margin 的影响。我的习惯是，动效相关的位移，全部走 transform；静态排版，才用布局属性。

第三个坑是 scale 和 rotate 同时作用的时候，中心点不统一。比如先旋转 45 度、再放大 1.5 倍，中心点是同一个，但如果你代码里把它们分散在两行，后面不小心改了一行的中心点，另一行没改，就会出现“旋转从中心转，放大从左上角放大”的诡异画面。写 transform 时建议把 rotate、scale、translate、skew 都放在同一个 transform 对象里，中心点只维护一份。

第四个和性能相关的是，transform 虽然不触发布局，但如果 transform 作用的那个组件特别大（比如全屏背景图），每一帧重绘的代价还是不低。我在列表项里给一个大缩略图做入场动效时，会先用小尺寸图配合 transform，入场结束再切换为正常尺寸图，避免开始几帧出现掉帧。

6. 我对 transform 的一点使用心得

写到这，想给一个我的个人经验：在 ArkTS 里，凡是涉及“视觉上移动、旋转、缩放”的动态效果，我优先想的是能不能用 transform 解决，而不是去改布局数值。一旦把这个习惯建立起来，写动效的效率和效果上限都会明显提高。

具体到这个项目，我的做法是准备几个常用的 transform 模板：

按压反馈模板，scale 从 1 到 0.94，配合 80 毫秒左右的收回；入场模板，translate 和 opacity 联动；3D 翻转模板，单独封装成组件，参数只留翻转状态和时间。这样业务线里重复使用的时候，改动成本非常低，也不容易因为某个页面漏配 perspective 导致效果不一致。

如果你刚开始接触 ArkTS transform，建议不要只看文档，直接把文章里第 2 节、第 3 节的示例代码搬到工程里跑一遍。先把每个参数单独改一改，观察屏幕上画面的变化，再去组合。视觉变换这种东西，建立直觉比背 API 要重要得多。等你能不看文档就知道 rotate 一个角度大概长什么样时，ArkTS transform 就算真正上手了。