API Top-Level

React este punctul de intrare în biblioteca React. Dacă încarci React dintr-un tag <script>, aceste API-uri top level sunt disponibile în variabila globală React. Dacă folosești ES6 cu npm, poți să scrii import React from 'react'. Dacă folosești ES5 cu npm, poți să scrii var React = require('react').

Prezentare generală

Componente

Componentele React iți permit împărțirea UI-ului în părți independente și refolosibile, și să te gândești la fiecare parte în mod izolat. Componentele React pot fi definite moștenind React.Component sau React.PureContent.

Dacă nu folosești clase ES6, poți folosi modulul create-react-class. Vezi React fără ES6 pentru mai multe informații.

Componentele React pot fi de asemenea definite ca funcții care pot fi impachetate:

Crearea elementelor React

Recomandăm folosirea JSX pentru a descrie cum ar trebui să arate UI-ul. Fiecare element JSX este doar syntactic sugar pentru apelul React.createElement(). Nu vei folosi următoarele metode în mod frecvent dacă folosești JSX.

Vezi React fără JSX pentru mai multe informații.

Transformarea elementelor

React oferă câteva API-uri pentru manipularea elementelor:

Fragmente

React oferă de asemenea o componentă pentru randarea de elemente multiple fără un container.

Refs

Suspense

Suspense oferă componentelor posibilitatea de a “aștepta” ceva înainte de randare. În prezent, Suspense permite doar un caz de utilizare: încărcarea dinamică a componentelor cu React.lazy. În viitor, va suporta alte cazuri de utilizare precum cererea datelor pe rețea.

Hooks

Hooks sunt un adaos nou în React 16.8. Îti permit să folosești state și alte funcționalități ale React fără a scrie o clasă. Hooks au o secțiune dedicata a documentației și o referință separată a API-ului:


Referință

React.Component

React.Component este clasa de bază pentru componentele React atunci când sunt definite folosind clase ES6:

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

Vezi Referință API pentru React.Component pentru o lista de metode și prorietăți ale clasei de bază React.Component.


React.PureComponent

React.PureComponent este similar cu React.Component. Diferența dintre ele este că React.Component nu implementează shouldComponentUpdate(), iar React.PureComponent o implementează cu un shallow prop și compararea state-ului.

Dacă metoda render() a unei componente React randează același rezultat considerând aceleași props și același state, poți folosi React.PureComponent pentru o creștere de performanță în unele cazuri.

Notă

Metoda shouldComponentUpdate() a clasei React.PureComponent compară obiectele doar pe primul nivel. Dacă acestea conțin structuri complexe de date, metoda poate produce false-negatives pentru diferențe pe nivele mai joase. Moștenește PureComponent doar atunci când te aștepți să ai props și state simple, sau foloseste forceUpdate() când știi că datele s-au schimbat. Sau consideră să folosești obiecte imutabile pentru a facilita compararea datelor imbricate.

În plus, metoda shouldComponentUpdate() a clasei React.PureComponent sare peste actualizarea props pentru întregul subtree. Asigură-te că toate componentele copil sunt “pure”.


React.memo

const MyComponent = React.memo(function MyComponent(props) {
  /* randează folosind props */
});

React.memo este un component higher order. Este similar cu React.PureComponent, dar pentru componente definite prin funcții.

Dacă componentul funcție randează același rezultat considerând aceleași props, îl poți împacheta într-un apel către React.memo pentru o îmbunătățire a performaneței în unele cazuri, prin memorarea rezultatului. Asta înseamnă că React nu va randa din nou componenta, ci va folosi ultimul rezultat randat.

În mod implicit, va compara obiectele din props doar pe primul nivel. Dacă vrei să controlezi logica comparației, poți scrie o funcție personalizată de comparație ca al doilea argument.

function MyComponent(props) {
  /* randează folosind props */
}
function areEqual(prevProps, nextProps) {
  /*
  întoarce true dacă nextProps și prevProps randează
  același rezultat, altfel întoarce false
  */
}
export default React.memo(MyComponent, areEqual);

Această metodă există doar pentru optimizarea performanței. Nu te baza pe ea pentru a “preveni” o randare, deoarece poate duce la bug-uri.

Notă

Spre deosebire de metoda shouldComponentUpdate() din componentele clasă, funcția areEqual întoarce true dacă props-urile sunt egale și false data props-urile nu sunt egale. Este comportamentul opus al metodei shouldComponentUpdate.


createElement()

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

Crează și întoarce un nou element React în funcție de tipul dat. Argumentul type poate fi un tag sub formă de string (precum 'div' sau 'span'), un component React (o clasă sau o funcție), sau un fragment React.

Codul scris cu JSX va fi convertit către React.createElement(). Nu vei apela de obicei React.createElement() în mod direct dacă folosești JSX. Vezi React Fara JSX pentru a afla mai multe.


cloneElement()

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

Cloneaza și întoarce un nou element React folosind element ca punct de plecare. Elementul rezultat va avea props-urile elementului original cu noile props îmbinate doar pe primul nivel. Noii copii vor înlocui copiii existenti. Vor fi păstrate key și ref de la elementul original.

React.cloneElement() este aproape echivalent cu:

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

Cu toate acestea, pastreaza refurile. Asta înseamnă că dacă un copil are ref, nu îl vei fura accidental de la parinte. Vei avea același ref atașat la noul element.

Acest API a fost introdus pentru a inlocui metoda depreciată React.addons.cloneWithProps().


createFactory()

React.createFactory(type)

Intoarce o funcție care produce elemente React de un tip dat. Precum React.createElement(), argumentul type poate fi de tipul tag sub formă de string (precum 'div' sau 'span'), de tipul component React (o clasă sau o funcție), sau de tipul fragment React.

Acest helper este considerat învechit și te încurajăm să folosești JSX sau direct React.createElement().

Nu vei apela de obicei React.createFactory() în mod direct dacă folosești JSX. Vezi React fără JSX pentru a afla mai multe.


isValidElement()

React.isValidElement(object)

Verifică dacă un obiect este un element React. Intoarce true sau false.


React.Children

React.Children oferă utilități pentru lucrul cu structura de date opaca this.props.children.

React.Children.map

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

Invocă o funcție pe fiecare copil conținut de children cu this aplicat pe thisArgs. Dacă children este un array, va fi traversat și funcția va fi aplicată pe fiecare copil în array. Dacă children este null sau undefined, această metodă o să întoarcă null sau undefined în locul unui array.

Notă

Dacă children este un Fragment va fi tratat ca un copil unic și nu va fi traversat.

React.Children.forEach

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

Precum React.Children.map() dar nu întoarce un array.

React.Children.count

React.Children.count(children)

Intoarce numărul total de componente din children, egal cu numărul de invocari ale callback-ului pasat către map sau forEach.

React.Children.only

React.Children.only(children)

Verifică dacă children are doar un singur copil (un element React) și îl întoarce. Altfel, această metodă declanșează o eroare.

Notă:

React.Children.only() nu acceptă valoare returnata de React.Children.map() pentru că este defapt un array și nu un element React.

React.Children.toArray

React.Children.toArray(children)

Intoarce structura de date opaca children ca un array liniar cu cheile asociate fiecărui copil. Este utila dacă vrei să manipulezi colecții de copii în metoda render, mai ales dacă vrei să reordonezi sau să selectezi anumiți copii din this.props.children înainte de a-i pasa mai departe.

Notă:

React.Children.toArray() schimbă cheile pentru a păstra semantica array-urilor imbricate atunci când se liniarizeaza listele de copii. Asta înseamnă că toArray prefixează fiecare cheie din array-ul rezultat în așa fel incât cheia fiecărui element este atribuită array-ului inițial care a conținut-o.


React.Fragment

Componenta React.Fragment iți permite să întorci mai multe elemente în metoda render() fără a crea elemente DOM adiționale:

render() {
  return (
    <React.Fragment>
      Niște text.
      <h2>Un heading</h2>
    </React.Fragment>
  );
}

De asemenea poți folosi sintaxa scurtă <></>. Pentru mai multe informații, vezi React v16.2.0: Improved Support for Fragments.

React.createRef

React.createRef crează un ref care poate fi atașat elementelor React folosind atributul ref.

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 crează o componentă React care dă mai departe atributul ref pe care îl primește, unei alte componente mai jos în ierarhie. Această tehnică nu este foarte comună, dar este folositoare în mod special în doua scenarii:

React.forwardRef acceptă o funcție care randează ca argument. React o să apeleze această funcție cu props și ref ca argumente. Această funcție trebuie să întoarcă un nod React.

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

// You can now get a ref directly to the DOM button:
const ref = React.createRef();
<FancyButton ref={ref}>Click me!</FancyButton>;

În exemplul de mai sus, React pasează un ref dat pentru elementul <FancyButton ref={ref}> ca al doilea argument al funcției de randare din apelul React.forwardRef. Această funcție de randare pasează ref către elementul <button ref={ref}>.

Ca rezultat, dupa ce React atașează ref-ul, ref.current va indica direct către instanța DOM <button>.

Pentru mai multe informații vezi pasarea refs.

React.lazy

React.lazy() iți permite să definesti o componentă care este încărcată dinamic. Asta ajută la reducerea dimensiunii bundle-ului și întârzie încărcarea componentelor care nu sunt folosite la randarea inițială.

Poți învăța cum să îl folosești din documentația code splitting. Te poți uita de asemenea și pe acest articol care arată cum să îl folosești mai în detaliu.

// Acestă componentă este încărcată dinamic
const SomeComponent = React.lazy(() => import('./SomeComponent'));

Reține că pentru randarea componentelor lazy este necesară randarea unei componente<React.Suspense> mai sus în ierarhia de randare. Așa specifici un indicator de încărcare.

Notă

Folosirea React.lazy cu importuri dinamice face obligatorie disponibilitatea Promise-urilor în mediul JS. Acest lucru cere un polyfill pe IE11 și pe versiuni mai vechi.

React.Suspense

React.Suspense iți permite să specifici indicatorul de încărcare în cazul în care unele componente din ierarhia copil nu sunt gata pentru randare. În prezent, componentele lazy loading sunt singurele cazuri suportate de <React.Suspense>:

// Acestă componentă este încărcată dinamic
const OtherComponent = React.lazy(() => import('./OtherComponent'));

function MyComponent() {
  return (
    // Afișează <Spinner> până când OtherComponent se incarcă
    <React.Suspense fallback={<Spinner />}>
      <div>
        <OtherComponent />
      </div>
    </React.Suspense>
  );
}

Este documentat în ghidul de code splitting. Reține ca lazy se pot afla adânc în ierarhia Suspense — nu trebuie să le împacheteze pe toate. Cea mai buna practică este să pui <Suspense> unde vrei să vezi un indicator de încărcare, dar să folosești lazy() unde vrei să faci code splitting.

Deși nu este acoperit în prezent, în viitor planificam ca Suspense să acopere scenarii precum requesturi pe rețea. Poți să citești despre asta în roadmap-ul nostru.

Notă:

React.lazy() și <React.Suspense> nu sunt înca suportate de ReactDOMServer. Este o limitare știută care va fi rezolvată în viitor.