diff --git a/docs/07-forms.zh-CN.md b/docs/07-forms.zh-CN.md new file mode 100644 index 00000000..b5a7f3f4 --- /dev/null +++ b/docs/07-forms.zh-CN.md @@ -0,0 +1,168 @@ +--- +id: forms-zh-CN +title: 表单组件 +permalink: forms-zh-CN.html +prev: transferring-props-zh-CN.html +next: working-with-the-browser-zh-CN.html +--- + +诸如 ``、``、`` 这样的表单组件不同于其他组件,因为他们可以通过用户交互发生变化。这些组件提供的界面使响应用户交互的表单数据处理更加容易。 + +关于 `` 事件详情请查看 [表单事件](/react/docs/events.html#form-events)。 + +## 交互属性 + +表单组件支持几个受用户交互影响的属性: + +* `value`,用于 ``、`` 组件。 +* `checked`,用于类型为 `checkbox` 或者 `radio` 的 `` 组件。 +* `selected`,用于 `` 组件。 + +在 HTML 中,`` 的值通过子节点设置;在 React 中则应该使用 `value` 代替。 + +表单组件可以通过 `onChange` 回调函数来监听组件变化。当用户做出以下交互时,`onChange` 执行并通过浏览器做出响应: + +* `` 或 `` 的 `value` 发生变化时。 +* `` 的 `checked` 状态改变时。 +* `` 的 `selected` 状态改变时。 + +和所有 DOM 事件一样,所有的 HTML 原生组件都支持 `onChange` 属性,而且可以用来监听冒泡的 `change` 事件。 + + +## 受限组件 + +设置了 `value` 的 `` 是一个*受限*组件。 对于受限的 ``,渲染出来的 HTML 元素始终保持 `value` 属性的值。例如: + +```javascript + render: function() { + return ; + } +``` + +上面的代码将渲染出一个值为 `Hello!` 的 input 元素。用户在渲染出来的元素里输入任何值都不起作用,因为 React 已经赋值为 `Hello!`。如果想响应更新用户输入的值,就得使用 `onChange` 事件: + +```javascript + getInitialState: function() { + return {value: 'Hello!'}; + }, + handleChange: function(event) { + this.setState({value: event.target.value}); + }, + render: function() { + var value = this.state.value; + return ; + } +``` + +上面的代码中,React 将用户输入的值更新到 `` 组件的 `value` 属性。这样实现响应或者验证用户输入的界面就很容易了。例如: + +```javascript + handleChange: function(event) { + this.setState({value: event.target.value.substr(0, 140)}); + } +``` + +上面的代码接受用户输入,并截取前 140 个字符。 + + +## 不受限组件 + +没有设置 `value`(或者设为 `null`) 的 `` 组件是一个*不受限*组件。对于不受限的 `` 组件,渲染出来的元素直接反应用户输入。例如: + +```javascript + render: function() { + return ; + } +``` + +上面的代码将渲染出一个空值的输入框,用户输入将立即反应到元素上。和受限元素一样,使用 `onChange` 事件可以监听值的变化。 + +如果想给组件设置一个非空的初始值,可以使用 `defaultValue` 属性。例如: + +```javascript + render: function() { + return ; + } +``` + +上面的代码渲染出来的元素和**受限组件**一样有一个初始值,但这个值用户可以改变并会反应到界面上。 + +同样地, 类型为 `radio`、`checkbox` 的`` 支持 `defaultChecked` 属性, `` 支持 `defaultValue` 属性。 + +```javascript + render: function() { + return ( + + Option 1 + Option 2 + + Apple + Banana + Cranberry + + + ); + } +``` + + +## 高级主题 + +### 为什么使用受限组件? + +在 React 中使用诸如 `` 的表单组件时,遇到了一个在传统 HTML 中没有的挑战。 + +比如下面的代码: + +```html + +``` + +在 HTML 中将渲染初始值为 `Untitled` 的输入框。用户改变输入框的值时,节点的 `value` 属性(*property*)将随之变化,但是 `node.getAttribute('value')` 还是会返回初始设置的值 `Untitled`. + +与 HTML 不同,React 组件必须在任何时间点描绘视图的状态,而不仅仅是在初始化时。比如在 React 中: + +```javascript + render: function() { + return ; + } +``` + +该方法在任何时间点渲染组件以后,输入框的值就应该*始终*为 `Untitled`。 + + +### 为什么 `` 使用 `value` 属性? + +在 HTML 中, `` 的值通常使用子节点设置: + +```html + + This is the description. +``` + +对 HTML 而言,让开发者设置多行的值很容易。但是,React 是 JavaScript,没有字符限制,可以使用 `\n` 实现换行。简言之,React 已经有 `value`、`defaultValue` 属性,`` 组件的子节点扮演什么角色就有点模棱两可了。基于此, 设置 `` 值时不应该使用子节点: + +```javascript + +``` + +如果*非要**使用子节点,效果和使用 `defaultValue` 一样。 + + +### 为什么 `` 使用 `value` 属性 + +HTML 中 `` 通常使用 `` 的 `selected` 属性设置选中状态;React 为了更方面的控制组件,采用以下方式代替: + +```javascript + + Apple + Banana + Cranberry + +``` + +如果是不受限组件,则使用 `defaultValue`。 + +> 注意: +> +> 给 `value` 属性传递一个数组,可以选中多个选项:``。 diff --git a/docs/ref-05-events.zh-CN.md b/docs/ref-05-events.zh-CN.md new file mode 100644 index 00000000..2da62a18 --- /dev/null +++ b/docs/ref-05-events.zh-CN.md @@ -0,0 +1,194 @@ +--- +id: events-zh-CN +title: 事件系统 +permalink: events-zh-CN.html +prev: tags-and-attributes-zh-CN.html +next: dom-differences-zh-CN.html +--- + +## 合成事件 + +事件处理程序通过 `合成事件`(`SyntheticEvent`)的实例传递,`SyntheticEvent` 是浏览器原生事件跨浏览器的封装。`SyntheticEvent` 和浏览器原生事件一样有 `stopPropagation()`、`preventDefault()` 接口,而且这些接口夸浏览器兼容。 + +如果出于某些原因想使用浏览器原生事件,可以使用 `nativeEvent` 属性获取。每个和成事件(`SyntheticEvent`)对象都有以下属性: + +```javascript +boolean bubbles +boolean cancelable +DOMEventTarget currentTarget +boolean defaultPrevented +Number eventPhase +boolean isTrusted +DOMEvent nativeEvent +void preventDefault() +void stopPropagation() +DOMEventTarget target +Date timeStamp +String type +``` + +> 注意: +> +> React v0.12 中,事件处理程序返回 `false` 不再停止事件传播,取而代之,应该根据需要手动触发 `e.stopPropagation()` 或 `e.preventDefault()`。 + + +## 支持的事件 + +React 将事件统一化,使事件在不同浏览器上有一致的属性。 + +下面的事件处理程序在事件冒泡阶段被触发。如果要注册事件捕获处理程序,应该使用 `Capture` 事件,例如使用 `onClickCapture` 处理点击事件的捕获阶段,而不是 `onClick`。 + + +### 剪贴板事件 + +事件名称: + +``` +onCopy onCut onPaste +``` + +属性: + +```javascript +DOMDataTransfer clipboardData +``` + + +### 键盘事件 + +事件名称: + +``` +onKeyDown onKeyPress onKeyUp +``` + +属性: + +```javascript +boolean altKey +Number charCode +boolean ctrlKey +function getModifierState(key) +String key +Number keyCode +String locale +Number location +boolean metaKey +boolean repeat +boolean shiftKey +Number which +``` + + +### 焦点事件 + +事件名称 + +``` +onFocus onBlur +``` + +属性: + +```javascript +DOMEventTarget relatedTarget +``` + + +### 表单事件 + +事件名称: + +``` +onChange onInput onSubmit +``` + +关于 `onChange` 事件的更多信息,参见 [表单组件](/react/docs/forms-zh-CN.html)。 + + +### 鼠标事件 + +事件名称: + +``` +onClick onDoubleClick onDrag onDragEnd onDragEnter onDragExit onDragLeave +onDragOver onDragStart onDrop onMouseDown onMouseEnter onMouseLeave +onMouseMove onMouseOut onMouseOver onMouseUp +``` + +属性: + +```javascript +boolean altKey +Number button +Number buttons +Number clientX +Number clientY +boolean ctrlKey +function getModifierState(key) +boolean metaKey +Number pageX +Number pageY +DOMEventTarget relatedTarget +Number screenX +Number screenY +boolean shiftKey +``` + + +### 触控事件 + +在渲染任意组件之前调用 `React.initializeTouchEvents(true)`,以启用触控事件。 + +事件名称: + +``` +onTouchCancel onTouchEnd onTouchMove onTouchStart +``` + +属性: + +```javascript +boolean altKey +DOMTouchList changedTouches +boolean ctrlKey +function getModifierState(key) +boolean metaKey +boolean shiftKey +DOMTouchList targetTouches +DOMTouchList touches +``` + + +### 用户界面事件 + +事件名称: + +``` +onScroll +``` + +属性: + +```javascript +Number detail +DOMAbstractView view +``` + + +### 滚轮事件 + +事件名称: + +``` +onWheel +``` + +属性: + +```javascript +Number deltaMode +Number deltaX +Number deltaY +Number deltaZ +```