opbeans/opbeans-frontend

Opbeans Frontend App 文档

!Build Status]([***]

本项目基于 https://github.com/***incubator/create-react-app 构建。

以下是执行常见任务的相关信息。最新版本的指南可在 https://github.com/***incubator/create-react-app/blob/master/packages/react-scripts/template/README.md 查看。

目录

• 更新到新版本
• 反馈
• 文件夹结构
• 可用脚本
  • npm start
  • npm test
  • npm run build
  • npm run eject
• 编辑器中的语法高亮
• 在编辑器中显示 Lint 输出
• 安装依赖
• 导入组件
• 添加样式表
• CSS 后处理
• 添加图片和字体
• 使用 public 文件夹
• 使用全局变量
• 添加 Bootstrap
• 添加 Flow
• 添加自定义环境变量
• 是否支持装饰器？
• 集成 Node 后端
• 开发环境中的 API 请求代理
• 开发环境中使用 HTTPS
• 在服务器上生成动态 <meta> 标签
• 运行测试
  • 文件名约定
  • 命令行界面
  • 版本控制集成
  • 编写测试
  • 测试组件
  • 使用第三方断言库
  • 初始化测试环境
  • 聚焦和排除测试
  • 覆盖率报告
  • 持续集成
  • 禁用 jsdom
  • 实验性快照测试
  • 编辑器集成
• 独立开发组件
• 创建渐进式 Web 应用（PWA）
• 部署
  • 使用客户端路由的应用部署
  • 为相对路径构建
  • Firebase
  • GitHub Pages
  • Heroku
  • Modulus
  • Netlify
  • Now
  • S3 和 CloudFront

  • ---

• 故障排除
  • macOS Sierra 上 npm test 挂起
  • npm run build 静默失败
• 缺少某些内容？

更新到新版本

Create React App 分为两个包：

• create-react-app：全局命令行工具，用于创建新项目。
• react-scripts：生成项目中的开发依赖（包括本项目）。

几乎不需要更新 create-react-app 本身：它将所有设置委托给 react-scripts。

运行 create-react-app 时，它始终使用最新版本的 react-scripts 创建项目，因此新创建的应用会自动获得所有新功能和改进。

要将现有项目更新到新版本的 react-scripts，请https://github.com/***incubator/create-react-app/blob/master/CHANGELOG.md%EF%BC%8C%E6%89%BE%E5%88%B0%E5%BD%93%E5%89%8D%E7%89%88%E6%9C%AC%EF%BC%88%E4%B8%8D%E7%A1%AE%E5%AE%9A%E7%9A%84%E8%AF%9D%E6%9F%A5%E7%9C%8B%E6%AD%A4%E6%96%87%E4%BB%B6%E5%A4%B9%E4%B8%AD%E7%9A%84 package.json），并应用更新版本的迁移说明。

大多数情况下，只需在 package.json 中更新 react-scripts 版本并在此文件夹中运行 npm install 即可，但最好查阅https://github.com/***incubator/create-react-app/blob/master/CHANGELOG.md%E4%BB%A5%E4%BA%86%E8%A7%A3%E6%BD%9C%E5%9C%A8%E7%9A%84%E7%A0%B4%E5%9D%8F%E6%80%A7%E5%8F%98%E6%9B%B4%E3%80%82

我们致力于将破坏性变更降至最低，以便您可以无缝升级 react-scripts。

反馈

我们始终欢迎https://github.com/***incubator/create-react-app/issues%E3%80%82

文件夹结构

创建项目后，结构如下：

my-app/
  README.md
  node_modules/
  package.json
  public/
    index.html
    favicon.ico
  src/
    App.css
    App.js
    App.test.js
    index.css
    index.js
    logo.svg

为使项目能够构建，必须存在以下具有确切文件名的文件：

• public/index.html：页面模板；
• src/index.js：JavaScript 入口点。

其他文件可以删除或重命名。

可以在 src 内创建子目录。为加快重建速度，Webpack 仅处理 src 内的文件。
必须将所有 JS 和 CSS 文件放在 src 内，否则 Webpack 无法识别它们。

只有 public 内的文件可从 public/index.html 中使用。
有关从 JavaScript 和 HTML 中使用资源的说明，请阅读下文。

但是，可以创建更多顶级目录。
它们不会包含在生产构建中，因此可用于文档等内容。

可用脚本

在项目目录中，可以运行：

npm start

以开发模式运行应用。
打开 http://localhost:3000 在浏览器中查看。

编辑文件时，页面会自动重新加载。
控制台中会显示任何 lint 错误。

npm test

以交互监视模式启动测试运行器。
有关更多信息，请参见运行测试部分。

npm run build

将应用构建到 build 文件夹以用于生产。
它会在生产模式下正确捆绑 React，并优化构建以获得最佳性能。

构建会被压缩，文件名包含哈希值。
应用已准备好部署！

有关更多信息，请参见部署部分。

npm run eject

注意：这是单向操作。执行 eject 后，无法恢复！

如果对构建工具和配置选择不满意，可以随时 eject。此命令会从项目中删除单个构建依赖项。

相反，它会将所有配置文件和传递依赖项（Webpack、Babel、ESLint 等）复制到项目中，以便完全控制它们。除 eject 外的所有命令仍然有效，但它们会指向复制的脚本，因此可以调整它们。此时，您需要自行维护这些配置。

不必使用 eject。精心选择的功能集适用于小型和中型部署，不必觉得必须使用此功能。但我们理解，如果无法在准备好时自定义工具，它将失去实用性。

编辑器中的语法高亮

要在您喜爱的文本编辑器中配置语法高亮，请前往 Babel 文档 并按照说明操作。其中涵盖了一些最流行的编辑器。

在编辑器中显示 Lint 输出

注意：此功能在 react-scripts@0.2.0 及更高版本中可用。

某些编辑器（包括 Sublime Text、Atom 和 Visual Studio Code）提供 ESLint 插件。

它们不是 linting 必需的。您应该在终端和浏览器控制台中看到 linter 输出。但是，如果希望 lint 结果直接显示在编辑器中，可以执行一些额外步骤。

首先需要为编辑器安装 ESLint 插件。

Atom linter-eslint 用户注意

如果使用 Atom linter-eslint 插件，请确保勾选 Use global ESLint installation 选项：

然后将此块添加到项目的 package.json 文件中：

js
{
  // ...
  "eslintConfig": {
    "extends": "react-app"
  }
}

最后，需要全局安装一些包：

sh
npm install -g eslint-config-react-app@0.3.0 eslint@3.8.1 babel-eslint@7.0.0 eslint-plugin-react@6.4.1 eslint-plugin-import@2.0.1 eslint-plugin-jsx-a11y@2.2.3 eslint-plugin-flowtype@2.21.0

我们认识到这不是最佳方式，但由于我们隐藏 ESLint 依赖的方式，目前这是必需的。ESLint 团队已在https://github.com/eslint/eslint/issues/3458%EF%BC%8C%E5%9B%A0%E6%AD%A4%E5%87%A0%E4%B8%AA%E6%9C%88%E5%90%8E%E8%BF%99%E5%8F%AF%E8%83%BD%E4%B8%8D%E5%86%8D%E9%9C%80%E8%A6%81%E3%80%82

安装依赖

生成的项目包含 React 和 ReactDOM 作为依赖项。它还包含 Create React App 使用的一组脚本作为开发依赖项。可以使用 npm 安装其他依赖项（例如 React Router）：

npm install --save <library-name>

导入组件

此项目设置借助 Babel 支持 ES6 模块。
虽然仍可使用 require() 和 module.exports，但建议使用 import 和 export。

例如：

Button.js

js
import React, { Component } from 'react';

class Button extends Component {
  render() {
    // ...
  }
}

export default Button; // 不要忘记使用 export default!

DangerButton.js

js
import React, { Component } from 'react';
import Button from './Button'; // 从另一个文件导入组件

class DangerButton extends Component {
  render() {
    return <Button color="red" />;
  }
}

export default DangerButton;

注意默认导出和命名导出的区别。这是常见错误来源。

建议在模块仅导出单个内容（例如组件）时使用默认导入和导出。当使用 export default Button 和 import Button from './Button' 时就是这种情况。

命名导出适用于导出多个函数的工具模块。一个模块最多可以有一个默认导出和任意多个命名导出。

了解更多关于 ES6 模块的信息：

• 何时使用花括号？
• Exploring ES6: Modules
• Understanding ES6: Modules

添加样式表

此项目设置使用 https://webpack.github.io/ 处理所有资源。Webpack 提供了一种自定义方式，将 import 的概念扩展到 JavaScript 之外。要表示 JavaScript 文件依赖于 CSS 文件，需要从 JavaScript 文件中导入 CSS：

Button.css

css
.Button {
  padding: 20px;
}

Button.js

js
import React, { Component } from 'react';
import './Button.css'; // 告诉 Webpack Button.js 使用这些样式

class Button extends Component {
  render() {
    // 可以像常规 CSS 样式一样使用它们
    return <div className="Button" />;
  }
}

这不是 React 必需的，但许多人发现此功能很方便。您可以在此处了解这种方法的好处。但请注意，这会使代码在 Webpack 之外的其他构建工具和环境中移植性降低。

在开发中，以这种方式表达依赖关系允许在编辑样式时实时重新加载样式。在生产中，所有 CSS 文件将被连接成单个压缩的 .css 文件输出到构建目录中。

如果担心使用 Webpack 特定的语法，可以将所有 CSS 直接放入 src/index.css。它仍然会从 src/index.js 导入，但如果以后迁移到其他构建工具，可以删除该导入。

CSS 后处理

此项目设置通过 https://github.com/postcss/autoprefixer 自动压缩 CSS 并添加 vendor 前缀，因此无需担心这些问题。

例如，以下 CSS：

css
.App {
  display: flex;
  flex-direction: row;
  align-items: center;
}

会被处理为：

css
.App {
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-box-orient: horizontal;
  -webkit-box-direction: normal;
      -ms-flex-direction: row;
          flex-direction: row;
  -webkit-box-align: center;
      -ms-flex-align: center;
          align-items: center;
}

目前不支持 Less 等预处理器，也不支持跨 CSS 文件共享变量。

添加图片和字体

使用 Webpack 时，处理图片和字体等静态资源的方式与 CSS 类似。

可以在 JavaScript 模块中直接 import 图片。这告诉 Webpack 将该图片包含在 bundle 中。与 CSS 导入不同，导入图片或字体会得到一个字符串值，该值是可在代码中引用的最终图片路径。

例如：

js
import React from 'react';
import logo from './logo.png'; // 告诉 Webpack 此 JS 文件使用此图片

console.log(logo); // /logo.84287d09.png

function Header() {
  // 导入结果是图片的 URL
  return <img src={logo} alt="Logo" />;
}

export default Header;

这确保在构建项目时，Webpack 会正确将图片移动到构建目录，并提供正确的路径。

在 CSS 中也可以这样使用：

css
.Logo {
  background-image: url(./logo.png);
}

Webpack 会找到 CSS 中的所有相对模块引用（以 ./ 开头），并将它们替换为编译后的 bundle 中的最终路径。如果输入错误或意外删除了重要文件，会看到编译错误，就像导入不存在的 JavaScript 模块一样。编译后的 bundle 中的最终文件名由 Webpack 根据内容哈希生成。如果将来文件内容更改，Webpack 会在生产环境中为其赋予不同的名称，因此无需担心资产的长期缓存问题。

请注意，这也是 Webpack 的自定义功能。

这不是 React 必需的，但许多人喜欢使用它（React Native 对图片使用类似机制）。
下一节将介绍处理静态资产的另一种方法。

使用 public 文件夹

注意：此功能在 react-scripts@0.5.0 及更高版本中可用。

通常，我们建议按照上述方式在 JavaScript 文件中 import 资产。这种机制提供了许多好处：

• 脚本和样式表被压缩并捆绑在一起，以避免额外的网络请求。
• 缺少的文件会导致编译错误，而不是给用户显示 404 错误。
• 结果文件名包含内容哈希，因此无需担心浏览器缓存旧版本。

但是，有一个逃生舱可用于添加模块系统之外的资产。

如果将文件放入 public 文件夹，它不会被 Webpack 处理。相反，它会原封不动地复制到构建文件夹中。要引用 public 文件夹中的资产，需要使用名为 PUBLIC_URL 的特殊变量。

在 index.html 中，可以这样使用：

html
<link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico">

只有 public 文件夹中的文件才能通过 %PUBLIC_URL% 前缀访问。如果需要使用 src 或 node_modules 中的文件，必须将其复制到 public 文件夹中，以明确表示要将此文件作为构建的一部分。

运行 npm run build 时，Create React App 会将 %PUBLIC_URL% 替换为正确的绝对路径，因此即使使用客户端路由或将应用托管在非根 URL，项目也能正常工作。

在 JavaScript 代码中，可以使用 process.env.PUBLIC_URL 实现类似目的：

js
render() {
  // 注意：这是一个逃生舱，应谨慎使用！
  // 通常我们建议使用“添加图片和字体”部分中描述的 `import` 获取资产 URL
  return <img src={process.env