Editor-SDK

Editor-SDK 是编辑器部分的 SDK，可以直接在项目中引入编辑并导出 MP4 文件，Editor 是基于 Core-SDK 开发。

使用方法如下：

// 引入视频编辑器的SDK
import { VideoEditorSDK } from "@h5/videoEditorSDK";

// 创建编辑器的实例
const vs = new VideoEditorSDK({
  registerId: "test123", // 必填，注册ID，需要去官网进行申请
  movieData: "工程数据", // 选填二选一，工程数据，工程数据和作品ID必须传入一个，会优先读取工程数据，如果没有传入工程数据，会通过appid去api server 去获取工程数据
  EModuleEffectSourcePath: '/assets/effectcanvas', // 特效资源模块加载路径
  appid: "作品ID", // 选填二选一，作品id
  target: document.body, // 选填，容器，默认是document.body
  server: "api server配置", // 选填，如果没有传入会调用video.h5ds.com的API服务，api接口配置，具体参考APIServer
});

// 初始化
const vsdk = await vs.init();

/**
 * 假设工程数据是movieData，修改数据->更新视图
 */
// 1、获取工程数据中第一个元素
const [element] = movieData.elements;

// 2、修改第一个元素的坐标为[100, 200]
element.style.x = 100;
element.style.y = 200;

// 3、更新视图
vsdk.editor.updateMovie();

可以通过new VideoEditorSDK(...)获取到vs实例，通过实例vs.init()获取到vsdk，该实例vsdk.editor中包含了很多属性和方法，下面就挨个介绍这些属性和方法以及使用技巧。

// 更新视图
vsdk.editor.updateMovie();

// 更新设置区域
vsdk.editor.updateOption();

// 更新时间轴
vsdk.editor.updateTimeline();

属性说明

属性:后面的表示属性的数据类型。@表示@observable被 mobx 监听的数据，直接修改可以触发视图的更新。

.movie: Store

内核video-core的实例，类型为video-core的实例，请参考video-core的实例movie的实例说明。

// eg: 调用movie里面的方法，播放&暂停
vsdk.editor.movie.play();
vsdk.editor.movie.pause();

.data: MovieData

视频项目的原始 JSON 数据，数据结构请参考数据说明文档：video-core/src/react-pixi/types/data.ts

.apiServer: APIServer

外部传入的 API 服务配置，参考 APIServer 的定义（packages\video-editor\src\config\sdk.d.ts），如果不传默认使用官方的 API

import type {
  Err,
  AppDataRes,
  CreateAppParams,
  UpdateAppParams,
  TypesRes,
  TemplateParams,
  MaterialParams,
  MaterialRes,
  CollectRes,
  CollectParams,
  UserMaterialParams,
  UserMaterialTypeParams,
  CreateUserMaterialParams,
  UpdateUserMaterialParams,
} from "@config/sdk.d.ts";

interface APIServer {
  // 获取appData数据
  getAppData: (appid: string) => Promise<[{ url: string }, Err]>;
  // 创建新的作品
  createApp: (params: CreateAppParams) => Promise<[{ id: string }, Err]>;
  // 更新作品
  updateApp: (params: UpdateAppParams) => Promise<[string, Err]>;
  // 删除作品
  deleteApp?: (id: string) => Promise<[string, Err]>;
  // 获取模版的分类信息
  getTemplateTypes: () => Promise<[{ name: string; id: string }[], Err]>;
  // 获取模版列表
  getTemplates: (
    params: TemplateParams
  ) => Promise<[{ name: string; id: string }[], Err]>;
  // 获取素材的分类
  getMaterialTypes: (
    type: string
  ) => Promise<[{ name: string; id: string }[], Err]>;
  // 获取素材
  getMaterials: (
    params: MaterialParams
  ) => Promise<[{ id: string; name: string }[], Err]>;
  // 收藏元素
  collect: (params: {
    source_id: string;
    type: string;
  }) => Promise<[string, Err]>;
  // 取消收藏
  cancelCollect: (sourceIds: string[]) => Promise<[string, Err]>;
  // 收藏列表
  getCollects: (
    params: CollectParams
  ) => Promise<[{ id: string; name: string }[], Err]>;
  // 上传base64图片
  uploadBase64: (
    params: UploadBase64Params
  ) => Promise<[{ storage_path: string }, Err]>;
  // 表单上传
  formUpdate: (params: FormData) => Promise<[{ storage_path: string }, Err]>;
  // 获取用户素材
  getUserMaterial: (
    params: UserMaterialParams
  ) => Promise<[{ data: MaterialItemRes[]; total: number }, Err]>;
  // 获取用户的素材分类
  getUserMaterialType: (
    params: UserMaterialTypeParams
  ) => Promise<[{ data: { id: string; name: string }[]; total: number }, Err]>;
  // 删除用户素材
  deleteUserMaterial: (ids: string[]) => Promise<[string, Err]>;
  // 新增用户素材
  createUserMaterial: (
    params: CreateUserMaterialParams
  ) => Promise<[MaterialItemRes, Err]>;
  //tts
  createTTS: (
    params: CreateTTSParams
  ) => Promise<[{ storage_path: string }, Err]>;
  //ai字幕，传入音频的url，返回taskId，轮训taskId查询转换结果
  createCaption: (url: string) => Promise<[{ TaskId: string }, Err]>;
  // 轮训
  seekCaptionTask: (taskId: string) => Promise<[any, Err]>;
  // 修改用户素材
  updateUserMaterial: (
    params: UpdateUserMaterialParams
  ) => Promise<[MaterialItemRes, Err]>;
}

.copyTempData: any

缓存复制的数据，可以是文字内容，元素数据等数据，复制后赋值给此属性，缓存到内存中，等待粘贴的时候使用。

.copyTempFrameData: FrameItem[] | null

缓存复制的帧数据，等待粘贴的时候使用。

@.previewSource: PreviewSourceParams

点击预览的素材的时候，会缓存起来，方便展示

.activeItems: Record<ctypes.SourceType, SourceItem[]>

资源切换后，缓存 list 数据避免重复的请求服务端的数据

@.editMode: template' | 'auto'

编辑器模式分：模版替换模式 和 自由编辑模式

@.optionPanelCustom: 'background' | ''

控制切换设置区域的面板，切换到背景设置

@.appid: string

记录当前编辑项目的 appid

@.themeUpdateKey: 'dark' | 'light'

记录当前的风格主题类型，修改后会触发视图更新

@.languageUpdateKey: 'zh-CN' | 'en-US'

记录当前的多语言参数，修改后出触发视图更新

@.movieCreateSuccess: boolean

movie 实例创建成功的时候该参数会被设置为 true

@.currentTime: number

游标位置对应的时间

@.rulerScale: number

时间轴 1s 对应的缩放比例，默认是 50px，表示 1 秒对应 50px

@.playing: boolean

播放状态，播放中和暂停两种状态

@.updateKey: string

用于控制设置区域的视图更新

@.movieDataUpdateKey: string

视频数据替换后，需要修改该参数，会强制更新画布区域

@.timelineUpdateKey: string

用于控制时间轴视图的更新

@.timelineToolsUpdateKey: string

用于控制时间轴上面部分的快捷工具栏的视图更新

@.totalTimeKey: string

总时间变化后需要修改该参数，确保其他地方都可以同步更新

@.frameSelectedId: string

选中时间轴的帧小点的时候会切换到帧模式下，帧模式下修改元素的坐标缩放旋转等信息表示直接修改该帧状态

@.selectedElementIds: string[]

编辑器中选中的元素的 ID，修改后会自动同步选中状态

@.layoutKeys: Record<ctypes.LayoutName, string>

用于更新布局的标识，字段变化后会自动更新指定模块，比如：

// 更新header部分的组件
editor.layoutKeys.header = String(+new Date());

@.sourceType: ctypes.SourceType

控制资源面板切换的变量，配合setSourceType(t: ctypes.SourceType) 方法来使用。

@.elementOptionType: ctypes.ElementOptionType

控制设置面板切换的变量，配合setElementOptionType(t: ctypes.ElementOptionType)方法来使用。

方法说明

updateMovie(t?: number): void

更新画布区域的画面

updateOption(): void

更新设置区域视图

updateTimeline(): void

更新时间轴区域视图

setActiveItems(items: SourceItem[], type: ctypes.SourceType): void

设置缓存素材资源数据，将已经展示过的素材资源数据缓存起来，方便拖拽的时候使用

getFromActiveItems(id: string, type: ctypes.SourceType): SourceItem

从缓存的素材资源数据中读取数据，主要用于拖拽的时候使用

updateTimelineTools(): void

更新时间轴工具栏模块

record(params: types.RecordItem<types.RecordType>): void

记录用户的操作日志，redo/undo 的时候使用

export interface RecordItem<T> {
  desc: string; // 描述信息
  type: T;
}

export type RecordType =
  | "elements_delete"
  | "elements_create"
  | "elements_update"
  | "global";

vsdk.editor.record({
  type: "elements_update",
  desc: "元素更新了",
});

setSelectedElementIds(ids: string[]): void

传入元素 ID 去选中元素

// 同时选中2个元素
vsdk.editor.setSelectedElementIds(["elementId1", "elementId2"]);

setContorlAndSelectedElemenent(ids: string[]): Promise<null>

选中元素并设置元素的控制器，需要注意的是元素控制器的设置是异步的，并非同步过程。

// 同时选中2个元素并且设置元素控制器
await vsdk.editor.setContorlAndSelectedElemenent(["elementId1", "elementId2"]);

updateComponent(...keyName: ctypes.LayoutName[]): void

批量更新指定模块

// 布局名称
export type LayoutName =
  | "sources"
  | "timeline"
  | "options"
  | "canvas"
  | "header";

// 批量更新时间轴和设置区域
await vsdk.editor.updateComponent("timeline", "options");

setSourceType(t: ctypes.SourceType): void

切换左侧资源面板

// 资源面板类型
export type SourceType =
  | "my"
  | "template"
  | "image"
  | "video"
  | "audio"
  | "text"
  | "filter"
  | "effect"
  | "transition"
  | "lottie"
  | "background"
  | "more"
  | string;

// 切换到图片资源面板
await vsdk.editor.setSourceType("image");

setElementOptionType(t: ctypes.ElementOptionType): void

切换设置面板的方法

// 设置面板类型
export type ElementOptionType =
  | "basic"
  | "audio"
  | "speed"
  | "animation"
  | "colour"
  | "caption"
  | "mask";

// 切换到动画设置
await vsdk.editor.setElementOptionType("animation");

getElementData(): types.BaseElement

获取选中的元素，如果选中了多个元素，只会返回一个元素

// 如果editor.selectedElementIds有数据，可以调用该方法获取选中元素的数据
const elementData = vsdk.editor.getElementData();

getGroupElementData(): types.BaseElement[]

和 getElementData 方法类似，获取选中的多个元素，返回一个数组

mergeCaption(id: string): void

和下一个字幕进行合并，合并成一个新的字幕，这里传入字幕的 ID，如果下一个字幕没有数据将无法合并

deleteCaption(id: string): void

删除字幕，传入要删除的字幕 ID

addCaption(text: string, index?: number): void

添加字幕数据，text 是传入的字幕内容，index 是要添加到第 index + 1 个元素后面，如果不传将会插入到最后面

// 插入到第2个元素后面
vsdk.editor.addCaption("今天是个好天气", 1);

pause(time?: number): void

暂停到指定的时间，如果不传参数将暂停到最后一帧