# 答题卡

## 功能概述

本模块主要用于接收和处理讲师、助教和管理员等用户发起的答题卡，方便接入方实现题目处理展示、观众答题和结果显示等功能。

答题卡分为普通答题和快速问答。

* 快速问答只有单选/多选答题形式。
* 普通答题功能较为齐全，包含单选、多选、评分和投票题目，还可以使用答题限时功能，答题者需在限定时间内进行答题。

## 初始化及销毁

在实例化该模块并进行使用之前，需要对SDK进行初始化配置，详细见[参考文档](https://git.polyv.net/help-center/document-center/-/blob/master/live/js/new_sdk/interactions_receive_sdk/sdk/overview/README.md#初始化)。

#### 在线文件引入方式

```html
// script 标签引入，根据版本号引入JS版本。
<script src="https://websdk.videocc.net/interactions-receive-sdk/0.24.0/lib/polyv-ir.umd.js"></script>

<script>
    const { AnswerCard } = window.PolyvIRSDK;
</script>
```

#### import 方式引入（推荐）

```javascript
import { AnswerCard } from '@polyv/interactions-receive-sdk';

const answerCardSdk = new AnswerCard();
// ...
// 销毁 SDK 实例，清除逻辑
answerCardSdk.destroy();
```

## 使用流程

### 监听“答题开始”事件

当讲师/助教等发起端发起一次答题卡时，会触发 SDK 的 `answerCardSdk.events.GET_TEST_QUESTION_CONTENT` 事件，该事件含有答题卡相关信息，包括答题卡类型、题目、选项及是否限时题目等，可以将对应信息展示给用户用于作答。

```javascript
answerCardSdk.on(answerCardSdk.events.GET_TEST_QUESTION_CONTENT, function(msg) {
  console.log('接收到答题开始事件', msg，'题目：', msg.name, '题目限时：', msg.duration);
});
```

展示答题卡题目时，可以根据答题卡类型和题目类型做不同的展示：

* `answerCardSdk.questionItemTypes` 下的属性表示答题卡类型列表（快速问答、普通答题）。将其属性值与 `msg.itemType` 的值进行对比，就可以知道当前是哪种答题卡。
* `answerCardSdk.questionTypes` 下的属性表示题目具体类型（单选、多选、评分或者投票类型）。将其属性值与 `msg.type` 的值对比，就可以知道当前题目的具体类型。

例如：

```javascript
function questionHandler(msg) {
  if (msg.itemType === answerCardSdk.questionItemTypes.QuickAnswerCard) {
    const questionType = {
      [answerCardSdk.questionTypes.CheckBox]: '多选题',
      [answerCardSdk.questionTypes.Radio]: '单选题',
    }[msg.type];
    console.log('本次答题卡为快速问答, 题目类型为: ' + questionType);
  } else if (msg.itemType === answerCardSdk.questionItemTypes.Normal) {
    const questionType = {
      [answerCardSdk.questionTypes.CheckBox]: '多选题',
      [answerCardSdk.questionTypes.Radio]: '单选题',
      [answerCardSdk.questionTypes.Score]: '评分题',
      [answerCardSdk.questionTypes.Vote]: '投票题',
    }[msg.type];
    console.log('本次答题卡为普通答题, 题目类型为: ' + questionType);
  }
}
answerCardSdk.on(answerCardSdk.events.GET_TEST_QUESTION_CONTENT, questionHandler);
```

对于限时题目，可以通过 `answerCardSdk.getServerTime()` 获取服务端当前剩余时间，在必要的时候进行同步。

```javascript
const data = await answerCardSdk.getServerTime();
console.log('剩余时间', data.time);
```

### 提交用户答案

如果当前正在答题，可使用 `answerCardSdk.answerQuestion` 将用户答案提交给服务端。该方法是异步方法，参数是用户所选选项的字符串数组（大写），根据返回结果 code 字段展示不同的提示信息。code 的值所表示的状态见 API 文档中 `answerCardSdk.answerQuestionResCode` 的属性。

```javascript
const res = await answerCardSdk.answerQuestion(['A', 'B']);
if (res.code === answerCardSdk.answerQuestionResCode.SubmitSuccess) {
  console.log('提交成功');
}
```

### 监听“答题结束”事件

发起端停止答题，或限时题目倒计时结束时，`answerCardSdk.events.STOP_TEST_QUESTION` 会被触发，此时需要将正在显示的题目关闭、或者显示截止答题等提示。

```javascript
answerCardSdk.on(answerCardSdk.events.STOP_TEST_QUESTION, function(msg) {
  console.log('答题结束', msg);
});
```

### 监听“答题结果”事件

在讲师发送结果后，SDK 将触发 `answerCardSdk.events.GET_TEST_QUESTION_RESULT` 事件，该事件含有题目内容、题目答案和选项人数等，可基于这些信息，与用户个人答案进行对比，展示用户答题结果。

```javascript
answerCardSdk.on(answerCardSdk.events.GET_TEST_QUESTION_RESULT, function(msg) {
  console.log('答题结果', msg);
});
```

可使用 `answerCardSdk.curSubmittedAnswer`（string类型） 获取用户当前题目的个人已提交答案，与正确答案进行对比。

### 注意

如果不需要再使用答题卡 SDK 时，请调用 SDK 实例的 destroy 方法去销毁实例。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://polyv.gitbook.io/document/docs/live/js/new-sdk/interactions-receive-sdk/sdk/answer_card.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.