# @bdelab/roar-firekit 中文文档

规范地址：https://npmcn.com/package/%40bdelab/roar-firekit/

版本：9\.17\.0
npm 元数据更新时间：2026-06-25T22:39:10.666Z
中文译文更新时间：2026-11-07T19:19:33.222Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bdelab/roar-firekit
原文对照：https://npmcn.com/package/%40bdelab/roar-firekit/?lang=original
项目主页：https://github.com/yeatmanlab/roar-firekit#readme
源码仓库：https://github.com/yeatmanlab/roar-firekit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：350 kB，39 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：11 个
- 首次发布：2022-03-08T22:29:59.568Z
- 最新版本发布：2026-04-09T19:08:09.284Z
- 近 30 天下载量：6103（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：179（近 12 个月 4 个）

## 中文简介

为注重成果的年度报告应用程序提供方便Firebase认证和Cloud Firestore互动的图书馆

## 安装

```sh
npm install @bdelab/roar-firekit
```

也可以使用：`pnpm add @bdelab/roar-firekit`、`yarn add @bdelab/roar-firekit`、`bun add @bdelab/roar-firekit`

## README

[![npm version](https://badge.fury.io/js/@bdelab%2Froar-firekit.svg)](https://badge.fury.io/js/@bdelab%2Froar-firekit) ![NPM License](https://img.shields.io/npm/l/@bdelab/roar-firekit)

# 咆哮出击

欢迎来到"咆哮"火腿! Roar -firekit 帮助您存储您所保存的数据 [注重成果的年度报告应用](https://dyslexia.stanford.edu/roar/) 内 [云火炉](https://cloud.google.com/firestore)。 。 。 .

## 安装

您可以安装 [来自npm的咆哮相火](https://www.npmjs.com/package/@bdelab/roar-firekit) 与

```bash
npm i @bdelab/roar-firekit
```

## 使用量

Roar-firekit对您的数据来源是不可知的,但我预计大多数用户会用Roar-firekit 来做他们的实验 [jssych 语录](https://www.jspsych.org/)。 。 。 .

咆哮-firekit的API的主要入口是\[\[\]\]`RoarAppkit`班级。 内容 构造器需要带有密钥的对象 `userInfo`, (中文(简体) ), `taskInfo`,以及 `config`时 `userInfo` 是一个 \[\[`UserDataInAdminDb`对象, `taskInfo` 是一个 \[\[`TaskVariantInput`对象,和 `config` 是一个 \[\[`AssessmentConfigData`对象.

### 构造输入

#### `userInfo`

用户信息封装在 \[\[`UserDataInAdminDb`对象。 唯一需要的东西 键为 `id`这应该是目前的用户注重成果的年度报告UID,有时也称为注重成果的年度报告PID:

```javascript
const minimalUserInfo = { id: 'roar-user-id' };
```

但是,如果您知道,您可以提供用户的其他信息:

```javascript
const fullUserInfo = {
  id: 'roar-user-id',
  birthMonth: 7,
  birthYear: 2014,
  classId: 'roar-class-id',
  schoolId: 'roar-school-id',
  districtId: 'roar-district-id',
  groupId: 'roar-group-id',
  userCategory: 'student',
};
```

#### `taskInfo`

关于当前任务的信息被封装在 \[\[`TaskVariantInput`对象。 以下是虚构的"非热狗"任务的任务信息:

```javascript
const taskInfo = {
  taskId: 'nhd',
  taskName: 'Not Hotdog',
  variantName: 'Not Hotdog, one block',
  taskDescription: 'A demonstration task using the hot dog / not hot dog problem',
  variantDescription: 'One block, random order',
  blocks: [
    {
      blockNumber: 1,
      trialMethod: 'random-without-replacement',
      corpus: 'pointer-to-location-of-stimulus-corpus',
    },
  ],
};
```

#### `config`

配置对象包含您的 Firebase 项目的配置信息 。 您可能想要将您的配置对象存储在单独的javascript文件中(为此文档命名为"roarConfig.js"). 下文提供了一个模板

点击扩展!

```javascript
export const roarConfig = {
  firebaseConfig: {
    apiKey: 'insert your firebase API key here',
    authDomain: 'insert your firebase auth domain here',
    projectId: 'insert your firebase project ID here',
    storageBucket: 'insert your firebase storage bucket here',
    messagingSenderId: 'insert your firebase messaging sender ID here',
    appId: 'insert your firebase app ID here',
    measurementId: 'insert your firebase measurement ID here',
  },
  rootDoc: ['some collection name', 'some document name'],
};
```

##### `firebaseConfig`

为了得到 `firebaseConfig` 字段,参见 [本条](https://support.google.com/firebase/answer/7015592#zippy=%2Cin-this-article) 如何取回你的火库配置。 直接转到 [您的项目设置](https://console.firebase.google.com/project/_/settings/general/),向下滚动到"SDK设置和配置",点击"Config"的收音机按钮,并复制片段供您的应用程序的Firebase配置对象使用.

##### `rootDoc`

这个 `rootDoc` 是一个字符串,代表将存储所有注重成果的年度报告数据的文档。 请注意: `rootDoc` 不需要在您的 Cloud Firestore 数据库的实际根中.

### 构造火柴

使用上述定义的输入,您将使用

```javascript
import { RoarAppkit } from '@bdelab/roar-firekit';
import { roarConfig } from './roarConfig.js';

// Insert input definition code from above

const firekit = new RoarAppkit({
  userInfo: minimalUserInfo,
  taskInfo,
  config: roarConfig,
});
```

## 开始运行

开始运行将用户、任务和运行信息写入 Cloud Firestore :

```javascript
await firekit.startRun();
```

如果你用"咆哮"和"JsPsych",你应该用这种方法 试验开始,要么在开始前等待 `jsPsych.run` 方法,

```javascript
await firekit.startRun();
jsPsych.run(timeline);
```

或称其为 `on_timeline_start` 召回电话,

```javascript
const procedure = {
  timeline: [trial1, trial2],
  on_timeline_start: function() {
    await firekit.startRun();
  }
}
```

## 向 Firestore 撰写审判

启动运行后,您可以使用 Cloud Firestore 写入单个试运行数据 `writeTrial` 方法. 这种方法可以通过调用来添加到单个 jsPsych 试验中 页:1 `on_finish` 函数,例如:

```javascript
var trial = {
  type: 'image-keyboard-response',
  stimulus: 'imgA.png',
  on_finish: function (data) {
    firekit.writeTrial(data);
  },
};
```

或者你可以在JsPsych的所有试验中称呼它 时间轴: `on_data_update` 调用。 在这 ,通过有条件的调用,可以避免节省无关的审判 这种方法基于数据。 例如:

```javascript
initJsPsych({
  on_data_update: function (data) {
    if (data.saveToFirestore) {
      firekit.addTrialData(data);
    }
  },
});
const timeline = [
  // A fixation trial; don't save to Firestore
  {
    type: htmlKeyboardResponse,
    stimulus: '<div style="font-size:60px;">+</div>',
    choices: 'NO_KEYS',
    trial_duration: 500,
  },
  // A stimulus and response trial; save to Firestore
  {
    type: imageKeyboardResponse,
    stimulus: 'imgA.png',
    data: { saveToFirestore: true },
  },
];
```

## 运行结束

在你的实验结束后,你可以用 `finishRun` 方法。 例如,可以在 [`on_finish` (实验)召回](https://www.jspsych.org/7.1/overview/events/#on_finish-experiment)数字 :

```javascript
initJsPsych({
  on_finish: function (data) {
    firekit.finishRun();
  },
});
```

## 完整实例

下面是一个jsPsych实验的例子,它执行诺霍特多克评估,同时使用咆哮-firekit将数据写入Cloud Firestore.

点击扩展!

```javascript
import { initJsPsych } from 'jspsych';
import preload from '@jspsych/plugin-preload';
import htmlKeyboardResponse from '@jspsych/plugin-html-keyboard-response';
import imageButtonResponse from '@jspsych/plugin-image-button-response';
import { RoarAppkit } from '@bdelab/roar-firekit';
import { roarConfig } from './roarConfig.js';

const taskInfo = {
  taskId: 'nhd',
  taskName: 'Not Hotdog',
  variantName: 'nhd-1block-random',
  taskDescription: 'A ROAR demonstration using the hot dog / not hot dog task.',
  variantDescription: 'One block, random order',
  blocks: [
    {
      blockNumber: 1,
      trialMethod: 'random-without-replacement',
      corpus: 'assets',
    },
  ],
};

const minimalUserInfo = { id: 'roar-user-id' };

const firekit = new RoarAppkit({
  userInfo: minimalUserInfo,
  taskInfo,
  config: roarConfig,
});

await firekit.startRun();

const jsPsych = initJsPsych({
  on_data_update: function (data) {
    if (data.saveToFirestore) {
      firekit.writeTrial(data);
    }
  },
  on_finish: function () {
    firekit.finishRun();
  },
});

// This example assumes that the hot dog / not hot dog images are stored in the
// assets folder.
const numFiles = 30;
const hotDogFiles = Array.from(Array(numFiles), (_, i) => i + 1).map(
  (idx) => new URL(`../assets/hotdog/${idx}.jpg`, import.meta.url),
);
const notHotDogFiles = Array.from(Array(numFiles), (_, i) => i + 1).map(
  (idx) => new URL(`../assets/nothotdog/${idx}.jpg`, import.meta.url),
);
const allFiles = hotDogFiles.concat(notHotDogFiles);
const allTargets = allFiles.map((url) => {
  return { target: url, isHotDog: !url.pathname.includes('nothotdog') };
});

let timeline = [];

/* preload images */
const preloadImages = {
  type: preload,
  auto_preload: true,
};
timeline.push(preloadImages);

/* define welcome message trial */
const welcome = {
  type: htmlKeyboardResponse,
  stimulus: 'Welcome to ROAR-HD, a rapid online assessment of hot dog differentiating ability. Press any key to begin.',
};
timeline.push(welcome);

const hotDogTrials = {
  timeline: [
    {
      type: htmlKeyboardResponse,
      stimulus: '<div style="font-size:60px;">+</div>',
      choices: 'NO_KEYS',
      trial_duration: 500,
    },
    {
      type: imageButtonResponse,
      stimulus: jsPsych.timelineVariable('target'),
      choices: ['Hot Dog', 'Not a Hot Dog'],
      prompt: 'Is this a hot dog?',
      data: { saveToFirestore: true },
      on_finish: function (data) {
        data.correct = jsPsych.timelineVariable('isHotDog') == data.response;
      },
    },
  ],
  timeline_variables: allTargets,
  sample: {
    type: 'without-replacement',
    size: 20,
  },
};

timeline.push(hotDogTrials);

const fixation = {
  type: htmlKeyboardResponse,
  stimulus: 'You are all done. Thanks!',
  choices: 'NO_KEYS',
};
timeline.push(fixation);

jsPsych.run(timeline);
```

## 常见问题

### @bdelab/roar-firekit 是什么？

为注重成果的年度报告应用程序提供方便Firebase认证和Cloud Firestore互动的图书馆

### 如何安装 @bdelab/roar-firekit？

在项目目录运行 npm install @bdelab/roar-firekit，或使用 pnpm add / yarn add / bun add。

### @bdelab/roar-firekit 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bdelab/roar-firekit 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bdelab/roar-firekit 可以商用吗？

@bdelab/roar-firekit 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bdelab/roar-firekit 的下载量有多少？

根据 npm 官方下载统计，@bdelab/roar-firekit 在 2026/10/08 – 2026/11/06 这 30 天内被下载 6,103 次，日均约 203 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bdelab/roar-firekit 还在维护吗？

最新版本 9\.17\.0 发布于 2026/04/10（6 个月前）；至今共发布 179 个版本，其中过去 12 个月发布了 4 个；首次发布于 2022/03/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。