更新记录

1.0.0（2026-09-05） 下载此版本

跨端帧驱动，提供 requestFrame/cancelFrame（对齐 requestAnimationFrame 语义）。Android 基于 Choreographer，Web 基于 requestAnimationFrame，iOS/鸿蒙/小程序基于高精度定时器

平台兼容性

uni-app x(5.24)

jzfw-frame

跨端帧驱动 UTS 插件，提供 requestFrame / cancelFrame，语义对齐 Web 的 requestAnimationFrame / cancelAnimationFrame。支持 Android / iOS / 鸿蒙 / H5(Web) / 小程序。

各端实现

无论哪端，回调入参都是毫秒时间戳（Android/Web 为高精度帧时间，其余端为 Date.now()），可跨端一致地用于计算帧间隔。

为什么用插件封装 Android 原生帧驱动

蒸汽模式（manifest.json 里 uni-app-x.vapor = true）下，Android 页面/工具脚本走 JS 引擎（vite/Rollup 打包），共享 .uts 里不能内联 android.* / kotlin.* 原生 import，否则打包报 Rollup failed to resolve import "android.view.Choreographer"。

原生能力必须下沉到 uni_modules/xxx/utssdk/app-android/ 由原生工具链单独编译。本插件即把 Choreographer 帧驱动封装为标准 UTS 原生插件，供 JS 侧通过桥接调用；其余端则用各自运行时的能力实现同一套 API。

说明：蒸汽模式下各端 JS 运行时大多已提供 requestAnimationFrame，简单动画直接用它即可。本插件的价值在于：①统一跨端 API；②Android 走真正的 vsync 级 Choreographer；③vdom（非蒸汽）模式下也能用原生帧驱动。

API

requestFrame(callback): number

请求下一帧回调，返回帧请求 id。单次调用只触发一次；做连续动画需在 callback 内再次调用（与 rAF 一致）。

• callback(timestamp: number)：帧时间戳（毫秒，单调递增，可用于计算帧间隔）。

cancelFrame(id): void

取消一个尚未触发的帧请求。

用法

import { requestFrame, cancelFrame } from "@/uni_modules/jzfw-frame";

let frameId = 0;
let last = 0;

function tick(timestamp: number) {
    const delta = last == 0 ? 16 : timestamp - last;
    last = timestamp;

    // ...按 delta 推进动画...

    // 继续下一帧
    frameId = requestFrame(tick);
}

// 启动
frameId = requestFrame(tick);

// 停止
cancelFrame(frameId);

实现要点

• Android：Choreographer.getInstance() 依赖当前线程 Looper，postFrameCallback / removeFrameCallback 均切到 UI 主线程执行；FrameCallback 实例创建不涉及 Looper，同步登记到注册表以避免 request/cancel 的跨线程竞态；frameTimeNanos 转毫秒回调。
• Web：直接透传 requestAnimationFrame / cancelAnimationFrame。
• iOS / 鸿蒙 / 小程序：setTimeout 16ms 近似帧节拍，返回的定时器 id 即帧 id，clearTimeout 取消。