wp-bootstrap/wp-bootstrap-navwalker

一个自定义的WordPress导航遍历类，用于在自定义主题中完全实现Bootstrap 4导航样式，同时使用WordPress内置菜单管理器。

维护者

详细信息

github.com/wp-bootstrap/wp-bootstrap-navwalker

来源

问题

安装: 36,233

依赖者: 0

建议者: 0

安全: 0

星级: 3,366

观察者: 212

分支: 1,943

开放问题: 35

v4.3.0 2019-10-02 18:15 UTC

Requires

Requires (Dev)

GPL-3.0+ 5d39044bcee8703d1402f7371b033c460b2e0a71

  • Brandon Hubbard
  • William Patton <will.woop@pattonwebz.com>

This package is not auto-updated.

Last update: 2024-09-14 19:42:26 UTC

README

Code Climate Test Coverage Issue Count Build Status Scrutinizer Code Quality Code Coverage Build Status

此代码库主分支正在进行大规模重构，以使其符合最新标准，并合并和测试我留下的长期悬而未决的PR。在此过程中，请使用v4.3.0标签进行稳定版本。请参阅https://github.com/wp-bootstrap/wp-bootstrap-navwalker/releases/tag/v4.3.0

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

说明

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

WordPress.org主题兼容性

此遍历器完全符合所有wordpress.org主题提交的主题审查指南。 它无需修改即可兼容，但您可以可选地用您的主题文本域替换 wp-bootstrap-navwalker 文本域（在 fallback 函数中出现两次）。

升级说明

遍历器从版本3到版本4的代码库发生了重大变化。遍历器的版本4旨在与Bootstrap 4一起使用，并且未对Bootstrap 3的向后兼容性进行测试。Bootstrap 3的单独分支在此维护：https://github.com/wp-bootstrap/wp-bootstrap-navwalker/tree/v3-branch

以下是最大变化的列表

  • 文件名已更改，并使用 class- 前缀，以更好地符合PHP编码标准的命名约定。
    • 新名称：class-wp-bootstrap-navwalker.php
    • 旧名称：wp-bootstrap-navwalker.php
  • 图标和链接修饰符处理现在是通过 CSS 类 菜单项输入而不是通过 标题 输入来完成的。
  • 可以使用图标类和 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 中找到）添加一个 'walker' 项到 wp_nav_menu 参数数组中，以使用新的遍历器。

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下拉导航。

通常菜单会包含额外的标记，以下是一个示例，该示例在md断点时折叠为响应式导航的 fixed-top 菜单。

<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>

要更改您的菜单样式，请向 menu_class 声明中添加Bootstrap导航类名。

请参阅Bootstrap文档中的导航类选项，以获取更多有关nav类的信息。

显示菜单

要显示菜单，您必须将菜单与您的主题位置关联。您可以在WordPress菜单管理器中编辑菜单时，在“主题位置”列表中选择您的主题位置来做到这一点。

将此Walker设置为导航菜单的默认Walker

有人对将此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;
}

菜单缓存

在某些网站上，生成大型菜单并且很少改变，在每次页面请求中都可能会造成一些不必要的开销。在这些情况下，我可以建议您考虑将菜单结果存储在transient中。

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

您可以选择是否愿意承受这些缺点以换取从大多数页面加载中移除菜单生成时间的好处。您可以参考Dave Clements的这篇文章，了解我们如何使用此walker生成并缓存导航菜单：[https://www.doitwithwp.com/use-transients-speed-wordpress-menus/](https://www.doitwithwp.com/use-transients-speed-wordpress-menus/)

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

另请参阅

附加功能

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

图标

要将图标添加到链接中，只需在菜单UI中的链接CSS Classes字段中输入Glyphicons或Font Awesome类名即可。walker类将完成其余工作。例如：glyphicons glyphicons-bullhorn或fa fa-arrow-left或fas fa-arrow-left。

仅图标项

要使项仅显示图标，请将bootstrap屏幕阅读器类sr-only应用于项和任何图标类名。这将仅隐藏作为链接文本出现的文本。

禁用链接

要设置禁用链接，请简单地在菜单UI中的CSS Classes字段中添加disabled。walker类将完成其余工作。注意：除了添加禁用类之外，这还会将链接href更改为#=，这样它就不是一个可访问的链接。

下拉标题、下拉分隔符和下拉项文本

可以在下拉菜单中添加标题、分隔符和纯文本项，方法是在“自定义链接”中添加，并在“CSS 类”输入框中添加 dropdown-header、dropdown-divider 或 dropdown-item-text。 注意：这将移除项目的 href 并将其更改为标题的 <span> 或分隔符的 <div>。

自定义预览中缺少编辑快捷键

根据 wp_nav_menu() 的文档，需要提供一个自定义遍历器类的实例，以便将自定义遍历器应用于菜单。由于实例不是 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',
) );
  1. 通过向你的 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 );

变更日志

请参阅 变更日志。