Skip to content

Commit

Permalink
update
Browse files Browse the repository at this point in the history
  • Loading branch information
@BingKui
BingKui committed May 25, 2018
1 parent 566847e commit ae7a816
Showing 1 changed file with 74 additions and 70 deletions.
144 changes: 74 additions & 70 deletions react/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,37 +1,39 @@
# Airbnb React/JSX Style Guide
# Airbnb React/JSX 代码规范

*A mostly reasonable approach to React and JSX*
*一套对于 React 和 JSX 基本合理的规范*

This style guide is mostly based on the standards that are currently prevalent in JavaScript, although some conventions (i.e async/await or static class fields) may still be included or prohibited on a case-by-case basis. Currently, anything prior to stage 3 is not included nor recommended in this guide.
本指南是主要基于目前流行的 JavaScript 标准，因此一些惯例（如：async/await 或静态类字段）可能仍然包含其中或者被禁止。 目前，处在第 3 阶段的任何内容都不包含在本指南中，也不建议使用。

## Table of Contents
## <a id="table-of-contents">目录</a>

1. [Basic Rules](#basic-rules)
1. [基本规则](#basic-rules)
1. [Class vs `React.createClass` vs stateless](#class-vs-reactcreateclass-vs-stateless)
1. [Mixins](#mixins)
1. [Naming](#naming)
1. [Declaration](#declaration)
1. [Alignment](#alignment)
1. [Quotes](#quotes)
1. [Spacing](#spacing)
1. [Props](#props)
1. [命名](#naming)
1. [声明模块](#declaration)
1. [代码对齐](#alignment)
1. [单引号和双引号](#quotes)
1. [空格](#spacing)
1. [属性](#props)
1. [Refs](#refs)
1. [Parentheses](#parentheses)
1. [Tags](#tags)
1. [Methods](#methods)
1. [Ordering](#ordering)
1. [括号](#parentheses)
1. [标签](#tags)
1. [方法](#methods)
1. [函数生命周期](#ordering)
1. [`isMounted`](#ismounted)

## Basic Rules
## <a id="basic-rules">基本规则</a>

- Only include one React component per file.
- However, multiple [Stateless, or Pure, Components](https://facebook.github.io/react/docs/reusable-components.html#stateless-functions) are allowed per file. eslint: [`react/no-multi-comp`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-multi-comp.md#ignorestateless).
- Always use JSX syntax.
- Do not use `React.createElement` unless you're initializing the app from a file that is not JSX.
- 每个文件只存在一个 React 组件。
- 但是，每个文件允许存在多个 [无状态或纯组件](https://facebook.github.io/react/docs/reusable-components.html#stateless-functions) 。 eslint: [`react/no-multi-comp`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-multi-comp.md#ignorestateless).
- 始终使用 JSX 语法。
- 除非你从一个非 JSX 文件中初始化你的应用，否则不要使用 `React.createElement` 。

## Class vs `React.createClass` vs stateless
**[⬆ 返回目录](#table-of-contents)**

- If you have internal state and/or refs, prefer `class extends React.Component` over `React.createClass`. eslint: [`react/prefer-es6-class`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prefer-es6-class.md) [`react/prefer-stateless-function`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prefer-stateless-function.md)
## <a id="class-vs-reactcreateclass-vs-stateless">Class vs `React.createClass` vs stateless</a>

- 如果你的组件有内部状态或者是 `refs` ，推荐使用 `class extends React.Component` 而不是 `React.createClass`。 eslint: [`react/prefer-es6-class`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prefer-es6-class.md) [`react/prefer-stateless-function`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/prefer-stateless-function.md)

```jsx
// bad
Expand All @@ -51,7 +53,7 @@ This style guide is mostly based on the standards that are currently prevalent i
}
```

And if you don't have state or refs, prefer normal functions (not arrow functions) over classes:
如果你的组件没有状态或者 `refs` 推荐使用普通函数（不是箭头函数）而不是类定义：

```jsx
// bad
Expand All @@ -71,18 +73,21 @@ This style guide is mostly based on the standards that are currently prevalent i
return <div>{hello}</div>;
}
```
**[⬆ 返回目录](#table-of-contents)**

## <a id="mixins">Mixins</a>

## Mixins
- [不要使用 mixins](https://facebook.github.io/react/blog/2016/07/13/mixins-considered-harmful.html).

- [Do not use mixins](https://facebook.github.io/react/blog/2016/07/13/mixins-considered-harmful.html).
> 为什么？ Mixins 会引入隐式的依赖关系，会导致名称冲突，并致使复杂性指数级增加。 在多数情况下 mixins 能够被更好的方法替代，如：组件化，高阶组件，工具模块等。

> Why? Mixins introduce implicit dependencies, cause name clashes, and cause snowballing complexity. Most use cases for mixins can be accomplished in better ways via components, higher-order components, or utility modules.
**[⬆ 返回目录](#table-of-contents)**

## Naming
## <a id="naming">命名</a>

- **Extensions**: Use `.jsx` extension for React components.
- **Filename**: Use PascalCase for filenames. E.g., `ReservationCard.jsx`.
- **Reference Naming**: Use PascalCase for React components and camelCase for their instances. eslint: [`react/jsx-pascal-case`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-pascal-case.md)
- **扩展名**: 使用 `.jsx` 作为 React 组件的扩展名。
- **文件名**: 使用帕斯卡命名法给文件命名。 例如： `ReservationCard.jsx`.
- **引用命名**: 使用帕斯卡命名法给 React 组件命名并用驼峰命名法给组件实例命名。 eslint: [`react/jsx-pascal-case`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-pascal-case.md)

```jsx
// bad
Expand All @@ -98,7 +103,7 @@ This style guide is mostly based on the standards that are currently prevalent i
const reservationItem = <ReservationCard />;
```

- **Component Naming**: Use the filename as the component name. For example, `ReservationCard.jsx` should have a reference name of `ReservationCard`. However, for root components of a directory, use `index.jsx` as the filename and use the directory name as the component name:
- **组件命名**: 使用文件名作为组件的名字。 例如： `ReservationCard.jsx` 应该包含一个名字叫 `ReservationCard` 的组件。 但是，如果整个文件夹是一个模块，使用 `index.jsx` 作为入口文件，并使用目录名称作为组件名称：

```jsx
// bad
Expand All @@ -110,9 +115,9 @@ This style guide is mostly based on the standards that are currently prevalent i
// good
import Footer from './Footer';
```
- **Higher-order Component Naming**: Use a composite of the higher-order component's name and the passed-in component's name as the `displayName` on the generated component. For example, the higher-order component `withFoo()`, when passed a component `Bar` should produce a component with a `displayName` of `withFoo(Bar)`.
- **高阶组件命名**: 在生成的新组件上，使用高阶组件的名称和传入组件的名称作为新组件的 `displayName` 。 例如：高价组件 `withFoo()`，当被传入到一个叫做 `Bar` 的组件中的时候，应该生成一个拥有 `displayName` 为 `withFoo(Bar)` 的组件。

> Why? A component's `displayName` may be used by developer tools or in error messages, and having a value that clearly expresses this relationship helps people understand what is happening.
> 为什么？ 一个组件的 `displayName` 可能在开发者工具或者错误信息中用到， 因此拥有一个能清楚表达层次结构的值能够帮助我们更好的理解触发的事件。

```jsx
// bad
Expand All @@ -137,9 +142,9 @@ This style guide is mostly based on the standards that are currently prevalent i
}
```

- **Props Naming**: Avoid using DOM component prop names for different purposes.
- **属性命名**: 避免使用 DOM 组件属性来用作其他用途。

> Why? People expect props like `style` and `className` to mean one specific thing. Varying this API for a subset of your app makes the code less readable and less maintainable, and may cause bugs.
> 为什么？ 对于像 `style` 和 `className` 这样的属性我们默认它们代表一些特殊的含义。 改变这些 API 会降低你代码的可读性和可维护性，并且可能导致问题。

```jsx
// bad
Expand All @@ -152,9 +157,9 @@ This style guide is mostly based on the standards that are currently prevalent i
<MyComponent variant="fancy" />
```

## Declaration
## <a id="declaration">声明模块</a>

- Do not use `displayName` for naming components. Instead, name the component by reference.
- 不要使用 `displayName` 来命名组件。 应该使用引用来命名组件。

```jsx
// bad
Expand All @@ -168,9 +173,9 @@ This style guide is mostly based on the standards that are currently prevalent i
}
```

## Alignment
## <a id="alignment">代码对齐</a>

- Follow these alignment styles for JSX syntax. eslint: [`react/jsx-closing-bracket-location`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-closing-bracket-location.md) [`react/jsx-closing-tag-location`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-closing-tag-location.md)
- 遵循以下的 JSX 代码对齐方式。 eslint: [`react/jsx-closing-bracket-location`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-closing-bracket-location.md) [`react/jsx-closing-tag-location`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-closing-tag-location.md)

```jsx
// bad
Expand All @@ -183,10 +188,10 @@ This style guide is mostly based on the standards that are currently prevalent i
anotherSuperLongParam="baz"
/>
// if props fit in one line then keep it on the same line
// 如果能写在一行，直接写成一行
<Foo bar="bar" />
// children get indented normally
// 子元素按照常规方式缩进
<Foo
superLongParam="bar"
anotherSuperLongParam="baz"
Expand All @@ -195,11 +200,11 @@ This style guide is mostly based on the standards that are currently prevalent i
</Foo>
```

## Quotes
## <a id="quotes">单引号和双引号</a>

- Always use double quotes (`"`) for JSX attributes, but single quotes (`'`) for all other JS. eslint: [`jsx-quotes`](https://eslint.org/docs/rules/jsx-quotes)
- 对于 JSX 属性总是使用双引号 （`"`）， 对于其他的 JS 来说使用单引号 （`'`）。 eslint: [`jsx-quotes`](https://eslint.org/docs/rules/jsx-quotes)

> Why? Regular HTML attributes also typically use double quotes instead of single, so JSX attributes mirror this convention.
> 为什么？ HTML 属性的规则就是使用双引号而不是单引号，因此 JSX 的属性也遵循这个约定。

```jsx
// bad
Expand All @@ -215,9 +220,9 @@ This style guide is mostly based on the standards that are currently prevalent i
<Foo style={{ left: '20px' }} />
```

## Spacing
## <a id="spacing">空格</a>

- Always include a single space in your self-closing tag. eslint: [`no-multi-spaces`](https://eslint.org/docs/rules/no-multi-spaces), [`react/jsx-tag-spacing`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-tag-spacing.md)
- 总是在自闭和标签的标签前加一个空格。 eslint: [`no-multi-spaces`](https://eslint.org/docs/rules/no-multi-spaces), [`react/jsx-tag-spacing`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-tag-spacing.md)

```jsx
// bad
Expand All @@ -234,7 +239,7 @@ This style guide is mostly based on the standards that are currently prevalent i
<Foo />
```

- Do not pad JSX curly braces with spaces. eslint: [`react/jsx-curly-spacing`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-curly-spacing.md)
- 不要在 JSX 中的括号两边添加空格。 eslint: [`react/jsx-curly-spacing`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-curly-spacing.md)

```jsx
// bad
Expand All @@ -244,9 +249,9 @@ This style guide is mostly based on the standards that are currently prevalent i
<Foo bar={baz} />
```

## Props
## <a id="props">属性</a>

- Always use camelCase for prop names.
- 总是使用驼峰命名法命名属性名。

```jsx
// bad
Expand All @@ -262,7 +267,7 @@ This style guide is mostly based on the standards that are currently prevalent i
/>
```

- Omit the value of the prop when it is explicitly `true`. eslint: [`react/jsx-boolean-value`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-boolean-value.md)
- 当一个属性的值为显式的 `true` 时，应该省略。 eslint: [`react/jsx-boolean-value`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/jsx-boolean-value.md)

```jsx
// bad
Expand All @@ -279,7 +284,7 @@ This style guide is mostly based on the standards that are currently prevalent i
<Foo hidden />
```

- Always include an `alt` prop on `<img>` tags. If the image is presentational, `alt` can be an empty string or the `<img>` must have `role="presentation"`. eslint: [`jsx-a11y/alt-text`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/alt-text.md)
- `<img>` 标签应该始终添加 `alt` 属性。 如果图片是直观的， `alt` 可以为空或者 `<img>` 必须有 `role="presentation"` 属性。 eslint: [`jsx-a11y/alt-text`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/alt-text.md)

```jsx
// bad
Expand All @@ -295,9 +300,9 @@ This style guide is mostly based on the standards that are currently prevalent i
<img src="hello.jpg" role="presentation" />
```

- Do not use words like "image", "photo", or "picture" in `<img>` `alt` props. eslint: [`jsx-a11y/img-redundant-alt`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/img-redundant-alt.md)
- 不要在 `<img>` 的 `alt` 属性中使用 "image"， "photo"， 或 "picture" 这些词汇。 eslint: [`jsx-a11y/img-redundant-alt`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/img-redundant-alt.md)

> Why? Screenreaders already announce `img` elements as images, so there is no need to include this information in the alt text.
> 为什么？ 屏幕阅读器已经把 `img` 元素作为图片了，因此 alt 中不需要再进行说明。

```jsx
// bad
Expand All @@ -307,22 +312,22 @@ This style guide is mostly based on the standards that are currently prevalent i
<img src="hello.jpg" alt="Me waving hello" />
```

- Use only valid, non-abstract [ARIA roles](https://www.w3.org/TR/wai-aria/roles#role_definitions). eslint: [`jsx-a11y/aria-role`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-role.md)
- 只是用有效的，非抽象的 [ARIA roles](https://www.w3.org/TR/wai-aria/roles#role_definitions)。 eslint: [`jsx-a11y/aria-role`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/aria-role.md)

```jsx
// bad - not an ARIA role
// bad - 不是一个 ARIA role
<div role="datepicker" />
// bad - abstract ARIA role
// bad - 抽象的 ARIA role
<div role="range" />
// good
<div role="button" />
```

- Do not use `accessKey` on elements. eslint: [`jsx-a11y/no-access-key`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/no-access-key.md)
- 不要在元素上使用 `accessKey` 。 eslint: [`jsx-a11y/no-access-key`](https://github.com/evcohen/eslint-plugin-jsx-a11y/blob/master/docs/rules/no-access-key.md)

> Why? Inconsistencies between keyboard shortcuts and keyboard commands used by people using screenreaders and keyboards complicate accessibility.
> 为什么？ 设置的键盘快捷键和使用显示器和键盘的人的键盘命令不一致会导致访问的复杂性。

```jsx
// bad
Expand All @@ -332,7 +337,7 @@ This style guide is mostly based on the standards that are currently prevalent i
<div />
```

- Avoid using an array index as `key` prop, prefer a unique ID. ([why?](https://medium.com/@robinpokorny/index-as-a-key-is-an-anti-pattern-e0349aece318))
- 避免使用数组的索引作为 `key` 属性的值，应该是唯一的 ID。 ([why?](https://medium.com/@robinpokorny/index-as-a-key-is-an-anti-pattern-e0349aece318))

```jsx
// bad
Expand All @@ -352,9 +357,9 @@ This style guide is mostly based on the standards that are currently prevalent i
))}
```

- Always define explicit defaultProps for all non-required props.
- 总是为所有非必要的属性定义明确的 defaultProps 。

> Why? propTypes are a form of documentation, and providing defaultProps means the reader of your code doesn’t have to assume as much. In addition, it can mean that your code can omit certain type checks.
> 为什么？ propTypes 可以作为组件的文档说明，并且声明 defaultProps 意味着，阅读代码的人不需要假设一下默认的值。更重要的是，显式的声明默认属性可以让你的组件跳过属性的类型检查。

```jsx
// bad
Expand Down Expand Up @@ -382,12 +387,12 @@ This style guide is mostly based on the standards that are currently prevalent i
};
```

- Use spread props sparingly.
> Why? Otherwise you're more likely to pass unnecessary props down to components. And for React v15.6.1 and older, you could [pass invalid HTML attributes to the DOM](https://reactjs.org/blog/2017/09/08/dom-attributes-in-react-16.html).
- 尽可能少使用扩展运算符。
> 为什么？ 这样你有更大的可能将不必要的属性传递个组件。对于 React v15.6.1 和更老的版本，你可以查看 [将无效的属性传递给 DOM ](https://reactjs.org/blog/2017/09/08/dom-attributes-in-react-16.html).

Exceptions:
例外：

- HOCs that proxy down props and hoist propTypes
- 代理高阶组件和 propTypes 变量提升。

```jsx
function HOC(WrappedComponent) {
Expand All @@ -404,7 +409,7 @@ This style guide is mostly based on the standards that are currently prevalent i
}
```

- Spreading objects with known, explicit props. This can be particularly useful when testing React components with Mocha's beforeEach construct.
- 对于已知的，明确的对象使用扩展运算符。这非常有用尤其是在使用 Mocha 测试组件的时候。

```jsx
export default function Foo {
Expand All @@ -417,8 +422,7 @@ This style guide is mostly based on the standards that are currently prevalent i
}
```

Notes for use:
Filter out unnecessary props when possible. Also, use [prop-types-exact](https://www.npmjs.com/package/prop-types-exact) to help prevent bugs.
使用注意事项：尽可能的过滤掉不必要的属性。 此外，可以使用 [prop-types-exact](https://www.npmjs.com/package/prop-types-exact) 来帮助避免错误。

```jsx
// good
Expand All @@ -434,9 +438,9 @@ This style guide is mostly based on the standards that are currently prevalent i
}
```

## Refs
## <a id="refs">Refs</a>

- Always use ref callbacks. eslint: [`react/no-string-refs`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-string-refs.md)
- 总是在 ref 中使用回调函数。 eslint: [`react/no-string-refs`](https://github.com/yannickcr/eslint-plugin-react/blob/master/docs/rules/no-string-refs.md)

```jsx
// bad
Expand Down

0 comments on commit ae7a816

Please sign in to comment.