UI 配置 ​

预装版 UI 的配置分为三部分：初始化参数负责打开 iframe，routerOptions 决定默认页面，options 控制下载、权限判断和创建流程。

配置分层 ​

预装版（UI 版本）的配置分为三层：

配置层作用典型配置
基础配置初始化 iframe，传入 appkey、code、channel、容器和消息回调appkey、code、container、onMessage
options 配置控制功能板块、下载模式、场景鉴权和自定义创建fc_plate、download_mode、scene_auth、custom_generate
routerOptions 配置控制默认进入哪些页面，以及部分页面的路由参数list、generate、editor

基础参数即可打开完整 AiPPT 页面。需要隐藏功能、接管下载、做场景权限校验或直达指定页面时，再补充 options 和 routerOptions。

按目标选择配置 ​

接入目标优先配置继续阅读
只嵌入完整 AiPPT 页面基础配置UI 接入
隐藏或开放指定功能入口options.fc_plate功能板块配置
接管下载动作或获取下载地址options.download_mode下载配置
在生成、模板、下载等场景做权限判断options.scene_auth + SCENE_AUTH场景鉴权配置、事件通知
初始化时带标题、文件或 Markdownoptions.custom_generate自定义创建功能
默认进入作品列表、生成页或编辑器routerOptionsrouterOptions配置

配置分为三个层次：基础配置负责完成初始化，routerOptions 决定默认入口，功能板块、下载、场景鉴权和自定义创建用于控制具体能力。

页面入口选择 ​

入口类型使用方式适合场景后续流程
默认进入配置 routerOptions.list，可选 routerOptions.generate 或 routerOptions.editor用户从作品列表、AI 任务生成页或编辑器进入完整 UI 流程由用户在 iframe 内继续操作
UI 自定义创建配置 options.custom_generate.type 和 content / File / referList接入方前端直接传标题、文件、Markdown 或参考文档发起生成默认进入编辑大纲；粘贴 Markdown 可按 step=2 跳到模板选择
API 自定义创建配置 options.custom_generate.taskId，并按需传 step、templateId、isEnterprise拼装版 API 已创建任务，希望交给 UI 版本继续展示、编辑、选模板或合成step=1 编辑大纲，step=2 选择模板，step=3 直接合成 PPT

入口边界

routerOptions 控制 iframe 默认打开哪些页面；custom_generate 控制是否带内容或任务直达生成流程。不要把 API 自定义创建的 taskId 用在普通 UI 自定义创建场景中。

基础配置 ​

options配置 ​

功能板块配置 (主要用于按钮的隐藏展示) ​

fc_plate 入口控制 ​

fc_plate 用于限制 iframe 中可见的功能入口。子功能会自动补齐所属父级入口，但不会顺带开启同级功能。

功能提示

fc_plate 按父子级补齐入口。启用 生成方式(2003) 时，同时开启 AI 智能生成和本地上传。只启用子项时，例如 上传Word(2006)，系统会补齐父级 文档生成PPT(2005) 和 生成方式(2003)，不会开启其他同级功能。 参数支持数组或逗号分隔的场景值字符串；未传时默认全部开启。 [2006, 2007] 表示只开启上传 Word 和上传 XMind，[2024] 表示只开启 PPT 编辑器。完整取值见下方场景值参考。

场景值参考 ​

使用方式 ​

ts
 AipptIframe.show({
    options: { 
      // fc_plate: "2001,2002",
      // fc_plate: [2001, 2002],
      fc_plate: [2001, 2003, 2011, 2014, 2024] 
    }, 
  })

下载配置 ​

三种下载处理方式 ​

download_mode 决定文件由 iframe 直接下载、只通知宿主，还是下载并同时通知宿主。

功能提示

download_mode 只接受数字 0、1、2。未传时由 PPT 内部下载，并在下载成功后发送有效期 5 分钟的 OSS 链接。 0：只发送消息通知，不自动下载；消息包含下载地址，事件见 PPT_DOWNLOAD、OUTLINE_DOWNLOAD。 1：直接下载，不发送消息通知。 2：直接下载并发送消息通知；消息包含下载地址。

使用方式 ​

ts
 AipptIframe.show({
    options: { 
      // download_mode: 0 // 只发送消息通知，但不会进行自动下载，包含可下载地址
      // download_mode: 1 // 直接进行下载，但是不会发送消息通知
      download_mode: 2  // 直接进行下载，并且发送消息通知，包含可下载地址
    }, 
  })

场景鉴权配置 ​

宿主确认场景 ​

scene_auth 让宿主页面在指定动作执行前做一次业务判断，例如检查额度或权限。命中场景后，iframe 会暂停，直到宿主明确允许或拒绝。

功能提示

scene_auth 支持布尔值、数组或逗号分隔的场景值字符串；未传时所有场景均不鉴权。 true 表示所有场景需要鉴权，false 表示所有场景不鉴权。 [1001, 1002] 或 1001,1002 表示只对输入生成和预置词生成执行权限验证。完整取值见下方场景值参考。

方法 ​

场景值参考 ​

处理要求 ​

开启场景鉴权后，iframe 会在命中的场景暂停当前动作，并通过 onMessage 发出 SCENE_AUTH。接入方必须在业务判断完成后调用 AipptIframe.sceneAuthContinue(true | false)，否则用户会停留在等待状态。

返回值含义用户体验
true允许继续iframe 继续执行当前动作
false拒绝继续iframe 取消当前动作，接入方可在宿主页面提示原因

使用方式 ​

ts
 AipptIframe.show({
    options: { 
      // scene_auth: "1001,1002",
      // scene_auth: [1001, 1002],
      scene_auth: false, // 默认值
    }, 
    onMessage(type,data){  
      if (type === 'SCENE_AUTH') { // 鉴权功能验证
        if (data.scene === 1021) { // 点击换个大纲 不允许进行下一步
           AipptIframe.sceneAuthContinue(false); 
        } else {
          AipptIframe.sceneAuthContinue(true); // 可继续执行下一步
        } 
      } 
    }
  })

自定义创建功能 ​

custom_generate 可以在初始化时传入标题、文件、Markdown、参考文档或已有任务，并直接进入相应生成步骤。使用的生成类型还需要在功能板块配置中开放。当前不支持专业布局生成。

自定义创建功能适合两类场景：

  • UI 版本直接传入标题、文件或 Markdown 等内容，让用户进入生成流程。
  • API 版本已经创建任务，希望 UI 版本继续展示或编辑该任务。

如果接入方还没有通过 API 创建任务，不应传入 API 版本接入参数中的 taskId。

流程选择 ​

接入目标推荐配置进入位置
前端传标题生成type=1 + content编辑大纲界面
前端传 Word、XMind、FreeMind、Markdown 文件、PDF、TXT、WPStype + content: File编辑大纲界面
前端粘贴 Markdowntype=7 + content默认编辑大纲；可用 step=2 直接进入模板选择
前端传参考文档type=17 + content + referList编辑大纲界面
前端传单页内容type=20 + content单页生成流程
API 已有任务继续编辑taskId + step=1编辑大纲界面
API 已有任务选择模板taskId + step=2选择模板弹框
API 已有任务直接合成taskId + step=3 + templateId合成 PPT

使用边界 ​

场景必要参数说明
UI 自定义创建type + content / File / referList由 UI 初始化参数直接提供生成内容
API 自定义创建taskId接入 API 已创建任务；传入 taskId 后，同级 type、content 不再生效
API 自定义创建直接合成taskId + step=3 + templateId如果使用企业模板，同时传 isEnterprise=true

step 的含义：

step进入位置说明
1编辑大纲界面默认流程，用户可确认或编辑大纲
2选择模板弹框UI 自定义创建当前主要用于粘贴 Markdown；API 自定义创建可用于已有任务
3合成 PPT仅 API 自定义创建支持，需传入 taskId 和模板信息

默认参数 ​

拼装版(API版本)接入参数 ​

异常处理 ​

在初始化自定义上传的情况下会存在异常处理，用户可根据下列的错误进行排查。

默认使用方式 ​

ts
try {
     await AipptIframe.show({ 
        options: { 
          custom_generate: { 
            content: "标题", 
            type: 1
          }
        } 
      })
  } catch (e) {  // 进行异常描述的信息捕获
    console.log(e, 'catch exception')
  }

拼装版(API版本)使用方式 ​

ts
try {
     await AipptIframe.show({ 
        options: { 
          custom_generate: { 
            taskId: 1, 
            step: 1
          }
        } 
      })
  } catch (e) {  // 进行异常描述的信息捕获
    console.log(e, 'catch exception')
  }

routerOptions配置 ​

选择 iframe 默认页面 ​

预装版 UI 有三个页面：

  1. 作品列表页面
  2. AI任务生成页面
  3. 编辑器页面

作品列表页面和AI任务生成页面至少保留一个；两者都缺失时，iframe 无法创建预期页面。

routerOptions 只控制默认页面和路由参数，不负责携带生成内容。需要初始化时携带标题、文件、Markdown 或 API 任务 ID 时，请使用 options.custom_generate。

配置项控制范围不负责
routerOptions.list默认开放或进入作品列表、AI 任务生成页、编辑器不携带生成内容
routerOptions.generate生成页内的模板场景、流程节点、自定义回退等路由参数不创建 API 任务
routerOptions.editor是否直达指定作品编辑器，以及编辑器页 Logo 展示方式不表示作品合成成功

必填边界

routerOptions.list 至少需要包含 workspace 或 generate 中的一个。只配置 editor 但没有可进入的基础页面时，iframe 不会创建预期页面。

配置项 ​

事件信息 ​

自定义回退 ​
ts
try {
  await AipptIframe.show({
    routerOptions: {
      list: ['workspace', 'generate', 'editor'],
      generate: {
        customBack: true
      }
    }, 
    onMessage(type: string, data: any) {
      if (type === 'BACK_BUTTON') {
        switch (data.from) {
          case 'outline': // (PC,移动端)大纲页回退按钮//
            AipptIframe.sceneBack(true, data.from)
            break
          case 'generate': // (PC,移动端)合成页回退按钮//
            AipptIframe.sceneBack(true, data.from)
            break
          case 'template': // (PC)模板页回退按钮//
            AipptIframe.sceneBack(true, data.from)
            break
          case 'edit': // (移动端)编辑页回退按钮//
            AipptIframe.sceneBack(true, data.from)
            break
        }
      }
    }
  })
} catch (e) {  // 进行异常描述的信息捕获
  console.log(e, 'catch exception')
}

使用说明 ​

默认配置 ​
ts
try {
  await AipptIframe.show({
    routerOptions: {
      list: ['workspace', 'generate', 'editor'],
    } 
  })
} catch (e) {  // 进行异常描述的信息捕获
  console.log(e, 'catch exception')
}
配置作品列表页面 ​
ts
try {
  await AipptIframe.show({
    routerOptions: {
      list: ['workspace'],
    }
  })
} catch (e) {  // 进行异常描述的信息捕获
  console.log(e, 'catch exception')
}
配置AI任务生成页面 ​
ts
try {
  await AipptIframe.show({
    routerOptions: {
      list: ['generate'],
    }
  })
} catch (e) {  // 进行异常描述的信息捕获
  console.log(e, 'catch exception')
}
配置作品列表页面 + 编辑PPT页面 ​
ts
try {
  await AipptIframe.show({
    routerOptions: {
      list: ['workspace', 'editor'],
    }
  })
} catch (e) {  // 进行异常描述的信息捕获
  console.log(e, 'catch exception')
}
配置AI任务生成页面 + 编辑PPT页面 ​
ts
try {
  await AipptIframe.show({
    routerOptions: {
      list: ['generate', 'editor'],
    }
  })
} catch (e) {  // 进行异常描述的信息捕获
  console.log(e, 'catch exception')
}
直接进入编辑PPT页面 ​
ts
try {
  await AipptIframe.show({
    routerOptions: {
      list: ['workspace', 'generate', 'editor'],
      // 存在editor 并且存在id的情况下 则直接跳转至编辑器页面
      editor: {
        id: 1
      }
    }
  })
} catch (e) {  // 进行异常描述的信息捕获
  console.log(e, 'catch exception')
}
模板场景配置 ​
ts
try {
  await AipptIframe.show({
    routerOptions: {
      list: ['workspace', 'generate', 'editor'],
      // 存在generate 并且存在templateScene的情况下 则进入选择模板页面时会自动选择字段并筛选 不存在则为全部模板
      generate: {
        templateScene: 1
      }
    }
  })
} catch (e) {  // 进行异常描述的信息捕获
  console.log(e, 'catch exception')
}
自定义生成页流程节点 (主要针对自定义上传功能使用) ​

特别说明：目前只支持自定义上传功能中的粘贴Markdown

ts
try {
  await AipptIframe.show({
    routerOptions: {
      list: ['workspace', 'generate', 'editor'],
      // 存在generate 并且 并且存在step !== 1的情况下
      generate: {
        step: 2, // 默认为1
      }
    }
  })
} catch (e) {  // 进行异常描述的信息捕获
  console.log(e, 'catch exception')
}

异常处理 ​