diff --git a/docs/_data/nav_tutorial.yml b/docs/_data/nav_tutorial.yml index 49cc7557f9..15b50af222 100755 --- a/docs/_data/nav_tutorial.yml +++ b/docs/_data/nav_tutorial.yml @@ -1,77 +1,77 @@ -- title: Tutorial +- title: 入门教程 items: - id: tutorial - title: Before We Start + title: 课前准备 subitems: - id: what-were-building - title: What We're Building + title: 教程简介 href: /react/tutorial/tutorial.html#what-were-building forceInternal: true - id: prerequisites - title: Prerequisites + title: 前置知识 href: /react/tutorial/tutorial.html#prerequisites forceInternal: true - id: how-to-follow-along - title: How to Follow Along + title: 如何编写代码 href: /react/tutorial/tutorial.html#how-to-follow-along forceInternal: true - id: help-im-stuck - title: Help, I'm Stuck! + title: 寻求帮助 href: /react/tutorial/tutorial.html#help-im-stuck forceInternal: true - id: overview - title: Overview + title: 总览 href: /react/tutorial/tutorial.html#overview forceInternal: true subitems: - id: what-is-react - title: What is React? + title: React 是什么？ href: /react/tutorial/tutorial.html#what-is-react forceInternal: true - id: getting-started - title: Getting Started + title: 开始编码 href: /react/tutorial/tutorial.html#getting-started forceInternal: true - id: passing-data-through-props - title: Passing Data Through Props + title: 通过 Props 传递数据 href: /react/tutorial/tutorial.html#passing-data-through-props forceInternal: true - id: an-interactive-component - title: An Interactive Component + title: 给组件添加交互功能 href: /react/tutorial/tutorial.html#an-interactive-component forceInternal: true - id: developer-tools - title: Developer Tools + title: 开发工具 href: /react/tutorial/tutorial.html#developer-tools forceInternal: true - id: lifting-state-up - title: Lifting State Up + title: 状态提升 href: /react/tutorial/tutorial.html#lifting-state-up forceInternal: true subitems: - id: why-immutability-is-important - title: Why Immutability Is Important + title: 为什么不可变性在React当中非常重要 href: /react/tutorial/tutorial.html#why-immutability-is-important forceInternal: true - id: functional-components - title: Functional Components + title: 函数定义组件 href: /react/tutorial/tutorial.html#functional-components forceInternal: true - id: taking-turns - title: Taking Turns + title: 轮流落子 href: /react/tutorial/tutorial.html#taking-turns forceInternal: true - id: declaring-a-winner - title: Declaring a Winner + title: 判断赢家 href: /react/tutorial/tutorial.html#declaring-a-winner forceInternal: true - id: storing-a-history - title: Storing A History + title: 保存历史纪录 href: /react/tutorial/tutorial.html#storing-a-history forceInternal: true subitems: - id: showing-the-moves - title: Showing the Moves + title: 展示每步历史纪录链接 href: /react/tutorial/tutorial.html#showing-the-moves forceInternal: true - id: keys @@ -79,10 +79,10 @@ href: /react/tutorial/tutorial.html#keys forceInternal: true - id: implementing-time-travel - title: Implementing Time Travel + title: 实现时间旅行 href: /react/tutorial/tutorial.html#implementing-time-travel forceInternal: true - id: wrapping-up - title: Wrapping Up + title: 总结 href: /react/tutorial/tutorial.html#wrapping-up forceInternal: true diff --git a/docs/_layouts/tutorial.html b/docs/_layouts/tutorial.html index c6bd4832df..9e91f1fa7b 100755 --- a/docs/_layouts/tutorial.html +++ b/docs/_layouts/tutorial.html @@ -8,8 +8,8 @@
Edit on GitHub + href="https://github.com/discountry/react/tree/master/docs/{{ page.path }}" + target="_blank">纠错

{{ page.title }}

diff --git a/docs/docs/integrating-with-other-libraries.md b/docs/docs/integrating-with-other-libraries.md index c7a3ab0083..94f8276144 100755 --- a/docs/docs/integrating-with-other-libraries.md +++ b/docs/docs/integrating-with-other-libraries.md @@ -4,23 +4,23 @@ title: 与第三方库协同 permalink: docs/integrating-with-other-libraries.html --- -React can be used in any web application. It can be embedded in other applications and, with a little care, other applications can be embedded in React. This guide will examine some of the more common use cases, focusing on integration with [jQuery](https://jquery.com/) and [Backbone](http://backbonejs.org/), but the same ideas can be applied to integrating components with any existing code. +我们可以在任何网页应用中使用 React。不仅可以把 React 添加到其他应用里，而且只要稍作改动，我们也可以把其他应用添加到 React 项目里。本文将着重介绍如何将 React 与 [jQuery](https://jquery.com/) 以及 [Backbone](http://backbonejs.org/) 结合使用。当然，类似的思路同样可以应用与其他场景。 -## Integrating with DOM Manipulation Plugins +## 与 DOM 节点操作类插件结合 -React is unaware of changes made to the DOM outside of React. It determines updates based on its own internal representation, and if the same DOM nodes are manipulated by another library, React gets confused and has no way to recover. +对于 React 之外的 DOM 节点操作，React 是不会去处理的，因为 React 内部有自己的渲染逻辑。当相同的 DOM 节点被外部的代码改变时，React 就会很迷茫，并不知道发生了什么。 -This does not mean it is impossible or even necessarily difficult to combine React with other ways of affecting the DOM, you just have to be mindful of what each are doing. +但这也不意味着 React 无法与其他操作 DOM 节点的库一起使用，你只要清楚他们分别在做什么就可以了。 -The easiest way to avoid conflicts is to prevent the React component from updating. You can do this by rendering elements that React has no reason to update, like an empty `
`. +最简单的方式就是阻止 React 更新外部在操作的节点，那么你可以通过生成一个 React 根本不会去更新的元素来实现，比如空的 `
`。 -### How to Approach the Problem +### 进一步的解释 -To demonstrate this, let's sketch out a wrapper for a generic jQuery plugin. +为了解释得更清楚，我们先来封装一个通用的 jQuery 插件吧。 -We will attach a [ref](/react/docs/refs-and-the-dom.html) to the root DOM element. Inside `componentDidMount`, we will get a reference to it so we can pass it to the jQuery plugin. +在这里，我们给 DOM 的根节点元素加了一个 [ref](/react/docs/refs-and-the-dom.html)。在 `componentDidMount` 中，我们会调用这个 ref，并把它传给 jQuery 插件。 -To prevent React from touching the DOM after mounting, we will return an empty `
` from the `render()` method. The `
` element has no properties or children, so React has no reason to update it, leaving the jQuery plugin free to manage that part of the DOM: +为了防止 React 在 DOM 加载后修改节点，我们先要在 `render()` 中返回一个空的 `
`。这个空的 `
` 既没有属性也没有子元素，这样一来，React 就不会更新它了。那么，我们封装的 jQuery 插件就可以随意地更新这个节点。 ```js{3,4,8,12} class SomePlugin extends React.Component { @@ -39,21 +39,21 @@ class SomePlugin extends React.Component { } ``` -Note that we defined both `componentDidMount` and `componentWillUnmount` [lifecycle hooks](/react/docs/react-component.html#the-component-lifecycle). Many jQuery plugins attach event listeners to the DOM so it's important to detach them in `componentWillUnmount`. If the plugin does not provide a method for cleanup, you will probably have to provide your own, remembering to remove any event listeners the plugin registered to prevent memory leaks. +值得注意的是，我们既调用了 `componentDidMount` 也调用了 `componentWillUnmount` [生命周期函数](/react/docs/react-component.html#the-component-lifecycle)。由于很多 jQuery 的插件都会在 DOM 上挂载事件监听器，因此我们必须要在 `componentWillUnmount` 的时候把这个监听器删掉。如果某个插件没有提供“删除监听器”这类的方法，那你很可能需要自己写一个。为了防止内存泄漏，请务必在生命周期函数中移除插件挂载的事件监听器。 -### Integrating with jQuery Chosen Plugin +### 集成 jQuery Chosen 插件 -For a more concrete example of these concepts, let's write a minimal wrapper for the plugin [Chosen](https://harvesthq.github.io/chosen/), which augments `` 功能的 jQuery 插件。 ->**Note:** +> **注：** > ->Just because it's possible, doesn't mean that it's the best approach for React apps. We encourage you to use React components when you can. React components are easier to reuse in React applications, and often provide more control over their behavior and appearance. +> 尽管以下的做法是可以实现的，但这样处理，并不是最佳的解决方案。更好的方式，显然是使用 React 组件。不仅因为在 React 应用中组件的可复用性强，而且通常来说，组件的行为及外观也是更容易控制的。 -First, let's look at what Chosen does to the DOM. +首先，我们先来看一下 Chosen 插件是如何操作 DOM 节点的。 -If you call it on a ``. Then it fires jQuery events to notify us about the changes. +如果你在 `` 这个节点隐藏起来。接下来，Chosen 插件会在隐藏起来的这个 `` wrapped in a `
`: +首先，我们来创建一个带有 `render()` 方法的空组件，这个组件返回用 `
` 包着的 `` in an extra `
`. This is necessary because Chosen will append another DOM element right after the ``，因为 Chosen 插件会在 `` node in `componentDidMount`, and tear it down in `componentWillUnmount`: + +接下来，我们需要添加生命周期函数。在 Chosen 插件初始化节点的时候，我们需要在 `componentDidMount` 里面给 ` this.el = el}> ``` -This is enough to get our component to render, but we also want to be notified about the value changes. To do this, we will subscribe to the jQuery `change` event on the `` 元素中"订阅" jQuery 的 `change` 事件。 -We won't pass `this.props.onChange` directly to Chosen because component's props might change over time, and that includes event handlers. Instead, we will declare a `handleChange()` method that calls `this.props.onChange`, and subscribe it to the jQuery `change` event: +我们不需要直接给 Chosen 传入 `this.props.onChange`，因为组件的 props 会随时发生变化，而且我们还需要一个处理 jQuery 事件的方法。在这里，我们定义了一个 `handleChange` 方法，这个方法会调用 `this.props.onChange`。然后，我们就用方法来订阅 jQuery 的 `change` 事件： ```js{5,6,10,14-16} componentDidMount() { @@ -131,11 +132,11 @@ handleChange(e) { } ``` -[Try it on CodePen.](http://codepen.io/gaearon/pen/bWgbeE?editors=0010) +[CodePen 上的示例](http://codepen.io/gaearon/pen/bWgbeE?editors=0010) -Finally, there is one more thing left to do. In React, props can change over time. For example, the `` component can get different children if parent component's state changes. This means that at integration points it is important that we manually update the DOM in response to prop updates, since we no longer let React manage the DOM for us. +最后，我们还剩下一件事要做。正如上面提到的，在 React 中，props 可以随时改变。举个例子，如果 `` 组件父级元素的 state 改变了，那么 `` 组件里面的 DOM 节点也很可能发生变化。这也就意味着，在集成插件的时候，如果 props 发生了改变，那我们就需要手动更新 DOM 元素，这是因为我们之前已经保证过 React 不会去处理这个节点。 -Chosen's documentation suggests that we can use jQuery `trigger()` API to notify it about changes to the original DOM element. We will let React take care of updating `this.props.children` inside `` 中的 `this.props.children`，然后用 `componentDidUpdate()` 来通知 Chosen 去更新节点的 DOM 元素： ```js{2,3} componentDidUpdate(prevProps) { @@ -145,9 +146,9 @@ componentDidUpdate(prevProps) { } ``` -This way, Chosen will know to update its DOM element when the `` 子元素变化的时候去更新 DOM 元素了。 -The complete implementation of the `Chosen` component looks like this: +我们把上面提到的内容结合起来，`Chosen` 组件的最终代码如下： ```js class Chosen extends React.Component { @@ -186,21 +187,21 @@ class Chosen extends React.Component { } ``` -[Try it on CodePen.](http://codepen.io/gaearon/pen/xdgKOz?editors=0010) +[CodePen 上的示例](http://codepen.io/gaearon/pen/xdgKOz?editors=0010) -## Integrating with Other View Libraries +## 在 React 中使用其他引擎加载页面 -React can be embedded into other applications thanks to the flexibility of [`ReactDOM.render()`](/react/docs/react-dom.html#render). +由于 [`ReactDOM.reander()`](/react/docs/react-dom.html#render) 方法很灵活，因此我们可以将 React 与其他处理页面显示的库结合使用。 -Although React is commonly used at startup to load a single root React component into the DOM, `ReactDOM.render()` can also be called multiple times for independent parts of the UI which can be as small as a button, or as large as an app. +通常来说，尽管 React 是在页面加载的时候把一个根组件放到 DOM 里，但 `ReactDOM.render()` 方法也可以被不同的 UI 部件多次调用。这个部件可以仅仅是一个按钮，或者也可以是一个应用。 -In fact, this is exactly how React is used at Facebook. This lets us write applications in React piece by piece, and combine it with our existing server-generated templates and other client-side code. +事实上，Facebook 就是这么使用 React 的。我们可以独立地开发每一个部件，然后把这些部件与服务端创建的模板以及客户端代码结合起来，这样就形成了一个完整的应用。 -### Replacing String-Based Rendering with React +### 在 React 中使用“字符串替换”类的库 -A common pattern in older web applications is to describe chunks of the DOM as a string and insert it into the DOM like so: `$el.html(htmlString)`. These points in a codebase are perfect for introducing React. Just rewrite the string based rendering as a React component. +早起的网页应用中，一个常用的方式是先把内容定义成字符串片段，然后插入到 DOM 节点中，就像这样：`$el.html(htmlString)`。采用这种方式写出来的应用，其实非常适合引入 React。只需要把那些字符串定义成 React 组件就可以了。 -So the following jQuery implementation... +比如，这一段 jQuery 代码…… ```js $('#container').html(''); @@ -209,7 +210,7 @@ $('#btn').click(function() { }); ``` -...could be rewritten using a React component: +……可以改写成这样的 React 组件： ```js function Button() { @@ -227,7 +228,7 @@ ReactDOM.render( ); ``` -From here you could start moving more logic into the component and begin adopting more common React practices. For example, in components it is best not to rely on IDs because the same component can be rendered multiple times. Instead, we will use the [React event system](/react/docs/handling-events.html) and register the click handler directly on the React `