【HarmonyOS 7新能力｜033】互动卡片工程封装：把接入逻辑放进可维护的分层结构

贾伟康

331人浏览 · 2026-09-17 00:42:40

贾伟康 · 2026-09-17 00:42:40 发布

【HarmonyOS 7新能力｜033】互动卡片工程封装：把接入逻辑放进可维护的分层结构

互动卡片工程封装

摇一摇触发动画、前景主体突破卡片边界，可以让内容更有层次。但如果把传感器事件直接绑定动画，轻微走动可能反复触发；列表滚出屏幕后还在监听；前景出框区域遮挡其他控件；低性能设备上粒子效果持续掉帧。

本文把互动卡片拆成页面编排、交互会话、传感处理、视觉模型、渲染合成和治理六层。示例类型、滤波方式和阈值均为应用侧教学封装，不代表 HarmonyOS 7 官方 API 或硬件标准；传感器能力、权限、组件裁剪与动效接口应以当前 SDK 和华为官方文档为准。

一、先定义卡片的互动边界

动效应帮助用户理解内容，而不是无条件抢占注意力。第一版只允许当前可见、处于前台且用户已启用动态效果的卡片响应摇动；一次触发完成前不接受新触发。

验收目标包括：环境轻微晃动不触发；一次摇动只触发一次；页面离开停止监听；前景出框不改变点击区域；减少动态效果模式使用静态替代；资源不足时平滑降级。

二、按可见性管理传感器订阅

页面存在不等于卡片可见。只有进入有效可见区并获得前台状态后才订阅，离开后立即取消。

interface CardVisibility {
  cardId: string
  visibleRatio: number
  pageActive: boolean
  windowFocused: boolean
}

function shouldListen(v: CardVisibility): boolean {
  return v.pageActive && v.windowFocused && v.visibleRatio >= 0.6
}

比例阈值是产品策略，需要通过滚动场景验证；不能让列表中所有卡片同时持有监听。

三、统一传感器输入模型

业务层不直接处理平台回调对象，只接收时间戳和三个轴的加速度样本。

interface AccelerationSample {
  x: number
  y: number
  z: number
  occurredAt: number
}

interface MotionMagnitude {
  raw: number
  linear: number
}

样本必须是有限数值，时间戳应单调。采样中断后重新初始化滤波状态，避免旧数据参与新一轮判断。

四、滤除重力和短时噪声

只比较加速度模长容易把设备姿态变化当成摇动。应用侧可通过低通估计重力分量，再计算线性加速度，并对短尖峰做时间窗口过滤。

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

function updateGravity(g: GravityState, s: AccelerationSample, alpha: number): GravityState {
  return {
    x: alpha * g.x + (1 - alpha) * s.x,
    y: alpha * g.y + (1 - alpha) * s.y,
    z: alpha * g.z + (1 - alpha) * s.z
  }
}

这里的滤波仅用于说明分层。参数必须结合设备采样率和真实数据标定。

五、摇动识别同时检查强度与频率

互动卡片触发与渲染链路

有效摇动不应由单个峰值决定。可在滑动窗口中统计越过阈值的方向变化次数、持续时间和峰值上限。

interface ShakeWindow {
  startedAt: number
  signChanges: number
  peak: number
  samples: number
}

function isShake(w: ShakeWindow, now: number): boolean {
  const duration = now - w.startedAt
  return duration >= 250 && duration <= 1200 && w.signChanges >= 3 && w.peak > 1
}

数值为教学示意。真实阈值需记录误触发率和漏检率后确定。

六、状态机与冷却时间防止重复触发

识别成功后进入播放状态，动画收敛后进入冷却，冷却结束才重新待机。

type CardMotionState = 'idle' | 'tracking' | 'triggered' | 'playing' | 'settling' | 'cooldown' | 'disabled'

interface CardMotionSession {
  cardId: string
  state: CardMotionState
  revision: number
  cooldownUntil: number
}

新 revision 使旧动画回调失效。取消或页面离开直接进入 disabled，并清理计时器。

七、视觉内容使用显式分层模型

互动卡片分层架构

背景、内容、前景、粒子和交互热点分别建模。前景允许视觉出框，但卡片自身的点击区域保持不变。

interface VisualLayer {
  id: string
  kind: 'background' | 'content' | 'foreground' | 'particle'
  zIndex: number
  clipToCard: boolean
  interactive: boolean
}

const foreground: VisualLayer = {
  id: 'subject', kind: 'foreground', zIndex: 30, clipToCard: false, interactive: false
}

出框层默认不响应点击，避免遮挡相邻控件。如果确需交互，应重新设计布局与无障碍语义。

八、出框范围必须受安全区域约束

前景可以超出卡片，但不能进入状态栏、底部导航或覆盖关键按钮。根据卡片位置和页面安全区计算最大扩展范围。

interface Insets { top: number; right: number; bottom: number; left: number }

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

横竖屏、分屏和小窗口下都要重新计算约束，而不是沿用首次布局值。

九、每帧合并传感与动画更新

传感器采样可能高于屏幕刷新率。事件层只更新最新运动状态，渲染层在帧回调中读取一次并提交统一视觉参数。

interface CardFrameState {
  tiltX: number
  tiltY: number
  foregroundOffset: number
  particleIntensity: number
}

function staticFrame(): CardFrameState {
  return { tiltX: 0, tiltY: 0, foregroundOffset: 0, particleIntensity: 0 }
}

动画完成且参数收敛后停止帧调度，避免静止页面仍持续计算。

十、性能分级控制视觉复杂度

完整模式包含前景位移、局部形变和少量粒子；均衡模式关闭粒子；轻量模式只保留缩放或高光；静态模式展示固定分层图。

type CardEffectTier = 'full' | 'balanced' | 'lite' | 'static'

function chooseTier(frameCost: number, reduceMotion: boolean): CardEffectTier {
  if (reduceMotion) return 'static'
  if (frameCost > 24) return 'lite'
  if (frameCost > 16) return 'balanced'
  return 'full'
}

阈值必须在目标设备实测，降级过程应在一次动效结束后切换，避免中途突变。

十一、静态替代同样传达状态

减少动态效果、传感器不可用或权限拒绝时，卡片仍要提供按钮或轻触入口，并用静态层次、图标或文字反馈展示可探索内容。

interface InteractionFallback {
  enabled: boolean
  actionLabel: string
  resultAnnouncement: string
}

const fallback: InteractionFallback = {
  enabled: true, actionLabel: '查看卡片动态内容', resultAnnouncement: '卡片内容已展开'
}

关键内容不能只存在于动画瞬间，屏幕朗读也应获得等价信息。