功能概览
通过贴纸与文字操作的接口类和方法,包括创建、加载、移除贴纸,以及设置贴纸属性如时间区间、动画模式、位置等。本文还提供了使用示例和贴纸数据模型的说明。
贴纸与文字
相关接口类
接口类名 | 描述 |
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,持续 durationUssticker.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() {@Overridepublic void onStickerListChanged(List<TAVSticker> stickers) {// 列表整体变化,可用于重建图层列表}@Overridepublic void onStickerAdd(TAVSticker sticker) {// 新增贴纸}@Overridepublic void onStickerRemove(TAVSticker sticker) {// 移除贴纸}};
// 注册与注销stickerManager.addStickerObserver(mStickerObserver);stickerManager.removeStickerObserver(mStickerObserver);
说明:
TAVWidgetContentView 已内置实现该接口,自定义挂件手势层时通常无需再单独注册。贴纸数据模型(TAVSticker)
贴纸类型
// 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);