diff --git a/src/content/reference/react-dom/components/input.md b/src/content/reference/react-dom/components/input.md index dddab6f7df..57fcc40ca3 100644 --- a/src/content/reference/react-dom/components/input.md +++ b/src/content/reference/react-dom/components/input.md @@ -4,7 +4,7 @@ title: "" -The [built-in browser `` component](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input) lets you render different kinds of form inputs. +[浏览器内置的 `` 组件](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input) 允许你渲染不同类型的表单输入框。 ```js @@ -16,92 +16,92 @@ The [built-in browser `` component](https://developer.mozilla.org/zh-CN/d --- -## Reference {/*reference*/} +## 参考 {/*reference*/} ### `` {/*input*/} -To display an input, render the [built-in browser ``](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input) component. +渲染 [浏览器内置的 ``](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input) 组件以展示输入框。 ```js ``` -[See more examples below.](#usage) - -#### Props {/*props*/} - -`` supports all [common element props.](/reference/react-dom/components/common#props) - -You can [make an input controlled](#controlling-an-input-with-a-state-variable) by passing one of these props: - -* [`checked`](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLInputElement#checked): A boolean. For a checkbox input or a radio button, controls whether it is selected. -* [`value`](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLInputElement#value): A string. For a text input, controls its text. (For a radio button, specifies its form data.) - -When you pass either of them, you must also pass an `onChange` handler that updates the passed value. - -These `` props are only relevant for uncontrolled inputs: - -* [`defaultChecked`](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLInputElement#defaultChecked): A boolean. Specifies [the initial value](#providing-an-initial-value-for-an-input) for `type="checkbox"` and `type="radio"` inputs. -* [`defaultValue`](https://developer.mozilla.org/zh-CN/docs/Web/API/HTMLInputElement#defaultValue): A string. Specifies [the initial value](#providing-an-initial-value-for-an-input) for a text input. - -These `` props are relevant both for uncontrolled and controlled inputs: - -* [`accept`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#accept): A string. Specifies which filetypes are accepted by a `type="file"` input. -* [`alt`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#alt): A string. Specifies the alternative image text for a `type="image"` input. -* [`capture`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#capture): A string. Specifies the media (microphone, video, or camera) captured by a `type="file"` input. -* [`autoComplete`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#autocomplete): A string. Specifies one of the possible [autocomplete behaviors.](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/autocomplete#values) -* [`autoFocus`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#autofocus): A boolean. If `true`, React will focus the element on mount. -* [`dirname`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#dirname): A string. Specifies the form field name for the element's directionality. -* [`disabled`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#disabled): A boolean. If `true`, the input will not be interactive and will appear dimmed. -* `children`: `` does not accept children. -* [`form`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#form): A string. Specifies the `id` of the `
` this input belongs to. If omitted, it's the closest parent form. -* [`formAction`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#formaction): A string. Overrides the parent `` for `type="submit"` and `type="image"`. -* [`formEnctype`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#formenctype): A string. Overrides the parent `` for `type="submit"` and `type="image"`. -* [`formMethod`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#formmethod): A string. Overrides the parent `` for `type="submit"` and `type="image"`. -* [`formNoValidate`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#formnovalidate): A string. Overrides the parent `` for `type="submit"` and `type="image"`. -* [`formTarget`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#formtarget): A string. Overrides the parent `` for `type="submit"` and `type="image"`. -* [`height`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#height): A string. Specifies the image height for `type="image"`. -* [`list`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#list): A string. Specifies the `id` of the `` with the autocomplete options. -* [`max`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#max): A number. Specifies the maximum value of numerical and datetime inputs. -* [`maxLength`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#maxlength): A number. Specifies the maximum length of text and other inputs. -* [`min`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#min): A number. Specifies the minimum value of numerical and datetime inputs. -* [`minLength`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#minlength): A number. Specifies the minimum length of text and other inputs. -* [`multiple`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#multiple): A boolean. Specifies whether multiple values are allowed for `` changes. React extends the `onSelect` event to also fire for empty selection and on edits (which may affect the selection). -* `onSelectCapture`: A version of `onSelect` that fires in the [capture phase.](/learn/responding-to-events#capture-phase-events) -* [`pattern`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#pattern): A string. Specifies the pattern that the `value` must match. -* [`placeholder`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#placeholder): A string. Displayed in a dimmed color when the input value is empty. -* [`readOnly`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#readonly): A boolean. If `true`, the input is not editable by the user. -* [`required`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#required): A boolean. If `true`, the value must be provided for the form to submit. -* [`size`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#size): A number. Similar to setting width, but the unit depends on the control. -* [`src`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#src): A string. Specifies the image source for a `type="image"` input. -* [`step`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#step): A positive number or an `'any'` string. Specifies the distance between valid values. -* [`type`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#type): A string. One of the [input types.](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#input_types) -* [`width`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#width): A string. Specifies the image width for a `type="image"` input. - -#### Caveats {/*caveats*/} - -- Checkboxes need `checked` (or `defaultChecked`), not `value` (or `defaultValue`). -- If a text input receives a string `value` prop, it will be [treated as controlled.](#controlling-an-input-with-a-state-variable) -- If a checkbox or a radio button receives a boolean `checked` prop, it will be [treated as controlled.](#controlling-an-input-with-a-state-variable) -- An input can't be both controlled and uncontrolled at the same time. -- An input cannot switch between being controlled or uncontrolled over its lifetime. -- Every controlled input needs an `onChange` event handler that synchronously updates its backing value. +[参见下面更多示例](#usage)。 + +#### 属性 {/*props*/} + +`` 支持所有 [常见的元素属性](/reference/react-dom/components/common#props)。 + +你可以传递以下属性中的任意一个,以将其变为 [受控输入框](#controlling-an-input-with-a-state-variable): + +* `checked`:布尔值,控制复选框或单选按钮是否被选中。 +* `value`:字符串,控制文本框的输入文本(如果是单选按钮,则为其表单数据)。 + +当你传递它们之一时,你必须同时传递 `onChange` 处理函数,用于更新传递的值。 + +以下 `` 属性仅在非受控输入框中有效: + +* `defaultChecked`:布尔值,指定 `type="checkbox"` 和 `type="radio"` 输入的 [初始值](#providing-an-initial-value-for-an-input)。 +* `defaultValue`:字符串,指定文本框的 [初始值](#providing-an-initial-value-for-an-input)。 + +以下 `` 属性均可用于受控与非受控输入框: + +* `accept`:字符串,指定 `type="file"` 输入框所接受的文件类型。 +* `alt`:字符串,指定 `type="image"` 输入框的替代图像文本。 +* `capture`:字符串,指定 `type="file"` 输入框所捕获的媒体(麦克风、视频或摄像头)。 +* `autoComplete`:字符串,指定可能的 [自动填充行为](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes/autocomplete#values) 之一。 +* `autoFocus`:布尔值。如果为 `true`,React 将在挂载时聚焦于此元素。 +* `dirname`:字符串,指定元素的方向性的表单字段名称。 +* `disabled`:布尔值。如果为`true`,输入框将无法交互并显示为不可用(dimmed)。 +* `children`:`` 不接受子元素。 +* `form`:字符串,指定此输入框所属的 `` 的 `id`。如果未指定,则为最近的父表单。 +* `formAction`:字符串。输入框指定此值并指定 `type="submit"` 或 `type="image"` 后将覆盖父表单对应属性 ``。 +* `formEnctype`:字符串。输入框指定此值并指定 `type="submit"` 或 `type="image"` 后将覆盖父表单对应属性 ``。 +* `formMethod`:字符串。输入框指定此值并指定 `type="submit"` 或 `type="image"` 后将覆盖父表单对应属性 ``。 +* `formNoValidate`:字符串。输入框指定此值并指定 `type="submit"` 或 `type="image"` 后将覆盖父表单对应属性 ``。 +* `formTarget`:字符串。输入框指定此值并指定 `type="submit"` 或 `type="image"` 后将覆盖父表单对应属性 ``。 +* `height`:字符串,指定 `type="image"` 的图像高度。 +* `list`:字符串,指定带有自动完成选项的 `` 的 `id`。 +* `max`:数字,指定数值和日期时间输入的最大值。 +* `maxLength`:数字,指定文本和其他输入的最大长度。 +* `min`:数字,指定数值和日期时间输入的最小值。 +* `minLength`:数字,指定文本和其他输入的最小长度。 +* `multiple`:布尔值,指定是否允许 `` 内的选择更改后触发。React 扩展了 `onSelect` 事件,使其也能在选择为空和编辑时触发(可能会影响选择)。 +* `onSelectCapture`:与 `onSelect` 类似,但是是在 [捕获阶段](/learn/responding-to-events#capture-phase-events) 触发。 +* `pattern`:字符串,指定 `value` 必须匹配的模式。 +* `placeholder`:字符串,当输入值为空时,以暗淡的颜色显示的内容。 +* `readOnly`:布尔值。如果为 `true`,用户无法编辑输入。 +* `required`:布尔值。如果为 `true`,提交表单时必须提供此输入框的值。 +* `size`:数字,类似于设置宽度,但单位取决于控件。 +* `src`:字符串,指定 `type="image"` 输入框的图像源。 +* `step`:正数或 `'any'` 字符串,指定有效值之间的距离。 +* `type`:字符串,[输入框类型](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#input_types) 中的一个。 +* `width`:字符串,指定 `type="image"` 输入框的图像宽度。 + +#### 注意 {/*caveats*/} + +- 复选框需要使用 `checked` 或 `defaultChecked`,而不是 `value` 或 `defaultValue`。 +- 如果文本框接收到字符串类型的 `value` 属性,则会被 [视为受控组件](#controlling-an-input-with-a-state-variable)。 +- 如果复选框或单选按钮接收到布尔类型的 `checked` 属性,则会被 [视为受控组件](#controlling-an-input-with-a-state-variable)。 +- 一个输入框不能同时既是受控组件又是非受控组件。 +- 一个输入框在其生命周期中不能在受控和非受控之间切换。 +- 每个受控组件都需要一个 `onChange` 事件处理函数,用于同步更新其值。 --- -## Usage {/*usage*/} +## 用法 {/*usage*/} -### Displaying inputs of different types {/*displaying-inputs-of-different-types*/} +### 展示不同类型的输入框 {/*displaying-inputs-of-different-types*/} -To display an input, render an `` component. By default, it will be a text input. You can pass `type="checkbox"` for a checkbox, `type="radio"` for a radio button, [or one of the other input types.](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#input_types) +渲染 `input` 组件展示输入框。默认情况下,这是一个文本框。你可以传递 `type="checkbox"` 将其指定为多选框;或者传递 `type="radio"` 将其指定为单选按钮;[你也可以将其指定为其他类型](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/input#input_types)。 @@ -110,26 +110,26 @@ export default function MyForm() { return ( <>

- Radio buttons: + 单选按钮:

@@ -146,11 +146,11 @@ input { margin: 5px; } --- -### Providing a label for an input {/*providing-a-label-for-an-input*/} +### 为输入框提供 label 属性 {/*providing-a-label-for-an-input*/} -Typically, you will place every `` inside a [`