文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时互动-教育版>开发指南>定制化开发>Web 内核定制指南>定制化示例>多层级可切换 Tab 白板区域

多层级可切换 Tab 白板区域

最近更新时间：2026-03-18 16:41:02

我的收藏

本页目录：

说明：
阅读本文前，请确保您已经了解 Web 及 H5 快速接入 的内容。

功能描述

本文档将介绍如何在互动课堂 SDK 的白板区域集成自定义的多层级视图（如代码编辑器、文档预览等），并通过自定义的侧边 Tab 实现层级切换。
演示效果如下图所示（左侧切换器与中间多层级区域）。请注意，该区域的 UI 均支持自定义，您需要自行开发 UI 组件传入。因此下图样式仅供参考。


说明：
为方便您接入，上方效果图的 Demo 演示项目可参考 Demo GitHub 仓库。您可基于此 Demo 的开源代码，实现本功能的自定义开发。

核心机制

我们提供插槽机制，允许开发者通过以下两个状态注入自定义 UI：
TStateCustomLayers：定义除默认白板外的其他自定义层级（Layer）。通过数组形式指定并管理多个层级。
TStateLayerSwitcherTab：定义显示在白板左侧工具栏的切换器组件（Tab）。开发者可以通过调用 activateLayer 方法来控制不同层级的显示与隐藏（课堂会自动管理层级堆叠顺序）。

注意事项

1. 样式隔离与背景色
自定义层级组件（如 my-code-editor）必须设置背景色（如 background: #fff），否则会透出下方的白板内容，造成视觉重叠。
自定义层级组件（如 my-code-editor）必须配置高度及宽度为 100%，以确保占满提供的 Dom 节点挂载区域。
2. 组件注册时机
请确保在执行 setState 配置之前，customElements.define 已经执行完毕，否则 SDK 渲染时可能无法识别组件标签。
3. 生命周期管理
层级切换本质上是 CSS z-index 的变化。Vue 组件不会被销毁，其内部状态（如编辑器中的代码内容）会保持。

开发步骤

步骤一：开发自定义组件

为了确保组件样式的独立性并避免框架版本冲突，推荐使用 Vue 3 的 defineCustomElement 将业务组件封装为标准 Web Component。

1. 定义若干个业务层级组件 (例如：CodeEditorElement.ce.vue)

<!-- src/CodeEditorElement.ce.vue -->
<template>
  <div class="code-editor-layer">
    <div class="toolbar">代码编辑器模式</div>
    <textarea class="editor-area" placeholder="在此输入代码...">console.log('Hello World');</textarea>
  </div>
</template>

<script setup>
// 组件逻辑...
</script>

<style>
.code-editor-layer {
  width: 100%;
  height: 100%; /* 务必占满容器 */
  background: #1e1e1e; /* 务必设置背景色，防止透出下方白板 */
  display: flex;
  flex-direction: column;
}
/* ...其他样式 */
</style>

2. 定义切换器组件 (例如：LayerSwitcherComponent.ce.vue)

切换器负责调用 SDK API 切换视图。
<!-- src/LayerSwitcherComponent.ce.vue -->
<template>
  <div class="layer-switcher">
    <button @click="switchLayer('whiteboard')">白板</button>
    <button @click="switchLayer('code-editor')">代码</button>
  </div>
</template>

<script setup>
/**
 * 切换层级方法
 * @param {string} layerId - 目标层级ID ('whiteboard' 为默认内嵌白板组件)
 */
const switchLayer = (layerId) => {
  TCIC.SDK.instance.getComponent('board-component').getVueInstance().activateLayer(layerId);
};
</script>

步骤二：注册 Web Component

在项目入口文件（如 main.js）中，将上述组件注册为浏览器可识别的 Custom Elements。
import { defineCustomElement } from 'vue';
import CodeEditorElement from './CodeEditorElement.ce.vue';
import LayerSwitcherComponent from './LayerSwitcherComponent.ce.vue';

// 1. 注册代码编辑器组件
// 注册名为 'my-code-editor'
customElements.define('my-code-editor', defineCustomElement(CodeEditorElement, { shadowRoot: false }));

// 2. 注册切换器组件
// 注册名为 'my-layer-switcher'
customElements.define('my-layer-switcher', defineCustomElement(LayerSwitcherComponent, { shadowRoot: false }));

步骤三：配置 SDK 状态

步骤二组件注册完成后，通过 setState 将注册好的组件标签名注入到课堂前端项目中。
// 获取 SDK 实例
const sdkInstance = TCIC.SDK.instance;

// 1. 配置自定义层级列表
// 请注意, id 请不要占用我们内嵌默认白板的 "whiteboard"
const customLayersConfig = [
  {
    id: 'code-editor',       // 层级唯一标识 (Layer ID)，用于 activateLayer 调用
    component: 'my-code-editor' // 上一步注册的 Web Component 标签名
  }
  // 可配置多个...
];

// 注入自定义层级配置
sdkInstance.setState('TStateCustomLayers', customLayersConfig);

// 2. 注入侧边切换 Tab 组件
sdkInstance.setState('TStateLayerSwitcherTab', 'my-layer-switcher');

API 参考

方法：activateLayer(layerId)

切换当前激活的层级。SDK 会自动处理层级的 z-index（激活层级置顶）。
参数：
layerId ：String 类型。
'whiteboard'：固定值，代表默认的互动白板层级。
自定义 ID：对应 TStateCustomLayers 配置中的 id（例如 'code-editor'）。
返回：Boolean (执行是否成功)
示例：
const boardInstance = TCIC.SDK.instance.getComponent('board-component').getVueInstance();

// 切换到代码编辑器
boardInstance.activateLayer('code-editor');
// 切换回白板
boardInstance.activateLayer('whiteboard');
中国站