diff --git a/content/en/guide/v10/api-reference.md b/content/en/guide/v10/api-reference.md index c98309836..77fa1fd64 100644 --- a/content/en/guide/v10/api-reference.md +++ b/content/en/guide/v10/api-reference.md @@ -78,7 +78,8 @@ render( ## hydrate() -When you have a prerendered DOM, there is no need to re-render it again. With hydrate most of the diffing phase will be skipped with event listeners being the exception. It's mainly used in conjuncton with [Server-Side Rendering](/guide/v10/server-side-rendering). +If you have a prerendered DOM (because of [Server-Side-Rendering](/guide/v10/server-side-rendering) then there is no need to use `render` again. You can use `hydrate` which will skip the internal diffing algorithm and only attach event listeners if it finds any in `props`.” + ```jsx import { render } from 'preact'; diff --git a/content/en/guide/v10/debugging.md b/content/en/guide/v10/debugging.md index a3e4d2608..8171f71bb 100644 --- a/content/en/guide/v10/debugging.md +++ b/content/en/guide/v10/debugging.md @@ -146,7 +146,7 @@ const ref = createRef(); ### Invalid event handler -Sometimes you'll may accidentally pass a wrong value to an event handler. They must always be a `function` or `null` if you want to remove it. All other types are invalid. +Sometimes you'll may accidentally pass a wrong value to an event handler. They must always be a `function`, or if you want to remove it `null`. All other types are invalid. ```jsx // valid diff --git a/content/fr/guide/v10/api-reference.md b/content/fr/guide/v10/api-reference.md new file mode 100644 index 000000000..4d63e4929 --- /dev/null +++ b/content/fr/guide/v10/api-reference.md @@ -0,0 +1,181 @@ +--- +name: Référence API +description: ‘Apprenez en plus à propos de toutes les fonctions exporté Preact’ +--- + +# Référence API + +Cette page sert de rapide vue d’ensemble de toutes les fonctions exportées. + + +--- + + + +--- + +## Preact.Component + +`Component` est une classe de base dont vous allez généralement hériter afin de créer des composants Preact ayant leur propre état. + +### Component.render(props, state) + +Tous les composants doivent implémenter la fonction `render()`. Elle reçoit les propriétés et l'état du composant, et doit retourner un élément Preact ou null. + +```jsx +import { Component } from 'preact'; + +class MyComponent extends Component { + render(props, state) { + // props === this.props + // state === this.state + + return

Bonjour, {props.name}!

; + } +} +``` + +Pour en apprendre d’avantage à propos des `Components` et comment ils peuvent être utilisés, visitez la page [Components](guide/v10/components). + +## render() + +`render(component, containerNode, [replaceNode])` + +Change un composant Preact en élément DOM `containerNode`. Retourne une référence à l'élément DOM rendu. + +Si le paramètre optionnel `replaceNode` est fourni avec un élément DOM et que celui-ci est un enfant de `containerNode`, Preact fera une mise-à-jour et remplacera cet élément en utilisant son algorithme de différenciation. + +```js +import { render } from 'preact'; + +const Foo = () =>
foo
; + +// DOM avant le rendu: +//
+render(, document.getElementById('container')); +// Après rendu: +//
+//
foo
+//
+ +// DOM avant rendu: +//
+//
bar
+//
+//
+render( + Foo, + document.getElementById('container'), + document.getElementById('target') +); +// Après rendu: +//
+//
bar
+//
+//
foo
+//
+//
+``` + +## hydrate() +Si vous avez un dom déjà rendu (par exemple parce que vous avez un rendu serveur, SSR [Server-Side Rendering](/guide/v10/server-side-rendering)), vous n'avez pas besoin de réappliquer un rendu avec `render` encore une fois. Vous pouvez utiliser `hydrate` qui sautera la phase de rendu et ne fera qu'attacher l'écoute d'événement (en anglais : EventHandlers) s'ils sont passé en paramètre avec `props`. + + +```jsx +import { render } from 'preact'; + +const Foo = () =>
foo
; +hydrate(, document.getElementById('container)); +``` + +## h() / createElement() + +`h(nodeName, attributes, [...children])` + +Retourne un élément DOM virtuel Preact (en anglais : Preact Virtual DOM) avec les `attributes` donnés. + +Les arguments suivant sont collectés dans une liste de `children` (enfants), et peuvent être : + +- Une valeur scalaire (chaine de caractère, nombres, booléen, null, undefined, etc...) +- D'autres éléments DOM virtuel +- Une infinité de chaine imbriqués d'éléments spécifiés ci-dessus + +```js +import { h } from 'preact'; + +h('div', { id: 'foo' }, 'Bonjour!'); +//
Bonjour!
+ +h('div', { id: 'foo' }, 'Bonjour', null, ['Preact!']); +//
Bonjour Preact!
+ +h( + 'div', + { id: 'foo' }, + h('span', null, 'Bonjour!') +); +//
Bonjour!
+``` + +## toChildArray + +Cette fonction d'aide convertira toujours des enfants en liste. Si le paramètre est déjà une liste ceci ne fera rien. Cette fonction est nécessaire parce que le paramètre `children` ne garantit pas d'être une liste. + +Si un élément ne contient qu'un seul enfant, celui-ci le recevra directement. Ce n'est seulement que lorsqu'il y a plusieurs enfants que vous pouvez être certain que `children` sera une liste. + +Cependant, `toChildArray` retournant toujours une liste, cela vous facilitera la vie concernant leur prise en charge. + +```jsx +import { toChildArray } from 'preact'; + +function Foo(props) { + const count = toChildArray(props.children).length; + return
I have {count} children
; +} + +// children is not an array +render(bar, container); + +// Children is an array +render(( + +

A

+

B

+
, + container +); +``` + +## cloneElement + +Cette fonction vous permet de faire un clonage superficiel d'un composant et d'en faire le rendu autre part. + +## createContext + +Voir dans la section [Documentation du contexte](/guide/v10/context#createcontext). + +## createRef + +Voir dans la section [Documentation des références](/guide/v10/refs#createref). + +## Fragment + +Un type spécial de composant qui ne fait aucun rendu dans le DOM. Il permet à un composant de retourner plusieurs enfants sans avoir besoin de les emballer dans une balise div. + +```jsx +import { Fragment, render } from 'preact'; + +render(( + +
A
+
B
+
C
+
+), container); +// Renders: +//
; + +// Renders:
Mon nom est John Doe.
+render(App, document.body); +``` + +> NB : dans des versions antérieures elles étaient connues comme des composants sans état mais ceci n'est plus vrai depuis les [`Hooks`](/guide/v10/hooks) + +## Composant de classe + +Les composants class ont un état et des méthodes de cycle de vie. Ces dernières sont des méthodes spéciales qui seront appelés lorsque le composant est attaché au DOM ou lorsqu'il est détruit, par exemple. + +Ici, nous avons une simple classe composant appelé `` qui affiche le temps actuel: + +```js +class Clock extends Component { + state = { time: Date.now() } + + // Cycle de vie: Appellé lorsque notre composant est crée + componentDidMount() { + // update time every second + this.timer = setInterval(() => { + this.setState({ time: Date.now() }); + }, 1000); + } + + // Cycle de vie: Appelé lorsque notre composant est détruit + componentWillUnmount() { + // s'arrête lorsqu'il n'est plus affichable + clearInterval(this.timer); + } + + render() { + let time = new Date(this.state.time).toLocaleTimeString(); + return {time}; + } +} +``` + +### Méthodes de cycle de vie + +Afin de permettre à l'horloge de se mettre à jour toutes les secondes, nous avons besoin de savoir quand `` est monté au DOM. _Si vous avez utilisé des éléments personnalisés HTML5, ceci est similaire aux méthodes de cycle de vie `attachedCallback` et `detachedCallback`._ Preact invoque ces méthodes en suivant le cycle suivant s'ils sont défini dans le composant: + +| Méthode de cycle de vie | Quand est ce qu'elle est appelé | +|-----------------------------|--------------------------------------------------| +| `componentWillMount` | (obsolète) avant que le composant soit monté dans le DOM| +| `componentDidMount` | après que le composant soit monté dans le DOM | +| `componentWillUnmount` | avant la suppression de l'élément du DOM | +| `componentWillReceiveProps` | (obsolète) avant que de nouveaux paramètres soient ajoutés | +| `getDerivedStateFromProps` | juste avant `shouldComponentUpdate`. À utiliser avec précaution. | +| `shouldComponentUpdate` | avant `render()`. Retourner `false` pour sauter le rendu | +| `componentWillUpdate` | (obsolète) appelé avant `render()` | +| `getSnapshotBeforeUpdate` | appelé avant `render()` | +| `componentDidUpdate` | appelé après `render()` | + +> Voir [ce diagramme](https://twitter.com/dan_abramov/status/981712092611989509) pour avoir un visuel de leurs relations. + +#### componentDidCatch + +Une de ces méthodes est particulière : `componentDidCatch`. Elle est spéciale car elle permet de gérer les erreurs qui apparaissent pendant le rendu. Ceci inclus les erreurs qui apparaissent dans les fonctions attachés aux cycle de vie, mais exclut toute erreur gérée de manière asynchrone (Comme après un appel `fetch()`). + +Quand une erreur est lancée, nous pouvons utiliser cette méthode pour réagir à cette dernière, et afficher un joli message d'erreur ou tout autre contenu de retrait. + + +```jsx +class Catcher extends Component { + state = { errored: false } + + componentDidCatch(error) { + this.setState({ errored: true }); + } + + render(props, state) { + if (state.errored) { + return

Quelque chose s'est mal passé

; + } + return props.children; + } +} +``` + +## Fragments + +Un `Fragment` permet de retourner plusieurs éléments à la fois. Ils résolvent une limitation du JSX qui demande que chaque bloc ne doit avoir qu'un seul élément racine (`root`). Vous les rencontrerez souvent en combinaison avec les listes, les tables ou le CSS Flexbox où chaque élément intermédiaire aurait autrement un style différent. + +```jsx +import { Fragment, render } from 'preact'; + +function TodoItems() { + return ( + +
  • A
  • +
  • B
  • +
  • C
  • +
    + ) +} + +const App = ( +
      + +
    • D
    • +
    +); + +render(App, container); +// Renders: +//
      +//
    • A
    • +//
    • B
    • +//
    • C
    • +//
    • D
    • +//
    +``` + +Notez que les transpilateurs modernes vous permettent d'utiliser une syntaxe plus courte pour `Fragments`. Ce raccourci est bien plus commun et sera celui que vous rencontrerez le plus souvent. + +```jsx +// This: +const Foo = foo; +// ...is the same as this: +const Bar = <>foo; +``` diff --git a/content/fr/guide/v10/context.md b/content/fr/guide/v10/context.md new file mode 100644 index 000000000..1122c1916 --- /dev/null +++ b/content/fr/guide/v10/context.md @@ -0,0 +1,81 @@ +--- +name: Contexte +description: 'Le contexte vous permet de passer des paramètres (`props`) à travers des composants intermédiaires. Ce document décrit comment l'ancienne et la nouvelle API fonctionne.' +--- + +# Contexte + +Le contexte vous permet de passer une valeur à travers les `props` à un enfant plus bas dans l'arbre sans avoir à passer à travers tous les composants qui se trouvent entre. Il permet par exemple de pouvoir gérer des thèmes personalisés. En quelques mots, le contexte permet de faire des mise à jour dans Preact dans un style publieur / abonné. (terme originel : pub-sub) + +Il y a deux différents moyens d'utiliser `context`: Via la nouvelle API `createContext` et l'ancienne API héritée. La différence entre les deux est que l'ancienne ne peut pas mettre à jour un enfant lorsqu'un élément parent interrompt le rendu en utilisant `shouldComponentUpdate`. C'est pourquoi il est très recommandé d'utiliser `createContext`. + +--- + + + +--- + +## createContext + +En premier, nous avons besoin de créer un objet de contexte que nous puissions passer en paramètre. Ceci est fait via la fonction `createContext(initialValue)`, qui retourne un composant `Provider` (Publieur) qui est utilisé pour définir la valeur du contexte et un `Consumer` (Abonné) qui est responsable de récupérer la valeur du contexte. + + +```jsx +const Theme = createContext('light'); + +function ThemedButton(props) { + return ( + + {theme => { + return ; + }} + + ); +} + +function App() { + return ( + + + + + + ); +} +``` + +> Une façon plus simple d'utiliser un contexte est d'utiliser le "hook" [useContext](/guide/v10/hooks#context). + +## L'API contexte héritée (dite "Legacy") + +Nous incluons l'API héritée principalement à des fins de rétrocompatibilité. Elle a été remplacée par l'API `createContext`. L'API héritée est connue pour avoir des problèmes comme le blocage de mise-à-jours s'il y a des composants intermédiaires qui retournent `false` à `shouldComponentUpdate`. Si vous souhaitez l'utiliser malgré tout, vous pouvez continuer à lire. + +Pour passer une variable personnalisée à travers le contexte, un composant a besoin d'avoir la méthode `getChildContext`. Vous pouvez y retourner les nouvelles valeurs que vous voulez stocker dans le contexte. Le contexte peut être accédé à travers le second argument dans le cas d'une fonction, ou `this.context` dans le cas d'un composant de classe. + +```jsx +function ThemedButton(props, context) { + return ( + ; + ); +} + +class App extends Component { + getChildContext() { + return { + theme: 'light' + } + } + + render() { + return ( +
    + + + +
    + ); + } +} +``` diff --git a/content/fr/guide/v10/debugging.md b/content/fr/guide/v10/debugging.md new file mode 100644 index 000000000..4638541c7 --- /dev/null +++ b/content/fr/guide/v10/debugging.md @@ -0,0 +1,213 @@ +--- +name: Débogage d'une application Preact +description: 'Comment déboguer une application Preact quand quelque chose ne va pas.' +--- + +# Déboguer une application Preact + +Preact livre de nombreux outils pour permettre un débogage plus simple. Ils sont empaquetés dans un seul `import` et peuvent êtres inclus en important `preact/debug`. + +Ceux-ci incluent un pont vers l'excellente extension pour Chrome ou Firefox, [Outil développement React]. Si vous l'avez déjà installée vous pouvez **l'essayer sur ce site**. Vous n'avez qu'à ouvrir la console de développement et inspecter comment nous l'avons construit. + +Nous afficherons un message d'avertissement ou une erreur lorsque nous rencontrerons un problème comme un embriquement incorrect (en anglais nesting) des éléments ``. + + +--- + + + +--- + +## Installation +L'[Outil de développement React] peut être installé dans la page d'extensions de votre navigateur + + +- [Pour Chrome](https://chrome.google.com/webstore/detail/react-developer-tools/fmkadmapgofadopljbjfkapdkoienihi) +- [Pour Firefox](https://addons.mozilla.org/en-US/firefox/addon/react-devtools/) + +Une fois installé, nous avons besoin d'importer `preact/debug` quelque part pour initialiser la connexion à l'extension. Faites un sorte que cette import **est le premier** de toute votre application. + +> `preact-cli` inclue le paquet `preact/debug/` automatiquement. Vous pouvez sauter la prochaine étape en toute sécurité si vous l'utilisez. + +Voici un exemple d'entrée principale d'application. + +```jsx +// Doit être le premier import +import "preact/debug"; +import { render } from 'preact'; +import App from './components/App'; + +render(, document.getElementById('root')); +``` + +### Supprimer les outils de développement en production + +La plupart des "bundlers" vous permettent de supprimer du code lorsqu'ils détectent qu'une instruction `if` ne sera jamais rencontrée, vous pouvez utiliser ceci pour n'inclure `preact/debug` que pendant votre développement et sauvegarder quelques précieux octets dans votre application finale. + +```js +// Doit être le premier import +if (process.env.NODE_ENV==='development') { + // Ici nous devons utiliser require puisque les instructions + // "import" ne sont autorisé qu'en haut d'un fichier. + require("preact/debug"); +} + +import { render } from 'preact'; +import App from './components/App'; + +render(, document.getElementById('root')); +``` + +Soyez certain d'attribuer la variable d'environnement `NODE_ENV` à la valeur correcte dans votre outil de "bundling". + +Déboguer les avertissements et des erreurs + +De temps en temps vous pourrez rencontrer un avertissement (warning) ou une erreur (error) lorsque Preact détectera du code invalide. Elles doivent être corrigé pour permettre à l'application de fonctionner correctement. + +### `undefined` parent passed to `render()` + +Cela veut dire que le code essaie de faire un rendu de votre application dans le vide, au lieu d'un élément DOM. C'est la différence entre : + +```jsx +// Ce qu'à reçu Preact +render(, undefined); + +// vs. ce à quoi il s'attendait +render(, actualDomNode); +``` +La raison principale pour laquelle cette erreur apparaît est que votre élément DOM n'est pas présent lorsque la fonction `render()` est appelée. Soyez certain qu'il existe. + +### `undefined` component passed to `createElement()` + +Preact lancera une erreur lorsque vous passerez `undefined` au lieu d'un composant. Une cause commune a cette erreur est une confusion avec les exports de type `default` et `named`. + +```jsx +// app.js +export default function App() { + return
    Bonjour monde !
    ; +} + +// index.js: Faux, car `app.js` n'a pas d'export nommé +import { App } from './app'; +render(, dom); +``` + +La même erreur sera lancée lorsque çe sera l'inverse, par exemple lorsque vous déclarez un export nommé (`named` export) et que vous essayez d'utiliser l'export `default`. Une façon rapide de vérifier cela (dans le cas où votre éditeur ne le fait pas déjà), est de simplement faire usage de `console.log` afin d'en connaître la valeur. + +```js +// app.js +export function App() { + return
    Bonjour monde !
    ; +} + +// index.js +import App from './app'; + +console.log(App); +// Logs: { default: [Function] } Au lieu d'un composant +``` + +### Passed a JSX literal as JSX twice + +Passer une constante JSX ou un composant dans du JSX à nouveau est invalide et déclenchera cette erreur. + +```jsx +const Foo =
    foo
    ; +// Invalide: Foo contient déjà une constante JSX +render(, dom); +``` +Pour corriger cela, nous pouvons juste passer la variable directement: + +```jsx +const Foo =
    foo
    ; +render(Foo, dom); +``` + +### Improper nesting of table detected + +HTML a une direction très claire sur la manière dont les tables devraient être structurées. Ne pas respecter ce format amènera à des erreurs de rendu qui peuvent être difficile à déboguer. Dans Preact, nous détectons et affichons ces erreurs. Pour en apprendre d'avantage sur la structure correcte des tables, nous vous recommandons vivement la [documentation MDN](https://developer.mozilla.org/fr/docs/Apprendre/HTML/Tableaux/Basics) + +### Invalid `ref`-property + +Lorsque la propriété `ref` contient quelque chose de non attendu, nous lancerons cette erreur. Ceci inclut les `refs` à base de chaîne de caractères (`string-based refs`) qui ont été déprécié par le passé. + +```jsx +// valide +
    {/* ... */)}} /> + +// valide +const ref = createRef(); +
    + +// Invalide +
    +``` + +### Invalid event handler + +De temps en temps vous pourriez accidentellement passer une valeur incorrecte à un handler. Elles doivent toujours être une fonction, ou, si vous souhaitez l'enlever, `null`. Tous les autres types sont invalides. + + +```jsx +// valid +
    console.log("click")} /> + +// invalid +
    +``` + +### Hook can only be invoked from render methods + +Cette erreur survient lorsque vous essayez d'utiliser un `hook` en dehors d'un composant. Ceux-ci ne sont supportés qu'à l'intérieur d'un composant. + +```jsx +// Invalide, doit être utilisé à l'intérieur d'un composant +const [value, setValue] = useState(0); + +// valide +function Foo() { + const [value, setValue] = useState(0); + return
    ; +} +``` + +### Getting `vnode.[property]` is deprecated + +Avec Preact X, certains changement majeurs entraînent une rupture de compatibilité avec la précédente version de Preact dans la façon dont nous gérons la structure interne `vnode`. + +| Preact 8.x | Preact 10.x | +|---|---| +| `vnode.nodeName` | `vnode.type` | +| `vnode.attributes` | `vnode.props` | +| `vnode.children` | `vnode.props.children`| + +### Found children with the same key + +Un aspect unique des librairies basés sur un DOM virtuel est qu'elles ont une chance de détecter lorsqu'un nœud a été bougé. Cependant, pour savoir exactement quel nœud est lequel, nous avons besoin de les identifier. _Ceci n'est nécessaire que lorsque nous créons des éléments dynamiquement._ + + +```jsx +// Les deux enfants auront la même clé "A" +
    + {['A', 'A'].map(char =>

    {char}

    )} +
    +``` + +La bonne façon de gérer cela est de leur donner des clés uniques. Dans la plupart des cas, la donnée sur laquelle vous itérez aura une forme d'`id`. + + +```jsx +const persons = [ + { name: 'John', age: 22 }, + { name: 'Sarah', age: 24} +]; + +// Quelque part dans votre composant +
    + {persons.map(({ name, age }) => { + return

    {name}, Age: {age}

    ; + })} +
    +``` + +[Outil de développement React]: https://github.com/facebook/react-devtools diff --git a/content/fr/guide/v10/differences-to-react.md b/content/fr/guide/v10/differences-to-react.md new file mode 100644 index 000000000..2a82f686d --- /dev/null +++ b/content/fr/guide/v10/differences-to-react.md @@ -0,0 +1,150 @@ +--- +name: Différences avec React +permalink: '/guide/differences-to-react' +description: 'Différences détaillées entre Preact et React' +--- + +# Différences à React + +Preact en soit même n'est pas fait pour être une ré-implémentation de React. Il y a des différences, beaucoup d'entre elles sont triviales, peut être complètement supprimés en utilisant [preact/compat], qui est une fine couche au dessus de Preact afin de lui permettre d'avoir 100% de compatibilité avec React. + +La raison pour laquelle Preact n'essaie pas d'inclure toutes les fonctionnalités de React est qu'elle est faite pour rester **petite** et **concentré** - autrement, cela aurait eu plus de sense de soumettre des optimisations au projet React, qui a déjà une architecture complexe et solide. + +--- + + + +--- + +## Principales différences + +La principal différence en comparant une application Preact et React est que nous ne livrons pas un système de gestion d'événement synthétique. Preact utilise la gestion d'événement native `addEventlistener` pour gêrer les évènements internes. Voir [Evénements Globaux] pour une liste complète des événements DOM. + +Une gestion synthétique n'a pas de sense car le navigateur supporte toutes les fonctionnalités dont nous avons besoin. Une implémentation d'une gestion d'événement personnalisé augmenterait nos frais de développement et une surface d'API plus large. + +L'autre principal différence est que nous suivons d'un peu plus prêt les spécifications DOM. Un exemple est que nous permettons d'utiliser `class` au lieu de `className`. + + +## Compatibilité de Versions + +Pour Preact et [preact/compat], la compatibilité de version est mesuré avec la version majeure _actuel_ et _précédente_ de React. Quand de nouvelles fonctionnalités sont annoncés par l'équipe de React, elles pourraient être ajouté à Preact si cela a du sens avec les [objectifs du projet]. Ceci est un processus démocratique, constamment évoluant à travers les discussions et les décisions faite ouvertement, utilisant des tickets (issues) et des propositions de modification (pull-requests). + +> Ainsi, le site et la documentation utilisent React `0.16.x` et `15.` lorsque l'on parle de compatibilité et de comparaisons. + + +## Fonctionnalités unique à Preact + +Preact a décidé d'ajouter quelques fonctionnalités pratique inspirés par le travail de la communauté (P)React. + +### Arguments dans `Component.render()` + +Nous passons `this.props` et `this.state` d'une classe composant à `render()`. vous pouvez voir que ce composant utilise un seul paramètre (`prop`) et une seul propriété d'état (`state property`). + +```jsx +// Fonctionne à la fois avec Preact et React +class Foo extends Component { + state = { age: 1 }; + + render() { + return
    Name: {this.props.name}, Age: {this.state.age}
    ; + } +} +``` +En Preact, ceci peut aussi être écrit comme ceci: + +```jsx +// Fonctionne seulement en Preact +class Foo extends Component { + state = { age: 1 }; + + render({ name }, { age }) { + return
    Name: {name}, Age: {age}
    ; + } +} +``` +Les deux extraits vont faire exactement le même rendu. Ce n'est qu'une question de préférence stylistique. + +### attributs HTML brut / noms des propriétés +Avec Preact nous suivons d'un peu plus prêt les spécifications DOM. Une principale différence est que nous permettons d'utiliser `class` au lieu de `className`. + +```jsx +// This: +
    + +// ...est le même que: +
    +``` +La plupart des développeurs Preact préfèrent d'utiliser une `class` parce que c'est plus court à écrire mais les deux sont supportés. + +### Utiliser `onInput` au lieu de `onChange` + +Pour des raisons historique, React a simplement lié (aliased) `onChange` à `onInput`. La dernière est celle utilisé par le DOM et est supporté partout. L'événement `input` est celui principalement celui qui est utilisé dans tous les cas où vous souhaitez être notifié lorsque l'élément de contrôle de formulaire (`input`, `textarea`, `checkbox`, etc...) est mis-à-jour. + + +```jsx +// React + console.log(e.target.value)} /> + +// Preact + console.log(e.target.value)} /> +``` +Si vous utilisez [preact/compat] nous mettrons en place cet alias 'onChange' à `onInput` globalement de manière similaire à React. Ceci est une des astuces que nous utilisons pour nous assurer d'une compatibilité avec l'écosystème de React. + +### JSX-Constructor +Cette idée était originellement appellé [hyperscript] et a de la valeur bien au dela de l'écosystème React, alors Preact promu le standard originel. ([Lire : pourquoi `h()`?]((http://jasonformat.com/wtf-is-jsx)). Si vous regardez la sortie transpilé, ce sera plus simple à lire que `React.createElement`. + +```js +h( + 'a', + { href:'/' }, + h('span', null, 'Home') +); + +// vs +React.createElement( + 'a', + { href:'/' }, + React.createElement('span', null, 'Home') +); +``` +Dans la plupart des applications Preact vous rencontrerez `h()`, mais nous supportons les deux, alors peut importe celui que vous utiliserez. + +### Pas besoin de contextTypes + +L'API hérité `Context` a besoin que les `Component` implémente `contextTypes` ou `childContextTypes` dans react. Avec Preact nous n'avons pas cette limitation et tous les composants reçoivent toutes les entrées `context` récupérés dans `getChildContext()`. + +## Fonctionnalités exclusives à `preact/compat` + +`preact/compat` est notre couche de **compat**ibilité qui traduit du code React en Preact. Pour des utilisateurs de React existant il est très simple d'utiliser Preact en mêttant en place quelques alias dans leur fichier de configuration et laisser le reste du code tel qu'il est. + +### Children-API + +L'API `children` est spécialisé dans une façon d'itérer les `children` d'un composant. Pour Preact cette API n'est pas nécéssaire et nous recommandons d'utiliser une chaine native à la place. + +```jsx +// React +function App(props) { + return
    {Children.count(props.children)}
    +} + +// Preact: Convert children to an array and use standard array methods. +function App(props) { + return
    {toChildArray(props.children).length}
    +} +``` + +### Composants spécialisés + +[preact/compat] livre une version spécialisé des composants qui ne sont pas fait pour toutes les applications. Ceci inclus: + +- `PureComponent`: Ne se met à jour que si un `props` ou un `state` a changé +- `memo`: Similaire à `PureComponent` mais permet de passer une fonction de comparaison. +- `forwardRef`: Livre une référence (`ref`) à un enfant spécifique d'un composant. +- `Portals`: Continue le rendu dans un container DOM différent. +- `Suspense`: **experimental** Permet de définir un affichage temporaire pendant que le rendu n'est pas fini. +- `lazy`: **experimental** "Lazy load" du code asynchrone et marque l'arbre comme étant prêt ou pas en fonction. + +[objectifs du projet]: /about/project-goals +[hyperscript]: https://github.com/dominictarr/hyperscript +[preact/compat]: #features-exclusive-to-preactcompat +[Evénements Globaux]: https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers \ No newline at end of file diff --git a/content/fr/guide/v10/extending-component.md b/content/fr/guide/v10/extending-component.md new file mode 100644 index 000000000..1cc564933 --- /dev/null +++ b/content/fr/guide/v10/extending-component.md @@ -0,0 +1,66 @@ +--- +name: Extending Component +permalink: '/guide/extending-component' +--- + +# Étendre un Composant + +Il est possible que certain projets souhaitent étendre les fonctionnalités de base d'un Composant. + +Il y a de différentes opinions sur la valeur ajouté de l'héritage en Javascript, mais si vous souhaitez créer vos propres "base class" desquels tous vous composants héritent, Preact vous permet de le faire. + +Peut être que vous voulez une connection automatique avec des stores/reducers dans une architecture "Flux". Peut être que vous souhaitez ajouter des mixins basés sur des propriétés pour avoir quelque chose qui ressemble plus à `React.createClass()` _(note: le [décorateur `@bind`](https://github.com/developit/decko#bind) est préférable_) + +Dans tous les cas, juste utiliser un héritage de class ES2015 pour étendre une class Composant Preact : + +```js +class BoundComponent extends Component { + // example: récupère les méthodes liés + binds() { + let list = this.bind || [], + binds = this._binds; + if (!binds) { + binds = this._binds = {}; + for (let i=list.length; i--; ) { + binds[list[i]] = this[list[i]].bind(this); + } + } + return binds; + } +} +``` + +Example Usage: + +```js +class Link extends BoundComponent { + bind = ['click']; + click() { + open(this.props.href); + } + render({ children }) { + let { click } = this.binds(); + return { children }; + } +} + +render( + Click Me, + document.body +); +``` + +Les possibilités sont infinis. Il y a un class `Component` étendu qui supporte les mixins rudimentaires: + +```js +class MixedComponent extends Component { + constructor() { + super(); + (this.mixins || []).forEach( m => Object.assign(this, m) ); + } +} +``` + +--- + +> **Note de bas de page:** Il est intéressant de noter que l'héritage peut vous verrouiller dans des relations fragiles "enfant-parent". Souvent lorsque nous faisons face à un problème qui peut être résolu avec un paradigme objet peut aussi l'être avec une façon plus fonctionnel sans avoir à créer ce genre de relation. diff --git a/content/fr/guide/v10/external-dom-mutations.md b/content/fr/guide/v10/external-dom-mutations.md new file mode 100644 index 000000000..6ef18170e --- /dev/null +++ b/content/fr/guide/v10/external-dom-mutations.md @@ -0,0 +1,84 @@ +--- +name: Mutations DOM externes +permalink: '/guide/external-dom-mutations' +description: "Comment intégrer Peact avec jQuery et d'autres extraits JavaScript qui mutent le DOM directement" +--- + +# Mutation DOM externe + +Parfois on a besoin de travailler avec une librairie qui a besoin de manipuler librement le DOM, sauvegarder des états en celui-ci, ou qui n'a aucune limite de composant. Il y a beaucoup de très bon outils réutilisables qui fonctionnent de cette manière. + +En Preact (et de manière similaire, en React), travailler avec ce type de libraire demande à ce que vous disiez à l'algorithme de changement du DOM virtuel qu'il ne devrait pas essayer de _défaire_ les changements DOM externes fait à l'intérieur d'un composant (`Component`) ou l'élément DOM qu'il représente. + +--- + + + +--- + +## Technique + +Ceci peut être aussi simple que définir une méthode `shouldComponentUpdate()` sur votre composant, et lui faire retourner `false`: + +```js +class Block extends Component { + shouldComponentUpdate() { + return false; + } +} +``` + +... ou pour le raccourcie: + +```js +class Block extends Component { + shouldComponentUpdate = () => false; +} +``` + +Avec ce hook sur le cycle de vie, et en disant à Preact de ne pas refaire un rendu sur le composant quand des changements se font dans l'arbre VDOM (DOM virtuel), votre composant a maintenant une référence à son élément DOM racine qui peut être considéré comme static jusqu'à ce que le composant est retiré du DOM (unmounted). Comme tous les composants cette référence s'appelle tout simplement `this.base`, et correspond à la racine de l'élément JSX qui a été retourné par `render()`. + +--- + +## Exemple pas à pas + +Ceci est est un exemple de comment on peut "éteindre" la re-génération du rendu d'un composant. Notez que `render()` est toujours invoqué dans la procédure où l'on crée et charge le composant afin de générer sa structure DOM initiale. + +```js +class Example extends Component { + shouldComponentUpdate() { + // Ne re-fait pas le rendu via l'algorithme de différenciation (`diff`) + return false; + } + + componentWillReceiveProps(nextProps) { + // Vous pouvez faire quelque chose avec les paramètres entrant ici + } + + componentDidMount() { + // maintenant qu'il est chargé, vous pouvez modifier le DOM librement + let thing = document.createElement('maybe-a-custom-element'); + this.base.appendChild(thing); + } + + componentWillUnmount() { + // le composant est sur le point d'être supprimé du DOM, faites un nettoyage. + } + + render() { + return
    ; + } +} +``` + + +## Démonstration + +[![demo](https://i.gyazo.com/a63622edbeefb2e86d6c0d9c8d66e582.gif)](http://www.webpackbin.com/V1hyNQbpe) + +[**Voir cette démo sur Webpackbin**](https://www.webpackbin.com/bins/-KflCmJ5bvKsRF8WDkzb) + + +## Exemples dans la vie réel + +Alternativement, vous pouvez voir cette technique en action sur [preact-token-input](https://github.com/developit/preact-token-input/blob/master/src/index.js) - ceci utilise un composant comme une attache au DOM, mais désactive ensuite les mises-à-jours et permet [tags-input](https://github.com/developit/tags-input) re reprendre la main. Un exemple plus complexe peut être [preact-richtextarea](https://github.com/developit/preact-richtextarea), qui utilise cette technique afin d'éviter de re-générer un rendu sur une `