API 参考
组件

常见组件 (例如 <div>)

所有的内置浏览器组件, 例如 <div>, 都支持一些常见的属性和事件.

参考

通用组件 (例如 <div>) 

<div className="wrapper">Some content</div>

查看更多用例

Props

这些特殊的 React 属性适用于所有内置组件:

  • children: 一个 React 节点 (可以是元素, 字符串, 数字, portal, 空节点（ 如null, undefined） 和 布尔值, 或其他 React 数组节点)。 指定组件内部的内容. 当你使用JSX时, 通常会通过嵌套标签 <div><span /></div> 隐式地指定 children属性。

  • dangerouslySetInnerHTML: 一个形如 { __html: '<p>一些 HTML</p>' } 的对象，其中包含原始的 HTML 字符串。 覆盖DOM节点的 innerHTML 属性 ，并在内部显示传递的HTML内容. 这个属性应该极度谨慎使用! 如果内部的HTML不可信（例如，如果它基于用户数据）, 你有引入 XSS 漏洞的风险。 阅读更多关于使用dangerouslySetInnerHTML的内容。

  • ref: 来自 useRef 或者 createRef的ref对象, 或者一个 ref 回调函数, 或者一个用于 传统 refs 的字符串，你的引用将被填充为此节点的 DOM 元素。 阅读更多关于使用 refs 操纵 DOM 的内容。

  • suppressContentEditableWarning: 一个布尔值。 如果是 true, 抑制React对同时具有子元素和contentEditable={true}属性的元素发出的警告（这两者通常不能同时使用）。如果你正在构建一个手动管理contentEditable内容的文本输入库，请使用此选项。

  • suppressHydrationWarning: 一个布尔值。 如果你使用 服务器渲染,，通常会在服务器和客户端呈现不同内容时发出警告。 在一些罕见的情况下（比如时间戳），很难或者不可能保证完全匹配。 如果你设置 suppressHydrationWarning 为 true, React 不会警告你有关元素属性和内容不匹配的问题。 它只能在一个层级上工作，并且旨在用作紧急逃生通道。 阅读有关抑制混合错误的内容。

  • style: 一个带有CSS样式的对象，例如{ fontWeight: 'bold', margin: 20 }. 与DOM样式属性类似，CSS属性名称需要写成驼峰式，例如fontWeight而不是font-weight。 你可以将字符串或数字作为值传递，类似 width: 100, React会自动将值附加为px（“像素”），除非它是一个 无单位的属性.。 我们建议仅在动态样式中使用样式，其中是你事先不知道样式值。 在其他情况下，使用普通的CSS类和className更有效。了解有关className和style的更多信息.。

所有内置组件也支持这些标准的 DOM 属性：

你还可以将自定义属性作为 props 传递。 例如 mycustomprop="someValue". 当与第三方库集成时，这可能很有用。 自定义属性名称必须为小写，并且不能以 on 开头。 该值将被转换为一个字符串。If你传递null或undefined，则自定义属性将被删除。

这些事件仅适用于 <form> 元素：

这些事件仅适用于<dialog>元素，与浏览器事件不同，React 中的事件会冒泡：

这些事件仅适用于 <details>元素，与浏览器事件不同，React 中的事件会冒泡：

这些事件会触发在 <img>, <iframe>, <object>, <embed>, <link>, 和 SVG <image> 元素。 与浏览器事件不同，React 中的事件会冒泡：

  • onLoad: 一个 Event 处理 函数。 与浏览器事件不同，React 中的事件会冒泡：
  • onLoadCapture: 一个在捕获阶段捕获阶段.触发的onLoad版本。
  • onError: 一个 Event 处理 函数。 当资源无法加载时触发。
  • onErrorCapture: 一个在捕获阶段捕获阶段.触发的onError版本。

这些事件会触发在 <audio> and <video>. 与浏览器事件不同，React 中的事件会冒泡：

注意事项

  • 你不能同时传递children和dangerouslySetInnerHTML。
  • 有些事件(像 onAbort 和 onLoad) 在浏览器中不冒泡, 但是在React中冒泡.

ref 回调函数

你可以将一个函数传递给ref 属性，而不是像 useRef) 返回的那样使用 ref 对象。

<div ref={(node) => console.log(node)} />

查看使用 ref 回调函数的示例。

当 <div> DOM 节点被添加到屏幕上时，React 将使用该节点作为参数调用你的 ref 回调函数。

当你传递不同的ref回调时，React 也会调用你的 ref 回调。在上面的示例中，(node) => { ... } 在每次渲染时都是一个不同的函数。当组件重新渲染时，先前的函数将被调用并带有 null 参数，并且下一个函数将被调用并带有 DOM 节点。

参数

  • node: 一个DOM节点或null。 当 ref 被附加时React 会将 DOM 节点传递给你, 当引用被分离时值为 null。除非你在每次渲染时都传递相同的函数引用作为 ref 回调，否则该回调将在组件的每次重新渲染期间被暂时分离和重新连接。

返回

不要从 ref 回调函数中返回任何内容。

React 事件对象

你的事件处理程序将接收到一个React事件对象。它有时也被称为“合成事件”（synthetic event）.

<button onClick={e => {

  console.log(e); // React 事件对象

}} />

它符合与底层DOM事件相同的标准，但修复了一些浏览器不一致性。

一些React事件不能直接映射到浏览器的原生事件。 例如，在 onMouseLeave 事件中，e.nativeEvent 将指向 mouseout 事件。具体的映射关系不是公共 API 的一部分，可能会在未来发生变化。如果你需要某些原因下层浏览器事件，请从 e.nativeEvent 中读取它。

属性

React 事件对象实现了一些标准的事件属性：

  • bubbles: 一个布尔值。 返回事件是否会在 DOM 中冒泡传播。
  • cancelable: 一个布尔值。 返回事件是否可以被取消。
  • currentTarget: 一个 DOM 节点。 返回当前处理程序所附加到的节点在 React 树中的位置。
  • defaultPrevented: 一个布尔值。 返回是否调用了preventDefault。
  • eventPhase: 一个数字。 返回事件当前所处的阶段。
  • isTrusted: 一个布尔值。 返回事件是否由用户发起。
  • target: 一个 DOM 节点。 返回事件发生的节点（可能是远程子节点）“。
  • timeStamp: 一个数字。 返回事件发生的时间。

此外，React 事件对象提供了以下属性 ：

  • nativeEvent: 一个DOM事件。原始的浏览器事件对象。

方法

React 事件对象实现了一些标准的 事件 方法：

此外，React事件对象提供了以下方法：

  • isDefaultPrevented(): 返回一个布尔值，指示是否调用了preventDefault方法。
  • isPropagationStopped(): 返回一个布尔值，指示是否调用了 stopPropagation 方法。
  • persist(): 不适用于React DOM。在React Native中，调用此函数以读取事件后的属性。
  • isPersistent(): 不适用于 React DOM。在 React Native 中，返回是否已调用 persist。

注意事项

  • currentTarget、eventPhase、target 和 type 的值反映了你的 React 代码所期望的值。在幕后，React 在根处附加事件处理程序，但这不会反映在 React 事件对象中。例如，e.currentTarget 可能与底层 e.nativeEvent.currentTarget 不同。对于 polyfill 的事件，e.type（React 事件类型）可能与 e.nativeEvent.type（底层类型）不同。

AnimationsEvent 处理函数

一个用于 CSS 动画 事件的事件处理程序类型。

<div

  on aimationStart={e => console.log('on aimationStart')}

  on aimationIteration={e => console.log('on aimationIteration')}

  on aimationEnd={e => console.log('on aimationEnd')}

/>

参数

ClipboardEvent处理函数

一个用于 剪贴板 API 事件的处理程序类型。

<input

  onCopy={e => console.log('onCopy')}

  onCut={e => console.log('onCut')}

  onPaste={e => console.log('onPaste')}

/>

参数

CompositionEvent 处理函数

一个用于 输入法编辑器（IME）事件的事件处理程序类型。

<input

  onCompositionStart={e => console.log('onCompositionStart')}

  onCompositionUpdate={e => console.log('onCompositionUpdate')}

  onCompositionEnd={e => console.log('onCompositionEnd')}

/>

参数

DragEvent 处理

一个HTML 拖放 API 事件的一个事件处理程序类型。

<>

  <div

    draggable={true}

    onDragStart={e => console.log('onDragStart')}

    onDragEnd={e => console.log('onDragEnd')}

  >

    Drag source

  </div>



  <div

    onDragEnter={e => console.log('onDragEnter')}

    onDragLeave={e => console.log('onDragLeave')}

    onDragOver={e => { e.preventDefault(); console.log('onDragOver'); }}

    onDrop={e => console.log('onDrop')}

  >

    Drop target

  </div>

</>

参数

FocusEvent 处理函数

一个用于焦点事件的事件处理程序类型。

<input

  onFocus={e => console.log('onFocus')}

  onBlur={e => console.log('onBlur')}

/>

看一个例子

参数

Event 处理函数

一个通用事件的事件处理程序类型。

参数

InputEvent 处理函数

一个用于 onBeforeInput 事件的事件处理程序类型。

<input onBeforeInput={e => console.log('onBeforeInput')} />

属性

KeyboardEvent 处理函数

一个用于键盘事件的事件处理程序类型。

<input

  onKeyDown={e => console.log('onKeyDown')}

  onKeyUp={e => console.log('onKeyUp')}

/>

看一个例子

参数

MouseEvent 处理函数

一个用于鼠标事件的事件处理程序类型。

<div

  onClick={e => console.log('onClick')}

  onMouseEnter={e => console.log('onMouseEnter')}

  onMouseOver={e => console.log('onMouseOver')}

  onMouseDown={e => console.log('onMouseDown')}

  onMouseUp={e => console.log('onMouseUp')}

  onMouseLeave={e => console.log('onMouseLeave')}

/>

看一个例子

参数

它还包括继承的UIEvent属性：

PointerEvent 处理函数

一个pointer events的事件处理程序类型。

<div

  onPointerEnter={e => console.log('onPointerEnter')}

  onPointerMove={e => console.log('onPointerMove')}

  onPointerDown={e => console.log('onPointerDown')}

  onPointerUp={e => console.log('onPointerUp')}

  onPointerLeave={e => console.log('onPointerLeave')}

/>

看一个例子

参数

它还包括继承的UIEvent属性：

TouchEvent 处理函数

一个用于touch events.的事件处理程序类型。

<div

  onTouchStart={e => console.log('onTouchStart')}

  onTouchMove={e => console.log('onTouchMove')}

  onTouchEnd={e => console.log('onTouchEnd')}

  onTouchCancel={e => console.log('onTouchCancel')}

/>

参数

它还包括继承的UIEvent属性：

TransitionEvent 处理函数

一个用于CSS过渡事件的事件处理程序类型。

<div

  onTransitionEnd={e => console.log('onTransitionEnd')}

/>

参数

UIEvent 处理函数

一个通用 UI 事件的事件处理程序类型。

<div

  onScroll={e => console.log('onScroll')}

/>

参数

WheelEvent 处理函数

一个用于 onWheel 事件的事件处理程序类型。

<div

  onScroll={e => console.log('onScroll')}

/>

参数

它还包括继承的鼠标事件属性：

它还包括继承的UIEvent属性：

Usage

应用CSS样式

在React中，你可以使用className.指定CSS类。它的工作方式类似于HTML中的class属性：

<img className="avatar" />

然后你在单独的CSS文件中编写它的CSS规则：

/* In your CSS */

.avatar {

  border-radius: 50%;

}

在最简单的情况下，你可以将<link>标签添加到HTML中。如果你使用构建工具或框架，请查阅其文档以了解如何将CSS文件添加到项目中。React 不规定如何添加 CSS 文件。

有时，样式值取决于数据。使用style属性动态传递一些样式：

<img

  className="avatar"

  style={{

    width: user.imageSize,

    height: user.imageSize

  }}

/>

在上面的例子中，style={{}} 不是特殊语法，而是 style={ } JSX 花括号.内的常规 {} 对象。 我们建议只在样式依赖于 JavaScript 变量时使用 style 属性。

export default function Avatar({ user }) {
  return (
    <img
      src={user.imageUrl}
      alt={'Photo of ' + user.name}
      className="avatar"
      style={{
        width: user.imageSize,
        height: user.imageSize
      }}
    />
  );
}
深入探讨

如何有条件地应用多个CSS类？

要有条件地应用CSS类，你需要使用JavaScript自己生成className字符串。

例如， className={'row ' + (isSelected ? 'selected': '')} 将会生成className="row" 或者 className="row selected" 取决于 isSelected 是不是 true.

为了更好的可读性，你可以使用像 classnames:这样的小助手库：

import cn from 'classnames';



function Row({ isSelected }) {

  return (

    <div className={cn('row', isSelected && 'selected')}>

      ...

    </div>

  );

}

如果你有多个条件类，则特别方便：

import cn from 'classnames';



function Row({ isSelected, size }) {

  return (

    <div className={cn('row', {

      selected: isSelected,

      large: size === 'large',

      small: size === 'small',

    })}>

      ...

    </div>

  );

}

使用 ref 操作 DOM 节点

有时候，你需要获取与JSX标签相关联的浏览器DOM节。 举个例子, 当你希望在点击一个按钮的时候聚焦一个 <input> , 你需要在浏览器的<input> DOM节点上调用 focus() 方法。

要获取标签的浏览器DOM节点， 请声明一个ref 并将其作为一个 ref 属性传递给标签:

import { useRef } from 'react';



export default function Form() {

  const inputRef = useRef(null);

  // ...

  return (

    <input ref={inputRef} />

    // ...

在渲染到屏幕后，React会将DOM节点放入inputRef.current中。

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);

  function handleClick() {
    inputRef.current.focus();
  }

  return (
    <>
      <input ref={inputRef} />
      <button onClick={handleClick}>
        Focus the input
      </button>
    </>
  );
}

阅读更多关于使用 refs 操纵 DOM 的内容并查看更多示例。

对于更高级的用例，ref 属性还可以接受回调函数.。

危险地设置内部 HTML

你可以像这样将原始的HTML字符串传递给元素:

const markup = { __html: '<p>some raw html</p>' };

return <div dangerouslySetInnerHTML={markup} />;

这很危险。与底层的DOM innerHTML 属性一样,你必须极度谨慎！ 除非标记语言来自完全可信的来源, 否则通过这种方式引入 XSS 是容易被攻击的。

例如，如果你使用将Markdown转换为HTML的Markdown库，你得相信它的解析器没有漏洞， 用户只能看到自己的输入，你可以像这样显示生成的HTML:

import { Remarkable } from 'remarkable';

const md = new Remarkable();

function renderMarkdownToHTML(markdown) {
  // 这里安全的原因是输出的HTML代码

  // 仅显示给同一用户，

  // 并且你信任此Markdown解析器没有漏洞。

  const renderedHTML = md.render(markdown);
  return {__html: renderedHTML};
}

export default function MarkdownPreview({ markdown }) {
  const markup = renderMarkdownToHTML(markdown);
  return <div dangerouslySetInnerHTML={markup} />;
}

要了解为什么渲染任意HTML是危险的，请将上面的代码替换为此代码:

const post = {

  // 想象这个内容被存储在数据库中

  content: `<img src="" onerror='alert("you were hacked")'>`

};



export default function MarkdownPreview() {

  // 🔴 安全漏洞：将不受信任的输入传递给dangerouslySetInnerHTML

  const markup = { __html: post.content };

  return <div dangerouslySetInnerHTML={markup} />;

}

HTML中嵌入的代码将会运行。 黑客可以利用这个安全漏洞窃取用户信息或代表他们执行操作。 只有在使用受信任和经过消毒的数据时才能使用 dangerouslySetInnerHTML 。

处理鼠标事件

这个例子展示了一些常见的鼠标事件以及它们触发的时机。

export default function MouseExample() {
  return (
    <div
      onMouseEnter={e => console.log('onMouseEnter (parent)')}
      onMouseLeave={e => console.log('onMouseLeave (parent)')}
    >
      <button
        onClick={e => console.log('onClick (first button)')}
        onMouseDown={e => console.log('onMouseDown (first button)')}
        onMouseEnter={e => console.log('onMouseEnter (first button)')}
        onMouseLeave={e => console.log('onMouseLeave (first button)')}
        onMouseOver={e => console.log('onMouseOver (first button)')}
        onMouseUp={e => console.log('onMouseUp (first button)')}
      >
        First button
      </button>
      <button
        onClick={e => console.log('onClick (second button)')}
        onMouseDown={e => console.log('onMouseDown (second button)')}
        onMouseEnter={e => console.log('onMouseEnter (second button)')}
        onMouseLeave={e => console.log('onMouseLeave (second button)')}
        onMouseOver={e => console.log('onMouseOver (second button)')}
        onMouseUp={e => console.log('onMouseUp (second button)')}
      >
        Second button
      </button>
    </div>
  );
}

处理指针事件

这个例子展示了一些常见的指针事件 以及它们触发的时机。

export default function PointerExample() {
  return (
    <div
      onPointerEnter={e => console.log('onPointerEnter (parent)')}
      onPointerLeave={e => console.log('onPointerLeave (parent)')}
      style={{ padding: 20, backgroundColor: '#ddd' }}
    >
      <div
        onPointerDown={e => console.log('onPointerDown (first child)')}
        onPointerEnter={e => console.log('onPointerEnter (first child)')}
        onPointerLeave={e => console.log('onPointerLeave (first child)')}
        onPointerMove={e => console.log('onPointerMove (first child)')}
        onPointerUp={e => console.log('onPointerUp (first child)')}
        style={{ padding: 20, backgroundColor: 'lightyellow' }}
      >
        First child
      </div>
      <div
        onPointerDown={e => console.log('onPointerDown (second child)')}
        onPointerEnter={e => console.log('onPointerEnter (second child)')}
        onPointerLeave={e => console.log('onPointerLeave (second child)')}
        onPointerMove={e => console.log('onPointerMove (second child)')}
        onPointerUp={e => console.log('onPointerUp (second child)')}
        style={{ padding: 20, backgroundColor: 'lightblue' }}
      >
        Second child
      </div>
    </div>
  );
}

处理焦点事件

在React中 焦点事件 冒泡。你可以使用currentTarget和relatedTarget来区分焦点或模糊事件是否起源于父元素之外。 该示例展示了如何检测子元素的聚焦、父级元素的聚焦，以及如何检测整个子树的聚焦进入或离开。

export default function FocusExample() {
  return (
    <div
      tabIndex={1}
      onFocus={(e) => {
        if (e.currentTarget === e.target) {
          console.log('focused parent');
        } else {
          console.log('focused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // 在子元素之间切换焦点时不会触发

          console.log('focus entered parent');
        }
      }}
      onBlur={(e) => {
        if (e.currentTarget === e.target) {
          console.log('unfocused parent');
        } else {
          console.log('unfocused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // 在子元素之间切换焦点时不会触发

          console.log('focus left parent');
        }
      }}
    >
      <label>
        First name:
        <input name="firstName" />
      </label>
      <label>
        Last name:
        <input name="lastName" />
      </label>
    </div>
  );
}

处理键盘事件

\这个例子展示了一些常见的键盘事件以及它们触发的时机。

export default function KeyboardExample() {
  return (
    <label>
      First name:
      <input
        name="firstName"
        onKeyDown={e => console.log('onKeyDown:', e.key, e.code)}
        onKeyUp={e => console.log('onKeyUp:', e.key, e.code)}
      />
    </label>
  );
}
上一页组件下一页<input>

你觉得这些文档怎么样？