{{ params.recipient }}
``` ```htmlTembuilder
```{{ props.heading }} → Invoice{{ params.recipient }} → TembuilderTembuilder
{{ params.recipient }} · {{ params.quantity }}
{{ params.totalLabel }}
{{#if params.paid}}Paid{{else}}Awaiting payment{{/if}} ``` El texto se muestra como texto, los números muestran su valor y la impresión directa de un booleano produce `true` o `false`. Utilice una condición para una etiqueta fácil de leer. Mantenga `2` numérico y `false` booleano; `"2"` y `"false"` son cadenas. Un valor no resuelto normalmente no imprime nada. Esto no sustituye a declarar campos obligatorios o validar datos de ejecución. La sintaxis no es válida o un asistente desconocido detiene la compilación. Handlebars no calcula `quantity * price`, no llama a `.toFixed(2)` ni formatea fechas/monedas automáticamente. Prepare totales y cadenas formateadas antes de renderizar. `{{ params.quantity + 1 }}` y `{{ params.total.toFixed(2) }}` no son expresiones compatibles con JavaScript. ## 4. Objetos y nombres de propiedades ```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 }}
``` Utilice nombres de campo como `recipientName` o `postal_code`. El editor reemplaza espacios, guiones y otros caracteres fuera de letras, dígitos y guiones bajos con `_`; el primer carácter debe ser una letra o un guión bajo. Para un esquema importado existente con claves como `postal code`, Handlebars puede leerlas usando `{{ params.labels.[postal code] }}`. Esa sintaxis no cambia las reglas de nomenclatura del editor. Para representar un objeto de manera significativa, seleccione sus campos o repítalos; imprimir todo el objeto no es una serialización JSON. ## 5. Condiciones: `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` toma la rama negativa para `false`, `null`, valores faltantes, una cadena vacía, cero y una matriz vacía. `includeZero=true` hace que el cero tome la rama positiva. Un objeto vacío y la cadena `"false"` toman la rama positiva. `unless` invierte la condición. `if` no cambia el contexto actual. No hay asistentes `eq`, `gt`, `and` o `or` integrados en esta plataforma. Calcule un booleano como `overdue` en la entrada en lugar de escribir `{{#if params.balance > 0}}`. ## 6. Arrays: `each` y estados vacíos ```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}} ``` No utilice `@index + 1` para crear números de fila. Proporcione un campo `rowNumber` si necesita una numeración que comience en uno. ## 8. Contexto: `with`, rutas padre y raíz ```handlebars {{#with params.recipient}}{{ name }}
{{else}}No recipient
{{/with}} {{#each params.items}}{{ this.name }} — {{ ../props.heading }}
{{ @root.global.props.company }} {{/each}} ``` `with` y `each` cambian de contexto. `../` vuelve al contexto principal; `@root` proporciona acceso estable a la raíz de compilación a través de bucles anidados. Agregar un `if` no requiere otro `../`. Los alias hacen que las listas anidadas sean más fáciles de seguir. Aquí, declara `groups` como una matriz de objetos, cada uno con una matriz `name` y una matriz `items`: ```handlebars {{#each params.groups as |group groupIndex|}}{{ groupIndex }}.{{ itemIndex }} — {{ item.name }}
{{/each}} {{/each}} ``` ## 9. Búsqueda dinámica y subexpresiones Utilice `lookup` para una clave proporcionada como datos. Declare `labels` como objeto y `selectedKey` como Texto; Para `{ "labels": { "approved": "Approved" }, "selectedKey": "approved" }`: ```handlebars{{ lookup params.labels params.selectedKey }}
{{#with (lookup params.labels params.selectedKey)}}{{ this }}{{/with}} ``` Los paréntesis anidan un resultado auxiliar dentro de otro auxiliar. No evalúan JavaScript arbitrario. Los argumentos entre comillas son cadenas literales, mientras que las rutas sin comillas leen datos. `includeZero=true` es una opción de ayuda con nombre, no una asignación para ingresar datos. ## 10. Escape HTML y valores CSS ```handlebars{{ params.recipient }}
``` Para `recipient` igual a `Tembuilder & Tembuilder`, la fuente HTML contiene `Tembuilder & Tembuilder` y el documento muestra **Tembuilder & Tembuilder**. Mantenga llaves dobles para la entrada ordinaria. `{{{ params.trustedHtml }}}` y `{{& params.trustedHtml }}` insertan HTML sin escapar. Úselos únicamente para marcas confiables y desinfectadas que desee convertir en elementos del documento. Escapar no es una validación de URL o CSS. Valide los valores destinados a `href`, `src` o estilos. En el editor CSS, un accesorio de color controlado se puede leer directamente: ```css h1 { color: {{ props.accent }}; } ``` Asigne a `accent` un color válido como `#2563eb`. Handlebars proporciona sustitución; el resultado aún debe ser válido CSS. ## 11. Comentarios, espacios en blanco y llaves literales ```handlebars {{! Internal note, omitted from output }} {{!-- A longer note that can include {{ expressions }} --}} {{ params.recipient ~}} ``` `~` junto a un delimitador recorta los espacios en blanco adyacentes en ese lado. Úselo con cuidado alrededor de palabras que necesitan un espacio de separación. Handlebars elimina sus propios comentarios durante la compilación. Tembuilder también elimina los comentarios de HTML durante la desinfección, por lo que ninguno de los tipos permanece en el documento final HTML. Para mostrar una expresión literal en lugar de evaluarla: ```handlebars\{{ params.recipient }}
``` El documento muestra `{{ params.recipient }}`. Los bloques sin formato (`{{{{raw}}}}…{{{{/raw}}}}`) requieren un asistente de bloque registrado; Esta plataforma no proporciona un asistente `raw`. ## 12. Parciales y otras funciones avanzadas Un parcial en línea puede reutilizar el marcado **dentro de una fuente compilada**: ```handlebars {{#*inline "recipientCard"}}{{ name }}
{{/inline}} {{> recipientCard params.recipient}} ``` No se comparte automáticamente entre archivos de sección, encabezados o pies de página. `{{> sharedCard}}` necesita una definición; Tembuilder no expone un registro para parciales globales definidos por el usuario ni ayudantes personalizados de JavaScript. Handlebars también admite parámetros parciales, selección parcial dinámica, bloques parciales y ayudas de bloques personalizados. Estas son capacidades de idioma, no una promesa de funciones de registro en la plataforma. No pegue etiquetas `registerHelper`, `registerPartial` o script en la plantilla HTML esperando que configuren la compilación. El asistente integrado `log` escribe en el registro del entorno de ejecución en lugar de en PDF. Prefiera Vista previa y Run para inspeccionar la salida; Evite registrar datos de ejecución confidenciales. No se necesitan decoradores ni acceso a prototipos/métodos para la creación de documentos: utilice valores JSON simples y los ayudantes documentados. ## 13. Ejemplo de sección completa Cree el accesorio de sección `heading = "Invoice"` y el accesorio Global `company = "Tembuilder"`. Declare `recipient` (Objeto con `name`: Texto), `items` (Matriz de objetos con `name`: Texto y `quantity`: Número), `paid` (Booleano) y `totalLabel` (Texto). Run con: ```json { "recipient": { "name": "Tembuilder" }, "items": [{ "name": "Design", "quantity": 2 }], "paid": false, "totalLabel": "250,000 VND" } ``` Pegar en la sección HTML: ```handlebars{{ global.props.company }} → {{ params.recipient.name }}
Total: {{ params.totalLabel }}
{{#if params.paid}}Paid{{else}}Awaiting payment{{/if}}
``` Contenido esperado: **Factura**, **Tembuilder → Tembuilder**, **Diseño × 2**, **Total: 250 000 VND**, **Pendiente de pago**. Pruebe con una matriz `items` vacía y `paid: true` para verificar ambas ramas alternativas en Vista previa/Run. ## 14. Resolución de problemas y reglas de creación de IA | Síntoma | Verificar | | --- | --- | | Valor vacío | Ortografía del campo, tipo declarado, carga útil de ejecución, variante activa y contexto actual. | | Valor incorrecto dentro de un bucle | Utilice `this`, un alias, `../` o `@root` para seleccionar el contexto deseado. | | Cero oculto | Utilice `includeZero=true` donde cero es un valor mostrado válido. | | Condición positiva inesperada | Busque una cadena `"false"` en lugar del booleano `false`. | | Error de compilación | Haga coincidir los nombres de apertura/cierre de cada bloque; elimine los operadores JavaScript y los ayudantes/parciales no disponibles. | | `[object Object]` | Seleccione campos de objetos o repítalos en lugar de imprimir el objeto completo. | Para autores de IA: conserve los nombres y tipos de campos declarados, utilice espacios de nombres explícitos, calcule la lógica empresarial antes de renderizar, proporcione estados vacíos, mantenga los valores ordinarios escapados y verifique ejemplos con datos tanto completos como vacíos. Un valor faltante no demuestra una vinculación exitosa. Consulte [errores comunes](/docs/es/help/common-errors/). ## 15. Referencias oficiales de Handlebars Utilice la [guía oficial Handlebars](https://handlebarsjs.com/guide/) para obtener la documentación completa en el idioma. El comportamiento de la plataforma descrito anteriormente tiene prioridad cuando un ejemplo ascendente requiere registro del lado del host o configuración del tiempo de ejecución. - [Expresiones, escape, rutas y espacios en blanco](https://handlebarsjs.com/guide/expressions.html) - [Ayudantes incorporados](https://handlebarsjs.com/guide/builtin-helpers.html) - [Variables de datos de bucle y raíz](https://handlebarsjs.com/api-reference/data-variables.html) - [Parciales y parciales en línea](https://handlebarsjs.com/guide/partials.html) - [Ayudantes de bloqueo personalizados](https://handlebarsjs.com/guide/block-helpers.html)