wp bootstrap navwalker

WP Bootstrap 导航器

主仓库分支中的这段代码正在经历一次大的调整，以使其符合最新的标准，并合并和测试我积压已久的 PR。在此过程发生时，请使用 v4.3.0 标签以获得稳定版本。 https://github.com/wp-bootstrap/wp-bootstrap-navwalker/releases/tag/v4.3.0

自定义 WordPress Nav Walker 类，使用 WordPress 内置菜单管理器在自定义主题中完全实现 Bootstrap 4 导航样式。

笔记

这是一个实用程序类，旨在使用正确的语法和 CSS 类来格式化您的 WordPress 主题菜单，以利用 Bootstrap 下拉导航。它不包含所需的 Bootstrap JS 和 CSS 文件 - 您必须手动包含它们。

WordPress.org 主题合规性

该步行器完全符合 wordpress.org 主题提交的所有主题审查指南。它不需要修改即可兼容，但您可以选择将wp-bootstrap-navwalker文本域（在fallback函数中出现两次）替换为主题的文本域。

升级注意事项

walker 的版本 3 和版本 4 之间的代码库发生了重大变化。 walker 的版本 4 是为与 Bootstrap 4 配合使用而构建的，尚未测试与 Bootstrap 3 的向后兼容性。此处维护 Bootstrap 3 的单独分支：https://github.com/wp-bootstrap/wp-bootstrap- navwalker/树/v3-分支

以下是最显着变化的列表：

• 文件名已更改并以class-为前缀，以更好地符合 PHP 编码标准命名约定。
  • 新名称： class-wp-bootstrap-navwalker.php
  • 旧名称： wp-bootstrap-navwalker.php
• 图标和链接修饰符处理现在通过CSS Classes菜单项输入而不是Title输入完成。
• 仅图标项目可以使用图标类与sr-only类名相结合。

安装

将class-wp-bootstrap-navwalker.php放入 WordPress 主题文件夹/wp-content/themes/your-theme/

打开 WordPress 主题functions.php文件 - /wp-content/themes/your-theme/functions.php - 并添加以下代码：

 /**
 * Register Custom Navigation Walker
 */
function register_navwalker (){
	require_once get_template_directory () . ' /class-wp-bootstrap-navwalker.php ' ;
}
add_action ( ' after_setup_theme ' , ' register_navwalker ' );

如果您在上述代码中遇到错误，请使用这样的检查来返回干净的错误，以帮助诊断问题。

 if ( ! file_exists ( get_template_directory () . ' /class-wp-bootstrap-navwalker.php ' ) ) {
    // File does not exist... return an error.
    return new WP_Error ( ' class-wp-bootstrap-navwalker-missing ' , __ ( ' It appears the class-wp-bootstrap-navwalker.php file may be missing. ' , ' wp-bootstrap-navwalker ' ) );
} else {
    // File exists... require it.
    require_once get_template_directory () . ' /class-wp-bootstrap-navwalker.php ' ;
}

如果您的functions.php文件尚不存在，您还需要声明一个新菜单。

 register_nav_menus ( array (
    ' primary ' => __ ( ' Primary Menu ' , ' THEMENAME ' ),
) );

用法

添加或更新主题中的任何wp_nav_menu()函数（通常在header.php中找到），以通过向 wp_nav_menu args 数组添加'walker'项来使用新的 walker。

 wp_nav_menu ( array (
    ' theme_location '  => ' primary ' ,
    ' depth '           => 2 , // 1 = no dropdowns, 2 = with dropdowns.
    ' container '       => ' div ' ,
    ' container_class ' => ' collapse navbar-collapse ' ,
    ' container_id '    => ' bs-example-navbar-collapse-1 ' ,
    ' menu_class '      => ' navbar-nav mr-auto ' ,
    ' fallback_cb '     => ' WP_Bootstrap_Navwalker::fallback ' ,
    ' walker '          => new WP_Bootstrap_Navwalker (),
) );

您的菜单现在将使用正确的语法和类进行格式化，以实现 Bootstrap 下拉导航。

通常，菜单会用附加标记进行包装，下面是一个fixed-top菜单的示例，该菜单会在 md 断点处折叠以进行响应式导航。

<nav class="navbar navbar-expand-md navbar-light bg-light" role="navigation">
  <div class="container">
    <!-- Brand and toggle get grouped for better mobile display -->
    <button class="navbar-toggler" type="button" data-toggle="collapse" data-target=" #bs - example - navbar - collapse - 1 " aria-controls= " bs - example - navbar - collapse - 1 " aria-expanded= " false " aria-label= " <? php esc_attr_e ( 'Toggle navigation' , 'your - theme - slug' ) ; ?> ">
        <span class="navbar-toggler-icon"></span>
    </button>
    <a class="navbar-brand" href="#">Navbar</a>
        <?php
        wp_nav_menu ( array (
            ' theme_location '    => ' primary ' ,
            ' depth '             => 2 ,
            ' container '         => ' div ' ,
            ' container_class '   => ' collapse navbar-collapse ' ,
            ' container_id '      => ' bs-example-navbar-collapse-1 ' ,
            ' menu_class '        => ' nav navbar-nav ' ,
            ' fallback_cb '       => ' WP_Bootstrap_Navwalker::fallback ' ,
            ' walker '            => new WP_Bootstrap_Navwalker (),
        ) );
        ?>
    </div>
</nav>

要更改菜单样式，请将 Bootstrap 导航类名称添加到menu_class声明中。

查看 Bootstrap 文档中的选项以获取有关导航类的更多信息。

显示菜单

要显示菜单，您必须将菜单与主题位置相关联。您可以通过在 WordPress 菜单管理器中编辑菜单时在主题位置列表中选择主题位置来完成此操作。

使此 Walker 成为导航菜单的默认 Walker

有人有兴趣让这个助行器成为所有菜单的默认助行器。这可能会导致一些意外情况，但可以通过将此函数添加到您的functions.php 文件中来实现。

 function prefix_modify_nav_menu_args ( $ args ) {
    return array_merge ( $ args , array (
        ' walker ' => new WP_Bootstrap_Navwalker (),
    ) );
}
add_filter ( ' wp_nav_menu_args ' , ' prefix_modify_nav_menu_args ' );

简单地更新 walker 可能不足以让菜单正常工作，您可能需要添加包装器或其他类，您也可以通过上述函数来做到这一点。

与 Bootstrap 5 一起使用

Bootstrap 5 使用命名空间数据属性。所有data属性现在都包含bs作为中缀。新属性的工作方式与旧属性一样。这是上面示例中的菜单切换按钮，其中包含重命名的数据属性。

<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target=" #bs - example - navbar - collapse - 1 " aria-controls= " bs - example - navbar - collapse - 1 " aria-expanded= " false " aria-label= " <? php esc_attr_e ( 'Toggle navigation' , 'your - theme - slug' ) ; ?> ">
    <span class="navbar-toggler-icon"></span>
</button>

walker 还通过start_el()方法添加用于下拉切换的数据属性。将其粘贴到您的functions.php中以使walker使用固定数据属性。

 add_filter ( ' nav_menu_link_attributes ' , ' prefix_bs5_dropdown_data_attribute ' , 20 , 3 );
/**
 * Use namespaced data attribute for Bootstrap's dropdown toggles.
 *
 * @param array    $atts HTML attributes applied to the item's `<a>` element.
 * @param WP_Post  $item The current menu item.
 * @param stdClass $args An object of wp_nav_menu() arguments.
 * @return array
 */
function prefix_bs5_dropdown_data_attribute ( $ atts , $ item , $ args ) {
    if ( is_a ( $ args -> walker , ' WP_Bootstrap_Navwalker ' ) ) {
        if ( array_key_exists ( ' data-toggle ' , $ atts ) ) {
            unset( $ atts [ ' data-toggle ' ] );
            $ atts [ ' data-bs-toggle ' ] = ' dropdown ' ;
        }
    }
    return $ atts ;
}

菜单缓存

在某些网站上，生成一个大菜单，而该菜单很少在每个页面请求上发生变化，这是您可能希望避免的开销。在这些情况下，我建议您考虑将菜单结果存储在瞬态中。

使用此方法缓存导航菜单的最大缺点是，它无法轻松地将.current-menu-item或.active类应用于当前活动项目，因为 WP 决定页面加载时当前活动的内容 - 并且由于菜单已缓存它只知道最初缓存它的活动页面。

您可以自行决定是否要忍受这些缺点，以消除大多数页面加载时的菜单生成时间。您可以关注 Dave Clements 的这篇文章，了解我们如何缓存此步行器生成的导航菜单：https://www.doitwithwp.com/use-transients-speed-wordpress-menus/

执行此操作时，请务必在the wp_nav_menu()调用中将echo参数设置为 FALSE，以便可以存储结果而不是回显到页面。

参见：

• https://generatewp.com/how-to-use-transients-to-speed-up-wordpress-menus/
• https://vip-svn.wordpress.com/plugins/cache-nav-menu/cache-nav-menu.php

附加功能

该脚本包括通过 WordPress 菜单 UI 在菜单中使用 Bootstrap 导航链接模块的功能。支持禁用链接、下拉标题和下拉分隔线。此外，Glyphicons 和 Font Awesome 内置了图标支持（注意：您需要单独包含图标样式表或资源）。

图标

要将图标添加到链接，只需在菜单 UI 的链接CSS 类字段中输入 Glyphicons 或 Font Awesome 类名称，walker 类将完成剩下的工作。 IE glyphicons glyphicons-bullhorn或fa fa-arrow-left或fas fa-arrow-left 。

仅图标项目

要使项目与图标一起显示，只需将引导屏幕阅读器类sr-only应用于该项目以及任何图标类名。这将仅隐藏显示为链接文本的文本。

禁用链接

要设置禁用链接，只需将disabled添加到菜单 UI 中的CSS 类字段，walker 类将完成剩下的工作。注意：除了添加 .disabled 类之外，这还会将链接href更改为# ，以便它不是可跟踪的链接。

下拉标题、下拉分隔线和下拉项目文本

通过添加自定义链接并将dropdown-header 、 dropdown-divider或dropdown-item-text添加到CSS 类输入中，可以在下拉列表中添加标题、分隔线和纯文本项目。注意：这将删除项目上的href并将其更改为用于标题的<span>或用于分隔符的<div> 。

定制器预览中缺少编辑快捷方式

根据wp_nav_menu()的文档，必须提供自定义 walker 类的实例才能将自定义 walker 应用于菜单。由于实例不可 JSON 序列化，这将导致菜单编辑快捷方式不会出现在定制器预览中。要解决此问题，请执行以下操作：

1. 提供类名字符串而不是类实例作为 wp_nav_menu 参数数组中“walker”键的值，

wp_nav_menu( array(
    'theme_location'  => 'primary',
    'depth'           => 2, // 1 = no dropdowns, 2 = with dropdowns.
    'container'       => 'div',
    'container_class' => 'collapse navbar-collapse',
    'container_id'    => 'bs-example-navbar-collapse-1',
    'menu_class'      => 'navbar-nav mr-auto',
    'fallback_cb'     => 'WP_Bootstrap_Navwalker::fallback',
-    'walker'          => new WP_Bootstrap_Navwalker(),
+    'walker'          => 'WP_Bootstrap_Navwalker',
) );

2. 通过将此过滤器添加到您的functions.php来重新添加类实例

 function slug_provide_walker_instance ( $ args ) {
    if ( isset ( $ args [ ' walker ' ] ) && is_string ( $ args [ ' walker ' ] ) && class_exists ( $ args [ ' walker ' ] ) ) {
        $ args [ ' walker ' ] = new $ args [ ' walker ' ];
    }
    return $ args ;
}
add_filter ( ' wp_nav_menu_args ' , ' slug_provide_walker_instance ' , 1001 );

变更日志

请参阅变更日志。