import { ReactNode, useState, Children, isValidElement, useEffect, } from "react"; import { AnimatePresence, motion } from "framer-motion"; import { cn, getBackgroundImage } from "@/lib/utils"; import { Overlay } from "@/components/overlay"; import { useVideoContextSafe } from "@/contexts/VideoContext"; import { useAudioManager } from "@/hooks/useAudioManager"; /** * 使用示例: * * * 第一步内容... * * */ interface GuideStepsProps { children: ReactNode; className?: string; visible?: boolean; onVisibleChange?: (visible: boolean) => void; currentStep?: number; onStepChange?: (step: number) => void; /** 每个步骤对应的高亮选择器数组,索引对应步骤序号 */ highlightSelectors?: (string | string[])[]; /** 控制是否显示遮罩层(包括背景蒙版和 Overlay 遮罩,默认:true,保持向后兼容) */ showMask?: boolean; /** 自定义 z-index,用于控制层级(默认:50) */ zIndex?: number; /** 音频分组 id,相同 channel 内互斥,不同 channel 可同时播放;不传则全局互斥 */ audioChannelId?: string; } interface GuideStepsItemProps { children: ReactNode; speaker?: "guide" | "student"; /** 当前步骤对应的音频地址 */ audioSrc?: string; /** 进入该步骤时是否自动播放音频(有 audioSrc 且未显式设置时,默认自动播放) */ autoPlayOnEnter?: boolean; } const GuideSteps = ({ children, className, visible, onVisibleChange, currentStep: controlledStep, onStepChange, highlightSelectors, showMask = true, zIndex = 50, audioChannelId, }: GuideStepsProps) => { const [internalStep, setInternalStep] = useState(0); const [internalVisible, setInternalVisible] = useState(true); // 安全地获取视频上下文(如果不在 VideoProvider 中,返回 null) const videoContext = useVideoContextSafe(); // 音频管理:默认全局互斥,如果传了 audioChannelId 则按 channel 互斥 const { play, stop } = useAudioManager( audioChannelId ? { mode: "channel", channelId: audioChannelId } : { mode: "global" } ); // 收集每个步骤的内容和 speaker 信息 const stepsData = Children.toArray(children).map((child) => { if ( isValidElement(child) && child.type === GuideStepsItem ) { const hasAudio = !!child.props.audioSrc; return { content: child.props.children, speaker: child.props.speaker || "guide", // 默认为 "guide" 保持向后兼容 audioSrc: child.props.audioSrc, // 如果没有显式设置 autoPlayOnEnter,则在有 audioSrc 时默认自动播放 autoPlayOnEnter: child.props.autoPlayOnEnter !== undefined ? child.props.autoPlayOnEnter : hasAudio, }; } // 如果不是 GuideStepsItem,保持原有行为 return { content: child, speaker: "guide" as const, audioSrc: undefined, autoPlayOnEnter: false, }; }); const steps = stepsData.map((step) => step.content); const totalSteps = steps.length; // 使用受控或非受控模式 const isControlled = controlledStep !== undefined; const currentStep = isControlled ? controlledStep : internalStep; const baseVisible = visible !== undefined ? visible : internalVisible; // 如果视频正在播放或内容不可见,则不显示 GuideSteps // 如果不在 VideoProvider 中(videoContext 为 null),则正常显示 const isVisible = baseVisible && (!videoContext || (!videoContext.isVideoPlaying && videoContext.isContentVisible)); // 获取当前步骤的 speaker const currentSpeaker = stepsData[currentStep]?.speaker || "guide"; const currentStepData = stepsData[currentStep]; const currentAudioSrc = currentStepData?.audioSrc; const currentAutoPlayOnEnter = currentStepData?.autoPlayOnEnter ?? false; // 步骤变化时,按需自动播放音频(依赖稳定值,避免循环触发) useEffect(() => { if (!isVisible) return; if (currentAutoPlayOnEnter && currentAudioSrc) { play(currentAudioSrc); } }, [isVisible, currentStep, currentAutoPlayOnEnter, currentAudioSrc, play]); const updateStep = (newStep: number) => { if (!isControlled) { setInternalStep(newStep); } onStepChange?.(newStep); }; const updateVisible = (newVisible: boolean) => { if (visible === undefined) { setInternalVisible(newVisible); } // 隐藏引导时,停止当前 channel 的音频 if (!newVisible) { stop(); } onVisibleChange?.(newVisible); }; // 受控 visible 场景:当外部把 visible 置为 false 时,也需要停止音频 useEffect(() => { if (!isVisible) { stop(); } }, [isVisible, stop]); const handleNext = (e: React.MouseEvent) => { e.stopPropagation(); // 阻止事件冒泡 if (currentStep < totalSteps - 1) { updateStep(currentStep + 1); } }; const handleTextClick = () => { if (currentStep < totalSteps - 1) { updateStep(currentStep + 1); } else { // 最后一步,隐藏组件 updateVisible(false); } }; // 获取当前步骤的高亮选择器 const currentHighlightSelectors = highlightSelectors && highlightSelectors[currentStep] ? highlightSelectors[currentStep] : undefined; // 根据 speaker 选择背景图片 const currentBackgroundPath = currentSpeaker === "student" ? "components/引导板2" : "components/引导板"; // GuideSteps 内容 const guideStepsContent = ( {isVisible && ( {/* 引导板容器和背景 - 作为整体切换,确保 padding 和背景同步 */} {/* 只在 isVisible 为 true 时才渲染,避免阻塞 exit 动画 */} {isVisible && ( {/* 背景层 */}
{/* 引导文本区域 - 只在步骤变化时动画 */}
{steps[currentStep]}
{/* 下一步提示 - 最后一页不显示 */} {currentStep < totalSteps - 1 && (
继续 →
)}
)} )} ); // 始终使用 Overlay 包裹,showMask 由 Overlay 处理 return ( {guideStepsContent} ); }; const GuideStepsItem = ({ children }: GuideStepsItemProps) => { return <>{children}; }; export { GuideSteps, GuideStepsItem };