Pular para o conteúdo principal

Introdução

Recupere menus de navegação de site em múltiplos níveis construídos a partir de páginas configuradas no OneEntry.

Mais informações sobre a interface do usuário do módulo https://doc.oneentry.cloud/docs/category/menu

🎯 O que este módulo faz?​

O módulo Menus permite que você recupere estruturas de navegação do site - menus de cabeçalho, menus de rodapé, navegação de barra lateral, menus móveis - construindo dinamicamente navegação em múltiplos níveis a partir de páginas configuradas no OneEntry.

Você cria menus no painel de administração do OneEntry (ligando páginas entre si) e este módulo busca a árvore completa do menu, para que você possa renderizar a navegação dinamicamente sem codificar links. O SDK é somente leitura para menus - você os recupera, não os cria via código.

🚀 Início Rápido​

Inicialize o módulo a partir de defineOneEntry:


const { Menus } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Recupere um menu pelo seu marcador e percorra suas páginas:

// Fetch the "main_menu" structure in English.
const menu = await Menus.getMenusByMarker("main_menu", "en_US");

console.log(menu.identifier, menu.localizeInfos.title);

// Top-level items; nested items live in each item's children[].
menu.pages.forEach((item) => {
  console.log(item.pageUrl, item.localizeInfos.title, item.children);
});

✨ Conceitos Chave​

O que é um Menu?​

Um Menu (IMenusEntity) é uma estrutura de navegação que liga páginas entre si:

  • identifier - o marcador do menu (ex: "main_menu")
  • localizeInfos - o título do menu localizado
  • pages - o array de itens do menu (cada item é uma página)

Estrutura do Item do Menu​

Cada item em pages é um objeto IMenusPages:

{
  id: 123,                       // Page ID
  pageUrl: "home",               // Page URL (marker)
  localizeInfos: { title: "Home" },
  attributeValues: {},           // Custom attribute values
  parentId: null,                // null for top-level items
  position: 1,                   // Display order
  children: []                   // Nested menu items
}

Hierarquia do Menu​

Menus suportam estruturas aninhadas. O aninhamento é expresso através do array children[] de cada item junto com seu parentId (itens de nível superior têm parentId: null). Não há um campo de profundidade separado - você determina a profundidade percorrendo children[].

📂 Header Menu
├─ Home (parentId: null)
├─ About (parentId: null)
│  ├─ Team (parentId: 2)
│  └─ History (parentId: 2)
├─ Products (parentId: null)
│  └─ Electronics (parentId: 4)
│     ├─ Phones (parentId: 5)
│     └─ Laptops (parentId: 5)
└─ Contact (parentId: null)

📋 O que Você Precisa Saber​

Você não pode criar menus via SDK - eles são criados no painel de administração do OneEntry (Menus → Criar Menu → Adicionar Páginas → Salvar) ou via Admin API. O SDK é para recuperar estruturas de menu.

Itens de menu são páginas​

Cada item de menu é uma página configurada no OneEntry - você não pode adicionar links arbitrários. Para adicionar um link externo, crie uma página com uma URL externa no Módulo de Páginas e adicione-a ao menu.

Ordenar por posição​

Os itens possuem um campo position - ordene por ele para respeitar a ordem de exibição configurada no painel de administração.

Multi-idioma​

Menus são localizados pelo langCode passado para getMenusByMarker() (revertendo para o idioma definido em defineOneEntry()). Recupere menus no idioma preferido do usuário.

📊 Tabela de Referência Rápida​

MétodoDescriçãoCaso de Uso
getMenusByMarker()Obter menu por marcadorRecuperar uma estrutura de menu específica

❓ Perguntas Comuns (FAQ)​

Como eu crio um menu de múltiplos níveis (dropdown)?​

Construa a árvore do menu no painel de administração aninhando páginas. O aninhamento é retornado através do array children[] de cada item - renderize-o recursivamente.

Os itens de menu devem ser páginas configuradas no OneEntry. Para adicionar um link externo, crie uma página com uma URL externa no Módulo de Páginas, e então adicione-a ao seu menu.

Como eu lido com o estado do item de menu ativo?​

Compare a URL da página atual com o pageUrl de cada item e aplique uma classe ativa quando elas coincidirem.

Como eu construo breadcrumbs?​

Rastreie a partir da página atual através das relações de parentId (Início > Categoria > Subcategoria > Página Atual).

Posso ter menus diferentes para seções diferentes?​

Sim - crie múltiplos menus com marcadores diferentes (ex: header_menu, footer_menu, sidebar_menu) e recupere cada um com getMenusByMarker().

🎓 Melhores Práticas​

  • Use marcadores, não IDs - marcadores são estáveis entre ambientes.
  • Renderize children[] recursivamente - é assim que o aninhamento é representado.
  • Ordene por position - respeite a ordem de exibição configurada.
  • Cache os menus - eles raramente mudam.
  • Passe langCode - recupere o menu no idioma do usuário.
  • Lide com menus ausentes de forma elegante - forneça uma alternativa quando o marcador não for encontrado.

🔗 Documentação Relacionada​