{{ params.recipient }}
``` ```htmlTembuilder
```{{ props.heading }} → Invoice{{ params.recipient }} → TembuilderTembuilder
{{ params.recipient }} · {{ params.quantity }}
{{ params.totalLabel }}
{{#if params.paid}}Paid{{else}}Awaiting payment{{/if}} ``` Le texte s'affiche sous forme de texte, les nombres affichent leur valeur et l'impression directe d'un booléen produit `true` ou `false`. Utilisez une condition pour une étiquette conviviale. Conservez `2` numérique et `false` booléen ; `"2"` et `"false"` sont des chaînes. Une valeur non résolue n'imprime normalement rien. Cela ne remplace pas la déclaration des champs obligatoires ou la validation des données d'exécution. Une syntaxe invalide ou un assistant inconnu arrête la compilation. Handlebars ne calcule pas `quantity * price`, n'appelle pas `.toFixed(2)` et ne formate pas automatiquement les dates/devises. Préparez les totaux et les chaînes formatées avant le rendu. `{{ params.quantity + 1 }}` et `{{ params.total.toFixed(2) }}` ne sont pas des expressions JavaScript prises en charge. ## 4. Objets et noms de propriétés ```json { "recipient": { "name": "Tembuilder", "address": { "city": "Hanoi" } }, "labels": { "invoice_title": "Invoice", "postal_code": "10000" } } ``` ```handlebars{{ params.recipient.name }} · {{ params.recipient.address.city }}
{{ params.labels.postal_code }}
``` Utilisez des noms de champs tels que `recipientName` ou `postal_code`. L'éditeur remplace les espaces, les tirets et autres caractères en dehors des lettres, des chiffres et des traits de soulignement par `_` ; le premier caractère doit être une lettre ou un trait de soulignement. Pour un schéma importé existant avec des clés telles que `postal code`, Handlebars peut les lire à l'aide de `{{ params.labels.[postal code] }}`. Cette syntaxe ne modifie pas les règles de dénomination de l’éditeur. Pour restituer un objet de manière significative, sélectionnez ses champs ou itérez-les ; l'impression de l'objet entier n'est pas une sérialisation JSON. ## 5. Conditions : `if`, `else`, `unless` ```handlebars {{#if params.paid}}Payment received
{{else if params.overdue}}Payment overdue
{{else}}Awaiting payment
{{/if}} {{#unless params.paid}}Please pay before the due date.
{{/unless}} {{#if params.balance includeZero=true}}Balance: {{ params.balance }}
{{/if}} ``` `if` prend la branche négative pour `false`, `null`, les valeurs manquantes, une chaîne vide, zéro et un tableau vide. `includeZero=true` fait prendre à zéro la branche positive. Un objet vide et la chaîne `"false"` prennent la branche positive. `unless` inverse la condition. `if` ne change pas le contexte actuel. Il n'y a pas d'assistants `eq`, `gt`, `and` ou `or` intégrés dans cette plate-forme. Calculez un booléen tel que `overdue` dans l'entrée au lieu d'écrire `{{#if params.balance > 0}}`. ## 6. Tableaux : `each` et états vides ```json { "items": [{ "name": "Design", "quantity": 2 }, { "name": "Review", "quantity": 1 }], "tags": ["Draft", "Internal"] } ``` ```handlebars| Item | Quantity |
|---|---|
| {{ this.name }} | {{ this.quantity }} |
| No items | |
{{#each params.items}} {{ this.name }} · {{ this.quantity }}{{else}} No items {{/each}}{{ @key }}: {{ this }}
{{/each}} ``` N'utilisez pas `@index + 1` pour créer des numéros de ligne. Fournissez un champ `rowNumber` si vous avez besoin d'une numérotation commençant par un. ## 8. Contexte : `with`, chemins parents et racine ```handlebars {{#with params.recipient}}{{ name }}
{{else}}No recipient
{{/with}} {{#each params.items}}{{ this.name }} — {{ ../props.heading }}
{{ @root.global.props.company }} {{/each}} ``` `with` et `each` changent de contexte. `../` renvoie au contexte parent ; `@root` fournit un accès stable à la racine de compilation à travers des boucles imbriquées. L'ajout d'un `if` ne nécessite pas un autre `../`. Les alias facilitent le suivi des listes imbriquées. Ici, déclarez `groups` comme un tableau d'objets, chacun avec un tableau `name` et un tableau `items` : ```handlebars {{#each params.groups as |group groupIndex|}}{{ groupIndex }}.{{ itemIndex }} — {{ item.name }}
{{/each}} {{/each}} ``` ## 9. Recherche dynamique et sous-expressions Utilisez `lookup` pour une clé fournie en données. Déclarez `labels` comme objet et `selectedKey` comme texte ; pour `{ "labels": { "approved": "Approved" }, "selectedKey": "approved" }` : ```handlebars{{ lookup params.labels params.selectedKey }}
{{#with (lookup params.labels params.selectedKey)}}{{ this }}{{/with}} ``` Les parenthèses imbriquent un résultat d'assistance dans un autre assistant. Ils n’évaluent pas les JavaScript arbitraires. Les arguments entre guillemets sont des chaînes littérales, tandis que les chemins sans guillemets lisent les données. `includeZero=true` est une option d'assistance nommée, pas une affectation aux données d'entrée. ## 10. Échappement HTML et valeurs CSS ```handlebars{{ params.recipient }}
``` Pour `recipient` égal à `Tembuilder & Tembuilder`, la source HTML contient `Tembuilder & Tembuilder` et le document affiche **Tembuilder & Tembuilder**. Conservez des accolades doubles pour une saisie ordinaire. `{{{ params.trustedHtml }}}` et `{{& params.trustedHtml }}` insèrent HTML sans s'échapper. Utilisez-les uniquement pour le balisage fiable et aseptisé que vous avez l'intention de devenir des éléments de document. L'échappement n'est pas une validation d'URL ou de CSS. Validez les valeurs destinées à `href`, `src` ou aux styles. Dans l'éditeur CSS, un accessoire Color contrôlé peut être lu directement : ```css h1 { color: {{ props.accent }}; } ``` Donnez à `accent` une couleur valide telle que `#2563eb`. Handlebars fournit une substitution ; le résultat doit toujours être valide CSS. ## 11. Commentaires, espaces et accolades littérales ```handlebars {{! Internal note, omitted from output }} {{!-- A longer note that can include {{ expressions }} --}} {{ params.recipient ~}} ``` `~` à côté d'un délimiteur coupe les espaces adjacents de ce côté. Utilisez-le avec précaution autour des mots qui nécessitent un espace de séparation. Handlebars supprime ses propres commentaires lors de la compilation. Tembuilder supprime également les commentaires HTML lors de la désinfection, de sorte qu'aucun des deux types ne reste dans le document final HTML. Pour afficher une expression littérale plutôt que de l'évaluer : ```handlebars\{{ params.recipient }}
``` Le document affiche `{{ params.recipient }}`. Les blocs bruts (`{{{{raw}}}}…{{{{/raw}}}}`) nécessitent un assistant de bloc enregistré ; cette plateforme ne fournit pas d'assistant `raw`. ## 12. Partiels et autres fonctionnalités avancées Un partiel en ligne peut réutiliser le balisage **dans une source compilée** : ```handlebars {{#*inline "recipientCard"}}{{ name }}
{{/inline}} {{> recipientCard params.recipient}} ``` Il n'est pas partagé automatiquement entre les fichiers de section, les en-têtes ou les pieds de page. `{{> sharedCard}}` a besoin d'une définition ; Tembuilder n'expose pas de registre pour les partiels globaux définis par l'utilisateur ou les assistants JavaScript personnalisés. Handlebars prend également en charge les paramètres partiels, la sélection partielle dynamique, les blocs partiels et les assistants de bloc personnalisés. Il s’agit de capacités linguistiques et non d’une promesse de fonctionnalités d’enregistrement sur la plateforme. Ne collez pas `registerHelper`, `registerPartial` ou les balises de script dans le modèle HTML en attendant qu'ils configurent la compilation. L'assistant `log` intégré écrit dans le journal de l'environnement d'exécution plutôt que dans le PDF. Préférez Aperçu et Run pour inspecter la sortie ; évitez de consigner des données d’exécution sensibles. Les décorateurs et l'accès aux prototypes/méthodes ne sont pas nécessaires pour la création de documents : utilisez des valeurs JSON simples et les assistants documentés. ## 13. Exemple de section complète Créez les Props de section `heading = "Invoice"` et les Props Global `company = "Tembuilder"`. Déclarez `recipient` (Objet avec `name` : Texte), `items` (Tableau d'objets avec `name` : Texte et `quantity` : Nombre), `paid` (Booléen) et `totalLabel` (Texte). Run avec : ```json { "recipient": { "name": "Tembuilder" }, "items": [{ "name": "Design", "quantity": 2 }], "paid": false, "totalLabel": "250,000 VND" } ``` Coller dans la section HTML : ```handlebars{{ global.props.company }} → {{ params.recipient.name }}
Total: {{ params.totalLabel }}
{{#if params.paid}}Paid{{else}}Awaiting payment{{/if}}
``` Contenu attendu : **Facture**, **Tembuilder → Tembuilder**, **Design × 2**, **Total : 250 000 VND**, **En attente de paiement**. Essayez un tableau `items` vide et un `paid: true` pour vérifier les deux branches alternatives dans Preview/Run. ## 14. Dépannage et règles de création d'IA | Symptôme | Vérifier | | --- | --- | | Valeur vide | Orthographe du champ, type déclaré, charge utile d'exécution, variante active et contexte actuel. | | Mauvaise valeur dans une boucle | Utilisez `this`, un alias, `../` ou `@root` pour sélectionner le contexte souhaité. | | Zéro caché | Utilisez `includeZero=true` où zéro est une valeur affichée valide. | | Condition positive inattendue | Recherchez une chaîne `"false"` au lieu de la booléenne `false`. | | Erreur de compilation | Faites correspondre les noms d'ouverture/fermeture de chaque bloc ; supprimez les opérateurs JavaScript et les assistants/partiels indisponibles. | | `[object Object]` | Sélectionnez les champs de l'objet ou itérez-les au lieu d'imprimer l'objet entier. | Pour les auteurs d'IA : conservez les noms et les types de champs déclarés, utilisez des espaces de noms explicites, calculez la logique métier avant le rendu, fournissez des états vides, conservez les valeurs ordinaires échappées et vérifiez les exemples par rapport aux données renseignées et vides. Une valeur manquante ne prouve pas une liaison réussie. Voir [erreurs courantes](/docs/fr/help/common-errors/). ## 15. Références officielles Handlebars Utilisez le [guide officiel Handlebars](https://handlebarsjs.com/guide/) pour la documentation linguistique complète. Le comportement de la plateforme décrit ci-dessus est prioritaire lorsqu'un exemple en amont nécessite un enregistrement côté hôte ou une configuration d'exécution. - [Expressions, échappement, chemins et espaces](https://handlebarsjs.com/guide/expressions.html) - [Aide intégrée](https://handlebarsjs.com/guide/builtin-helpers.html) - [Variables de données de boucle et de racine](https://handlebarsjs.com/api-reference/data-variables.html) - [Partiaux et partiels en ligne](https://handlebarsjs.com/guide/partials.html) - [Aide aux blocs personnalisés](https://handlebarsjs.com/guide/block-helpers.html)