refactor: 横屏提示与缩放改为组件标签（OrientationGuard）

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/App.tsx

@@ -1,17 +1,13 @@
 import { useEffect } from "react";
 import { Outlet } from "react-router-dom";
+import { appConfig } from "@/app.config";
 import { ToastProvider, ToastViewport } from "@/components/ui/toast";
 import { CourseCanvas, useCourseCanvas } from "@/course-runtime/canvas";
+import { OrientationGuard } from "@/course-runtime/orientation";
 import { Navigation } from "./components/business";
-import { LandscapePrompt } from "./components/common";
 import { registerAppPortalRoot } from "./components/common/canvasPortal";
 import { useUserStore } from "./stores";
-import {
+import { isVideoAjaxAvailable } from "./utils";
-	DESIGN_HEIGHT,
-	DESIGN_WIDTH,
-	isVideoAjaxAvailable,
-	useOrientation,
-} from "./utils";
 
 function CourseShell() {
 	const { portalContainer } = useCourseCanvas();
@@ -30,8 +26,6 @@ function CourseShell() {
 }
 
 function App() {
-	const isPortrait = useOrientation();
-
 	useEffect(() => {
 		const params = new URLSearchParams(window.location.search);
 		const courseId = params.get("courseId") ?? params.get("courseid");
@@ -69,10 +63,10 @@ function App() {
 
 	return (
 		<>
-			{isPortrait && <LandscapePrompt />}
+			<OrientationGuard />
 			<CourseCanvas
-				width={DESIGN_WIDTH}
+				width={appConfig.design.width}
-				height={DESIGN_HEIGHT}
+				height={appConfig.design.height}
 				className="bg-gray-900"
 				canvasClassName="flex flex-col overflow-hidden bg-white"
 			>

src/components/common/LandscapePrompt/index.ts

@@ -1 +0,0 @@
-export { LandscapePrompt } from "./LandscapePrompt";

src/components/common/index.ts

@@ -31,5 +31,4 @@ export type {
 	SpotlightController,
 } from "./GuideSpotlight";
 export { defineSpotlight, GuideSpotlight } from "./GuideSpotlight";
-export { LandscapePrompt } from "./LandscapePrompt";
 export { RouteError, RouteFallback } from "./RouteFallback";

src/course-runtime/canvas/useCanvasScale.ts

@@ -6,17 +6,25 @@ interface CanvasScaleOptions {
 	maxScale: number;
 }
 
+function getViewportSize() {
+	if (typeof window === "undefined") {
+		return null;
+	}
+	return {
+		width: window.visualViewport?.width ?? window.innerWidth,
+		height: window.visualViewport?.height ?? window.innerHeight,
+	};
+}
+
 function calculateScale({
 	width,
 	height,
 	maxScale,
 }: CanvasScaleOptions): number {
 	if (typeof window === "undefined") return maxScale;
-	return Math.min(
+	const viewport = getViewportSize();
-		window.innerWidth / width,
+	if (!viewport) return maxScale;
-		window.innerHeight / height,
+	return Math.min(viewport.width / width, viewport.height / height, maxScale);
-		maxScale,
-	);
 }
 
 export function useCanvasScale({
@@ -33,11 +41,15 @@ export function useCanvasScale({
 			setScale(calculateScale({ width, height, maxScale }));
 		updateScale();
 		window.addEventListener("resize", updateScale);
+		window.addEventListener("orientationchange", updateScale);
 		window.visualViewport?.addEventListener("resize", updateScale);
+		window.visualViewport?.addEventListener("scroll", updateScale);
 
 		return () => {
 			window.removeEventListener("resize", updateScale);
+			window.removeEventListener("orientationchange", updateScale);
 			window.visualViewport?.removeEventListener("resize", updateScale);
+			window.visualViewport?.removeEventListener("scroll", updateScale);
 		};
 	}, [height, maxScale, width]);
 

src/course-runtime/orientation/OrientationGuard.tsx

@@ -1,4 +1,7 @@
-export function LandscapePrompt() {
+import type { OrientationGuardProps } from "./OrientationGuard.types";
+import { useOrientation } from "./useOrientation";
+
+function DefaultLandscapePrompt() {
 	return (
 		<div className="fixed inset-0 z-2000 flex items-center justify-center bg-gray-950/80 px-8 text-white">
 			<div className="text-center">
@@ -17,9 +20,18 @@ export function LandscapePrompt() {
 				</div>
 				<h1 className="text-2xl font-semibold">请旋转屏幕</h1>
 				<p className="mt-3 text-base text-gray-400">
-					为获得最佳体验,请横屏浏览
+					为获得最佳体验，请横屏浏览
 				</p>
 			</div>
 		</div>
 	);
 }
+
+export function OrientationGuard({ renderPrompt }: OrientationGuardProps) {
+	const isPortrait = useOrientation();
+
+	if (!isPortrait) return null;
+	if (renderPrompt) return <>{renderPrompt()}</>;
+
+	return <DefaultLandscapePrompt />;
+}

src/course-runtime/orientation/OrientationGuard.types.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from "react";
+
+export interface OrientationGuardProps {
+	/** 竖屏时渲染的自定义提示；不传则用内置的横屏提示 */
+	renderPrompt?: () => ReactNode;
+}

src/course-runtime/orientation/index.ts

@@ -0,0 +1,3 @@
+export { OrientationGuard } from "./OrientationGuard";
+export type { OrientationGuardProps } from "./OrientationGuard.types";
+export { useOrientation } from "./useOrientation";

src/pages/Components/DragDropDemo.tsx

@@ -6,8 +6,8 @@ import {
 	Droppable,
 } from "@/components/course-interactions/drag-drop";
 import { Button } from "@/components/ui/button";
+import { useCourseCanvas } from "@/course-runtime/canvas";
 import { cn } from "@/lib/cn";
-import { useScale } from "@/utils";
 import type {
 	DragDemoItem,
 	DragDemoZone,
@@ -153,7 +153,7 @@ const renderPlacedItem = (item: DragDemoItem) => (
 );
 
 export function DragDropDemo() {
-	const scale = useScale();
+	const { scale } = useCourseCanvas();
 	const [dropResult, setDropResult] = useState<DragDropDemoResult>(null);
 	const [placedItemIds, setPlacedItemIds] = useState<Record<string, string[]>>(
 		{},

src/pages/Components/index.tsx

@@ -5,8 +5,8 @@ import { Button } from "@/components/ui/button";
 import { Overlay, type OverlayProps } from "@/components/ui/overlay";
 import { Portal } from "@/components/ui/portal";
 import { useToast } from "@/components/ui/toast";
+import { useCourseCanvas } from "@/course-runtime/canvas";
 import { useSpotlightStore } from "@/stores";
-import { useScale } from "@/utils";
 import { DragDropDemo } from "./DragDropDemo";
 
 type OverlayDemoKey =
@@ -113,7 +113,7 @@ export default function Components() {
 			? customRootRef
 			: getAppPortalRoot;
 	const toast = useToast();
-	const scale = useScale();
+	const { scale } = useCourseCanvas();
 
 	const startGuideSpotlight = () => {
 		useSpotlightStore.getState().startSpotlight({

src/utils/index.ts

@@ -1,6 +1,4 @@
 export * from "./assets";
 export * from "./lazyRoute";
 export * from "./tailwind";
-export * from "./useOrientation";
-export * from "./useScale";
 export * from "./yiban";

src/utils/useScale.ts

@@ -1,43 +0,0 @@
-import { useCallback, useEffect, useState } from "react";
-import { appConfig } from "@/app.config";
-
-export const DESIGN_WIDTH = appConfig.design.width;
-export const DESIGN_HEIGHT = appConfig.design.height;
-
-function getViewportSize() {
-	if (typeof window === "undefined") {
-		return { width: DESIGN_WIDTH, height: DESIGN_HEIGHT };
-	}
-	return {
-		width: window.visualViewport?.width ?? window.innerWidth,
-		height: window.visualViewport?.height ?? window.innerHeight,
-	};
-}
-
-export function useScale() {
-	const calculateScale = useCallback(() => {
-		const viewport = getViewportSize();
-		return Math.min(
-			viewport.width / DESIGN_WIDTH,
-			viewport.height / DESIGN_HEIGHT,
-			appConfig.scale.max,
-		);
-	}, []);
-	const [scale, setScale] = useState(calculateScale);
-
-	useEffect(() => {
-		const updateScale = () => setScale(calculateScale());
-		window.addEventListener("resize", updateScale);
-		window.addEventListener("orientationchange", updateScale);
-		window.visualViewport?.addEventListener("resize", updateScale);
-		window.visualViewport?.addEventListener("scroll", updateScale);
-		return () => {
-			window.removeEventListener("resize", updateScale);
-			window.removeEventListener("orientationchange", updateScale);
-			window.visualViewport?.removeEventListener("resize", updateScale);
-			window.visualViewport?.removeEventListener("scroll", updateScale);
-		};
-	}, [calculateScale]);
-
-	return scale;
-}