README

每次我构建一个新的Laravel应用程序时，我都会发现自己正在重复使用那些我多年来一直在完善的自定义导航助手。这些工具允许您根据当前页面准确地简洁地更改导航元素的类。这样的工具可以让您的导航自我管理，加快开发进度，同时保持长期生产使用的效率。

安装

安装简单，设置类似于其他Laravel包。

1. 通过Composer安装

首先通过Composer引入包

composer require devmarketer/easynav

2. 定义服务提供者和别名

接下来我们需要引入别名和服务提供者。

注意：此包支持Laravel 5.5的新自动发现功能，因此如果您正在使用Laravel 5.5项目，则安装已完成，您可以直接跳到步骤3。

如果您正在使用Laravel 5.0 - 5.4，则需要添加提供者和别名。在您的config/app.php文件中定义一个新的服务提供者

'providers' => [
	//  other providers

	DevMarketer\EasyNav\EasyNavServiceProvider::class,
];

然后我们希望在相同的config/app.php文件中定义一个别名。

'aliases' => [
	// other aliases

	'Nav' => DevMarketer\EasyNav\EasyNavFacade::class,
];

3. 发布配置文件（可选）

配置文件允许您覆盖此包的默认设置以满足您的特定需求。它是可选的，并允许您设置一个默认的激活类名，以输出到激活的导航元素。您可以在每个函数中覆盖此值，但设置默认值可以使您的代码更简洁。默认为"active"，这是许多开发者常用的类名，并且支持Bootstrap。如果您正在使用像Bulma这样的框架，则希望将此值更改为"is-active"。许多CSS框架可能需要"--active"。设置一次即可。

要在终端生成配置文件，请输入以下命令

php artisan vendor:publish --tag=easynav

这将在config/easynav.php中生成一个配置文件。

用法

此包易于使用。它提供了一些有用的函数用于导航。将这些方法视为定义导航元素规则的“工具”。一旦为该导航元素设置了“规则”，您就不必担心它。如果用户根据规则访问该页面，则它将输出您定义的CSS类（通常类似于"active"或"is-active"），并将其显示在HTML元素上，从而在导航上显示激活状态。

[重要] 此包不做什么

此包不生成导航的HTML。它只是根据您定义的规则将“激活”CSS类添加到您的HTML元素中。您可以在CSS中自定义激活菜单/导航链接的样式。

导航规则如何工作

对于每个导航元素，您需要在HTML元素的class=" "字段中添加以下“规则”之一。您仍然负责在CSS中设置元素的样式。许多CSS框架已经为您做了这件事。

示例

Current Url - https://domain.com/posts/laravel-is-awesome
---

<nav>
	<ul class="navigation">
		<li class="{{ Nav::isRoute('home') }}">Home</li>
		<li class="{{ Nav::isResource('posts') }}">Posts</li> 				// This one will render a class of "active" to the <li></li>
		<li class="{{ Nav::hasSegment('about')}}">About</li>
		<li class="{{ Nav::urlContains('contact') }}">Contact</li>
	</ul>
</nav>

此示例显示了如何将4个不同的“规则”相互连接，以定义何时某个导航元素应该接收“激活”类。

请注意：元素的样式仍然由您自己决定！此插件仅根据您定义的规则动态地为元素添加一个活动类。

现在您已经看到了它在实际中的应用，让我们逐个查看每个规则，以了解如何定义它。

isRoute() - 匹配命名路由

此规则会将元素标记为活动状态，如果当前页面与指定的命名路由相匹配。

Nav::isRoute($routeName, $activeClass = "active")

参数

$routeName - 必需的 String
这是您希望匹配的命名路由。它必须匹配您运行 php artisan route:list 时在 "name" 列中注册的值。
$activeClass - 可选的 String
它默认为您的配置文件中的 default_class 下定义的值，如果没有生成配置则默认为 "active"。

示例

Current Url - https://domain.com/contact
---

Routes File:
	Route::get('contact', 'BaseController@contact')->name('contact');
---

{{ Nav::isRoute('contact') }} 						// returns "active" [1]
{{ Nav::isRoute('contact', 'is-open') }}	// returns "is-open" [2]
{{ Nav::isRoute('about') }}								// returns "" [3]

(1) 字符串 "contact" 匹配名为 "contact" 的命名路由，因此返回默认活动类
(2) "contact" 匹配我们当前所在的命名路由，因此返回第二个参数提供的活动类，"is-open" (3) "about" 不匹配我们当前所在的 "contact" 路由，因此返回 ""

hasSegment() - 匹配定义的段

此规则会将元素标记为活动状态，如果提供的字符串与提供的段相匹配。这对于定义当其子元素中的任何一个也处于活动状态时希望标记为活动状态的父母元素非常有用。

Nav::hasSegment($slugs, $segments = 1, $activeClass = "active")

参数

$slug - 必需的 | String 或 String 数组
这是我们尝试匹配的值。如果您想匹配多个字符串，请传递字符串数组。注意，这就像一个 OR、|| 子句。如果有任何一个匹配，它返回 true。
$segments - 可选的 | Integer 或 Integer 数组
这定义了与 $slug 匹配的段。如果没有提供，默认为第一个段。使用整数（从1开始）来定义段。段值表示为：https://domainDoesntCount.com/1/2/3/4。由于 Laravel 的请求限制，您只能定义到第4个段。如果您想扫描多个段，请传递一个整数数组来检查这些段中的任何段（就像一个 OR、|| 子句）。
$activeClass - 可选的 | String
它默认为您的配置文件中的 default_class 下定义的值，如果没有生成配置则默认为 "active"。

示例

Current Url - https://domain.com/posts/created-by/devmarketer
---

{{ Nav::hasSegment('posts') }} 																// returns "active" [1]
{{ Nav::hasSegment('posts', 2) }} 														// returns "" [2]
{{ Nav::hasSegment('devmarketer', [2,3], 'is-active') }} 			// returns "active" [3]
{{ Nav::hasSegment(['devmarketer', 'jacurtis'], [2,3]) }} 		// returns "active" [4]
{{ Nav::hasSegment('posts', [2,3]) }} 												// returns "" [5]

(1) "posts" 在第一个段（默认段）中，因此返回默认活动类
(2) "posts" 不在第二个段中，因此返回 nothing
(3) 检查 "devmarketer" 是否在第二个或第三个段中。它在第三个段中，因此返回提供的活动类，"is-active"
(4) 检查 "devmarketer" 或 "jacurtis" 是否在第二个或第三个段中。 "devmarketer" 在第三个段中，因此返回默认活动类
(5) 检查 "posts" 是否在第二个或第三个段中，返回 nothing。

示例 2

它只匹配整个段。

Current Url - https://domain.com/example/text/segments
---

{{ Nav::hasSegment('example') }}		// returns "active"
{{ Nav::hasSegment('exam') }}				// returns ""

在第一个示例中，它工作是因为 "example" 是一个完整的段。但第二个示例不工作，因为即使 "exam" 包含在第一个段 "example" 中，它也不匹配整个段。

如果您想匹配段的一部分，请查看 urlDoesContain 规则，该规则会在第二个示例中返回 true，即使它是一个部分匹配。

isResource()

如果 URL 属于指定的资源，则匹配。
此规则会将元素标记为活动状态，如果它是给定资源之一。传递资源名称和（如果适用）前缀。这允许您通过一个规则匹配 https://domain.com/posts/create、https://domain.com/posts/1 和 https://domain.com/posts/19/edit。

Nav::isResource($resource, $prefix, $activeClass = "active", $strict)

参数

$resource - 必需的 | String
您想要匹配的资源。必须等于在Route::resource()中提供的值（但使用此辅助函数不是必需的，也不是为了使其工作）。在类似/posts/create的URL中的资源将是"posts"而不是"post"。
$prefix - 可选 | 字符串
这是适用时的前缀。例如，/admin/posts/create的"admin"是前缀。对于深层前缀，如/admin/manage/posts/create，您可以提交"admin.manage"或"admin/manage"作为前缀。
$activeClass - 可选的 | String
它默认为您的配置文件中的 default_class 下定义的值，如果没有生成配置则默认为 "active"。
$strict - 可选 | 布尔值
如果设置为TRUE，则将启用严格模式，要求对资源的搜索从路径开始。请参见示例以获取更多说明。

示例 1

Current Url - https://domain.com/posts/1/edit
---

{{ Nav::isResource('posts') }} 									// returns "active" [1]
{{ Nav::isResource('posts', NULL, 'is-open') }}	// returns "is-open" [2]
{{ Nav::isResource('users') }}									// returns "" [3]

(1) 当前URL是"posts"资源，因此返回默认活动类
(2) 当前URL是"posts"资源，因此返回第三参数中指定的活动类。第二个参数为NULL表示没有为该资源存在前缀。
(3) 搜索"users"资源，但活动URL是"posts"资源。因此返回""。

示例 2

使用前缀

Current Url - https://domain.com/admin/posts/1/edit
---

{{ Nav::isResource('posts') }} 												// returns "active", !IMPORTANT read notes [1]
{{ Nav::isResource('posts', 'admin', 'is-active') }}	// returns "is-active" [2]
{{ Nav::isResource('posts', 'admin.manage') }}				// returns "" [3]

(1) 重要提示：就像没有前缀一样，这仍然返回默认活动类。它仍然确定这是一个"post"资源。然而，这也会在正常的domain.com/posts或domain.com/user/posts上返回true。因此，如果您想全部都返回活动状态，那么请勿使用前缀，如本示例所示。但如果您只想让具有"admin"前缀或"users"前缀的资源返回活动状态，请确保在第二个参数中提供前缀以避免这些错误结果。
(2) 当前URL与带有"admin"前缀的"posts"资源匹配，因此返回第三参数中提供的活动类，"is-active"。
(3) 尽管此URL具有"admin"前缀，但它将返回""，因为需要"admin.manage"或"admin/manage"。您可以使用斜杠或点来表示层级，但这并不重要。但是，提供的URL不包含"manage"层，因此此规则将返回非活动状态。

示例 3

使用严格模式可能很棘手且令人困惑，但如果理解和适当使用，则非常强大。

Current Url - https://domain.com/admin/manage/posts/1/edit
---

{{ Nav::isResource('posts', NULL, NULL, TRUE) }} 		  			// returns "" [1]
{{ Nav::isResource('posts', 'manage', 'is-active', TRUE) }}	// returns "" [2]
{{ Nav::isResource('posts', 'manage', NULL, FALSE) }}				// returns "active" [3]
{{ Nav::isResource('posts', 'admin.manage', NULL, TRUE) }}	// returns "active" [4]

(1) 返回非活动状态，因为虽然它是"posts"资源，但严格模式已启用。这意味着前缀必须匹配并且必须从路径的开始处匹配（.com/后面的部分）。要启用严格模式，请确保它是第四个参数。您可能需要添加NULL值或填写其他值以到达第四个参数。
(2) 返回非活动状态，因为严格模式指示前缀与URL路径的开始处不完全匹配（admin/manage是严格前缀）。
(3) 与(2)完全相同，除了严格模式被禁用，这意味着它现在可以返回活动状态。严格模式默认禁用，因此将其标记为FALSE是不必要的，但达到了相同的结果。
(4) 返回活动状态，因为资源和前缀与精确匹配，且启用了严格模式。

urlDoesContain()

此规则将匹配路径中字符串的存在。请小心使用此方法，因为它如果不适当使用可能会导致错误结果。

Nav::urlDoesContain($search, $activeClass = "active", $strict = FALSE)

参数

$search - 必需 | 字符串
在URL中搜索的值，表示为字符串。
$activeClass - 可选的 | String
它默认为您的配置文件中的 default_class 下定义的值，如果没有生成配置则默认为 "active"。
$strict - 必需 | 布尔值
如果设置为TRUE，则将启用严格模式，要求从路径的开始处进行搜索。（请参见示例以获取更多说明）

示例

Current Url - https://domain.com/about/devmarketer/edit
---

{{ Nav::hasSegment('about') }}																// returns "active" [1]
{{ Nav::hasSegment('devm', 'open') }}													// returns "open" [2]
{{ Nav::hasSegment('devmarketer', 'active', TRUE) }} 					// returns "" [3]
{{ Nav::hasSegment('about/devmarketer', NULL, TRUE) }} 				// returns "active" [4]
{{ Nav::hasSegment('about', NULL, TRUE) }}										// returns "" [5]

(1) "about"包含在URL中，因此返回活动状态
(2) "devm" 包含在 URL 中（尽管它不是一个完整的段）。请注意这一点，因为它可能导致错误判断。提供的活动类是 "open"，因此返回的就是这个类。
(3) "devmarketer" 出现在 URL 中，但 严格模式 也处于活动状态，因为搜索词不是从路径开始，所以它将返回为非活动状态。
(4) 返回为活动状态，因为 严格模式 为真，并且 "about/devmarketer" 出现在路径的开始，即使 URL 超过了搜索词。
(5) 返回为活动状态，因为 "about" 包含在 URL 中，并且启用 严格模式 后，它仍然有效，因为 "about" 被找到在 URL 的开始位置。

辅助函数

除了我们学习过的 Nav::method() 外观之外，还有一些辅助函数你可以使用，如果你更喜欢使用辅助函数。

如果你不想加载这些函数，可以通过将 config/easynav.php 文件中的 enable_helper_functions 设置改为 FALSE 来禁用辅助函数。

`navHasSegment($slugs, $segments, $activeClass)`

这与 Nav::hasSegment() 完全相同。请参阅上面的文档了解如何使用它。

`navIsRoute($routeName, $activeClass)`

这与 Nav::isRoute() 完全相同。请参阅上面的文档了解如何使用它。

`navIsResource($resource, $prefix, $activeClass, $strictMode)`

这与 Nav::isResource() 完全相同。请参阅上面的文档了解如何使用它。

注意：没有辅助函数为 Nav::urlDoesContain() 方法。这个方法太危险了，不能与辅助函数一起使用。

贡献

我鼓励你为此包做出贡献，以改进它并使其变得更好。即使你不舒服于编码或提交 pull-request (PR)，你也可以通过提交有关错误的报告或请求新功能来支持它，或者简单地帮助讨论现有问题，以提供你的观点并塑造此包的发展。

阅读完整的贡献指南

联系

我很乐意听到你的声音。我在 YouTube 上运营 DevMarketer 频道，我们讨论如何 "构建和成长你的下一个伟大想法"，请订阅并查看视频。

我在 Twitter 上也一直活跃，这是与我沟通或关注我的好方法。在 Twitter 上找到我。

你也可以通过 hello@jacurtis.com 发送电子邮件，提出其他请求。

devmarketer / easynav

维护者

详细信息