跳转至

配置jsPsych开发环境

环境搭建

JsPsych使用TypeScript编写，该语言是JavaScript的超集，引入了静态类型，在经过编译后会生成JavaScript代码。TypeScript编译器自身是由JavaScript编写的，可以使用Node.js（不适用浏览器运行JavaScript的运行时）。 Node.js自带一个名为NPM (Node Package Manager)的包管理器，可以安装JavaScript包，例如TypeScript和jsPsych的一些构建工具。如果要使用jsPsych或jspsych-contrib仓库中的代码，最后按照下面的步骤搭建开发环境。

安装Node.js

jsPsych开发环境需要Node.js LTS。

将仓库clone下来并安装依赖

在终端中运行下面的命令clone jsPsych或jspsych-contrib仓库。

git clone https://github.com/jspsych/jsPsych.git && cd jsPsych

或

git clone https://github.com/jspsych/jspsych-contrib.git && cd jspsych-contrib

然后运行npm install。此时，会自动创建一个node_modules文件夹，并将依赖安装到该文件夹中。

注意

请只在仓库的根目录下运行npm install (这是由NPM工作空间特性决定的)。如果不小心在别的地方运行了npm install，把那个路径下的node_modules文件夹和生成的package-lock.json文件删掉，然后再根目录重新运行npm install。

注意

jsPsych (-contrib)仓库需要用到canvas包，这个包有一些预构建的二进制文件。有一些系统上找不到这些二进制文件，此时npm install会尝试从零构建，这样有时候会失败，报错信息中会提到canvas包。如果你遇到了这种问题，请参照canvas包的安装指南操作，然后再运行npm install。

补充

如果在jsPsych仓库中运行npm install，会为仓库中所有的包进行构建，可能会花上劫难中。如果想要在这段时间内找些事情做，不妨继续读下面的部分

仓库结构

Node.js包中包含了一个用来描述的package.json文件，该文件列出了包的依赖项。jsPsych和jspsych-contrib仓库用到了NPM 工作空间 。这意味着在根目录下运行npm install会为packages路径下的包安装依赖。核心的jsPsych库和每一个插件、扩展都是一个单独的包，这些包被发布在了NPM，可以通过NPM下载或通过CDN (例如unpkg)使用。

构建工具链

JsPsych用到了一套构建工具链 (见@jspsych/config)，可以通过npm run build运行。工具链会读取包的内容 (从src/index.ts文件开始)，并在报的dist目录下生成下列内容：

  • index.js 该文件包含来自 index.ts 的所有内容，但是编译成了JavaScript并打包到了单个文件中（即不对同一包中的内容使用import）。它被 webpack 等打包程序使用。

  • index.cjs 类似于 index.js，但使用旧的 CommonJS 标准来支持如 Jest 这样的测试框架。

  • index.browser.js 这个文件和 index.js 一样，将整个包打包为JavaScript，但封装在一个函数中，以便浏览器可以使用 <script> 标签直接包含它。对于插件或扩展，模块的默认导出内容（即 index.ts 文件中 export default 之后的任何语句）被赋值给一个全局变量。这个全局变量的名称在包的 rollup.config.mjs 文件中指定，也是 makeRollupConfig() 函数的参数。比如说，如果在plugin-html-keyboard-response 包中加入 index.browser.js 文件，则会将 HtmlKeyboardResponsePlugin 类赋值给全局变量jsPsychHtmlKeyboardResponse。index.browser.js 中的代码看起来与 index.ts 代码非常相似，且浏览器完全支持，因此examples目录中的所有示例都使用了index.browser.js文件，这样用户就可以直接修改源代码，无需重新运行构建链。

  • index.browser.min.js JavaScript 语言规范有不同版本，并非所有浏览器和浏览器版本都支持所有的特性。因此，jsPsych构建链使用esbuild将源文件转换为兼容大多数浏览器的代码。这一操作会生成index.browser.min.js，其功能类似于 index.browser.js，但对于旧浏览器不支持的特性，会对该部分的JavaScript代码进行替换。此外，index.browser.min.js 中的代码也通过Terser压缩，以提高加载速度。

  • *.js.map 在浏览器中调试代码时（尤其是 index.browser.min.js，因为被压缩了，导致其可读性很差），需要能看到源代码。对于构建后的文件，都对应了一个.map文件，将生成的代码映射到原始源代码。浏览器会自动读取这些 .map 文件并在其调试器中显示原始代码，而不是生成的代码。

  • index.d.ts 该文件包含TypeScript的类型定义，否则这些定义会在编译为JavaScript期间丢失。当一个包被导入另一个TypeScript项目时，Typescript和编辑器会读取这些文件。

测试

jsPsych使用Jest进行自动化测试。

运行测试需要Node和npm。在 jsPsych 根目录中运行 npm install。然后运行npm test。我们也可以在想测试的包目录中运行npm test。例如，如果测试 html-keyboard-response 插件，则可以在 /packages/plugin-html-keyboard-response 中运行 npm test。如果想运行根目录中的某一个文件，还是以前面的例子为例，可以运行npm test -- /packages/plugin-html-keyboard-response/src/index.spec.ts。

jsPsych库核心部分的测试位于/packages/jspsych/tests。

插件和扩展的测试位于相应包的 /src 文件夹中。插件和扩展的测试文件名为 index.spec.ts。

/packages/jspsych/tests/utils.ts 中有用于帮助测试的函数。我们推荐去看一些测试文件，以更多了解测试中的一些常见的习惯。