云策 WordPress 开发者社区

钩子文档

navigation_markup_template

查看官方原文 ↗
💡 云策文档标注

概述

navigation_markup_template 是一个 WordPress 过滤器，用于自定义导航标记模板的 HTML 输出。它允许开发者修改导航链接的包装结构，以满足特定样式或功能需求。

关键要点

  • 过滤器名称：navigation_markup_template，用于过滤导航标记模板的 HTML 字符串。
  • 参数：接受两个参数，$template（默认模板字符串）和 $css_class（调用函数传递的 CSS 类名）。
  • 模板要求：过滤后的模板必须包含占位符 %1$s（导航类）、%2$s（屏幕阅读器文本）、%3$s（导航链接位置）和 %4$s（ARIA 标签文本）。
  • 应用场景：常用于子主题开发中，调整导航样式以匹配父主题或插件（如 WooCommerce）的样式。

代码示例

function wpdocs_pagination_output( $template, $class ) {
    $template = '
    <nav class="navigation %1$s" role="navigation" aria-label="%4$s">
        <div class="screen-reader-text">%2$s</div>
        <div class="nav-links">%3$s</div>
    </nav>';
    return $template;
}
add_filter( 'navigation_markup_template', 'wpdocs_pagination_output', 99, 2 );

注意事项

  • 过滤器优先级：可以使用高优先级（如 99）确保自定义模板最后执行，覆盖其他修改。
  • 样式匹配：在子主题中，需检查父主题的 CSS 规则，可能需要添加特定类（如 .woocommerce）或移除容器（如 .nav-links）以实现样式一致。
📄 原文内容

Filters the navigation markup template.

Description

Note: The filtered template HTML must contain specifiers for the navigation class (%1$s), the screen-reader-text value (%2$s), placement of the navigation links (%3$s), and ARIA label text if screen-reader-text does not fit that (%4$s):

<nav class="navigation %1$s" aria-label="%4$s">
    <h2 class="screen-reader-text">%2$s</h2>
    <div class="nav-links">%3$s</div>
</nav>

Parameters

$templatestring
The default template.
$css_classstring
The class passed by the calling function.

Source

$template = apply_filters( 'navigation_markup_template', $template, $css_class );

View all references View on Trac View on GitHub

Used by Description
_navigation_markup()wp-includes/link-template.php

Wraps passed links in navigational markup.

Changelog

Version Description
4.4.0 Introduced.

User Contributed Notes

  1. Skip to note 2 content


    luboslives


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    When creating a child theme, if your parent theme includes styles for WooCommerce navigation which you prefer, here’s a simple way to match the look and markup of the nav on non-WooCommerce pages, so you don’t have to rewrite the styles for it.

    In your template files, update the_posts_pagination() (or replace your parent theme’s custom pagination function) to match the default settings found inside WooCommerce. For example, inside search.php:

    the_posts_pagination(
	array(
		// match WooCommerce settings
		'prev_text' => '←',
		'next_text' => '→',
		'type'      => 'list',
		'end_size'  => 3,
		'mid_size'  => 3,
	)
);

    In your functions.php file, update the HTML output of the navigation using the navigation_markup_template filter.

    Check your parent theme’s style rules to see how specific they get. In my case, my parent theme specifies .woocommerce nav.woocommerce-pagination ul, so I will need to add a container with the .woocommerce class and add the .woocommerce-pagination class to our nav element. I also need to remove the .nav-links container so some other style rules match:

    function wpdocs_pagination_output( $template, $class ) {
	
	$template = '
	<div class="woocommerce">
		<nav class="woocommerce-pagination navigation %1$s" role="navigation" aria-label="%4$s">
			<h2 class="screen-reader-text">%2$s</h2>
			%3$s
		</nav>
	</div>';

	return $template;
}
add_filter( 'navigation_markup_template', 'wpdocs_pagination_output', 99, 2 );

    Note: 99 is the arbitrary priority I’ve assigned to the filter. Use a high number to run your filter last.