SlidePlayer 使用文档

目录

1. 简介
2. 安装
3. 基础使用
4. 配置项
5. API 参考
6. 事件系统
7. 页面通信
8. 最佳实践
9. 类型定义

简介

SlidePlayer 是一个专为在线教育场景设计的 Web 内容播放器，主要用于管理和展示基于 iframe 的多页面课件内容。它提供了完整的页面管理、导航控制、消息通信等功能，并针对教育场景提供了特殊的功能支持，如课程信息展示、计时器、课堂公约等。

安装

import { SlidePlayer } from '@courseware-player';

基础使用

创建实例

// 创建播放器实例
const player = new SlidePlayer({
    container: document.getElementById('player-container'),
    // 方式一：直接提供播放列表
    playlist: [
        {
            id: 'page1',
            viewUrl: 'page1.html',
            config: {
                templateId: 'template1',
                stepType: 'normal',
                tools: {
                    // 页面工具配置
                }
            }
        }
    ],
    // 方式二：通过异步方法获取播放列表
    getPlaylist: async () => {
        const response = await fetch('/api/playlist');
        return {
            code: 0,
            data: [/* 步骤和页面数据 */],
            msg: 'success'
        };
    },
    options: {
        hideToolbar: false,           // 隐藏所有工具栏
        hideNavigationToolbar: false, // 仅隐藏导航工具栏
        hideUtilityToolbar: false,    // 仅隐藏功能工具栏
        showNavigation: true,         // 是否创建导航工具栏组件
        showUtils: true,              // 是否创建功能工具栏组件
        loadAllPages: false,
        animation: {
            enabled: true,
            duration: 100,
            timingFunction: 'ease-in-out'
        }
    }
});

// 监听播放器就绪事件
player.on('ready', ({ totalPages }) => {
    console.log(`播放器已就绪，总页数: ${totalPages}`);
});

// 监听页面切换事件
player.on('pageChange', ({ current, total, pageConfig }) => {
    console.log(`当前页面: ${current}/${total}`);
    console.log('页面配置:', pageConfig);
});

配置项

PlayerConfig 接口

interface PlayerConfig {
    // 播放器容器元素
    container: HTMLElement;
    
    // 播放列表数组
    playlist?: PlaylistItem[];
    
    // 获取播放列表的异步方法
    getPlaylist?: () => Promise<{
        code: number;
        data: any[];
        msg: string;
    }>;
    
    // 用户信息
    userProfile?: UserProfile;
    
    // 其他选项
    options?: {
        // 是否隐藏所有工具栏
        hideToolbar?: boolean;
        
        // 是否仅隐藏导航工具栏
        hideNavigationToolbar?: boolean;
        
        // 是否仅隐藏功能工具栏
        hideUtilityToolbar?: boolean;
        
        // 是否创建导航工具栏组件
        showNavigation?: boolean;
        
        // 是否创建功能工具栏组件
        showUtils?: boolean;
        
        // 是否加载所有页面
        loadAllPages?: boolean;

        // 动画配置
        animation?: PlayerAnimationConfig | false;
        
        // 是否隐藏页码
        hidePageNumber?: boolean;
    };
}

PlaylistItem 接口

interface PlaylistItem {
    // 页面ID
    id: string;
    
    // 页面URL
    viewUrl: string;
    
    // 页面配置
    config?: {
        id: string;
        templateId?: string;
        stepType?: string;
        isLastPageBeforeLiving?: boolean;
        tools?: Record<string, any>;
        notes?: {
            content?: string;
        };
        [key: string]: any;
    };
}

API 参考

导航控制

// 前往下一页
await player.next();

// 前往上一页
await player.prev();

// 跳转到指定页面
await player.goto(2);

工具栏控制

// 显示工具栏
// 显示所有工具栏
player.showToolbar();

// 隐藏所有工具栏
player.hideToolbar();

// 仅显示导航工具栏
player.showNavigationToolbar();

// 仅隐藏导航工具栏
player.hideNavigationToolbar();

// 仅显示功能工具栏
player.showUtilityToolbar();

// 仅隐藏功能工具栏
player.hideUtilityToolbar();

// 重置工具栏到初始配置状态
player.resetToolbarToInitialState();

// 切换全屏
player.toggleFullscreen();

状态管理

// 获取当前状态
const state = player.getState();

// 获取当前页码
const currentPage = player.getCurrentPage();

// 获取总页数
const totalPages = player.getTotalPages();

// 检查是否就绪
const isReady = player.isReady();

键盘导航

// 启用键盘导航
player.enableKeyboardNavigation();

// 禁用键盘导航
player.disableKeyboardNavigation();

事件系统

SlidePlayer 基于 EventEmitter 实现了完整的事件系统，支持以下事件：

核心事件

ready

播放器初始化完成时触发

player.on('ready', ({ totalPages }) => {
    console.log(`播放器就绪，总页数: ${totalPages}`);
});

pageChange

页面切换时触发

player.on('pageChange', ({ current, total, pageConfig }) => {
    console.log(`当前页面: ${current}/${total}`);
    console.log('页面配置:', pageConfig);
});

pageLoaded

页面加载完成时触发

player.on('pageLoaded', ({ index }) => {
    console.log(`页面 ${index} 加载完成`);
});

pageReady

页面准备就绪时触发

player.on('pageReady', ({ index }) => {
    console.log(`页面 ${index} 准备就绪`);
});

error

发生错误时触发

player.on('error', (error) => {
    console.error('播放器错误:', error);
});

destroyed

播放器销毁时触发

player.on('destroyed', () => {
    console.log('播放器已销毁');
});

playlistUpdated

播放列表更新时触发

player.on('playlistUpdated', ({ totalPages, currentPage }) => {
    console.log(`播放列表已更新，总页数: ${totalPages}, 当前页: ${currentPage}`);
});

pageConfigUpdated

页面配置更新时触发

player.on('pageConfigUpdated', ({ index, config }) => {
    console.log(`页面 ${index} 配置已更新:`, config);
});

close

关闭播放器时触发

player.on('close', () => {
    console.log('播放器关闭');
});

videoFullscreenChange

视频全屏状态改变时触发

player.on('videoFullscreenChange', ({ isFullscreen }) => {
    console.log(`视频全屏状态: ${isFullscreen}`);
});

videoFullscreenEnter/videoFullscreenExit

视频进入/退出全屏时触发

player.on('videoFullscreenEnter', () => {
    console.log('视频进入全屏');
});

player.on('videoFullscreenExit', () => {
    console.log('视频退出全屏');
});

页面通信

SlidePlayer 提供了完整的页面间通信机制，通过 MessageBridge 实现。

发送消息到页面

// 检查是否可以发送消息
if (player.canSendMessage()) {
    // 发送消息到当前页面
    player.sendMessageToCurrentPage('customEvent', {
        data: 'some data'
    });
}

页面配置更新

// 更新当前页面配置
await player.updateCurrentPageConfig({
    theme: 'dark',
    customSetting: 'value'
});

播放列表更新

// 更新整个播放列表
await player.updatePlaylist([
    {
        viewUrl: 'new-page1.html',
        config: { templateId: 'new-template1' }
    },
    {
        viewUrl: 'new-page2.html',
        config: { templateId: 'new-template2' }
    }
]);

动画配置

PlayerAnimationConfig 接口

interface PlayerAnimationConfig {
    // 是否启用动画
    enabled: boolean;
    // 动画持续时间（毫秒）
    duration: number;
    // 动画缓动函数
    timingFunction: string;
}

更新动画配置

// 禁用动画
player.updateAnimationConfig(false);

// 自定义动画配置
player.updateAnimationConfig({
    duration: 200,
    timingFunction: 'ease-out'
});

组件集成

工具栏

播放器内置了功能丰富的工具栏，支持：

• 上一页/下一页导航
• 全屏切换
• 页码显示
• 刷新功能
• 个人信息面板
• 计时器
• 课程信息
• 协议展示

模态框

支持多种内置模态框：

• ProfileModal (个人信息)
• LessonModal (课程信息)
• AgreementModal (课堂公约)

键盘快捷键

支持以下键盘导航：

• ArrowLeft / PageUp: 上一页
• ArrowRight / PageDown / Space: 下一页

高级功能

页面预加载

// 通过配置启用所有页面预加载
const player = new SlidePlayer({
    container: element,
    playlist: playlist,
    options: {
        loadAllPages: true
    }
});

自定义播放列表加载

const player = new SlidePlayer({
    container: element,
    getPlaylist: async () => {
        const response = await fetch('/api/playlist');
        return await response.json();
    }
});

最佳实践

1. 错误处理

player.on('error', (error) => {
    console.error('播放器错误:', error);
    // 实现错误恢复逻辑
});

2. 资源清理

// 组件卸载时清理资源
function cleanup() {
    player.destroy();
}

3. 页面加载优化

// 监听页面加载状态
player.on('pageLoaded', ({ index }) => {
    // 处理页面加载完成后的逻辑
});

4. 响应式处理

window.addEventListener('resize', () => {
    // 播放器会自动处理响应式布局
});

5. 合理配置工具栏 typescript

// 在不同的场景下适当配置工具栏
const player = new SlidePlayer({
    // ...其他配置
    options: {
        // 仅显示导航，不显示功能工具栏
        showUtils: false,
        
        // 或仅显示功能工具栏，不显示导航
        showNavigation: false,
        
        // 创建所有工具栏但初始隐藏导航工具栏
        hideNavigationToolbar: true
    }
});

类型定义

PlayerState

interface PlayerState {
    currentPage: number;
    totalPages: number;
    isReady: boolean;
    isFullscreen: boolean;
    loadedPages: Set<number>;
    keyboardNavigationEnabled: boolean;
}

ToolbarVisibilityState

interface ToolbarVisibilityState {
    navigationHiddenByConfig: boolean;    // 导航工具栏是否因配置而隐藏
    utilityHiddenByConfig: boolean;       // 功能工具栏是否因配置而隐藏
    hiddenByFullscreen: boolean;          // 是否因全屏模式而隐藏
    initialNavigationState: boolean;      // 初始导航工具栏状态
    initialUtilityState: boolean;         // 初始功能工具栏状态
}

UserProfile

interface UserProfile {
    // 用户信息接口
    [key: string]: any;
}

注意事项

• 确保容器元素具有明确的宽度和高度。
• 页面URL必须遵循同源策略或正确配置CORS。
• 在销毁播放器时调用 destroy() 方法以清理资源。
• 大型播放列表建议使用按需加载而非预加载所有页面。
• 动画配置会影响页面切换的流畅度，建议根据实际需求调整。
• 在处理用户输入时，播放器会自动过滤输入框中的键盘事件

版本信息

当前版本: 1.0.0

主要更新内容包括：

1. 更新了简介，使其更符合项目的实际用途
2. 完善了配置项接口的定义
3. 添加了新的事件说明
4. 增加了动画配置相关的文档
5. 补充了页面通信的细节
6. 更新了注意事项