shanghai-residences/src/components/layout/quiz

Quiz Panel 组件

用于展示单选题和多选题的面板组件，内部管理选择状态，通过 onSubmit 回调通知外部。

组件列表

• SingleChoiceQuizPanel - 单选题面板
• MultipleChoiceQuizPanel - 多选题面板
• QuizPanel - 旧版组件（已废弃，保留以保持向后兼容）

SingleChoiceQuizPanel - 单选题面板

功能特性

• ✅ 内部管理选择状态
• ✅ 点击选项后自动提交
• ✅ 支持答案验证（可选）
• ✅ 自动显示错误提示
• ✅ 提交后禁用交互

使用方法

import { SingleChoiceQuizPanel } from "@/components";

function MyComponent() {
  const [showQuiz, setShowQuiz] = useState(false);

  return (
    <SingleChoiceQuizPanel
      visible={showQuiz}
      title="这是一道单选题：以下哪个选项是正确的？"
      options={[
        { value: "A", label: "选项A" },
        { value: "B", label: "选项B" },
        { value: "C", label: "选项C" },
      ]}
      correctAnswer="B"
      errorMessage="再想一想，注意题干中的时间和提示信息哦～"
      onSubmit={(value, isCorrect) => {
        console.log("用户选择:", value);
        console.log("是否正确:", isCorrect);
        if (isCorrect) {
          // 选择正确，可以关闭面板或进入下一步
          setShowQuiz(false);
        }
      }}
      onError={(error) => {
        console.log("错误信息:", error);
      }}
    />
  );
}

API

属性	类型	默认值	说明
属性	类型	默认值	说明
------	------	--------	------
visible	boolean	-	是否可见（必填）
zIndex	number	10000	z-index 层级
title	string	-	题目（必填）
options	SingleChoiceOption[]	-	选项列表（必填）
correctAnswer	string	-	正确答案（可选，用于验证）
errorMessage	string	"很抱歉，你选错了！请你再思考一下吧！"	自定义错误提示信息（答案错误时显示）
onSubmit	(value: string, isCorrect: boolean) => void	-	提交回调
onError	(error: string) => void	-	错误回调
disabled	boolean	false	是否禁用

行为说明

1. 点击选项：立即触发提交，如果提供了 correctAnswer，会自动验证
2. 答案正确：调用 onSubmit(value, true)，面板进入已提交状态
3. 答案错误：显示错误提示，调用 onError(error) 和 onSubmit(value, false)
4. 未提供正确答案：直接调用 onSubmit(value, true)，不进行验证

MultipleChoiceQuizPanel - 多选题面板

功能特性

• ✅ 内部管理多选状态
• ✅ 支持最小/最大选择数量限制
• ✅ 通过提交按钮提交
• ✅ 支持答案验证（可选）
• ✅ 自动显示错误提示
• ✅ 提交后禁用交互

使用方法

import { MultipleChoiceQuizPanel } from "@/components";

function MyComponent() {
  const [showQuiz, setShowQuiz] = useState(false);

  return (
    <MultipleChoiceQuizPanel
      visible={showQuiz}
      title="这是一道多选题：以下哪些选项是正确的？（可多选）"
      options={[
        { value: "A", label: "选项A" },
        { value: "B", label: "选项B" },
        { value: "C", label: "选项C" },
        { value: "D", label: "选项D" },
      ]}
      correctAnswer={["A", "B"]}
      errorMessage="很抱歉，你选错了！请你再思考一下吧！"
      minSelections={1}
      maxSelections={3}
      minSelectionsErrorMessage="请至少选择 1 项才能提交"
      submitText="确认提交"
      onSubmit={(values, isCorrect) => {
        console.log("用户选择:", values);
        console.log("是否正确:", isCorrect);
        if (isCorrect) {
          setShowQuiz(false);
        }
      }}
      onError={(error) => {
        console.log("错误信息:", error);
      }}
    />
  );
}

API

属性	类型	默认值	说明
属性	类型	默认值	说明
------	------	--------	------
visible	boolean	-	是否可见（必填）
zIndex	number	10000	z-index 层级
title	string	-	题目（必填）
options	MultipleChoiceOption[]	-	选项列表（必填）
correctAnswer	string[]	-	正确答案数组（可选，用于验证）
errorMessage	string	"很抱歉，你选错了！请你再思考一下吧！"	自定义错误提示信息（答案错误时显示）
minSelectionsErrorMessage	string	请至少选择 ${minSelections} 项	自定义最小选择数量不足时的提示信息
onSubmit	(values: string[], isCorrect: boolean) => void	-	提交回调
onError	(error: string) => void	-	错误回调
disabled	boolean	false	是否禁用
minSelections	number	-	最小选择数量
maxSelections	number	-	最大选择数量
submitText	string	"提交"	提交按钮文本

行为说明

1. 选择选项：点击选项进行多选，受 minSelections 和 maxSelections 限制
2. 点击提交：验证最小选择数量，如果提供了 correctAnswer，会验证答案
3. 答案正确：调用 onSubmit(values, true)，面板进入已提交状态
4. 答案错误：显示错误提示，调用 onError(error) 和 onSubmit(values, false)
5. 未提供正确答案：直接调用 onSubmit(values, true)，不进行验证

迁移指南

从旧版 QuizPanel 迁移

旧版用法：

<QuizPanel
  visible={showQuiz}
  title="题目"
  options={options}
  value={quizAnswer}
  error={quizError}
  onChange={(val) => {
    setQuizAnswer(val);
    if (val === "B") {
      setQuizError("");
    } else {
      setQuizError("很抱歉,你选错了!");
    }
  }}
/>

新版用法：

<SingleChoiceQuizPanel
  visible={showQuiz}
  title="题目"
  options={options}
  correctAnswer="B"
  onSubmit={(value, isCorrect) => {
    if (isCorrect) {
      // 选择正确
    } else {
      // 选择错误，错误信息已由组件内部显示
    }
  }}
/>

主要变化

1. 不再需要 onChange：组件内部管理选择状态
2. 不再需要 value 和 error：组件内部管理
3. 使用 onSubmit：替代 onChange，返回用户选择和是否正确
4. 使用 correctAnswer：让组件自动验证答案
5. 使用 onError：可选，用于处理错误信息

注意事项

1. 两个组件都使用内部状态管理，不需要外部传入 value
2. 提交后组件会进入禁用状态，防止重复提交
3. 如果提供了 correctAnswer，组件会自动验证并显示错误信息
4. 多选题的答案比较不考虑顺序，只要选择的选项和正确答案一致即可
5. 旧版 QuizPanel 仍然可用，但建议迁移到新组件