WordPress 選單註冊 register_nav_menus() 與調用 wp_nav_menu() 完整指南

前言

WordPress 3.0+ 引入選單系統，讓使用者可在後台拖曳建立導航選單。開發者需先在主題 functions.php 註冊選單位置，再在模板中呼叫輸出。本文完整解析 register_nav_menus() 與 wp_nav_menu() 的參數、範例與進階技巧。

register_nav_menus() — 註冊選單位置

函數原型

register_nav_menus( array $locations )

參數說明

• $locations：關聯陣列，Key 為選單識別碼，Value 為顯示名稱（支援多國語系 __()）

基本範例

function my_theme_register_menus() {
    register_nav_menus(array(
        'header_menu' => __('頂部導航', 'my-theme'),
        'footer_menu' => __('頁腳導航', 'my-theme'),
        'social_menu' => __('社群連結', 'my-theme'),
    ));
}
add_action('init', 'my_theme_register_menus');

註冊後，後台「外觀 → 選單」即可建立選單並指派至上述位置。

wp_nav_menu() — 前端輸出選單

函數原型

wp_nav_menu( array $args = array() )

預設參數完整表

常用範例

基本輸出（無容器、自訂 ul id、自訂 fallback）

wp_nav_menu(array(
    'theme_location' => 'header_menu',
    'container'      => false,
    'items_wrap'     => '
%3$s
',
    'fallback_cb'    => 'my_fallback_menu',
));

function my_fallback_menu() {
    echo '
首頁
';
}

輸出為 <nav> 容器、加入 BEM 命名

wp_nav_menu(array(
    'theme_location' => 'header_menu',
    'container'      => 'nav',
    'container_class' => 'site-nav',
    'menu_class'     => 'site-nav__list',
    'menu_id'        => 'site-nav-list',
    'depth'          => 2, // 僅顯示兩層
));

取得選單 HTML 字串供進一步處理

$menuHtml = wp_nav_menu(array(
    'theme_location' => 'footer_menu',
    'echo'           => false,
    'container'      => false,
));
// 可對 $menuHtml 進行字串替換、快取等操作
echo $menuHtml;

進階技巧

1. 動態新增 CSS 類別（如 active 狀態）

add_filter('nav_menu_css_class', function($classes, $item, $args, $depth) {
    if (in_array('current-menu-item', $classes) || in_array('current-menu-ancestor', $classes)) {
        $classes[] = 'is-active';
    }
    return $classes;
}, 10, 4);

2. 自訂 Walker 實現特殊結構（如 Mega Menu）

class My_Walker extends Walker_Nav_Menu {
    function start_lvl(&$output, $depth = 0, $args = []) {
        $indent = str_repeat("\t", $depth);
        $output .= "\n$indent
\n";
    }
}
// 使用
wp_nav_menu(array('walker' => new My_Walker()));

3. 選單項目加入圖示（利用 link_before/link_after 或 Walker）

add_filter('walker_nav_menu_start_el', function($item_output, $item, $depth, $args) {
    if ($item->attr_title) { // 在後台選單項目「標題屬性」填入圖示 class
        $item_output = str_replace(' ', $item_output);
    }
    return $item_output;
}, 10, 4);

常見問題 FAQ

小結

register_nav_menus() 定義「位置」，wp_nav_menu() 輸出「內容」。掌握參數陣列與 Filter/Hook，即可實現從簡單導航到複雜 Mega Menu 的彈性客製化。