旧 v1/v2 问题格式

!!! warning “已弃用”

本页介绍 v1 和 v2 中使用的旧 ZJUI-Learn 问题格式。该问题格式将无限期支持，但强烈建议所有新问题都以[v3格式](question/overview.md)编写。

部分学分

默认情况下，所有 v1/v2 问题均不授予部分学分。也就是说，学生对该问题要么得零分，要么得满分。问题评分函数（见下文）可以生成 0 到 1 范围内的小数分数，但随后会四舍五入到 0 或 1，以不得分或满分。低于 0.5 的分数将向下舍入为 0，而等于或高于 0.5 的分数将向上舍入为 1。例如，如果问题评分函数对于 10 分问题返回 0.3，则这将导致 0 分，而同一问题的评分为 0.7 将得到 10 分。

要为问题提供实际的部分学分，请在问题的 info.json 文件中设置 "partialCredit": true。例如，这将使 10 分问题的 0.3 分奖励 3 分。

v1/v2 格式的问题类型

ZJUI-Learn v1/v2 中的问题可以有以下类型。

问题类型	描述
MultipleChoice	多项选择题（单选按钮）。从正确答案和错误答案列表中选出一个正确答案和几个错误答案，顺序是随机的。
MultipleTrueFalse	多项选择题（单选按钮）。从正确答案和错误答案列表中选出一个正确答案和几个错误答案，顺序是随机的。
Checkbox	一道选择题(checkbox)。从正确和错误答案列表中选择多个正确和错误答案，并且顺序是随机的。
File	向学生提供一个文件供下载，他们必须上传编辑后的文件进行评分。
Calculation	一种非常通用的问题类型，允许服务器端和客户端代码生成问题并对其进行评分。

有关每种问题类型的详细信息，请参阅下文。

MultipleChoice 题型

• 示例：fossilFuelsRadio
• 所需文件：info.json
• 选项架构文档：MultipleChoice 选项

MultipleChoice 问题的 info.json 提供问题文本、一个或多个正确答案以及一个或多个错误答案。随机选择一个正确答案，并有足够多的错误答案组成 numberAnswers 总答案，然后以随机顺序向学生显示。例如：

info.json

{
  "title": "Advantages of fossil fuels (radio)",
  "topic": "Energy",
  "tags": ["comparative advantages", "fossil fuels", "renewables"],
  "type": "MultipleChoice",
  "options": {
    "text": "Which of the following is an advantage of fossil fuels relative to renewable energy sources?",
    "correctAnswers": ["Cheap", "High energy density", "Provide energy on demand"],
    "incorrectAnswers": [
      "Non-polluting",
      "Low energy density",
      "Low production of carbon dioxide",
      "High production of carbon dioxide",
      "Secure",
      "Sustainable",
      "Low energy return"
    ],
    "numberAnswers": 5
  }
}

MultipleTrueFalse 题型

• 示例：fossilFuelsTrueFalse
• 所需文件：info.json
• 选项架构文档：MultipleTrueFalse 选项

MultipleTrueFalse 问题有一个 info.json，它提供问题文本、零个或多个正确陈述以及零个或多个错误陈述。所有给定的陈述均被使用，并以随机顺序向学生显示。例如：

info.json

{
  "title": "Advantages of fossil fuels (MTF)",
  "topic": "Energy",
  "tags": ["comparative advantages", "fossil fuels", "renewables"],
  "type": "MultipleTrueFalse",
  "options": {
    "text": "For each of the following statements, select whether it is true or false.",
    "trueStatements": [
      "Cheapness is an advantage of fossil fuels relative to renewable energy sources."
    ],
    "falseStatements": [
      "This is a false statement",
      "This is another false statement",
      "Frugalness is an advantage of fossil fuels relative to renewable energy sources for its frugality and other various conditions that are consequences of frugality."
    ],
    "correctScore": 1,
    "incorrectScore": 0,
    "guessingPenalty": -1
  }
}

Checkbox 题型

• 示例：fossilFuelsCheckbox
• 所需文件：info.json
• 选项架构文档：Checkbox 选项

Checkbox 问题的 info.json 提供问题文本、一个或多个正确答案以及一个或多个错误答案。随机选择几个正确答案（在 minCorrectAnswers 和 maxCorrectAnswers 之间，包括在内），以及足够的错误答案以形成 numberAnswers 总答案，然后以随机顺序向学生显示。根据 minCorrectAnswers 和 maxCorrectAnswers 的值，所有可能的答案可能都是正确的，也可能都不正确。例如：

info.json

{
  "title": "Advantages of fossil fuels (checkbox)",
  "topic": "Energy",
  "tags": ["comparative advantages", "fossil fuels", "renewables"],
  "type": "Checkbox",
  "options": {
    "text": "Which of the following are advantages of fossil fuels relative to renewable energy sources? Select all that apply.",
    "correctAnswers": ["Cheap", "High energy density", "Provide energy on demand"],
    "incorrectAnswers": [
      "Non-polluting",
      "Low energy density",
      "Low production of carbon dioxide",
      "High production of carbon dioxide",
      "Secure",
      "Sustainable",
      "Low energy return"
    ],
    "numberAnswers": 5,
    "minCorrectAnswers": 1,
    "maxCorrectAnswers": 3
  }
}

File 题型

• 示例：fibonacciExternal
• 所需文件：info.json、question.html、answer.html
• 选项架构文档：File 选项

File 问题为学生提供了一个可供下载的文件，然后需要上传的文件作为答案。下载的文件在 info.json 中指定，如下所示：

info.json

{
  "title": "Write a Fibonacci function",
  "topic": "Functions",
  "tags": ["recursion"],
  "clientFiles": ["client.js", "question.html", "answer.html", "fib.py"],
  "type": "File",
  "options": {
    "fileName": "fib.py"
  }
}

请注意，文件问题也可以利用外部评分！请参阅外部评分文档。

Calculation 题型

• 示例：addVectors
• 所需文件：info.json、client.js、server.js
• 选项架构文档：Calculation 选项

Calculation 问题是最常见的问题类型，允许任意代码在服务器上生成问题实例并对其进行评分，并允许任意客户端代码与学生交互（例如，用于交互式绘图）。

Calculation 问题：server.js

server.js 是在服务器上运行的代码（客户端不会直接看到），它生成问题并对答案进行评分。

它可以随机（或系统）创建问题变量。它们存储在 server.getData() 返回的 JSON 元素中

在 server.getData() 函数中创建问题变量时定义答案是标准做法，但这不是必需的。

名为 server.gradeAnswer() 的函数可以接收参数以及提交的答案并返回分数和反馈。

define(['PrairieRandom'], function (PrairieRandom) {
  var server = {};

  server.getData = function (vid) {
    var rand = new PrairieRandom.RandomGenerator(vid);
    var a = rand.randInt(5, 10);
    var b = rand.randInt(5, 10);
    var c = a + b;
    var params = {
      a: a,
      b: b,
    };
    var trueAnswer = {
      c: c,
    };
    var questionData = {
      params: params,
      trueAnswer: trueAnswer,
    };
    return questionData;
  };

  server.gradeAnswer = function (vid, params, trueAnswer, submittedAnswer, options) {
    var score = 0;
    if (PrairieGeom.checkEqual(trueAnswer, submittedAnswer, 1e-2, 1e-8)) score = 1;
    return { score: score };
  };

  return server;
});

与每个问题相关的三个主要对象是：

对象	描述
params	指定特定问题实例的参数。
submittedAnswer	学生为回答问题而提交的所有内容。
trueAnswer	问题的正确答案，在问题评分后向学生显示。

这些都是 JavaScript 对象，编码为 JSON，以便在客户端和服务器之间传输。

Calculation 问题：client.js

JavaScript 向客户端呈现显示问题。如果使用专用接口，则可以重载/扩展。

不同的问题类型有不同的客户端 JavaScript 需求，因此只需从问题的默认模板中复制它即可。

Calculation 问题：question.html

question.html 包含呈现给学生的 HTML 数据。它是问题框内的内容，包括问题和用于回答问题的任何输入表单。不需要提交按钮（或其他表单设置）。

这里接受标准 HTML，以及用美元符号括起来的 LaTeX 数学，例如 $e^{i\pi} + 1 = 0$。

问题服务器生成的参数可以插入{{params.a}}等。

编写问题的最佳做法是将其分为三个部分：

1. 有关问题的信息、定义所有变量等。
2. 一个简短而明确的问题，要求一个非常具体的答案。
3. 数据输入字段。

例如：

<p>The length $c$ is defined by $c = {{params.a}}{\rm\ m} + {{params.b}}{\rm\ m}$.</p>
<p>What is $c$?</p>
<p>$c = $ <input data-instavalue="submittedAnswer.c" />$\rm\ m$</p>

Calculation 问题：answer.html

问题评分后向学生显示的框中的部分。

<p>$c = {{trueAnswer.c}}\rm\ m$.</p>

通过 RequireJS 从代码访问文件

这些库文件分为_client_ 和_server_ 库。每个问题中的客户端库都可以从 client.js 和 server.js 访问，而服务器库只能从 server.js 访问。这意味着学生不应访问的任何秘密代码都可以放入服务器库中，而其他非敏感代码可以放入客户端库中。永远不需要将库文件放入客户端和服务器目录中，因为它只能进入客户端目录并由 client.js 和 server.js 直接从那里访问。

library.js 文件的基本形式是：

define([<DEPENDENT-LIBRARIES-PATHS>], function(<DEPENDENT-LIBRARY-VARS>) {

    var library = {};

    library.add = function(arg1, arg2) {
        return arg1 + arg2;
    };

    // more library functions go here

    return library;
});

要在问题的 client.js 或 server.js 文件中使用此 library.js 文件：

define([<OTHER-LIBRARY-PATHS>, 'clientCode/library'], function(<OTHER-LIBRARY-VARS>, library) {

    var sum = library.add(3, 5); // sets sum to 8

});

已弃用的访问模式

为了支持旧代码，clientFilesCourse 也可以通过 clientFiles 和 clientCode 进行访问，而 serverFilesCourse 可以通过 serverCode 进行访问。

库代码和其他文件

有关从问题代码中访问 clientFiles 和 serverFiles 目录的信息，请参阅 clientFiles 和 serverFiles。