Plantillas
Las plantillas son componentes de Astro para proporcionar una estructura reutilizable, como una plantilla de página.
Convencionalmente usamos el término “plantilla” para proporcional elementos compartidos en la interfaz del usuario por medio de páginas, como encabezados, barras de navegación y pies de página. Una plantilla proporciona a Astro, Markdown o páginas MDX con:
- una página shell (con estiquetas
<html>
,<head>
y<body>
) - un
<slot/>
para especificar dónde colocar el contenido de la página.
Pero, ¡no hay nada especial acerca de los componentes plantilla! Pueden aceptar props e importar y usar otros componentes como cualquier otro componente de Astro. Pueden incluir componentes de framework y scripts de lado del cliente. Ni siquiera tienen que proporcionar un plantilla entera, en su lugar se pueden utilizar como plantillas parciales.
Sin embargo, si un componente de plantilla contiene una página shell, su elemento <html>
debe ser el padre de todos los demás elementos en el componente.
Los componentes de plantilla se colocan comúnmente en la carpeta src/layouts
en tu proyecto, pero esto no es un requisito; puedes elegir ubicarlos en cualquier lugar de tu proyecto. Incluso puedes colocar las plantillas junto a tus páginas mediante el uso de un prefijo _
en los nombres de las plantillas.
Plantilla de ejemplo
Sección titulada Plantilla de ejemplo---import BaseHead from '../components/BaseHead.astro';import Footer from '../components/Footer.astro';const { title } = Astro.props;---<html lang="es"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <BaseHead title={title} /> </head> <body> <nav> <a href="#">Inicio</a> <a href="#">Publicaciones</a> <a href="#">Contacto</a> </nav> <h1>{title}</h1> <article> <slot /> <!-- tu contenido es inyectado aquí --> </article> <Footer /> </body> <style> h1 { font-size: 2rem; } </style></html>
---import MySiteLayout from '../layouts/MySiteLayout.astro';---<MySiteLayout title="Página De Inicio"> <p>¡El contenido de mi página, envuelto en una plantilla!</p></MySiteLayout>
Usando TypeScript con plantillas
Sección titulada Usando TypeScript con plantillasCualquier plantilla de Astro puede ser modificada para introducir seguridad de tipos y autocompletado proporcionando los tipos en las props:
---interface Props { title: string; description: string; publishDate: string; viewCount: number;}
const { title, description, publishDate, viewCount } = Astro.props; ---<html lang="es"> <head> <meta charset="UTF-8"> <meta name="description" content={description}> <title>{title}</title> </head> <body> <header> <p>Publicado el {publishDate}</p> <p>Visto por {viewCount} amigos</p> </header> <main> <slot /> </main> </body></html>
Plantillas de Markdown
Sección titulada Plantillas de MarkdownLas plantillas son especialmente útiles para páginas de Markdown de lo contrario no tendría ningún estilo de página.
Astro proporciona una propiedad especial layout
en el frontmatter destinada a archivos individuales .md
ubicados dentro de src/pages/
utilizando enrutamiento basado en archivos para especificar qué componente .astro
utilizar como diseño de página. Este componente le permite proporcionar contenido <head>
como meta-etiquetas (por ejemplo, <meta charset="utf-8">
) y estilos para la página Markdown. Por defecto, este componente especificado puede acceder automáticamente a los datos del archivo Markdown.
Esto no se reconoce como una propiedad especial cuando se utiliza colecciones de contenido para consultar y renderizar su contenido.
---layout: ../layouts/BlogPostLayout.astrotitle: "¡Hola, mundo!"author: "Matthew Phillips"date: "09 Aug 2022"---Todas las propiedades frontmatter están disponibles como props en un componente plantilla de Astro.
La propiedad `layout` es la única especial proporcionada por Astro.
Puedes usarla en archivos Markdown localizada dentro de `src/pages/`.
Una plantilla típica para Markdown o páginas MDX incluye:
- La prop
frontmatter
para acceder al Markdown o frontmatter de la página y otra información. - Un
<slot />
por defecto para indicar el lugar donde el contenido Markdown de la página será renderizado.
---// 1. La prop frontmatter da acceso al frontmatter y otros datosconst { frontmatter } = Astro.props;---<html> <head> <!-- Agrega otro elemento Encabezado aquí, como estilos y etiquetas meta. --> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta charset="utf-8"> <title>{frontmatter.title}</title> </head> <body> <!-- Agrega otros componentes de interfaz de usuario aquí, como encabezados y pies de página comunes. --> <h1>{frontmatter.title} por {frontmatter.author}</h1> <!-- 2. El HTML renderizado será pasado al slot por defecto. --> <slot /> <p>Escrito en: {frontmatter.date}</p> </body></html>
Puedes establecer el tipo de una plantilla como Props
con el ayudante MarkdownLayoutProps
:
---import type { MarkdownLayoutProps } from 'astro';
type Props = MarkdownLayoutProps<{ // Define las propiedades frontmatter aquí title: string; author: string; date: string;}>;
// Ahora, `frontmatter`, `url` y otras propiedades de la plantilla de Markdown// están disponibles con seguridad de tiposconst { frontmatter, url } = Astro.props;---<html> <head> <meta charset="utf-8"> <link rel="canonical" href={new URL(url, Astro.site).pathname}> <title>{frontmatter.title}</title> </head> <body> <h1>{frontmatter.title} por {frontmatter.author}</h1> <slot /> <p>Escrito en: {frontmatter.date}</p> </body></html>
Props de plantillas Markdown
Sección titulada Props de plantillas MarkdownUna plantilla Markdown/MDX tendrá acceso a la siguiente información a través de Astro.props
:
file
- La ruta absoluta de este archivo (por ejemplo,/home/user/projects/.../file.md
).url
- La URL de la página (por ejemplo,/en/guides/markdown-content
).frontmatter
- Todo el frontmatter del documento Markdown o MDX.frontmatter.file
- La misma que la propiedad de nivel superiorfile
.frontmatter.url
- La misma que la propiedad de nivel superiorurl
.
headings
- Una lista de encabezados (h1 -> h6
) en el documento Markdown o MDX con metadatos asociados. Esta lista sigue el tipo:{ depth: number; slug: string; text: string }[]
.
rawContent()
- Función que devuelve el documento Markdown sin procesar como una string.
compiledContent()
- Función asíncrona que devuelve el documento Markdown compilado a una cadena HTML.
Una plantilla Markdown tendrá acceso a todas sus propiedades exportadas del archivo Markdown desde Astro.props
con dos diferencias clave:
-
Información de encabezados (es decir, elementos
h1 -> h6
) están disponibles a través del arrayheadings
, en lugar de la funcióngetHeadings()
. -
file
yurl
también están disponibles como propiedades anidadas defrontmatter
(es decir,frontmatter.url
yfrontmatter.file
).
Importando Plantillas Manualmente (MDX)
Sección titulada Importando Plantillas Manualmente (MDX)También puedes utilizar la propiedad especial Markdown layout en el frontmatter de los archivos MDX para pasar los props frontmatter
y headings
directamente a un componente layout especificado del mismo modo.
Para pasar información a tu plantilla MDX que no existe (o no puede existir) en su frontmatter, puede importar y utilizar un componente <Layout />
. Funciona como cualquier otro componente de Astro, y no recibirá ningún prop automáticamente. Pásale directamente los accesorios que necesites:
---layout: ../../layouts/BaseLayout.astrotitle: 'Mi primer post MDX'publishDate: '21 de Septiembre de 2022'---import BaseLayout from '../../layouts/BaseLayout.astro';
export function fancyJsHelper() { return "¡Intenta hacer eso con YAML!";}
<BaseLayout title={frontmatter.title} fancyJsHelper={fancyJsHelper}> Bienvenido a mi nuevo blog de Astro, ¡usando MDX!</BaseLayout>
Luego, tus valores estarán disponibles para ti a través de Astro.props
en tu plantilla, y tu contenido MDX se inyectará en la página donde se escriba tu componente <slot />
:
---// src/layouts/BaseLayout.astroconst { title, fancyJsHelper } = Astro.props;---<html> <head> <!-- --> <meta charset="utf-8"> </head> <body> <!-- --> <h1>{title}</h1> <slot /> <!-- tu contenido es inyectado aquí --> <p>{fancyJsHelper()}</p> <!-- --> </body> </html>
Cuando uses cualquier plantilla (ya sea a través de la propiedad layout
del frontmatter o importando una plantilla), debes incluir la etiqueta <meta charset="utf-8">
en tu plantilla ya que Astro ya no lo añadirá automáticamente a tu página MDX.
Plantillas anidadas
Sección titulada Plantillas anidadasLos componentes de plantilla no necesitan contener una página completa de HTML. Puedes dividir tus plantillas en componentes más pequeños y luego combinar estos componentes para crear plantillas aún más flexibles, como una plantilla de página. Este patrón es útil cuando deseas compartir cierto código entre múltiples plantillas.
Por ejemplo, un componente de plantilla BlogPostLayout.astro
podría dar estilo a un título, fecha y autor de un post. Luego, una plantilla BaseLayout.astro
podría manejar el resto de tu plantilla de página, como navegación, pies de página, etiquetas meta de SEO, estilos globales y fuentes. También puedes pasar propiedades recibidas de tu post a otra plantilla, como cualquier otro componente anidado.
---import BaseLayout from './BaseLayout.astro';const { frontmatter } = Astro.props;---<BaseLayout url={frontmatter.url}> <h1>{frontmatter.title}</h1> <h2>Autor del artículo: {frontmatter.author}</h2> <slot /></BaseLayout>