We want to hear from you!Take our 2020 Community Survey!
React
v17.0.1 LanguagesGitHub

React.Component

Diese Seite enthält eine detaillierte API-Referenz für die React-Component-Klassendefinition. Sie nimmt an, dass du mit den grundlegenden React-Konzepten, wie Komponenten und Props und State und Lifecycle, vertraut bist. Falls nicht, lies darüber zuerst.

Überblick

React erlaubt das Definieren von Komponenten als Klassen oder Funktionen. Als Klasse definierte Komponenten bieten aktuell mehr Funktionen, auf welche hier im Detail eingegangen wird. Um eine React-Komponente als Klasse zu definieren, muss React.Component erweitert werden:

class Welcome extends React.Component {
  render() {
    return <h1>Hallo, {this.props.name}</h1>;
  }
}

Die einzige Methode, die in einer React.Component-Unterklasse implementiert werden muss, heißt render(). Alle anderen auf dieser Seite beschriebenen Methoden sind optional.

Wir raten streng davon ab, eigene Basiskomponentenklassen zu schreiben. In React-Komponenten wird hauptsächlich Code-Wiederverwendung eher durch Komposition als durch Vererbung erreicht.

Hinweis:

React zwingt dich nicht die ES6-Klassensyntax zu verwenden. Falls du sie vermeiden möchtest, kannst du das create-react-class-Modul oder eine ähnliche eigene Abstraktion verwenden. Sieh dir React ohne ES6 an, um mehr darüber zu lernen.

Der Lebenszyklus von Komponenten

Jede Komponente hat verschiedene “Lifecycle-Methoden”, welche du überschreiben kannst, um Code zu einem bestimmten Zeitpunkt des Prozesses laufen zu lassen. Du kannst dieses Lifecycle-Diagramm als Spickzettel nutzen. In der Liste unten sind die häufig verwendeten Methoden fett hervorgehoben. Die restlichen Methoden existiert für relativ seltene Anwendungsfälle.

Das Einfügen

Diese Methoden werden, sobald eine Instanz einer Komponente erzeugt und in die DOM eingefügt wird, in der folgenden Reihenfolge aufgerufen:

Hinweis:

Diese Methoden werden als Altlasten angesehen und in neuem Code solltest du diese meiden:

Das Aktualisieren

Eine Aktualisierung kann durch Änderungen an Props oder State ausgelöst werden. Diese Methoden werden, sobald eine Komponente erneut gerendert wird, in der folgenden Reihenfolge aufgerufen:

Hinweis:

Diese Methoden werden als Altlasten angesehen und in neuem Code solltest du diese meiden:

Das Entfernen

Diese Methode wird aufgerufen, sobald eine Komponente aus der DOM entfernt wird:

Fehlerbehandlung

Diese Methoden werden aufgerufen, sobald während des Rendern, in einer Lifecycle-Methode oder im Konstruktor einer Kindkomponente ein Fehler auftritt.

Andere APIs

Jede Komponente bietet zudem noch andere APIs an:

Klassenattribute

Instanzattribute

Referenz

Meistgenutzte Lifecycle Methods

Die Methoden in diesem Abschnitt decken die große Mehrheit der Anwendungsfälle ab, denen du beim Erzeugen von React-Komponenten begegnen wirst. Für eine visuelle Referenz, sieh dir dieses Lifecycle-Diagramm an.

render() 

render()

Die render()-Methode ist die einzige erforderliche Methode einer Klassenkomponente.

Beim Aufruf überprüft sie this.props und this.state und gibt eines der folgenden Typen zurück:

  • React Elemente. Typischerweise erzeugt durch JSX. Beispielsweise geben <div /> und <MyComponent /> React-Elemente zurück, welche React anweisen, entsprechend einen DOM-Knoten oder eine andere benutzerdefinierte Komponente zu rendern.
  • Arrays und Fragmente. Erlaubt mehrere Elemente von der render-Methode zurückgeben zu lassen. Lies die Dokumentation bezüglich Fragmente für mehr Informationen.
  • Portale. Erlaubt das Rendern von Kindelementen innerhalb eines anderen DOM-Unterbaums. Lies die Dokumentation bezüglich Portale für mehr Informationen.
  • Zeichenketten und Zahlen. Diese werden als Textknoten in der DOM gerendert.
  • Booleans or null. Nichts wird gerendert. (Existiert hauptsächlich um das return test && <Child />-Muster zu unterstützen, wobei test ein Boolean ist.)

Die render()-Funktion sollte rein sein, was bedeutet, dass es den State der Komponente nicht verändert, jedesmal das gleiche Ergebnis beim Aufruf liefert und nicht direkt mit dem Browser interagiert.

Wenn du mit dem Browser interagieren musst, tue dies innerhalb von componentDidMount() oder den anderen Lifecycle-Methoden. Eine reine render()-Funktion hilft dabei Komponenten simpel zu halten.

Hinweis

render() wird nicht aufgerufen, falls shouldComponentUpdate() false zurückgibt.

constructor() 

constructor(props)

Wenn du den State nicht initialisierst und keine Methoden bindest, musst du keinen Konstruktor in deiner React-Komponente implementieren

The Konstruktor wird vor dem mounten der React-Komponente aufgerufen. Wenn du den Konstruktor für eine React.Component Sub-Klasse implementierst, solltest du super(props) vor jeder anderen Anweisung im Konstruktor aufrufen. The constructor for a React component is called before it is mounted. When implementing the constructor for a React.Component subclass, you should call super(props) before any other statement. Andernfalls wird this.props im Konstruktor nicht definiert sein, was zu Fehlern führen kann.

Üblicherweise werden in React, Konstruktoren nur für zwei Sachen verwendet:

  • Initialisieren des lokalen State, in dem this.state ein Objekt zugewiesen wird.
  • Um Event-Handler-Methoden an eine Instanz zu binden.

Du solltest setState() nicht im constructor() aurufen. Stattdessen weise this.state direkt im Konstruktor einen initialen State zu, wenn deine Komponente einen lokalen State benötigt:

constructor(props) {
  super(props);
  // Rufe hier nicht this.setState() auf!
  this.state = { counter: 0 };
  this.handleClick = this.handleClick.bind(this);
}

Der Konstruktur ist die einzige Stelle, an dem du this.state direkt einen Wert zuweisen solltest. In allen anderen Methoden solltest du stattdessen this.setState() aufrufen.

Vermeide Nebeneffekten (engl. side-effects) oder Subscriptions im Konstruktor. Verwende diese Anwendungsfälle stattdessen componentDidMount().

Hinweis

Vermeide das Kopieren von Props in den State! Dies ist ein häufiger Fehler:

constructor(props) {
 super(props);
 // Tue das nicht!
 this.state = { color: props.color };
}

Das Problem ist, dass es sowohl unnötig ist (du kannst stattdessen this.props.color direkt verwenden), als auch Fehler erzeugt (Aktualisierungen des color-Prop werden nicht im State widergespiegelt).

Verwende dieses Pattern nur, wenn du absichtlich Prop-Aktualisierungen ignorieren willst. In diesem Fall ist es sinnvoll, das Prop in initialColor oder defaultColor umzubenennen. Du kannst dann eine Komponente zwingen, ihren internen State “zurückzusetzen”, indem du ihren key wenn nötig änderst.

Lese unseren Blog-Beitrag zur Vermeidung eines abgeleiteten State um zu erfahren, was zu tun ist, wenn du glaubst, dass du einen State brauchst, der auf die Props angewiesen ist.

componentDidMount() 

componentDidMount()

componentDidMount() is invoked immediately after a component is mounted (inserted into the tree). Initialization that requires DOM nodes should go here. If you need to load data from a remote endpoint, this is a good place to instantiate the network request.

This method is a good place to set up any subscriptions. If you do that, don’t forget to unsubscribe in componentWillUnmount().

You may call setState() immediately in componentDidMount(). It will trigger an extra rendering, but it will happen before the browser updates the screen. This guarantees that even though the render() will be called twice in this case, the user won’t see the intermediate state. Use this pattern with caution because it often causes performance issues. In most cases, you should be able to assign the initial state in the constructor() instead. It can, however, be necessary for cases like modals and tooltips when you need to measure a DOM node before rendering something that depends on its size or position.

componentDidUpdate() 

componentDidUpdate(prevProps, prevState, snapshot)

componentDidUpdate() is invoked immediately after updating occurs. This method is not called for the initial render.

Use this as an opportunity to operate on the DOM when the component has been updated. This is also a good place to do network requests as long as you compare the current props to previous props (e.g. a network request may not be necessary if the props have not changed).

componentDidUpdate(prevProps) {
  // Typical usage (don't forget to compare props):
  if (this.props.userID !== prevProps.userID) {
    this.fetchData(this.props.userID);
  }
}

You may call setState() immediately in componentDidUpdate() but note that it must be wrapped in a condition like in the example above, or you’ll cause an infinite loop. It would also cause an extra re-rendering which, while not visible to the user, can affect the component performance. If you’re trying to “mirror” some state to a prop coming from above, consider using the prop directly instead. Read more about why copying props into state causes bugs.

If your component implements the getSnapshotBeforeUpdate() lifecycle (which is rare), the value it returns will be passed as a third “snapshot” parameter to componentDidUpdate(). Otherwise this parameter will be undefined.

Note

componentDidUpdate() will not be invoked if shouldComponentUpdate() returns false.

componentWillUnmount() 

componentWillUnmount()

componentWillUnmount() is invoked immediately before a component is unmounted and destroyed. Perform any necessary cleanup in this method, such as invalidating timers, canceling network requests, or cleaning up any subscriptions that were created in componentDidMount().

You should not call setState() in componentWillUnmount() because the component will never be re-rendered. Once a component instance is unmounted, it will never be mounted again.

Selten genutzte Lifecycle Methods

The methods in this section correspond to uncommon use cases. They’re handy once in a while, but most of your components probably don’t need any of them. You can see most of the methods below on this lifecycle diagram if you click the “Show less common lifecycles” checkbox at the top of it.

shouldComponentUpdate() 

shouldComponentUpdate(nextProps, nextState)

Use shouldComponentUpdate() to let React know if a component’s output is not affected by the current change in state or props. The default behavior is to re-render on every state change, and in the vast majority of cases you should rely on the default behavior.

shouldComponentUpdate() is invoked before rendering when new props or state are being received. Defaults to true. This method is not called for the initial render or when forceUpdate() is used.

This method only exists as a performance optimization. Do not rely on it to “prevent” a rendering, as this can lead to bugs. Consider using the built-in PureComponent instead of writing shouldComponentUpdate() by hand. PureComponent performs a shallow comparison of props and state, and reduces the chance that you’ll skip a necessary update.

If you are confident you want to write it by hand, you may compare this.props with nextProps and this.state with nextState and return false to tell React the update can be skipped. Note that returning false does not prevent child components from re-rendering when their state changes.

We do not recommend doing deep equality checks or using JSON.stringify() in shouldComponentUpdate(). It is very inefficient and will harm performance.

Currently, if shouldComponentUpdate() returns false, then UNSAFE_componentWillUpdate(), render(), and componentDidUpdate() will not be invoked. In the future React may treat shouldComponentUpdate() as a hint rather than a strict directive, and returning false may still result in a re-rendering of the component.

static getDerivedStateFromProps() 

static getDerivedStateFromProps(props, state)

getDerivedStateFromProps is invoked right before calling the render method, both on the initial mount and on subsequent updates. It should return an object to update the state, or null to update nothing.

This method exists for rare use cases where the state depends on changes in props over time. For example, it might be handy for implementing a <Transition> component that compares its previous and next children to decide which of them to animate in and out.

Deriving state leads to verbose code and makes your components difficult to think about. Make sure you’re familiar with simpler alternatives:

This method doesn’t have access to the component instance. If you’d like, you can reuse some code between getDerivedStateFromProps() and the other class methods by extracting pure functions of the component props and state outside the class definition.

Note that this method is fired on every render, regardless of the cause. This is in contrast to UNSAFE_componentWillReceiveProps, which only fires when the parent causes a re-render and not as a result of a local setState.

getSnapshotBeforeUpdate() 

getSnapshotBeforeUpdate(prevProps, prevState)

getSnapshotBeforeUpdate() is invoked right before the most recently rendered output is committed to e.g. the DOM. It enables your component to capture some information from the DOM (e.g. scroll position) before it is potentially changed. Any value returned by this lifecycle will be passed as a parameter to componentDidUpdate().

This use case is not common, but it may occur in UIs like a chat thread that need to handle scroll position in a special way.

A snapshot value (or null) should be returned.

For example:

class ScrollingList extends React.Component {
  constructor(props) {
    super(props);
    this.listRef = React.createRef();
  }

  getSnapshotBeforeUpdate(prevProps, prevState) {
    // Are we adding new items to the list?
    // Capture the scroll position so we can adjust scroll later.
    if (prevProps.list.length < this.props.list.length) {
      const list = this.listRef.current;
      return list.scrollHeight - list.scrollTop;
    }
    return null;
  }

  componentDidUpdate(prevProps, prevState, snapshot) {
    // If we have a snapshot value, we've just added new items.
    // Adjust scroll so these new items don't push the old ones out of view.
    // (snapshot here is the value returned from getSnapshotBeforeUpdate)
    if (snapshot !== null) {
      const list = this.listRef.current;
      list.scrollTop = list.scrollHeight - snapshot;
    }
  }

  render() {
    return (
      <div ref={this.listRef}>{/* ...contents... */}</div>
    );
  }
}

In the above examples, it is important to read the scrollHeight property in getSnapshotBeforeUpdate because there may be delays between “render” phase lifecycles (like render) and “commit” phase lifecycles (like getSnapshotBeforeUpdate and componentDidUpdate).

Fehlerbegrenzungen

Error boundaries are React components that catch JavaScript errors anywhere in their child component tree, log those errors, and display a fallback UI instead of the component tree that crashed. Error boundaries catch errors during rendering, in lifecycle methods, and in constructors of the whole tree below them.

A class component becomes an error boundary if it defines either (or both) of the lifecycle methods static getDerivedStateFromError() or componentDidCatch(). Updating state from these lifecycles lets you capture an unhandled JavaScript error in the below tree and display a fallback UI.

Only use error boundaries for recovering from unexpected exceptions; don’t try to use them for control flow.

For more details, see Error Handling in React 16.

Note

Error boundaries only catch errors in the components below them in the tree. An error boundary can’t catch an error within itself.

static getDerivedStateFromError() 

static getDerivedStateFromError(error)

This lifecycle is invoked after an error has been thrown by a descendant component. It receives the error that was thrown as a parameter and should return a value to update state.

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {    // Update state so the next render will show the fallback UI.    return { hasError: true };  }
  render() {
    if (this.state.hasError) {      // You can render any custom fallback UI      return <h1>Something went wrong.</h1>;    }
    return this.props.children;
  }
}

Note

getDerivedStateFromError() is called during the “render” phase, so side-effects are not permitted. For those use cases, use componentDidCatch() instead.

componentDidCatch() 

componentDidCatch(error, info)

This lifecycle is invoked after an error has been thrown by a descendant component. It receives two parameters:

  1. error - The error that was thrown.
  2. info - An object with a componentStack key containing information about which component threw the error.

componentDidCatch() is called during the “commit” phase, so side-effects are permitted. It should be used for things like logging errors:

class ErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(error) {
    // Update state so the next render will show the fallback UI.
    return { hasError: true };
  }

  componentDidCatch(error, info) {    // Example "componentStack":    //   in ComponentThatThrows (created by App)    //   in ErrorBoundary (created by App)    //   in div (created by App)    //   in App    logComponentStackToMyService(info.componentStack);  }
  render() {
    if (this.state.hasError) {
      // You can render any custom fallback UI
      return <h1>Something went wrong.</h1>;
    }

    return this.props.children;
  }
}

Production and development builds of React slightly differ in the way componentDidCatch() handles errors.

On development, the errors will bubble up to window, this means that any window.onerror or window.addEventListener('error', callback) will intercept the errors that have been caught by componentDidCatch().

On production, instead, the errors will not bubble up, which means any ancestor error handler will only receive errors not explicitly caught by componentDidCatch().

Note

In the event of an error, you can render a fallback UI with componentDidCatch() by calling setState, but this will be deprecated in a future release. Use static getDerivedStateFromError() to handle fallback rendering instead.

Veraltete Lifecycle Methods

The lifecycle methods below are marked as “legacy”. They still work, but we don’t recommend using them in the new code. You can learn more about migrating away from legacy lifecycle methods in this blog post.

UNSAFE_componentWillMount() 

UNSAFE_componentWillMount()

Note

This lifecycle was previously named componentWillMount. That name will continue to work until version 17. Use the rename-unsafe-lifecycles codemod to automatically update your components.

UNSAFE_componentWillMount() is invoked just before mounting occurs. It is called before render(), therefore calling setState() synchronously in this method will not trigger an extra rendering. Generally, we recommend using the constructor() instead for initializing state.

Avoid introducing any side-effects or subscriptions in this method. For those use cases, use componentDidMount() instead.

This is the only lifecycle method called on server rendering.

UNSAFE_componentWillReceiveProps() 

UNSAFE_componentWillReceiveProps(nextProps)

Note

This lifecycle was previously named componentWillReceiveProps. That name will continue to work until version 17. Use the rename-unsafe-lifecycles codemod to automatically update your components.

Note:

Using this lifecycle method often leads to bugs and inconsistencies

For other use cases, follow the recommendations in this blog post about derived state.

UNSAFE_componentWillReceiveProps() is invoked before a mounted component receives new props. If you need to update the state in response to prop changes (for example, to reset it), you may compare this.props and nextProps and perform state transitions using this.setState() in this method.

Note that if a parent component causes your component to re-render, this method will be called even if props have not changed. Make sure to compare the current and next values if you only want to handle changes.

React doesn’t call UNSAFE_componentWillReceiveProps() with initial props during mounting. It only calls this method if some of component’s props may update. Calling this.setState() generally doesn’t trigger UNSAFE_componentWillReceiveProps().

UNSAFE_componentWillUpdate() 

UNSAFE_componentWillUpdate(nextProps, nextState)

Note

This lifecycle was previously named componentWillUpdate. That name will continue to work until version 17. Use the rename-unsafe-lifecycles codemod to automatically update your components.

UNSAFE_componentWillUpdate() is invoked just before rendering when new props or state are being received. Use this as an opportunity to perform preparation before an update occurs. This method is not called for the initial render.

Note that you cannot call this.setState() here; nor should you do anything else (e.g. dispatch a Redux action) that would trigger an update to a React component before UNSAFE_componentWillUpdate() returns.

Typically, this method can be replaced by componentDidUpdate(). If you were reading from the DOM in this method (e.g. to save a scroll position), you can move that logic to getSnapshotBeforeUpdate().

Note

UNSAFE_componentWillUpdate() will not be invoked if shouldComponentUpdate() returns false.

Andere APIs

Unlike the lifecycle methods above (which React calls for you), the methods below are the methods you can call from your components.

There are just two of them: setState() and forceUpdate().

setState() 

setState(updater, [callback])

setState() enqueues changes to the component state and tells React that this component and its children need to be re-rendered with the updated state. This is the primary method you use to update the user interface in response to event handlers and server responses.

Think of setState() as a request rather than an immediate command to update the component. For better perceived performance, React may delay it, and then update several components in a single pass. React does not guarantee that the state changes are applied immediately.

setState() does not always immediately update the component. It may batch or defer the update until later. This makes reading this.state right after calling setState() a potential pitfall. Instead, use componentDidUpdate or a setState callback (setState(updater, callback)), either of which are guaranteed to fire after the update has been applied. If you need to set the state based on the previous state, read about the updater argument below.

setState() will always lead to a re-render unless shouldComponentUpdate() returns false. If mutable objects are being used and conditional rendering logic cannot be implemented in shouldComponentUpdate(), calling setState() only when the new state differs from the previous state will avoid unnecessary re-renders.

The first argument is an updater function with the signature:

(state, props) => stateChange

state is a reference to the component state at the time the change is being applied. It should not be directly mutated. Instead, changes should be represented by building a new object based on the input from state and props. For instance, suppose we wanted to increment a value in state by props.step:

this.setState((state, props) => {
  return {counter: state.counter + props.step};
});

Both state and props received by the updater function are guaranteed to be up-to-date. The output of the updater is shallowly merged with state.

The second parameter to setState() is an optional callback function that will be executed once setState is completed and the component is re-rendered. Generally we recommend using componentDidUpdate() for such logic instead.

You may optionally pass an object as the first argument to setState() instead of a function:

setState(stateChange[, callback])

This performs a shallow merge of stateChange into the new state, e.g., to adjust a shopping cart item quantity:

this.setState({quantity: 2})

This form of setState() is also asynchronous, and multiple calls during the same cycle may be batched together. For example, if you attempt to increment an item quantity more than once in the same cycle, that will result in the equivalent of:

Object.assign(
  previousState,
  {quantity: state.quantity + 1},
  {quantity: state.quantity + 1},
  ...
)

Subsequent calls will override values from previous calls in the same cycle, so the quantity will only be incremented once. If the next state depends on the current state, we recommend using the updater function form, instead:

this.setState((state) => {
  return {quantity: state.quantity + 1};
});

For more detail, see:

forceUpdate() 

component.forceUpdate(callback)

By default, when your component’s state or props change, your component will re-render. If your render() method depends on some other data, you can tell React that the component needs re-rendering by calling forceUpdate().

Calling forceUpdate() will cause render() to be called on the component, skipping shouldComponentUpdate(). This will trigger the normal lifecycle methods for child components, including the shouldComponentUpdate() method of each child. React will still only update the DOM if the markup changes.

Normally you should try to avoid all uses of forceUpdate() and only read from this.props and this.state in render().

Klassenattribute

defaultProps

defaultProps can be defined as a property on the component class itself, to set the default props for the class. This is used for undefined props, but not for null props. For example:

class CustomButton extends React.Component {
  // ...
}

CustomButton.defaultProps = {
  color: 'blue'
};

If props.color is not provided, it will be set by default to 'blue':

  render() {
    return <CustomButton /> ; // props.color will be set to blue
  }

If props.color is set to null, it will remain null:

  render() {
    return <CustomButton color={null} /> ; // props.color will remain null
  }

displayName

Der displayName-String wird in Debug-Nachrichten verwendet. Normalerweise musst du ihn nicht explizit festlegen, da er aus dem Namen der Funktion oder der Klasse, die die Komponente definiert, abgeleitet wird. Du solltest ihn explizit festlegen, wenn du zu Debugging-Zwecken einen anderen Namen anzeigen möchtest oder du eine “High-Order”-Komponente erstellst, schau dir Den Anzeigenamen umschließen zu reinfachen Fehlersuche für mehr Details an.

Instanzattribute

props

this.props contains the props that were defined by the caller of this component. See Components and Props for an introduction to props.

In particular, this.props.children is a special prop, typically defined by the child tags in the JSX expression rather than in the tag itself.

state

The state contains data specific to this component that may change over time. The state is user-defined, and it should be a plain JavaScript object.

If some value isn’t used for rendering or data flow (for example, a timer ID), you don’t have to put it in the state. Such values can be defined as fields on the component instance.

See State and Lifecycle for more information about the state.

Never mutate this.state directly, as calling setState() afterwards may replace the mutation you made. Treat this.state as if it were immutable.

Is this page useful?Bearbeite diese Seite