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 uma 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 busca, 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 (por exemplo, "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
  parentType: null,              // "page" | "custom" | null - kind of the parent
  itemType: "page",              // "page" | "custom" - kind of this item
  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 ao percorrer 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)

Dois tipos de item de menu: itemType e parentType​

Um menu contém dois tipos de item - páginas de menu e itens personalizados - e seus ids vêm de sequências diferentes, então eles se sobrepõem: parentId: 5 sozinho não diz se o pai é a página com id 5 ou o item personalizado com id 5.

Dois campos resolvem isso:

  • itemType ('page' | 'custom') - o que este item é.
  • parentType ('page' | 'custom' | null) - o que seu pai é. null junto com parentId: null significa que o item é de nível superior.

Os filhos de um item carregam seu itemType como seu parentType, então combine o par quando você reconstruir a árvore você mesmo:

const childrenOf = (items, parent) =>
  items.filter(
    (item) => item.parentId === parent.id && item.parentType === parent.itemType,
  );

📋 O Que Você Precisa Saber​

Você não pode criar menus via o SDK - eles são criados no painel de administração do OneEntry (Menus → Criar Menu → Adicionar Páginas → Salvar) ou via a API de Administração. O SDK é para buscar 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 carregam 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()). Busque menus no idioma preferido do usuário.

📊 Tabela de Referência Rápida​

MétodoDescriçãoCaso de Uso
getMenusByMarker()Obter menu por marcadorBuscar 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 (por exemplo, header_menu, footer_menu, sidebar_menu) e busque 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 - busque 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​