短视频 SDK iOS（贴纸与文字）

一、功能概览

注意：说明：

注意：贴纸与文字都是通过贴纸能力实现的，文字贴纸、图片贴纸、动效贴纸共用一套数据结构 TAVMediaStickerItem。

二、相关接口类

接口类名	描述
TAVEditor	SDK 操作入口类。
ITAVStickerManager	贴纸操作入口类。
TAVMediaStickerItem	贴纸数据模型类。
ITAVStickerViewDataSource	自定义贴纸视图的数据源协议。
TAVStickerContextObserver	贴纸集合变化观察者协议。

三、接口方法汇总

方法	参数	返回值	说明
setStickerViewDataSource:	dataSource：遵守 ITAVStickerViewDataSource 的对象。	void	设置自定义贴纸视图数据源。
createStickerItem:stickerType:	stickerPath：贴纸路径。stickerItemType：贴纸类型。	TAVMediaStickerItem *	创建贴纸对象。
loadStickerItem:	stickerItem：贴纸对象。	void	加载贴纸。
removeStickerItem:	stickerItem：贴纸对象。	void	移除贴纸。
removeAllStickerItem	–	void	移除所有贴纸。
removeCurrentSticker	–	void	移除当前激活的贴纸。
getCurrentStickerItem	–	TAVMediaStickerItem *	获取当前贴纸 Item。
getAllStickerItems	–	NSArray<TAVMediaStickerItem >	获取所有贴纸 Item。
getStickerItemWithSticker:	sticker：TAVSticker 对象。	TAVMediaStickerItem *	根据 sticker 取贴纸 Item。
getCurrentSticker	–	TAVSticker *	获取当前贴纸。
getCurrentStickerView	–	TAVStickerView *	获取当前贴纸视图。
fetchStickerView: / fetchStickerViewWithItem:	sticker / stickerItem	TAVStickerView *	取贴纸对应的视图。
addStickerObserver: / removeStickerObserver:	observer：观察者。	void	添加/移除贴纸状态监听。
activeStickerItem: / resignStickerItem:	stickerItem：贴纸对象。	void	激活/注销贴纸（切换渲染层与交互层显示）。
resignCurrentStickerItem / resignAllStickerItems	–	void	注销当前/全部贴纸。
currentVideoRect	–	CGRect	获取当前视频渲染区域。

四、获取贴纸操作接口

id<ITAVStickerManager> stickerManager = [editor getStickerManager];

五、创建贴纸对象

/// 创建贴纸item/// – Parameter stickerPath: 贴纸路径- (TAVMediaStickerItem *)createStickerItem:(NSString *)stickerPath stickerType:(TAVStickerItemType)stickerItemType;

TAVStickerItemType：

枚举值	值	说明
TAVStickerItemTypeMotion	0	动效贴纸。
TAVStickerItemTypeText	1	文字贴纸。
TAVStickerItemTypeImage	2	图片贴纸。

创建完成后，请通过基类属性 timeRange 设置贴纸的显示时间区间（不设置默认为整个资源时长）。

// 1、创建文字贴纸NSString *textPath = [[NSBundle mainBundle] pathForResource:@"text_default" ofType:@"bundle"];TAVMediaStickerItem *textItem = [stickerManager createStickerItem:textPath stickerType:TAVStickerItemTypeText];textItem.text = @"Hello World";textItem.stickerFont = [TAVMediaStickerFont stickerFont:fontPath family:@"" style:@""];textItem.timeRange = CMTimeRangeMake(kCMTimeZero, CMTimeMakeWithSeconds(5, 600));// 2、创建图片贴纸NSString *imagePath = [[NSBundle mainBundle] pathForResource:@"image_default" ofType:@"bundle"];TAVMediaStickerItem *imageItem = [stickerManager createStickerItem:imagePath stickerType:TAVStickerItemTypeImage];imageItem.imageFilePath = @"/path/to/image.jpg";// 3、创建动效贴纸（资源包内需包含 main.pag）NSString *motionPath = [[NSBundle mainBundle] pathForResource:@"sticker__plfttz_01" ofType:@"bundle"];TAVMediaStickerItem *motionItem = [stickerManager createStickerItem:motionPath stickerType:TAVStickerItemTypeMotion];

六、加载贴纸

[stickerManager loadStickerItem:stickerItem];

七、移除贴纸

[stickerManager removeStickerItem:stickerItem]; // 移除指定贴纸[stickerManager removeAllStickerItem]; // 移除所有贴纸[stickerManager removeCurrentSticker]; // 移除当前激活贴纸

八、贴纸列表操作

NSArray<TAVMediaStickerItem *> *allItems = [stickerManager getAllStickerItems];TAVMediaStickerItem *current = [stickerManager getCurrentStickerItem];

九、监听贴纸列表变化

TAVStickerContextObserver 用于监听贴纸集合的变化，便于自定义图层列表、时间线或按钮态做同步刷新。

回调	说明
stickerContextStickerListDidChange:	贴纸集合整体变化（新增/删除）。
stickerContextCurrentStickerDidChange:	当前激活贴纸变化。
stickerContextShouldRefreshVideoFrame:	需要刷新视频帧。

[stickerManager addStickerObserver:self];// 不再需要时注销，避免泄漏[stickerManager removeStickerObserver:self];

注意：说明：

注意：协议方法全部为 @optional，按需实现。

十、常用属性

属性	类型	说明
stickerType	TAVStickerType	贴纸类型。
subImageType	TAVStickerImageSubType	图片类型贴纸的子类型（_unkown / _image / _gif / _apng）。
stickerID	NSString *	贴纸 ID。
stickerPath	NSString *（只读）	贴纸路径。
imageFilePath	NSString *	图片贴纸的图片路径。
text	NSString *	文字贴纸的文本。
defaultText	NSString *	文字贴纸的默认文本。
textColor	UIColor *	文字颜色。
bgColor	UIColor *	整个贴纸背景色。
stickerFont	TAVMediaStickerFont *	文字字体（fontPath / fontFamily / fontStyle）。
textMaxLength	NSInteger	可输入文字最大字数。
contentMode	TAVStickerContentMode	文字框的影响区域（整个贴纸 / 仅文字区域）。
animationMode	TAVStickerAnimationMode	贴纸动效播放模式。
applyTextStroke	BOOL	是否开启文字描边。
textStrokeWidth	CGFloat	文字描边厚度。
textStrokeColor	UIColor *	文字描边颜色。
textBgColor	UIColor *	文字背景颜色。
textBgAlpha	CGFloat	文字背景透明度，取值 0-1。
stickerScale	CGFloat	贴纸缩放。
stickerEdgeInsets	UIEdgeInsets	贴纸边距。
timeRange	CMTimeRange（继承自 TAVMediaEffectItem）	贴纸显示时间区间。

十一、动画模式

TAVStickerAnimationMode 用于描述贴纸（动效类）的播放行为，常见取值包括循环播放、播放到最后一帧静止、慢速播放（当用户设定时长大于贴纸时长时）。

十二、其它方法

– (TAVStickerSolidItem *)findSolidLayer; // 返回 solid layer- (TAVStickerTextItem *)findTextLayer; // 返回 text layer- (void)updateTrackInfoAt:(CMTime)pts renderSize:(CGSize)renderSize; // 按 pts 更新追踪位置- (instancetype)initWithStickerPath:(NSString *)stickerPath stickerType:(TAVStickerType)stickerType;- (instancetype)initWithTextSticker:(TAVSticker *)sticker; // 由 TAVSticker 生成文字 item

十三、自定义贴纸视图

SDK 内部内置了默认的贴纸编辑视图，若默认视图不满足业务需求，可通过 ITAVStickerViewDataSource 返回自定义视图。

@protocol ITAVStickerViewDataSource <NSObject>/// 根据贴纸对象返回贴纸视图，可继承自 TAVStickerView 自定义某些控件- (TAVStickerView *)stickerViewWithStickerItem:(TAVMediaStickerItem *)stickerItem;@end

@interface MyStickerView : TAVStickerView/// …自行实现业务逻辑@end#pragma mark – ITAVStickerViewDataSource- (TAVStickerView *)stickerViewWithStickerItem:(TAVMediaStickerItem *)stickerItem { return [[MyStickerView alloc] initWithStickerItem:stickerItem];}// 设置数据源[stickerManager setStickerViewDataSource:self];

十四、使用示例

id<ITAVStickerManager> stickerManager = [editor getStickerManager];// 创建文字贴纸NSString *textPath = [[NSBundle mainBundle] pathForResource:@"text_default" ofType:@"bundle"];TAVMediaStickerItem *textItem = [stickerManager createStickerItem:textPath stickerType:TAVStickerItemTypeText];textItem.text = @"Hello World";textItem.textColor = [UIColor redColor];textItem.applyTextStroke = YES;textItem.textStrokeColor = [UIColor blackColor];textItem.textStrokeWidth = 1.5;textItem.timeRange = CMTimeRangeMake(CMTimeMakeWithSeconds(2, 600), CMTimeMakeWithSeconds(6, 600));[stickerManager loadStickerItem:textItem];// 创建动效贴纸NSString *motionPath = [[NSBundle mainBundle] pathForResource:@"sticker__plfttz_01" ofType:@"bundle"];TAVMediaStickerItem *motionItem = [stickerManager createStickerItem:motionPath stickerType:TAVStickerItemTypeMotion];motionItem.timeRange = CMTimeRangeMake(kCMTimeZero, CMTimeMakeWithSeconds(5, 600));[stickerManager loadStickerItem:motionItem];// 更新已有文字贴纸内容textItem.text = @"更新后的文案";textItem.bgColor = [UIColor clearColor];textItem.textColor = [UIColor whiteColor];// 查询所有贴纸NSArray<TAVMediaStickerItem *> *all = [stickerManager getAllStickerItems];NSLog(@"当前贴纸数量: %lu", (unsigned long)all.count);// 移除贴纸[stickerManager removeStickerItem:motionItem];