@tiku-canpoint/qp-component-ui

@tiku-canpoint/qp-component-ui

试题组件库 - 基于 Vue3，提供试题卡片和无头试题组件，支持 LaTeX 数学公式渲染。

安装

npm install @tiku-canpoint/qp-component-ui
# 或
pnpm add @tiku-canpoint/qp-component-ui

前置要求

• Vue 3.3.0+

完整引入

// main.ts
import { createApp } from 'vue'
import QpComponentUI from '@tiku-canpoint/qp-component-ui'
import '@tiku-canpoint/qp-component-ui/dist/style.css'

const app = createApp(App)
app.use(QpComponentUI)
app.mount('#app')

按需引入

<script setup>
import { QpQuestionCard } from '@tiku-canpoint/qp-component-ui'
</script>

组件

qp-question-card 试题卡片

试题卡片主容器组件，支持多种题型渲染、LaTeX 数学公式、答案解析显示、自定义插槽等。

功能特性

• ✅ 多题型支持：单选题、多选题、填空题、判断题、简答题、综合题、完形填空、听力题等
• ✅ LaTeX 公式渲染：自动加载 KaTeX，支持行内 $...$ 和块级 $$...$$ 公式
• ✅ 答案解析：支持显示/隐藏答案、解析、考点、专题
• ✅ 子题支持：综合题自动渲染子题
• ✅ 自定义插槽：头部、底部、操作区域、标签区域均可自定义
• ✅ 响应式设计：适配不同屏幕尺寸

Props

Events

Slots

基础用法

<template>
  <qp-question-card
    :questionData="questionData"
    :questionNum="1"
    :showExplain="false"
    :showTopInfo="true"
  />
</template>

<script setup>
import { QpQuestionCard } from '@tiku-canpoint/qp-component-ui'

const questionData = {
  questionId: 'Q001',
  quesStruct: { code: 11, name: '单选题' },
  quesType: { code: 11, name: '单选题' },
  context: {
    stem: '已知函数 $f(x) = x^2 - 2x + 1$，则 $f(2)$ 的值为（  ）',
    options: ['$0$', '$1$', '$2$', '$4$'],
  },
  explain: [{
    answers: [['B']],
    analysis: '将 $x = 2$ 代入：$f(2) = 2^2 - 2 \\times 2 + 1 = 1$，故选 B。',
  }],
  knowledge: [{ code: 'K001', name: '函数求值' }],
  difficulty: { code: 2, name: '中等' },
  level: 2,
}
</script>

使用插槽

<template>
  <qp-question-card :questionData="questionData">
    <!-- 自定义头部 -->
    <template #header="{ question }">
      <span>难度：{{ question.difficulty?.name }}</span>
    </template>

    <!-- 自定义底部 -->
    <template #footer="{ question }">
      <span>试题 ID: {{ question.questionId }}</span>
    </template>

    <!-- 底部操作按钮 -->
    <template #bottomActionArea="{ question }">
      <button @click.stop="handleEdit(question)">编辑</button>
      <button @click.stop="handleDelete(question)">删除</button>
    </template>
  </qp-question-card>
</template>

展开回调（异步加载详情）

当试题数据需要异步加载时，可以传入 onExpandExplain 回调函数，在点击展开答案解析时执行。常用于按需加载试题详情接口：

<template>
  <qp-question-card
    :questionData="questionData"
    :questionNum="1"
    :showExplain="false"
    :onExpandExplain="handleExpandExplain"
  />
</template>

<script setup>
import { ref } from 'vue'
import { QpQuestionCard } from '@tiku-canpoint/qp-component-ui'
import { getQuestionDetail } from '@/api/question'

const questionData = ref({
  questionId: '12345',
  // ... 基础试题数据（可能不包含完整的答案解析）
})

// 展开答案解析时的回调 - 异步加载完整试题详情
const handleExpandExplain = async (question, isExpanded) => {
  if (isExpanded && !question.explain) {
    try {
      // 调用接口获取完整的试题详情（包含答案解析）
      const detail = await getQuestionDetail(question.questionId)

      // 更新试题数据，组件会自动渲染答案解析
      questionData.value = {
        ...questionData.value,
        explain: detail.explain,
        knowledge: detail.knowledge,
        specialSubject: detail.specialSubject,
      }
    } catch (error) {
      console.error('加载试题详情失败', error)
    }
  }
}
</script>

注意事项：

• 回调支持异步函数（Promise），组件会等待回调完成后再展开显示
• 如果回调执行失败（抛出异常），组件会捕获错误并继续展开
• 回调仅在展开时（isExpanded = true）触发，收起时不会触发

无头组件

useQuestion

无头试题组件，提供试题解析逻辑，不包含 UI 渲染。

功能特性

• ✅ 试题题干解析
• ✅ 答案解析生成
• ✅ 显示规则控制
• ✅ 数学公式渲染支持
• ✅ 展开回调（异步加载详情）

Options

返回值

stem 属性

answer 属性

用法

<template>
  <div>
    <!-- 题干 -->
    <div v-if="stem.showStem" v-html="stem.stemHtml"></div>

    <!-- 选项 -->
    <div v-if="stem.showOptions">
      <div v-for="(option, index) in stem.options" :key="index">
        <span v-html="stem.getOptionHtml(option, index)"></span>
      </div>
    </div>

    <!-- 答案 -->
    <div>
      <div v-for="(item, index) in answer.answerList" :key="index" v-html="item"></div>
    </div>

    <!-- 解析 -->
    <div>
      <div v-for="(item, index) in answer.analysisList" :key="index" v-html="item"></div>
    </div>

    <!-- 考点 -->
    <div v-if="answer.knowledgeList.length">
      【考点】
      <span v-for="item in answer.knowledgeList" :key="item.code">{{ item.name }}</span>
    </div>
  </div>
</template>

<script setup>
import { useQuestion } from '@tiku-canpoint/qp-component-ui'

const questionData = {
  questionId: 'Q001',
  quesStruct: { code: 11, name: '单选题' },
  context: {
    stem: '已知函数 $f(x) = x^2$，则 $f(2)$ 的值为',
    options: ['$0$', '$1$', '$2$', '$4$'],
  },
  explain: [{
    answers: [['D']],
    analysis: '将 $x = 2$ 代入：$f(2) = 2^2 = 4$',
  }],
  knowledge: [{ code: 'K001', name: '函数求值' }],
}

const { stem, answer } = useQuestion({ question: questionData })
</script>

展开回调（异步加载详情）

使用组合式函数时，可以传入 onExpandExplain 回调，在展开答案解析时执行异步操作：

<template>
  <div ref="cardRef" class="question-card">
    <!-- 题干 -->
    <div v-if="stem.showStem" v-html="stem.stemHtml"></div>
    <div v-if="stem.showOptions">
      <div v-for="(option, index) in stem.options" :key="index">
        <span v-html="stem.getOptionHtml(option, index)"></span>
      </div>
    </div>

    <!-- 加载中提示 -->
    <div v-if="isExpanding" class="loading">加载试题详情中...</div>

    <!-- 答案解析 -->
    <div v-if="isShowExplain">
      <div v-for="item in answer.answerList" :key="item" v-html="item"></div>
    </div>

    <button @click="toggleExplain" :disabled="isExpanding">
      {{ isExpanding ? '加载中...' : (isShowExplain ? '收起解析' : '展开解析') }}
    </button>
  </div>
</template>

<script setup>
import { ref, computed, onMounted } from 'vue'
import { useQuestion } from '@tiku-canpoint/qp-component-ui'
import { getQuestionDetail } from '@/api/question'

const cardRef = ref(null)
const questionData = ref({
  questionId: '12345',
  // ... 基础试题数据
})

const questionRef = computed(() => questionData.value)

// 展开回调 - 异步加载试题详情
const handleExpandExplain = async (question, isExpanded) => {
  if (isExpanded && !question.explain) {
    const detail = await getQuestionDetail(question.questionId)
    questionData.value = {
      ...questionData.value,
      explain: detail.explain,
      knowledge: detail.knowledge,
      specialSubject: detail.specialSubject,
    }
  }
}

const {
  stem,
  answer,
  isShowExplain,
  isExpanding, // 回调执行中为 true
  toggleExplain,
  katex,
} = useQuestion({
  question: questionRef,
  showExplain: false,
  onExpandExplain: handleExpandExplain,
})

onMounted(() => {
  katex.render(cardRef.value)
})
</script>

注意事项：

• 回调支持异步函数（Promise），组件会等待回调完成后再展开显示
• 如果回调执行失败（抛出异常），组件会捕获错误并继续展开
• 回调仅在展开时（isExpanded = true）触发，收起时不会触发
• isExpanding 属性可用于显示加载状态（回调执行中为 true）
• 按钮可以使用 :disabled="isExpanding" 防止重复点击

LaTeX 公式支持

组件自动渲染 LaTeX 数学公式，支持以下格式：

• 行内公式：$...$ 或 \(...\)
• 块级公式：$$...$$ 或 \[...\]

预加载 KaTeX（可选）

使用 qp-katex-loader 组件提前加载 KaTeX，避免公式渲染延迟：

<template>
  <qp-katex-loader>
    <qp-question-card :questionData="questionData" />
  </qp-katex-loader>
</template>

<script setup>
import { QpKatexLoader, QpQuestionCard } from '@tiku-canpoint/qp-component-ui'
</script>

自定义 CDN

<template>
  <qp-katex-loader baseUrl="https://unpkg.com">
    <qp-question-card :questionData="questionData" />
  </qp-katex-loader>
</template>

使用本地 KaTeX

import katex from 'katex'
import renderMathInElement from 'katex/contrib/auto-render'
import { configure } from '@tiku-canpoint/qp-component-ui'

window.katex = katex
window.renderMathInElement = renderMathInElement

configure({ loadStrategy: 'none' })

数据类型

Question 试题数据

interface Question {
  /** 试题 ID */
  questionId: string;
  /** 题型结构 */
  quesStruct: {
    code: number;
    name: string;
  };
  /** 题型信息 */
  quesType?: {
    code: number;
    name: string;
  };
  /** 试题上下文 */
  context: {
    /** 题干 */
    stem: string;
    /** 选项 */
    options?: string[];
    /** 听力原文 */
    original_text?: string;
    /** 音频 URL */
    audioUrl?: string;
    /** 音频名称 */
    audioName?: string;
  };
  /** 解析 */
  explain?: QuestionExplain[];
  /** 考点 */
  knowledge?: Knowledge[];
  /** 专题 */
  specialSubject?: Knowledge[];
  /** 子题（综合题） */
  children?: Question[];
  /** 难度 */
  difficulty?: {
    code: number;
    name: string;
  };
  /** 等级 */
  level?: number;
  /** 标签 */
  tagPaper?: {
    year?: number;
    area?: string;
    paperType?: string;
  };
  /** 来源 */
  source?: string;
  /** 分数 */
  score?: number;
}

QuestionExplain 答案解析

interface QuestionExplain {
  /** 答案（二维数组支持多选、多空） */
  answers: string[][];
  /** 解析（支持 HTML 和 LaTeX） */
  analysis?: string;
  /** 点评 */
  comment?: string;
}

Knowledge 考点/专题

interface Knowledge {
  code: string;
  name: string;
}

MetaInfo 元信息

interface MetaInfo {
  label: string;
  value: string;
}

支持题型