一、相关接口类
| 接口类名 | 描述 |
| TAVEditor | SDK 操作入口类。 |
| ITAVStickerManager | 贴纸操作接口类。 |
| TAVSticker | 贴纸数据模型类。 |
二、接口方法汇总
| 方法 | 参数 | 返回值 | 说明 |
| createSticker(TAVSticker.TAVStickerType type, String stickerPath) | type：贴纸类型（TAVSticker 的嵌套枚举）。stickerPath：文件路径。 | TAVSticker | 创建贴纸对象。 |
| loadSticker(TAVSticker sticker) | sticker：贴纸对象。 | void | 加载贴纸。 |
| removeSticker(TAVSticker sticker) | sticker：贴纸对象。 | void | 移除贴纸。 |
| registerFallbackFont(String fontPath) | fontPath：字体路径。 | boolean | 注册保底字体。 |
| getStickers() | – | List<TAVSticker> | 获取所有贴纸。 |
| getSticker(int id) | id：贴纸 ID。 | TAVSticker | 获取指定贴纸。 |
| addStickerObserver(ITAVStickerContextObserver observer) | observer：观察者。 | void | 添加贴纸状态监听。 |
| removeStickerObserver(ITAVStickerContextObserver observer) | observer：观察者。 | void | 移除贴纸状态监听。 |
三、获取贴纸操作接口
/** * 获取贴纸操作接口 * * @return ITAVStickerManager实例 */ITAVStickerManager stickerManager = editor.getStickerManager();
四、创建贴纸对象
/** * 创建贴纸对象 * * @param type 贴纸类型（MOTION=动效贴纸, TEXT=文字贴纸, IMAGE=自定义图片贴纸） * @param path 贴纸 PAG 文件路径：以 "/" 开头按本地文件加载，否则按 assets 路径加载；IMAGE 类型可传 null 使用内置默认素材 * @return TAVSticker实例；素材加载失败时抛出 RuntimeException，不会返回 null */try { TAVSticker sticker = stickerManager.createSticker(type, path); // 设置显示时间区间（微秒）：起点 0，持续 durationUs sticker.setTimeRange(TAVTimeRange.fromUs(0, durationUs)); // 设置动画模式（可选） sticker.setAnimationMode(TAVSticker.TAVStickerAnimationMode.FREEZE);} catch (RuntimeException e) { // 贴纸素材不存在或解析失败}
五、加载贴纸
/** * 加载贴纸到编辑器 * * @param sticker 贴纸数据对象 */stickerManager.loadSticker(sticker);
六、移除贴纸
/** * 移除贴纸 * * @param sticker 要移除的贴纸对象 */stickerManager.removeSticker(sticker);
七、注册保底字体
/** * 注册保底字体 * * @param fontPath 字体文件路径 * @return 注册是否成功 */boolean success = stickerManager.registerFallbackFont(context.getFilesDir() + "/custom_font.ttf");if (success) { Log.i(TAG, "字体注册成功");}
八、贴纸列表操作
/** * 获取所有贴纸 * * @return 当前加载的贴纸列表 */List<TAVSticker> allStickers = stickerManager.getStickers();/** * 通过ID获取贴纸 * * @param id 贴纸ID * @return 对应的贴纸对象 */TAVSticker specificSticker = stickerManager.getSticker(stickerId);
九、监听贴纸列表变化
ITAVStickerContextObserver 用于监听贴纸集合的变化，便于自定义图层列表、时间线或按钮态做同步刷新。
| 回调 | 参数 | 说明 |
| onStickerListChanged(List<TAVSticker> stickers) | 当前全部贴纸。 | 贴纸集合整体变化时回调，携带最新列表。 |
| onStickerAdd(TAVSticker sticker) | 新增的贴纸。 | 新增一个贴纸时回调。 |
| onStickerRemove(TAVSticker sticker) | 被移除的贴纸。 | 移除一个贴纸时回调。 |
观察者以弱引用持有，业务方必须自己保留强引用（例如作为成员变量），否则对象被回收后回调不再触发。
// 声明为成员变量，避免被 GCprivate final ITAVStickerContextObserver mStickerObserver = new ITAVStickerContextObserver() { @Override public void onStickerListChanged(List<TAVSticker> stickers) { // 列表整体变化，可用于重建图层列表 } @Override public void onStickerAdd(TAVSticker sticker) { // 新增贴纸 } @Override public void onStickerRemove(TAVSticker sticker) { // 移除贴纸 }};
// 注册与注销stickerManager.addStickerObserver(mStickerObserver);stickerManager.removeStickerObserver(mStickerObserver);
注意：说明：
注意：TAVWidgetContentView 已内置实现该接口，自定义挂件手势层时通常无需再单独注册。
十、贴纸类型
// TAVStickerType 是 TAVSticker 的嵌套枚举，使用时写 TAVSticker.TAVStickerType// （以下为 TAVSticker 内部声明形式）public class TAVSticker { public enum TAVStickerType { MOTION(0), // 动效贴纸 TEXT(1), // 文字贴纸 IMAGE(2); // 图片贴纸 }}
十一、动画模式
public enum TAVStickerAnimationMode { DEFAULT, // 循环播放 FREEZE, // 播放到最后一帧静止 SCALE_UP // 慢速播放（当用户设定时长大于贴纸时长时）}
十二、常用方法
// 设置显示时间区间（微秒）sticker.setTimeRange(TAVTimeRange.fromUs(startUs, durationUs));// 设置动画模式sticker.setAnimationMode(TAVSticker.TAVStickerAnimationMode.FREEZE);// 设置可见性sticker.setVisible(true);// 设置位置（相对坐标，0-1）sticker.setPosition(0.5f, 0.5f);// 设置缩放比例sticker.setScale(1.2f);// 设置旋转角度（度数）sticker.setRotate(45);
十三、使用示例
// 获取贴纸操作接口ITAVStickerManager stickerManager = editor.getStickerManager();// 注册保底字体stickerManager.registerFallbackFont(context.getFilesDir() + "/custom_font.ttf");// 创建动效贴纸（素材加载失败时 createSticker 抛出 RuntimeException）TAVSticker motionSticker = null;try { motionSticker = stickerManager.createSticker( TAVSticker.TAVStickerType.MOTION, context.getFilesDir() + "/stickers/motion.pag" ); motionSticker.setTimeRange(TAVTimeRange.fromUs(0, 5_000_000)); // 0-5秒 motionSticker.setAnimationMode(TAVSticker.TAVStickerAnimationMode.SCALE_UP); // 加载贴纸 stickerManager.loadSticker(motionSticker);} catch (RuntimeException e) { Log.e(TAG, "create motion sticker failed", e);}// 创建文字贴纸try { TAVSticker textSticker = stickerManager.createSticker( TAVSticker.TAVStickerType.TEXT, context.getFilesDir() + "/stickers/text_template.pag" ); textSticker.setTimeRange(TAVTimeRange.fromUs(2_000_000, 6_000_000)); // 2-8秒（起点2s，持续6s） // 修改文字内容与样式（无文字图层的素材 getTextItem() 返回 null） TAVStickerTextItem newTextItem = textSticker.getTextItem(); if (newTextItem != null) { newTextItem.setText("Hello World"); newTextItem.setTextColor(Color.RED); newTextItem.setStrokeColor(Color.BLACK); newTextItem.setStrokeWidth(1.5f); } // 加载文字贴纸 stickerManager.loadSticker(textSticker);} catch (RuntimeException e) { Log.e(TAG, "create text sticker failed", e);}// 更新已有文字贴纸（已加载的贴纸需 clone 后再 setTextItem，修改才会生效）TAVSticker loadedSticker = stickerManager.getSticker(stickerId);if (loadedSticker != null && loadedSticker.getTextItem() != null) { // 更新播放区间 loadedSticker.setTimeRange(timeRange); TAVStickerTextItem textItem = loadedSticker.getTextItem().clone(); // 更新文字内容/背景色/文字颜色 textItem.setText(text); textItem.setBackgroundColor(color); textItem.setTextColor(color); // 让更新内容生效 loadedSticker.setTextItem(textItem); editor.flushImmediately();}// 获取所有贴纸List<TAVSticker> allStickers = stickerManager.getStickers();Log.d(TAG, "当前贴纸数量: " + allStickers.size());// 设置贴纸位置for (TAVSticker item : allStickers) { item.setPosition(0.3f, 0.7f); item.setScale(0.8f);}// 移除贴纸if (motionSticker != null) { stickerManager.removeSticker(motionSticker);}
十四、贴纸 ID 与克隆
// 获取贴纸唯一IDint stickerId = textSticker.getId();// 克隆贴纸（浅拷贝）TAVSticker clonedSticker = textSticker.clone();// 克隆贴纸（深拷贝）TAVSticker deepClonedSticker = textSticker.clone(true);