@alicloud-panxi/dhuman-editor-sdk

v0.1.2

Published

10 months ago

智创-通用编辑器

0High
0Medium
0Low

磐曦 2D 数字人编辑器 SDK 使用文档

1. 安装

安装前置依赖

npm i react react-dom @alifd/next @b-design/fusion moment --save

html 模板中引入组件库 css 依赖

<link href="//gw.alipayobjects.com/os/lib/alifd/next/1.25.45/dist/next-noreset.var.css" rel="stylesheet" />
<link href="//gw.alipayobjects.com/os/lib/b-design/fusion/3.0.3/dist/index.css" rel="stylesheet" />

请使用 npm 包管理工具安装 SDK。

npm install @alicloud-panxi/dhuman-editor-sdk --save

2. 快速接入

2.1 引入 SDK

// React 项目
import PanxiDhumanEditorSdk from '@alicloud-panxi/dhuman-editor-sdk';
// Vue 项目
// import PanxiDhumanEditorSdk from '@alicloud-panxi/dhuman-editor-sdk/dist/index.es.vue';

import '@alicloud-panxi/dhuman-editor-sdk/dhuman-editor-sdk.css';

// 创建容器 DOM 元素
const container = document.getElementById('sdk-container') as HTMLDivElement;

// 配置 SDK 参数
const sdkConfig: PanxiDhumanEditorSdkConfig = {
  // 要渲染的容器 DOM 节点
  container,
  // 数字人编辑器类型：'off'（离线） | 'rti'	(实时)
  type: 'off',
  // 项目 ID
  projectId: 'your-project-id',
  // 服务端接口地址
  apiPath: 'https://xxx.com/api/path/to/server',
  // 服务端流式接口地址
  streamApiPath: 'https://xxx.com/stream/api/path/to/server',

  customOptions: {
    global: {
      cssToken: {
        '--panxi-dhuman-editor-theme-color': 'pink',
        '--panxi-dhuman-editor-font-family': 'serif',
      },
    },

    headerPanel: {
      hideProjectTitle: false,
      CustomProjectTitleComponent: {
        View: ({ projectName, maxProjectNameLength, updateProjectName, ...otherProps }) => {
          return (
            <div
              style={{ color: 'pink', cursor: 'pointer' }}
              onClick={() => {
                console.log('otherProps:', otherProps);
                updateProjectName({ projectId: 'your-project-id', projectName: 'your-new-project-name' });
              }}
            >
              {projectName} / {maxProjectNameLength}
            </div>
          );
        },
        customProps: {
          bar: 'boo',
        },
      },
    },

    sidebarPanel: {
      hideMenuItems: ['paster', 'template'],
      script: {
        hideMenuItem: false,
        icon: {
          default: 'icon-url',
          selected: 'icon-url',
          hover: 'icon-url',
        },
        menuItemName: 'menu-item-name',
        hideAIWritingRAG: true,
      },
    },
  },

  // 项目生成/发布后的回调函数
  onProjectPublished: () => {
    console.log('2D offline / rti editor project published');
  },
};

// 初始化并渲染 SDK 实例
const sdkInstance = new PanxiDhumanEditorSdk(sdkConfig);

// 当不再需要时，可以调用 destroy 方法来销毁 SDK
sdkInstance.destroy();

import { Component } from 'vue';

interface PanxiDhumanEditorSdkConfig {
  container: HTMLDivElement; // 要渲染的容器 DOM 节点
  type: 'off' | 'rti'; // 数字人编辑器类型：'off'（离线） | 'rti'	(实时)
  projectId: string; // 项目 ID
  apiPath: string; // 服务端接口地址
  streamApiPath: string; // 服务端流式接口地址

  framework?: 'react' | 'vue'; // 框架类型：'react' | 'vue'
  customOptions?: CustomOptions; // 自定义UI选项

  onProjectPublished?: (data: any) => void; // 项目生成/发布后的回调函数
}

// UI自定义选项
interface CustomOptions {
  // 全局对象
  global?: {
    // 自定义 CSS 变量
    cssToken?: {
      '--panxi-dhuman-editor-theme-color'?: string; // 主题色
      '--panxi-dhuman-editor-font-family'?: string; // 字体
    };
  };

  // 顶部栏
  headerPanel?: {
    hideProjectTitle?: boolean; // 隐藏标题
    // 自定义项目标题组件
    CustomProjectTitleComponent?: {
      View: React.ComponentType<CustomProjectTitleComponentProps>; // 组件
      customProps?: Record<string, any>; // 组件自定义 props
    };
  };

  // 侧边栏
  sidebarPanel?: {
    hideMenuItems?: Array<MENU_ITEM_ENUMS>; // 隐藏菜单项
    // 脚本菜单项自定义可选项
    [MENU_ITEM_ENUMS.SCRIPT]?: {
      hideMenuItem?: boolean; // 隐藏脚本菜单项
      icon?: {
        // 菜单项 icon
        default: string; // 默认（未选中态）图标 URL
        selected: string; // 选中态图标 URL
        hover: string; // hover 态图标 URL
      };
      menuItemName?: string; // 菜单项名称
      hideAIWritingRAG?: boolean; // 隐藏 AI 写稿知识库入口
    };
  };
}

// 自定义项目标题组件 props
interface CustomProjectTitleComponentProps {
  projectName: string; // 项目名称
  maxProjectNameLength: number; // 项目名称最大长度
  updateProjectName: (params: UpdateProjectNameParams) => void; // 项目重命名方法
}

// 项目重命名方法参数
interface UpdateProjectNameParams {
  projectId: string; // 项目 ID
  projectName: string; // 新的项目名称
}

// 菜单项枚举值
export enum MENU_ITEM_ENUMS {
  ANCHOR = 'anchor', // 主播菜单项（离线/实时）
  BACKGROUND = 'background', // 背景菜单项（离线/实时）
  VOICE = 'voice', // 声音菜单项（离线/实时）
  SCRIPT = 'script', // 脚本菜单项（离线/实时）
  ASSETS = 'assets', // 素材菜单项（离线/实时）
  PASTER = 'paster', // 贴纸菜单项（离线）
  TEXT = 'text', // 文字菜单项（离线）
  TEMPLATE = 'template', // 模板菜单项（离线）
  AGENT = 'agent', // 智能体菜单项（实时）
  SETTING = 'setting', // 设置菜单项（实时）
}

2.2 参数说明

| 参数名 | 描述 | 类型 | 是否必填 | 默认值 | | ------------------ | -------------------------------------- | ------------- | -------- | ------- | | container | 要渲染的容器 DOM 节点 | HTMLElement | 是 | - | | type | 数字人编辑器类型，可选值：'off', 'rti' | string | 是 | - | | projectId | 项目 ID | string | 是 | - | | apiPath | 服务端 API 接口地址 | string | 是 | - | | streamApiPath | 服务端流式接口地址 | string | 是 | - | | framework | 框架类型：可选值：'react', 'vue' | string | 否 | 'react' | | customOptions | UI 自定义可选项 | CustomOptions | 否 | - | | onProjectPublished | 项目生成 / 发布后的回调函数 | function | 否 | - |

2.3 方法说明

| 参数名 | 描述 | 类型 | 是否必填 | 默认值 | | ------- | ------------ | -------- | -------- | ------ | | destroy | 销毁当前实例 | function | 否 | - |

2.4 UI 自定义可选项类型 - CustomOptions

| 参数名 | 描述 | 类型 | 是否必填 | 默认值 | | ------------ | -------- | ------------ | -------- | ------ | | global | 全局对象 | Global | 否 | - | | headerPanel | 顶部栏 | HeaderPanel | 否 | - | | sidebarPanel | 侧边栏 | SidebarPanel | 否 | - |

2.4.1 全局对象 - Global

| 参数名 | 描述 | 类型 | 是否必填 | 默认值 | | -------- | --------------- | -------- | -------- | ------ | | cssToken | 自定义 CSS 变量 | CssToken | 否 | - |

2.4.1.1 自定义 CSS 变量 - CssToken

| 参数名 | 描述 | 类型 | 是否必填 | 默认值 | | --------------------------------- | ------ | ------ | -------- | ------ | | --panxi-dhuman-editor-theme-color | 主题色 | string | 否 | - | | --panxi-dhuman-editor-font-family | 字体 | string | 否 | - |

2.4.2 顶部栏 - HeaderPanel

| 参数名 | 描述 | 类型 | 是否必填 | 默认值 | | --------------------------- | ------------------ | --------------------------- | -------- | ------ | | hideProjectTitle | 隐藏标题 | boolean | 否 | false | | CustomProjectTitleComponent | 自定义项目标题组件 | CustomProjectTitleComponent | 否 | - |

2.4.2.1 自定义项目标题组件 - CustomProjectTitleComponent

| 参数名 | 描述 | 类型 | 是否必填 | 默认值 | | ----------- | ---------------- | ----------------------------------------------------- | -------- | ------ | | View | 组件 | React.ComponentType | 否 | - | | customProps | 组件自定义 props | Record<string, any> | 否 | - |

2.4.2.2 自定义项目标题组件 props - CustomProjectTitleComponentProps

| 参数名 | 描述 | 类型 | 是否必填 | 默认值 | | -------------------- | ---------------- | ----------------------------------------- | -------- | ------ | | projectName | 项目名称 | string | - | - | | maxProjectNameLength | 项目名称最大长度 | number | - | - | | updateProjectName | 项目重命名方法 | (params: UpdateProjectNameParams) => void | - | - |

2.4.2.3 项目重命名方法参数 - UpdateProjectNameParams

| 参数名 | 描述 | 类型 | 是否必填 | 默认值 | | ----------- | ------------ | ------ | -------- | ------ | | projectId | 项目 ID | string | 是 | - | | projectName | 新的项目名称 | string | 是 | - |

2.4.3 侧边栏 - SidebarPanel

| 参数名 | 描述 | 类型 | 是否必填 | 默认值 | | ------------- | ---------------------- | -------------------------- | -------- | ------ | | hideMenuItems | 隐藏菜单项 | Array<MENU_ITEM_ENUMS> | 否 | - | | script | 脚本菜单项自定义可选项 | CustomSciptMenuItemOptions | 否 | - |

2.4.3.1 菜单项枚举值 - MENU_ITEM_ENUMS

| 枚举值 | 描述 | | ---------- | ----------------------- | | anchor | 主播菜单项（离线/实时） | | background | 背景菜单项（离线/实时） | | voice | 声音菜单项（离线/实时） | | script | 脚本菜单项（离线/实时） | | assets | 素材菜单项（离线/实时） | | paster | 贴纸菜单项（离线） | | template | 模板菜单项（离线） | | agent | 智能体菜单项（实时） | | setting | 设置菜单项（实时） |

2.4.3.2 脚本菜单项自定义可选项 - CustomSciptMenuItemOptions

| 参数名 | 描述 | 类型 | 是否必填 | 默认值 | | ---------------- | ---------------------- | ------------ | -------- | ------ | | hideMenuItem | 隐藏脚本菜单项 | boolean | 否 | false | | icon | 菜单项 icon | MenuItemIcon | 否 | - | | menuItemName | 菜单项名称 | string | 否 | '脚本' | | hideAIWritingRAG | 隐藏 AI 写稿知识库入口 | boolean | 否 | false |

2.4.3.3 菜单项 icon - MenuItemIcon

| 参数名 | 描述 | 类型 | 是否必填 | 默认值 | | -------- | ------------------------ | ------ | -------- | ------ | | default | 默认（未选中态）图标 URL | string | 是 | - | | selected | 选中态图标 URL | string | 是 | - | | hover | hover 态图标 URL | string | 是 | - |

2.5 版本更新

对于最新的版本更改日志，请参阅 changelog.md 文件。