Formularios para plantillas de Typst

Una plantilla de Typst suele traer sus propias funciones: una portada, un cuadro de información, un bloque de firma. Quien escribe el informe las llama, como en #info-box(title: "Supply risk", tone: "risk")[...]. Si mantienes la plantilla, puedes describir una sola vez los argumentos de cada función. El modo Visual muestra entonces cada llamada a esa función como un formulario: campos con etiqueta, una lista para las opciones fijas y un interruptor para el sí o el no. Al editar un campo se reescribe solo ese argumento en el archivo .typ, así que el informe sigue siendo código de Typst corriente que compila igual que antes.

Lo que ve el lector

Una llamada en líneas propias se convierte en una tarjeta. El encabezado de la tarjeta muestra el nombre del formulario y, si lo eliges, un breve resumen como el título del cuadro. Cada argumento tiene una fila con su etiqueta y un control.

Una llamada dentro de una frase, como #badge("review"), se convierte en un chip dentro de la línea de texto. Al hacer clic en el chip se abren los mismos campos en una ventana emergente pequeña.

Los campos de texto y de marcado se guardan al pulsar Enter (⌘ Enter o Ctrl Enter en un campo de varias líneas) o al salir del campo. Esc recupera el valor anterior. Las listas y los interruptores se guardan al instante. Cada cambio es un paso de deshacer.

Al mover el cursor a una llamada se muestra su código, como con cualquier otro elemento del modo Visual. Editar en el código en la tarjeta hace lo mismo.

Dónde declarar los formularios

Hay dos lugares, con el mismo formato:

• En un paquete. Añade una sección [tool.oleafly] al typst.toml del paquete. Typst reserva las secciones [tool.*] para otras herramientas, así que el paquete se sigue instalando y compilando en todas partes. Funciona con los paquetes @local y con los paquetes @preview de Typst Universe.
• En el proyecto. Para las plantillas que se guardan como archivos .typ normales dentro del proyecto, crea oleafly-forms.toml en la raíz del proyecto. Cada formulario nombra además el archivo que define la función, con module.

Un formulario de paquete:

[tool.oleafly]
schema = 1

[[tool.oleafly.forms]]
function = "info-box"
label = "Info box"
summary = "title"

  [[tool.oleafly.forms.fields]]
  arg = "title"
  kind = "text"
  label = "Heading"
  placeholder = "Short heading"
  required = true

  [[tool.oleafly.forms.fields]]
  arg = "tone"
  kind = "choice"
  label = "Tone"
  default = "note"
  options = [{ value = "note", label = "Note" }, { value = "risk", label = "Risk" }, "neutral"]

  [[tool.oleafly.forms.fields]]
  arg = 0
  kind = "content"
  label = "Text"

Un formulario de proyecto, en oleafly-forms.toml:

[tool.oleafly]
schema = 1

[[tool.oleafly.forms]]
module = "template/memo.typ"
function = "memo-header"
label = "Memo header"
fields = [
  { arg = "to", kind = "text", label = "To" },
  { arg = "subject", kind = "text", label = "Subject" },
]

Las claves

schema = 1 es obligatorio. Un archivo sin él, o con otro número, se ignora.

Cada entrada [[tool.oleafly.forms]] tiene:

Clave	Obligatoria	Significado
function	Sí	El nombre de la función, como un único identificador de Typst. Los guiones están permitidos.
module	Solo en oleafly-forms.toml	El archivo del proyecto que define la función, relativo a la raíz del proyecto, con / entre las carpetas.
label	No	El nombre del formulario en las tarjetas y los chips. El nombre de la función, de forma predeterminada.
summary	No	El argumento cuyo valor aparece junto a la etiqueta, escrito como el arg de un campo.
fields	Sí	Uno o más campos.

Cada campo tiene:

Clave	Obligatoria	Significado
arg	Sí	Un nombre para un argumento con nombre ("title"), o un número para uno posicional (0 es el primero). Un bloque [...] final cuenta como argumento posicional después de los que van entre paréntesis.
kind	Sí	text, content, choice, number o toggle.
label	Sí	La etiqueta del campo.
help	No	Una nota breve bajo el campo.
placeholder	No	Texto gris en un campo vacío.
required	No	true marca un campo vacío como que falta y oculta su botón Borrar. Oleafly nunca añade el argumento por sí mismo.
default	No	El valor que usa tu función cuando se omite el argumento. Se muestra, nunca se escribe.

Los tipos y sus claves adicionales:

• text escribe una cadena de Typst. Añade multiline = true para una caja más grande.
• content edita marcado de Typst y lo escribe como un bloque [...]. Un argumento de tipo cadena sigue siendo una cadena.
• choice necesita options: una lista de cadenas, o tablas { value, label } cuando la etiqueta difiere del valor. Los valores se escriben como cadenas.
• number admite integer, min, max y step. Los números no llevan unidades.
• toggle escribe true o false.

Qué llamadas reciben un formulario

Oleafly sigue las líneas #import y #let del propio informe en el nivel superior del archivo:

• #import "@local/acme-report:0.1.0" as acme hace que #acme.info-box(...) sea un formulario.
• #import "@local/acme-report:0.1.0": info-box, status-badge as badge hace que #info-box(...) y #badge(...) sean formularios.
• #import "@local/acme-report:0.1.0": * hace que cada función que declara el paquete tenga un formulario.
• #import "template/memo.typ": memo-header coincide con un formulario de proyecto cuyo module es template/memo.typ. Las rutas se leen desde la carpeta del propio informe, o desde la raíz del proyecto cuando empiezan por /.

La versión del paquete debe coincidir exactamente. Un #let con el mismo nombre, más adelante en el archivo, sustituye el formulario a partir de ese punto. Las llamadas a las que se llega a través de otro archivo que vuelve a importar el paquete conservan su texto de código.

Una función con el nombre de un elemento de Typst que el modo Visual ya dibuja, como table o figure, conserva el aspecto integrado cuando se llama por su nombre sin más. #acme.table(...) o una importación con otro nombre sí recibe el formulario.

Campos que se muestran de solo lectura

Algunos argumentos no se pueden editar de forma segura desde un formulario. Su fila muestra el código con el motivo, y Editar en el código salta hasta él:

• Calculado en el código: el valor es una expresión, como title: data.title.
• Escrito como otro tipo de valor: por ejemplo, un número donde el formulario espera texto.
• No es una de las opciones: un valor que tus options no enumeran.
• Definido por un argumento de propagación: una llamada con ..args pasa valores que el formulario no ve, así que todos los campos son de solo lectura.

Cuando un campo no se puede añadir donde iría, por ejemplo un argumento posicional después de uno que falta, el formulario lo dice y ofrece Añadir en el código.

Errores en una definición

Abre oleafly-forms.toml, o el typst.toml de un paquete incorporado, en Oleafly y cada problema aparece como una marca en su línea: un tipo desconocido, una etiqueta que falta, un formulario duplicado, un module fuera del proyecto. Un formulario defectuoso se omite y los demás siguen funcionando. Un archivo de más de 256 KB no se lee.

Compartir plantillas

Oleafly lee los formularios de los paquetes en las mismas carpetas que usa el compilador. Un colaborador que no tiene el paquete @local ve código normal y ningún error. Para compartir los formularios con todos los de un proyecto, abre el cuadro de diálogo Paquetes de Typst, activa Usar paquetes de la carpeta del proyecto y elige Incorporar los paquetes al proyecto. El paquete, y sus formularios, viajan entonces en la carpeta typst-packages del proyecto (consulta Proyectos de Typst).