React Top-Level API

React ist der Zugangspunkt zur React-Bibliothek. Falls du React von einem <script>-Tag heraus lädst, sind diese Top-Level APIs im globalen React-Objekt verfügbar. Solltest du ES6 mit npm verwenden, kannst du import React from 'react' schreiben. Wenn du ES5 mit npm verwendest, kannst du var React = require('react') schreiben.

Übersicht

Komponenten

Mit React-Komponenten kann die Benutzeroberfläche in unabhängige, wiederverwendbare Bestandteile aufgeteilt werden, die jeweils isoliert betrachtet werden können. React-Komponenten können als Unterklassen von React.Component oder React.PureComponent definiert werden.

Solltest du keine ES6-Klassen benutzen, kannst du stattdessen das create-react-class-Modul verwenden. Siehe React ohne ES6 für mehr Informationen.

React-Komponenten können auch als Funktionen definiert werden, die ummantelt werden können:

React-Elemente erstellen

Um zu beschreiben, wie die Benutzeroberfläche aussehen soll, empfehlen wir, JSX zu verwenden. Ein JSX-Element ist eine alternative Schreibweise für das Aufrufen von React.createElement(). Wenn du JSX verwendest, rufst du die folgenden Methoden normalerweise nicht direkt auf:

Siehe React ohne JSX für mehr Informationen.

Elemente verändern

React stellt mehrere APIs zur Verfügung, um Elemente zu manipulieren:

Fragmente

React stellt auch eine Komponente zu Verfügung, mit der mehrere Elemente ohne Wrapper gerendert werden können:

Refs

Suspense

Mit Suspense können Komponenten vor dem Rendern auf etwas “warten”. Momentan unterstützt Suspense nur einen Anwendungsfall: Komponenten dynamisch laden mit React.lazy. In Zukunft wird es auch andere Anwendungsfälle wie z.B. das Abrufen von Daten unterstützen.

Hooks

Hooks sind neu in React 16.8. Sie erlauben die Verwendung von State und anderen React-Features ohne Klassen. Hooks haben einen eigenen Bereich in der Dokumentation und eine eigene API-Referenz:


Referenz

React.Component

React.Component ist die Basis-Klasse für React-Komponenten, die mit ES6-Klassen definiert werden:

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

Unter React.Component API-Referenz gibt es eine Liste der Methoden und Eigenschaften, die sich auf die React.Component-Basisklasse beziehen.


React.PureComponent

React.PureComponent ähnelt React.Component, unterscheidet sich aber dahingehend, dass shouldComponentUpdate() von React.Component nicht implementiert wird, während React.PureComponent es durch das oberflächliche Vergleichen von Props und State implementiert.

Wenn die render()-Funktion einer React-Komponente bei Gleichbleiben von Props und State das gleiche Ergebnis rendert, kann die Nutzung von React.PureComponent in manchen Fällen die Performance verbessern.

Hinweis

shouldComponentUpdate() von React.PureComponent vergleicht Objekte nur oberflächlich. Falls diese komplexe Datenstrukturen enthalten, könnte es für tiefer gelegene Unterschiede zu falschen Negativbefunden kommen. Benutze PureComponent nur dann, wenn Props und State einfach sind, oder verwende forceUpdate() wenn du weißt, dass tiefergelegene Datenstrukturen sich verändert haben. Oder überlege dir, unveränderliche (immutable) Objekte zu verwenden, um das schnelle Vergleichen geschachtelter Daten zu erleichtern.

Darüber hinaus überspringt shouldComponentUpdate() von React.PureComponent den kompletten der Komponente untergeordneten Teilbaum. Es sollte also sichergestellt werden, dass alle Kind-Komponenten auch “pur” sind.


React.memo

const MyComponent = React.memo(function MyComponent(props) {
  /* rendere mit Props */
});

React.memo ist eine Higher-Order-Komponente. Sie ähnelt React.PureComponent, gilt allerdings für Funktionen statt für Klassen.

Wenn eine Funktions-Komponente bei Gleichbleiben von Props und State das gleiche Ergebnis rendert, kann in manchen Fällen die Performance verbessert werden, wenn die Komponente mit einem Aufruf an React.memo ummantelt wird und so das Ergebnis memoisiert wird. Das bedeutet, dass React das Rendern der Komponente überspringt und stattdessen das zuletzt gerenderte Ergebnis wiederverwendet.

Standardmäßig vergleicht es komplexe Objekte im Props-Objekt nur oberflächlich. Wenn du Kontrolle über den Vergleich haben möchtest, kannst du React.memo als zweites Argument eine benutzerdefinierte Vergleichsfunktion mitgeben.

function MyComponent(props) {
  /* rendere mit Props */
}
function areEqual(prevProps, nextProps) {
  /*
  Gib 'true' zurück, wenn nextProps das gleiche Ergebnis rendern würde 
  wie prevProps, ansonsten gib 'false' zurück
  */
}
export default React.memo(MyComponent, areEqual);

Diese Methode existiert nur zur Performance-Optimierung. Verlasse dich nicht auf sie, um das Rendern zu “verhindern”, da dadurch Bugs entstehen können.

Hinweis

Im Gegensatz zur shouldComponentUpdate()-Methode in Klassen-Komponenten gibt die areEqual-Funktion true zurück, wenn die Props gleich sind und false, wenn die Props unterschiedlich sind, also genau andersherum als shouldComponentUpdate.


createElement()

React.createElement(
  type,
  [props],
  [...children]
)

Erzeugt und gibt ein neues React-Element eines bestimmten Typs zurück. Das Typ-Argument kann entweder ein Tag-Name als String (z.B. 'div' oder 'span'), ein React-Komponenten-Typ (eine Klasse oder eine Funktion) oder ein React-Fragment-Typ sein.

In JSX geschriebener Code wird konvertiert, um React.createElement() zu benutzen. Wenn du JSX verwendest, rufst du React.createElement() normalerweise nicht direkt auf. Siehe React ohne JSX für mehr Informationen.


cloneElement()

React.cloneElement(
  element,
  [props],
  [...children]
)

Klone und gebe ein neues React-Element mit element als Ausgangspunkt zurück. Das resultierende Element hat die Props des ursprünglichen Elements, in die die neuen Props oberflächlich eingefügt werden. Neue Kinder ersetzen die existierenden Kinder. key und ref des ursprünglichen Elements bleiben erhalten.

React.cloneElement() ist fast äquivalent zu:

<element.type {...element.props} {...props}>{children}</element.type>

Zudem bleiben auch refs erhalten. Das bedeutet, dass bei einem Kindelement mit einer ref nicht versehentlich die Referenz vom Elternelement übertragen wird. Das Kindelement erhält die gleiche ref, verknüpft mit dem neuen Element.

Diese API wurde als Ersatz für das veraltete React.addons.cloneWithProps() eingeführt.


createFactory()

React.createFactory(type)

Gibt eine Funktion zurück, die React-Elemente eines bestimmten Typs erzeugt. Wie bei React.createElement() kann das Typ-Argument entweder ein Tag-Name als String (z.B. 'div' oder 'span'), ein React-Komponenten-Typ (eine Klasse oder eine Funktion) oder ein React-Fragment-Typ sein.

Dieser Helfer gilt als veraltet, und wir empfehlen, entweder JSX oder React.createElement() direkt zu verwenden.

Wenn du JSX verwendest, rufst du React.createFactory() normalerweise nicht direkt auf. Siehe React ohne JSX für mehr Informationen.


isValidElement()

React.isValidElement(object)

Überprüft, ob das Objekt ein React-Element ist. Gibt true oder false zurück.


React.Children

React.Children bietet Hilfsmittel, um mit der eher undurchschaubaren Datenstruktur von this.props.children umzugehen.

React.Children.map

React.Children.map(children, function[(thisArg)])

Ruft für jedes unmittelbare Kind aus children eine Funktion auf, bei der this auf thisArg gesetzt ist. Wenn children ein Array ist, wird dieses durchlaufen und die Funktion wird für jedes Kind im Array aufgerufen. Falls children null oder undefined ist, gibt diese Methode statt einem Array null oder undefined zurück.

Hinweis

Falls children ein Fragment ist, wird es wie ein einziges Kind behandelt und nicht durchlaufen.

React.Children.forEach

React.Children.forEach(children, function[(thisArg)])

Wie React.Children.map(), gibt jedoch kein Array zurück.

React.Children.count

React.Children.count(children)

Gibt die Gesamtzahl der Komponenten in children zurück, und gleicht der Anzahl der Callbacks, die mit der map- oder forEach-Methode aufgerufen werden würden.

React.Children.only

React.Children.only(children)

Überprüft, ob children nur ein Kind (ein React-Element) hat und gibt es zurück. Ansonsten wirft diese Methode einen Fehler.

Hinweis:

React.Children.only() akzeptiert nicht den Rückgabewert von React.Children.map(), da dieser ein Array ist und kein React-Element.

React.Children.toArray

React.Children.toArray(children)

Gibt die eher undurchschaubare children-Datenstruktur als flaches Array zurück, wobei jedem Kind ein Key zugeordnet ist. Nützlich, falls in render-Methoden Kinder-Ansammlungen manipuliert werden sollen, insbesondere beim Umordnen oder Slicen von this.props.children, bevor diese weitergegeben werden.

Hinweis:

React.Children.toArray() ändert Keys, um die Semantik verschachtelter Arrays zu erhalten, während Listen von Kindern geflattet werden. Das bedeutet, dass toArray ein Präfix vor jeden Key des zurückgegebenen Arrays setzt, damit der Key jedes Elements dem Input-Array, dem es angehört, zugeordnet ist.


React.Fragment

Die React.Fragment-Komponente erlaubt dir, mehrere Elemente in einer render()-Methode zurückzugeben, ohne ein zusätzliches DOM-Element zu kreieren:

render() {
  return (
    <React.Fragment>
      Irgendein Text.
      <h2>Eine Überschrift</h2>
    </React.Fragment>
  );
}

Du kannst auch die Kurzschreibweise <></> verwenden. Für mehr Informationen siehe React v16.2.0: Verbesserte Unterstützung für Fragmente.


React.createRef

React.createRef erstellt eine Referenz, die über das ref-Attribut an React-Elemente angehängt werden kann.

class MyComponent extends React.Component {
  constructor(props) {
    super(props);

    this.inputRef = React.createRef();
  }

  render() {
    return <input type="text" ref={this.inputRef} />;
  }

  componentDidMount() {
    this.inputRef.current.focus();
  }
}


React.forwardRef

React.forwardRef erstellt eine React-Komponente, die das ref-Attribut, das sie erhält, an eine ihr in der Baumstruktur untergeordnete Komponente weitergibt. Diese Technik ist nicht sehr verbreitet, ist jedoch in zwei Fällen besonders nützlich:

React.forwardRef akzeptiert eine render-Funktion als Argument. React ruft diese Funktion mit den zwei Argumenten props und ref auf und sollte einen React-Knoten zurückgeben.

const FancyButton = React.forwardRef((props, ref) => (
  <button ref={ref} className="FancyButton">
    {props.children}
  </button>
));

// Jetzt zeigt die ref direkt auf den DOM-button:
const ref = React.createRef();
<FancyButton ref={ref}>Click me!</FancyButton>;

Im obigen Beispiel übergibt React eine ref, die dem <FancyButton ref={ref}>-Element gegeben wurde, als zweites Argument an die render-Funktion innerhalb des React.forwardRef-Aufrufs. Diese render-Funktion gibt die ref an das <button ref={ref}>-Element weiter.

Dadurch zeigt ref.current direkt auf die <button>-DOM-Element-Instanz, nachdem React die ref eingefügt hat.

Für mehr Informationen siehe Refs weitergeben.


React.lazy

React.lazy() lässt dich eine Komponente definieren, die dynamisch geladen wird. Das hilft, die Bundlegröße zu reduzieren, indem das Laden von Komponenten, die im ursprünglichen Render nicht benutzt werden, verzögert wird.

In unserer Code-Splitting-Dokumentation kannst du lernen, wie es benutzt wird. Du kannst auch diesen Artikel lesen, in dem die Verwendung im Detail erläutert wird.

// Diese Komponente wird dynamisch geladen
const SomeComponent = React.lazy(() => import('./SomeComponent'));

Beachte, dass das Rendern von lazy-Komponenten ein <React.Suspense> weiter oben im Rendering-Baum benötigt. Damit wird ein Lade-Indikator bestimmt.

Hinweis

Die Verwendung von React.lazy mit dynamischen Imports setzt voraus, dass in der JS-Umgebung Promises verfügbar sind. Hierzu braucht man ein Polyfill für IE11 und darunter.


React.Suspense

React.Suspense lässt dich den Lade-Indikator bestimmen, der angezeigt wird, falls einige Komponenten weiter unten im Rendering-Baum noch nicht render-bereit sind. Momentan ist das Laden von lazy-Komponenten der einzige Anwendungsfall, den <React.Suspense> unterstützt:

// Diese Komponente wird dynamisch geladen
const OtherComponent = React.lazy(() => import('./OtherComponent'));

function MyComponent() {
  return (
    // Zeigt <Spinner>, bis OtherComponent geladen ist
    <React.Suspense fallback={<Spinner />}>
      <div>
        <OtherComponent />
      </div>
    </React.Suspense>
  );
}

Das ist in unserem Code-Splitting-Guide dokumentiert. Beachte, dass sich lazy-Komponenten tief im Suspense-Baum befinden können — es muss nicht jede einzelne davon ummantelt werden. Es wird empfohlen, <Suspense> dort zu verwenden, wo ein Lade-Indikator angezeigt werden soll, und lazy() dort zu verwenden, wo Code-Splitting stattfinden soll.

Wir planen, mit Suspense zukünftig weitere, bisher noch nicht unterstützte, Anwendungsfälle wie z.B. das Abrufen von Daten abzudecken. Mehr Informationen gibt es in unserer Roadmap.

Hinweis:

React.lazy() und <React.Suspense> werden noch nicht von ReactDOMServer unterstützt. Diese Einschränkung ist bekannt und wird in Zukunft gelöst.