企业官网建设流程全解析

Recordly扩展API完全指南：开发光标特效、渲染钩子与设备框架扩展

【免费下载链接】RecordlyCreate polished demo videos without editing skills. Mac/Windows/Linux项目地址: https://gitcode.com/gh_mirrors/re/Recordly

Recordly 是一款开源的屏幕录制与演示视频编辑工具，它的扩展 API允许开发者像安装插件一样为编辑器注入新能力：注册光标特效（cursor effects）、插入渲染钩子（render hooks）、贡献设备框架（device frames）、壁纸、光标样式和设置面板。本指南带你从零理解 Recordly 扩展系统的架构、权限模型与开发流程，让你快速做出自己的第一个扩展。

什么是 Recordly 扩展？

扩展运行在编辑器的渲染进程中，通过一套带权限门控的宿主 API（host API）与主程序交互。它能做到：

• ✨绘制进渲染管线：在视频、光标、摄像头、标注等图层之后叠加自己的视觉效果
• 🖱️响应播放与导出事件：跟随播放时间轴、监听点击、跟踪导出进度
• 📦贡献打包资产：设备框架、壁纸、光标样式、音效
• ⚙️注册设置面板：在编辑器侧边栏里添加自己的配置项

官方 API 文档在仓库根目录的 EXTENSIONS.md，完整参考手册建议配合阅读。

扩展结构：一个最小示例

一个可安装的扩展只需要两个文件——清单（manifest）+ 入口脚本：

my-extension/ recordly-extension.json index.js

清单文件声明身份与权限：

{ "id": "com.example.my-extension", "name": "My Extension", "version": "1.0.0", "description": "A short description", "main": "index.js", "permissions": ["render"] }

入口脚本只需导出两个生命周期函数：

export function activate(api) { api.log("Hello from my extension"); } export function deactivate() {}

如果你习惯 TypeScript，可以直接从仓库的types.ts导入RecordlyExtensionAPI类型，获得完整的 IDE 自动补全与编译期检查，编译打包成.js后即可加载。

权限模型：按需声明能力

Recordly 扩展采用最小权限原则，六大权限各司其职：

实践建议：只申请你真正用到的权限，清单在扩展加载时和上传市场时都会被校验。

开发光标特效：registerCursorEffect()

光标特效是 Recordly 扩展里最"出效果"的一类。回调从点击发生后的每一帧开始执行，直到你返回false为止——这让"点击波纹""点击脉冲"这类短暂动画变得非常自然：

api.registerCursorEffect((ctx) => { const progress = ctx.elapsedMs / 400; if (progress >= 1) return false; const sceneWidth = ctx.videoLayout?.maskRect.width ?? ctx.width; const x = ctx.cx * ctx.width; const y = ctx.cy * ctx.height; const radius = sceneWidth * 0.03 * progress; ctx.ctx.beginPath(); ctx.ctx.arc(x, y, radius, 0, Math.PI * 2); ctx.ctx.stroke(); return true; });

两个关键设计值得注意：

1. 返回false即结束——不用手动清理，特效自己"谢幕"
2. 场景相对缩放——特效上下文自带videoLayout、zoom、sceneTransform，让你的特效随场景缩放，而不是钉死在画布上

渲染钩子：把效果插入渲染管线

registerRenderHook()是更强大的底层能力。Recordly 在渲染管线的特定阶段（phase）调用你的钩子，参数是一个 Canvas 2D 上下文加上丰富的场景信息：

export function activate(api: RecordlyExtensionAPI) { api.registerRenderHook("final", (ctx) => { ctx.ctx.fillStyle = "rgba(255,255,255,0.1)"; ctx.ctx.fillRect(0, 0, ctx.width, 30); }); }

钩子上下文还提供了实用的像素级查询能力：

• getPixelColor(x, y)— 取任意像素颜色
• getAverageSceneColor()— 场景平均色，适合做"随画面变色"的动态效果
• getDominantColors(count)— 主色提取
• videoLayout.maskRect/videoLayout.borderRadius— 场景真实边界与圆角，做出与画面严格对齐的边框效果

所有注册函数（含钩子、特效、面板）都会返回一个 dispose 函数，方便精细管理生命周期。

设备框架、壁纸与光标样式扩展

除了"画东西"，扩展还能贡献整类资产，让所有用户共享：

• 🖼️registerFrame()— 设备框架（手机壳、浏览器边框、窗口框）。推荐使用draw(ctx, width, height)函数式绘制，输出不依赖分辨率
• 🌄registerWallpaper()— 场景背景壁纸，文件打包在扩展目录内
• 🖱️registerCursorStyle()— 光标图片包，替换默认光标外观
• 🔊playSound(path, { volume })— 播放打包音效，例如"点击音效"扩展

这三类都依赖扩展根目录下的打包文件，api.resolveAsset("images/overlay.png")负责解析相对路径。

设置面板：让你的扩展可配置

通过registerSettingsPanel()可以把配置项直接挂进编辑器侧边栏（用parentSection: "cursor"可嵌套进光标分区）：

api.registerSettingsPanel({ id: "my-settings", label: "My Extension", fields: [ { id: "enabled", label: "Enable", type: "toggle", defaultValue: true }, { id: "size", label: "Size", type: "slider", defaultValue: 1, min: 0.1, max: 3, step: 0.1 }, { id: "color", label: "Color", type: "color", defaultValue: "#2563EB" }, ], });

支持的字段类型：toggle、slider、select、color、text。配合getSetting()/setSetting()/onSettingChange()，设置值会自动持久化，无需自己写存储逻辑。

事件系统与只读查询

带timeline/cursor/export权限后，你可以订阅整个编辑器的脉搏：

同时有一批只读查询随时可用：getVideoInfo()、getZoomState()、getCursorAt(timeMs)、getSmoothedCursor()、getKeystrokesInRange()、getActiveFrame()等。甚至可以直接调用api.drawIcon(ctx, "Sparkle", x, y, 18, "#ffffff")从 Recordly 内置的 Phosphor 图标集里画图标，省掉打包自己的图标资源。

扩展生命周期与最佳实践

整个加载流程分四步，理解它有助于排查问题：

1. 发现（Discovery）：Recordly 扫描内置扩展与用户扩展目录（应用中通过Extensions -> Open Directory可打开）
2. 激活（Activation）：activate(api)执行，在这里完成所有注册
3. 运行（Runtime）：注册的回调用各自的阶段在预览与导出中执行
4. 停用（Deactivation）：deactivate()执行，所有注册自动清理

💡小贴士：

• 预览与导出走同一条场景逻辑，所以你在预览里看到的效果会 1:1 出现在导出文件中
• 用videoLayout做场景相对尺寸，而不是画布绝对尺寸，效果才能跨分辨率
• 清单里的screenshots字段可以为市场展示图，contributes目前只是元数据，运行时行为必须在activate()里注册

在哪里动手？

• 完整 API 参考：EXTENSIONS.md
• 扩展面板入口（编辑器侧边栏）：src/components/video-editor/ExtensionManager.tsx
• 侧边栏分区注册：src/components/video-editor/layout/EditorSidebar.tsx
• 项目总览与特性说明：README.md

从一段 10 行的registerCursorEffect开始，到完整的渲染管线叠加、设置面板与音效——Recordly 的扩展 API 为社区留出了一整块创作空间。打开编辑器，挑一个你喜欢的特效方向，动手做第一个扩展吧。

【免费下载链接】RecordlyCreate polished demo videos without editing skills. Mac/Windows/Linux项目地址: https://gitcode.com/gh_mirrors/re/Recordly