README

Ziggy - 在JavaScript中使用你的Laravel命名路由

Ziggy创建了一个Blade指令，你可以将其包含在视图文件中。这将导出一个JavaScript对象，其中包含应用的所有命名路由，以它们的名称（别名）为键，以及一个全局的route()辅助函数，你可以使用它来访问JavaScript中的路由。

安装

1. 将Ziggy添加到你的Composer文件：composer require tightenco/ziggy

2. (如果使用Laravel 5.4) 将Tightenco\Ziggy\ZiggyServiceProvider::class添加到config/app.php中的providers数组。

3. 在模板中包含我们的Blade指令（@routes）的位置，在主应用JavaScript加载之前——可能是在头部。

用法

此包替换了@routes指令，以一个由应用所有路由组成的集合，以它们的名称为键。这个集合在Ziggy.namedRoutes中可用。

此包还创建了一个可选的route()JavaScript辅助函数，它类似于Laravel的route()PHP辅助函数，可以用来通过名称和（可选）参数检索URL。

示例

不带参数

route('posts.index') // Returns '/posts'

带必需参数

route('posts.show', {id: 1}) // Returns '/posts/1'
route('posts.show', [1]) // Returns '/posts/1'
route('posts.show', 1) // Returns '/posts/1'

带多个必需参数

route('events.venues.show', {event: 1, venue: 2}) // Returns '/events/1/venues/2'
route('events.venues.show', [1, 2]) // Returns '/events/1/venues/2'

带查询参数

route('events.venues.show', {event: 1, venue: 2, page: 5, count: 10}) // Returns '/events/1/venues/2?page=5&count=10'

如果传递的是整个对象，Ziggy将自动查找id主键

var event = {id: 1, name: 'World Series'};
var venue = {id: 2, name: 'Rogers Centre'};

route('events.venues.show', [event, venue]) // Returns '/events/1/venues/2'

实际的AJAX示例

var post = {id: 1, title: 'Ziggy Stardust'};

return axios.get(route('posts.show', post))
    .then((response) => {
        return response.data;
    });

默认值

见Laravel 文档

默认值对于Laravel版本>=5.5.29是自动工作的，对于旧版本，你需要在Blade指令（@routes）所在的同一页面中包含以下代码来设置默认参数

Ziggy.defaultParameters = {
    //example
    locale: "en"
}

路由过滤

路由过滤是完全可选的。如果你想默认将所有路由传递给JavaScript，你可以继续使用Ziggy，如上所述。

基本白名单和黑名单

要利用基本白名单或黑名单功能，你首先需要在Laravel应用的config目录中创建一个名为ziggy.php的标准配置文件，并将whitelist或blacklist设置为一个包含路由名称的数组。

注意：你必须选择一个。设置whitelist和blacklist将完全禁用过滤，并简单地返回默认的路由列表。

示例config/ziggy.php

<?php
return [
    // 'whitelist' => ['home', 'api.*'],
    'blacklist' => ['debugbar.*', 'horizon.*', 'admin.*'],
];

如上例所示，Ziggy在过滤器中使用星号作为通配符。例如home将只匹配名为home的路由，而api.*将匹配任何以api.开头的路由，如api.posts.index和api.users.show。

简单的白名单和黑名单宏

白名单和黑名单也可以使用以下宏来实现。

示例白名单

Route::whitelist(function () {
    Route::get('...')->name('posts');
});

Route::whitelist()->get('...')->name('posts');

示例黑名单

Route::blacklist(function () {
    Route::get('...')->name('posts');
});

Route::blacklist()->get('...')->name('posts');

使用组的高级白名单

你也可以在config/ziggy.php中定义多个白名单，通过定义groups。

<?php
return [
    'groups' => [
        'admin' => [
            'admin.*',
            'posts.*',
        ],
        'author' => [
            'posts.*',
        ]
    ],
];

在上面的示例中，你可以看到我们为不同的用户角色配置了多个白名单。你可以通过将组键传递到blade视图中@routes中来公开特定的白名单组。示例

@routes('author')

注意：使用组将始终优先于上述提到的whitelist和blacklist设置。

其他有用的方法

current()

要获取当前路由的名称（基于浏览器的window.location），你可以使用

route().current()
// returns "events.index"

要检查我们是否处于当前路由，只需通过唯一参数传入所需的路由

route().current("events.index")
// returns true

您甚至可以使用通配符

route().current("events.*")
// returns true

url()

Ziggy返回一个字符串原始值的包装器，在几乎所有情况下都像字符串一样运行。在罕见的情况下，当第三方库使用严格的类型检查时，您可能需要实际的String字面量。

要实现这一点，只需在您的路由上调用.url()

route('home').url()
// http://myapp.local/

Artisan命令

Ziggy发布了一个Artisan命令来生成一个ziggy.js路由文件，该文件可以作为资产管道的一部分使用，例如Laravel Mix。

您可以在项目中运行php artisan ziggy:generate以在resources/assets/js/ziggy.js中生成一个静态路由文件。

可选地，包含第二个参数以覆盖路径和文件名（您必须传递包含路径的文件名）

php artisan ziggy:generate "resources/foo.js"

例如ziggy.js，其中命名的路由home和login存在于routes/web.php中

// routes/web.php

<?php

Route::get('/', function () {
    return view('welcome');
})->name('home');

Route::get('/login', function () {
    return view('login');
})->name('login');

// ziggy.js

var Ziggy = {
    namedRoutes: {"home":{"uri":"\/","methods":["GET","HEAD"],"domain":null},"login":{"uri":"login","methods":["GET","HEAD"],"domain":null}},
    baseUrl: 'http://myapp.local/',
    baseProtocol: 'http',
    baseDomain: 'myapp.local',
    basePort: false
};

export {
    Ziggy
}

基于环境的加载最小化路由助手文件

在加载blade助手文件时，Ziggy将检测当前环境，如果APP_ENV不是local，则最小化输出。

在这种情况下，将加载ziggy.min.js。否则，将使用ziggy.js。

可选的route助手

如果您只想通过@routes获取路由，但不需要route助手函数，您可以在配置中包含skip-route-function并将其设置为true

// config/ziggy.php

<?php

return [
    'skip-route-function' => true
];

与Vue组件一起使用

如果您想在Vue组件中使用route助手，您需要将其添加到您的app.js文件中

Vue.mixin({
    methods: {
        route: route
    }
});

然后，在您的Vue组件中如此使用该方法

<a class="nav-link" :href="route('home')">首页</a>

感谢Archer70提供此解决方案。

与laravel-haml（和其他自定义Blade编译器）一起使用

laravel-haml提供基于HAML的Blade模板。由于laravel-haml使用单独的BladeCompiler实例，自定义指令（如@route）不会自动导入。有一个pull request来修复这个问题。在同时，只需将此代码放在您的./app/Providers/AppServiceProvider.php的boot()部分即可

$customDirectives = $this->app['blade.compiler']->getCustomDirectives();
foreach ($customDirectives as $name => $closure) {
  $this->app['Bkwld\LaravelHaml\HamlBladeCompiler']->directive($name, $closure);
}

此模式不仅限于laravel-haml；它可以用于初始化您可能使用的任何自定义模板编译器。

贡献与致谢

要开始为Ziggy做出贡献，请查看贡献指南。

• 丹尼尔·科尔伯恩
• 马特·斯塔弗

感谢Caleb Porzio、Adam Wathan和Jeffrey Way帮助巩固这个想法。

感谢所有贡献者