@librex/education-web
v2.0.0
Published
LibreX Education Web — question editing, rendering and grading components
Maintainers
Readme
@librex/education-web
Vue 3 题库编辑和展示组件,提供 QuestionEditor、QuestionRenderer 与题目导入校验。数据契约来自 @librex/education-core,富文本能力来自 @librex/rich-web;本包不属于通用 librex-ui。
安装
npm install @librex/education-web @librex/education-core @librex/rich-web librex-ui vue如需渲染本包组件样式,在应用入口导入一次:
import '@librex/education-web/styles.css'vue、librex-ui 和 vue-i18n 是 peer dependencies。当前版本及范围见本包 package.json。
编辑题目
<script setup lang="ts">
import { QuestionEditor } from '@librex/education-web'
import { createDefaultQuestionData } from '@librex/education-core'
const question = createDefaultQuestionData('single')
</script>
<template>
<QuestionEditor v-model="question" />
</template>编辑器使用 QuestionData 草稿模型。保存前由应用将草稿转换为自己的持久化格式;本包不提供后端存储、身份权限或业务发布 API。
分值允许为 null,表示只判对错、不计分。开发者传 :show-score="false" 时,编辑器隐藏
分值设置,getData() / 更新事件输出 score:null,内置预览同样隐藏分值。已有题目显式传入
score:null 也会保留,清空分值输入可取消计分;数字 0 仍是零分题。无构建宿主使用
showScore:false。示例:
<QuestionEditor v-model="question" :show-score="false" />原生 question/3 的不计分题必须让所有区域的 score 同为 null,使用
questionDataToV3() 转换时自动保持一致。判题返回独立 correct 字段;score / maxScore
为 null 时显示“回答正确 / 回答错误”,不显示分数。手工或 AI 评阅规则尚无确定结论时继续
待评阅,不能把“不计分”解释成自动正确。历史 dwmg 的 easy_score 是难度值,不再当作分值。
选择是否接入讲解制作
NativeQuestionWorkbench 的 enableExplanation 由开发者在接入时明确配置,且为必填项。
传 false 时不显示或挂载讲解制作面板,也不调用 readExplanations;题目编辑、预览、保存和发布继续使用原有流程。
页面不提供教师开关,也不读取浏览器中保存的讲解显示偏好。
<NativeQuestionWorkbench
:question-id="questionId"
:transport="transport"
:enable-explanation="false"
/>无构建宿主使用同名配置:
LibrexEducation.mountNativeQuestionWorkbench('#workbench', {
questionId,
transport,
enableExplanation: false,
})需要讲解制作时传 true;不接入时传 false。宿主配置类型 NativeQuestionWorkbenchProps 从包根入口导出。
展示题目
<script setup lang="ts">
import { QuestionRenderer } from '@librex/education-web'
import type { QuestionData } from '@librex/education-core'
defineProps<{ data: QuestionData }>()
</script>
<template>
<QuestionRenderer :data="data" />
</template>只读/作答展示使用 QuestionRenderer。公开题目文档应先使用 @librex/education-core 的 inspectQuestionDocument() 校验,再调用 projectStudentQuestion() 投影学生数据;此投影契约与旧式 QuestionData 编辑草稿不同,转换到宿主展示模型由应用负责。
填空作答与共享公式键盘
行内填空统一使用 MathLive。空位按内容增宽并保留最小宽度;纯文本答案超出题干宽度时在输入框内自动换行、增高。分数、根式等公式保持结构布局,超宽公式在输入框内横向滚动。
clozeBlank / responseAnchor 的 attrs.blankStyle 可选 underline(默认)、grid(田字格)和 box(方框),HTML 对应 data-blank-style。编辑和只读时显示居中的占位序号,学生在同一空位直接输入;田字格外框为实线、内部十字为虚线。外观元数据不进入学生答案或评分值。
田字格的插入预览和 MathLive 纯文字作答采用正体习字排版,多字一字一格。字体优先级为“华文正楷”、STKaiti(华文楷体)、“华文楷体”、Kaiti SC、serif;本机 Chrome 已核实实际命中 STKaiti。框架不附带商业字库;宿主若使用另有授权的“华文正楷”字库,可通过全局 @font-face 注册该名称,或设置 --rich-cloze-grid-font-family。--rich-cloze-grid-font-size 和 --rich-cloze-grid-cell-size 默认分别为 20px、32px,这些是界面排版默认值,不是国家标准规定的尺寸。宿主可在包含预览/作答的容器上设置变量;插入弹窗 Teleport 到 body 时,应在根主题作用域提供同样变量。
中文输入法和粘贴可能让 MathLive 输出裸汉字(如 我)或 \text{我};两者均使用同样的田字格字体和排版,不要求宿主改写答案。含分数、上下标等数学结构的输入仍按公式排版。
用字规范依据为国务院公布的《通用规范汉字表》。切换字体不转换、删改教师答案;它不构成对特定字体文件字形或教材审定的认证。
每个题干默认只在顶部右侧显示一个纯图标键盘按钮,悬停或键盘聚焦时提示“显示公式键盘 / 隐藏公式键盘”,空位内不重复显示键盘和菜单图标。按钮操作最近聚焦的空位;还没有聚焦空位时选择第一个可作答空位。
开发者用 responseKeyboardTarget 指定一个已存在的宿主容器,按钮便会移到该容器,不重复生成第二个入口。位置与固定方式由宿主布局决定;省略配置时保留题干顶部右侧的默认位置。RichWeb、NativeQuestionPlayer、NativeQuestionPreview、NativeQuestionSession、QuestionRenderer、QuestionEditor 和 NativeQuestionWorkbench 均支持该配置。
<div id="answer-toolbar" />
<NativeQuestionPlayer
:question="studentQuestion"
v-model="responses"
response-keyboard-target="#answer-toolbar"
/>PHP/无构建宿主同样支持,不需要编写 Vue 插槽:
// #answer-toolbar 与 #workbench 由宿主先创建。
LibrexEducation.mountNativeQuestionWorkbench('#workbench', {
questionId,
transport,
enableExplanation: false,
responseKeyboardTarget: '#answer-toolbar',
})需要自定义按钮外观时,RichWeb、NativeQuestionPlayer 和 QuestionRenderer 仍提供 response-tools 插槽。插槽参数为 toggle()、open、disabled,不需要自行管理 MathLive 焦点;也可用 Vue Teleport 搭配宿主布局:
<script setup lang="ts">
import { KeyboardIcon } from '@lucide/vue'
import { LButton, LTooltip } from 'librex-ui/components'
// studentQuestion 和 responses 由宿主提供。
</script>
<template>
<!-- 先创建宿主容器,可放在页面顶部、侧栏或其他工具栏中。 -->
<div id="answer-toolbar" />
<NativeQuestionPlayer :question="studentQuestion" v-model="responses">
<template #response-tools="{ toggle, open, disabled }">
<Teleport to="#answer-toolbar">
<LTooltip :content="open ? '隐藏公式键盘' : '显示公式键盘'">
<LButton
:icon-component="KeyboardIcon"
:aria-label="open ? '隐藏公式键盘' : '显示公式键盘'"
:pressed="open"
:disabled="disabled"
variant="ghost"
size="sm"
@pointerdown.prevent
@click="() => toggle()"
/>
</LTooltip>
</Teleport>
</template>
</NativeQuestionPlayer>
</template>#answer-toolbar 由宿主预先创建,位置与固定方式由宿主决定。插槽替换默认入口,因此不会多出第二个按钮;切换键盘仍会回到最近作答的空位。普通宿主不传插槽即可使用默认入口。
方程组/分段函数入口位于 MathLive 键盘内的“公式”分类,默认界面只保留共享键盘图标。底层 RichWeb 的
responseTemplates 可替换该分类模板;新增模板必须使用 MathLive 已支持的语法,不改变题目或作答协议。
其他导出
validateQuestionImport():检查待导入题目并返回校验结果。QUESTION_TYPES、DEFAULT_LABELS:题目类型目录与默认标签。checkMathCloze()、htmlToPlainText():公式填空和文本投影工具。useQuestionSync():Vue 编辑器同步 composable。
表单 Props、事件和回调类型从 @librex/education-web 的 TypeScript 根入口导入;类型契约与题目转换见 @librex/education-core。完整说明见包 API 文档。
