Menus de Navegação

Os menus permitem que editores gerenciem links ordenados sem alterar um template do site. Um menu tem um nome estável, como primary ou footer, e um conjunto separado de itens para cada menu traduzido.

Criar um menu

Crie e organize menus em Menus no admin do EmDash.

Use o mesmo nome de menu em cada idioma. Em um site multilíngue, abra um menu e use seu painel Translations para criar e editar as versões em outros idiomas. Cada versão de idioma tem seu próprio rótulo, portanto renomear um menu altera apenas a versão que você está editando. O EmDash mantém as traduções do mesmo conteúdo ou termo de taxonomia conectadas, para que getMenu() possa usar o rótulo e o slug para o idioma solicitado.

Como os links do menu são resolvidos

Itens de menu de conteúdo e taxonomia armazenam uma referência em vez de uma URL completa. Quando um template chama getMenu(), o EmDash resolve essa referência usando os dados da coleção e do idioma atuais.

getMenu() omite um item de conteúdo quando nenhuma das traduções da sua entrada está publicada, por exemplo porque a entrada foi excluída, está na lixeira ou ainda é um rascunho. Uma tradução na lixeira ou ainda não publicada conta como ausente, então o item recorre a outra tradução. Quando um item é omitido, seus itens filhos são omitidos junto com ele. No modo de edição, os itens que apontam para entradas não publicadas permanecem no menu.

Cada item retornado também contém seu rótulo, destino opcional, atributo title, classes CSS e children aninhados. O exemplo de renderização abaixo usa esses valores diretamente.

Renderizar um menu

Chame getMenu() em um componente Astro renderizado no servidor. Ele retorna null quando o nome não existe.

O seguinte layout renderiza um menu principal e um nível de itens aninhados:

---
import { getMenu } from "emdash";
import { getRelativeLocaleUrl } from "astro:i18n";

const locale = Astro.currentLocale;
const menu = await getMenu("primary", { locale });

function menuHref(url: string) {
  return locale && url.startsWith("/")
    ? getRelativeLocaleUrl(locale, url)
    : url;
}
---

{menu && menu.items.length > 0 && (
  <nav aria-label="Navegação principal">
    <ul>
      {menu.items.map((item) => {
        const href = menuHref(item.url);

        return (
          <li class:list={item.cssClasses}>
            <a
              href={href}
              target={item.target}
              rel={item.target === "_blank" ? "noopener noreferrer" : undefined}
              title={item.titleAttr}
              aria-current={Astro.url.pathname === href ? "page" : undefined}
            >
              {item.label}
            </a>

            {item.children.length > 0 && (
              <ul>
                {item.children.map((child) => {
                  const childHref = menuHref(child.url);

                  return (
                    <li class:list={child.cssClasses}>
                      <a
                        href={childHref}
                        target={child.target}
                        rel={child.target === "_blank" ? "noopener noreferrer" : undefined}
                        title={child.titleAttr}
                        aria-current={Astro.url.pathname === childHref ? "page" : undefined}
                      >
                        {child.label}
                      </a>
                    </li>
                  );
                })}
              </ul>
            )}
          </li>
        );
      })}
    </ul>
  </nav>
)}

getMenu() escolhe primeiro o locale explícito, depois o idioma da requisição atual e então o idioma padrão configurado. Se um menu ou entrada referenciada estiver ausente nesse idioma, a busca segue a cadeia de fallback configurada.

As URLs dos itens do menu contêm o padrão de URL da coleção ou o caminho de taxonomia, mas não contêm o prefixo de idioma do Astro. O helper menuHref() adiciona esse prefixo aos links relativos à raiz e deixa os links externos inalterados.

O exemplo renderiza um nível filho, o que cobre um dropdown típico. Se os editores podem criar navegação mais profunda, mova a marcação do item para um componente recursivo que renderize os children de cada item com as mesmas regras.

Usar menus em áreas de widgets

Um widget de menu coloca um menu existente dentro de uma área de widgets. O widget lê o menu para o idioma da requisição atual. Use o padrão de renderização direta acima quando o site precisar de marcação aninhada personalizada ou tratamento explícito de URLs por idioma.

Consultar dados do menu diretamente

Use getMenus() quando um template precisar das definições de menu disponíveis em vez dos itens de um menu. A referência da API em tempo de execução documenta as assinaturas de consulta e os valores de retorno.

Para alterações programáticas em menus, autentique-se com um token Bearer e adicione X-EmDash-Request: 1 a cada requisição que altere o estado. Veja os endpoints de menu para corpos de requisição e respostas.

Veja Internacionalização para configuração de roteamento por idioma e fallback.