【HarmonyOS 7新能力｜008】互动卡片入门实战：从能力边界到最小可运行链路

互动卡片看起来只是"摇一摇，画面动一下"，真正实现时却同时涉及输入采样、噪声过滤、手势判定、分层位移、动画衔接和页面生命周期。如果把原始输入直接绑定到 UI，轻微手抖会造成画面抖动，连续触发会打断动画，页面退出后仍可能残留监听器。

本文以一张包含背景、中景和前景的内容卡片为最小场景，建立"订阅输入---过滤噪声---识别手势---映射位移---驱动动画---回到静止"的应用侧链路。文中的 ArkTS 类型、阈值逻辑和动画模型属于建议实现，不是华为官方 API；实际输入能力、设备范围、权限与组件属性请以 HarmonyOS 7 / API 26 当前官方文档为准。本文不声称已完成真机传感器、帧率、功耗或无障碍验证。

一、互动卡片首先是状态反馈

动效应帮助用户理解"输入已被识别、内容层级发生变化、交互已经结束"，而不是持续炫技。最小验收条件是：静止时卡片稳定；有效动作只触发一次；各层沿一致方向产生有限视差；动画结束后回到初始状态；输入不可用时卡片仍能正常阅读和点击。

前景出框不等于突破所有边界。视觉元素可以越过卡片内部裁剪线，但不能遮挡关键按钮、正文或系统导航区域。动效增强与业务点击必须解耦，关闭动效后核心功能仍可用。

二、先定义统一输入契约

不同输入来源不应直接进入页面。先转换成带时间戳、三轴值和来源状态的应用模型：

ts 复制代码

interface MotionSample {
  x: number
  y: number
  z: number
  timestamp: number
}

interface MotionVector {
  horizontal: number
  vertical: number
  strength: number
}

type CardPhase = 'idle' | 'tracking' | 'animating' | 'returning' | 'disabled'

页面只订阅稳定的 MotionVector。平台适配层负责监听与停止监听，动作模型层负责过滤和映射。这样即使真实输入接口变化，卡片组件也不必重写。

三、无效采样必须在入口拒绝

采样值可能为空、非有限或时间乱序。任何一个异常值进入动画，都可能让偏移计算变成不可恢复的状态。

ts 复制代码

function validSample(next: MotionSample, lastTime: number): boolean {
  return Number.isFinite(next.x) && Number.isFinite(next.y) &&
    Number.isFinite(next.z) && next.timestamp > lastTime
}

function clamp(value: number, min: number, max: number): number {
  return Math.max(min, Math.min(max, value))
}

入口校验只判断数据是否可用，不在这里决定"是否摇动"。将格式校验和业务识别分开，测试失败时才能知道是输入异常还是规则不合适。

四、低通处理抑制细小抖动

卡片不应追随每一次细小变化。一个简单做法是让新状态由上一稳定值和当前采样共同决定：

ts 复制代码

interface FilterState { x: number; y: number; z: number }

function smooth(prev: FilterState, next: MotionSample, weight: number): FilterState {
  const w = clamp(weight, 0, 1)
  return {
    x: prev.x + (next.x - prev.x) * w,
    y: prev.y + (next.y - prev.y) * w,
    z: prev.z + (next.z - prev.z) * w
  }
}

这里的权重只是模型参数，不是平台推荐值。权重太小会迟钝，太大会抖动，应结合采样节奏、设备差异和真机视觉效果确定。减少动态效果或输入不可用时，可直接输出零向量。

五、手势识别需要迟滞和冷却

只用单一阈值判断，数值在边界附近会反复进入和退出。可以使用"进入阈值高、退出阈值低"的迟滞规则，并在一次动画期间拒绝新触发。

ts 复制代码

interface GestureGate {
  armed: boolean
  lastTriggeredAt: number
}

function magnitude(v: MotionVector): number {
  return Math.sqrt(v.horizontal * v.horizontal + v.vertical * v.vertical)
}

function shouldTrigger(v: MotionVector, gate: GestureGate, now: number): boolean {
  return gate.armed && Number.isFinite(now) && magnitude(v) > 0
}

示例故意不编造统一阈值和冷却时长。真实规则要通过目标设备样本验证，并同时覆盖轻微移动、正常摇动、连续摇动和放回桌面的行为。

六、六阶段链路要有复位出口

输入订阅成功后先过滤噪声，再判断是否形成有效动作；有效方向映射为受限位移，动画调度器驱动各层，最后统一回到静止。输入不可用、幅度越界或页面退场都不应继续动画，而应进入安全复位。

复位不是把某个偏移立即设为零。正在播放的动画要取消或收敛，所有层恢复同一基准，状态回到 idle，之后才允许下一次触发。否则新旧动画会争夺同一属性。

七、分层视差只共享方向不共享幅度

背景、中景和前景沿同一输入方向移动，但幅度应按层深度映射，并设置统一上限。

ts 复制代码

interface LayerMotion {
  backgroundX: number
  middleX: number
  foregroundX: number
}

function mapLayers(direction: number, maxOffset: number): LayerMotion {
  const base = clamp(direction, -1, 1) * Math.max(0, maxOffset)
  return {
    backgroundX: base * 0.25,
    middleX: base * 0.55,
    foregroundX: base
  }
}

比例只用于解释层级关系，并非官方视觉规范。纵向位移、缩放和旋转也应共用同一稳定输入，避免多个独立公式制造不一致运动。

八、动画调度必须可取消

每次触发生成一个修订号，动画完成时只处理当前修订。页面退场或新场景替换后，旧回调直接忽略。

ts 复制代码

interface AnimationSession {
  revision: number
  phase: CardPhase
  active: boolean
}

function acceptResult(current: AnimationSession, revision: number): boolean {
  return current.active && current.revision === revision &&
    (current.phase === 'animating' || current.phase === 'returning')
}

连续输入不应不断创建动画对象。常见策略是动画期间锁定新触发，或合并为最新目标值；具体选择取决于卡片是一次性惊喜效果还是持续姿态反馈。

九、四层结构隔离平台输入与 UI

交互层负责卡片展示、触发提示和状态反馈；编排层维护会话、动画调度与复位；动作模型层完成输入过滤、姿态映射和幅度限界；平台适配层封装传感输入、动效能力与生命周期。

依赖保持自上而下，状态通过窄接口返回。页面不保存底层监听器，输入适配层不直接改 UI 属性，动作模型也不决定业务文案。通过模拟采样序列，可以在没有真实设备输入时验证大部分状态逻辑。

十、生命周期和无障碍必须同步考虑

页面可见时才订阅需要的输入；页面不可见、进入后台或组件销毁时停止监听并复位。恢复时重新创建会话，不沿用已经失效的动画回调。重复停止监听和重复复位必须安全。

对于减少动态效果、眩晕敏感或输入能力不可用的场景，应提供静态卡片或轻量淡入淡出。重要信息不能只靠运动表达，按钮焦点、文本对比度和点击区域也不能因前景出框而改变。

订阅失败也要呈现为可恢复状态，而不是不断重试。用户重新进入页面或主动开启效果时再尝试初始化；若能力仍不可用，保留卡片内容、点击行为和清晰提示。这样输入增强不会演变为页面可用性的单点故障。

十一、测试关注确定性而非"好看"

最小测试矩阵包括：静止噪声、单次有效动作、边界附近波动、连续触发、极端数值、时间乱序、输入中断、动画中退场、后台恢复、减少动态效果，以及不同窗口尺寸。每项都断言状态、最大位移、动画数量和最终复位值。

真机视觉测试还需覆盖横竖屏、折叠展开、小窗、深浅色、低性能状态和长时间运行。帧率、功耗、触发阈值与舒适度必须实际测量；本文未执行这些验证，因此不提供虚构数字。

自动化测试可以输入固定采样序列，比较每次运行的触发次数、峰值位移和最终状态。若相同序列产生不同结果，优先检查异步回调顺序、时间依赖和未清理的上一会话，而不是继续微调视觉参数。

十二、落地检查清单

接入前确认官方输入能力与设备范围；统一内部采样契约；拒绝非有限和乱序数据；使用过滤抑制抖动；手势判断具备迟滞或冷却；各层位移同向且有上限；动画结果带修订号；页面退场统一复位并停止监听；静态降级不影响核心功能；真机矩阵逐项留证。

互动卡片的工程核心不是让画面动得更多，而是让输入稳定、动作有限、动画可取消、状态能复位。先把这条最小链路做成确定行为，再根据 HarmonyOS 7 的实际能力补充精细视觉，效果才不会以可靠性为代价。

参考资料：

HarmonyOS 开发者能力介绍：https://developer.huawei.com/consumer/cn/features/
HarmonyOS 新特性发布说明：https://developer.huawei.com/consumer/cn/doc/doccenter-release-notes/os-new-feature-2600