logo

注册指标 ​

概述 ​

定义好指标后，就可以将其附加到资源上了。Nova 生成的每个资源都包含一个 cards 方法。要将指标附加到资源，只需将其添加到该方法返回的 指标/卡片 数组中即可：

php
use App\Nova\Metrics\UsersPerDay;
use Laravel\Nova\Http\Requests\NovaRequest;

/**
 * 获取资源可用的卡片。
 *
 * @param  \Laravel\Nova\Http\Requests\NovaRequest  $request
 * @return array
 */
public function cards(NovaRequest $request)
{
    return [
        new UsersPerDay
    ];
}

或者，你也可以使用 make 方法来实例化你的指标：

php
use App\Nova\Metrics\UsersPerDay;
use Laravel\Nova\Http\Requests\NovaRequest;

/**
 * 获取资源可用的卡片。
 *
 * @param  \Laravel\Nova\Http\Requests\NovaRequest  $request
 * @return array
 */
public function cards(NovaRequest $request)
{
    return [
        UsersPerDay::make()
    ];
}

传递给 make 方法的任何参数都将传递给指标的构造函数。

详情显示指标 ​

除了在资源索引页面放置指标外，你还可以在资源详情页面附加指标。例如，如果你正在构建播客应用程序，你您可能希望显示特定用户在一段时间内创建的播客总数。要指示在详细页面而非索引页面显示指标，请在注册指标时调用 onlyOnDetail 方法：

php
/**
 * 获取可满足要求的卡片。
 *
 * @param  \Laravel\Nova\Http\Requests\NovaRequest  $request
 * @return array
 */
public function cards(NovaRequest $request)
{
    return [
        (new Metrics\PodcastCount)->onlyOnDetail(),
    ];
}

当然，你需要修改指标的查询，以便只收集当前显示的资源的指标数据。要做到这一点，你的指标的 calculate 方法可以访问传入的 $request 上的 resourceId 属性：

php
use App\Models\Podcast;

return $this->count($request, Podcast::where('user_id', $request->resourceId));

仪表板显示指标 ​

你还可以在 Nova 的主 "仪表板"（即 Nova 登录后显示的默认页面）上自由添加指标。默认情况下，该页面会通过内置的 Help 卡显示一些指向 Nova 文档的有用链接。要将指标添加到仪表板，请将指标添加到您的 app/Nova/Dashboards/Main 类的 cards 方法返回的卡片数组中：

php
use App\Nova\Metrics\NewUsers;

/**
 * 获取应显示在 Nova 仪表板上的卡片。
 *
 * @return array
 */
protected function cards()
{
    return [
        new NewUsers,
    ];
}

授权 ​

如果只想向某些用户公开给定的指标，可以在注册指标时调用 canSee 方法。canSee 方法接受一个闭包，该闭包将返回 true 或 false。闭包将接收传入的 HTTP 请求：

php
use App\Models\User;
use Laravel\Nova\Http\Requests\NovaRequest;

/**
 * 获取资源可用的卡片。
 *
 * @param  \Laravel\Nova\Http\Requests\NovaRequest  $request
 * @return array
 */
public function cards(NovaRequest $request)
{
    return [
        (new Metrics\UsersPerDay)->canSee(function ($request) {
            return $request->user()->can('viewUsersPerDay', User::class);
        }),
    ];
}

在上面的例子中，我们在 User 模型上使用了 Laravel 的 Authorizable 特性的 can 方法来确定授权用户是否被授权进行 viewUsersPerDay 操作。不过，由于代理授权策略方法是 canSee 的常见用例，你可以使用 canSeeWhen 方法来实现相同的行为。canSeeWhen 方法与 Illuminate\Foundation\Auth\Access\Authorizable 特性的 can 方法具有相同的方法签名：

php
return [
    (new Metrics\UsersPerDay)->canSeeWhen(
        'viewUsersPerDay', User::class
    ),
];

默认指标范围 ​

你可能希望默认加载某个指标范围。你可以将范围的数组键传递给指标的 defaultRange 方法来实现这一目的：

php
use App\Nova\Metrics\NewUsers;

/**
 * 获取应显示在 Nova 仪表板上的卡片。
 *
 * @return array
 */
protected function cards()
{
    return [
        NewUsers::make()->defaultRange('YTD'),
    ];
}

指标尺寸 ​

默认情况下，指标占 Nova 内容区域的三分之一。不过，你可以自由地将它们变大。为此，请在注册指标时调用 width 方法：

php
/**
 * 获取可满足要求的卡片。
 *
 * @param  \Laravel\Nova\Http\Requests\NovaRequest  $request
 * @return array
 */
public function cards(NovaRequest $request)
{
    return [
        // 内容占据 三分之二...
        (new Metrics\UsersPerDay)->width('2/3'),

        // 全宽...
        (new Metrics\UsersPerDay)->width('full'),
    ];
}

当度量宽度设置为 full 时，卡片的高度将变为动态。你可以通过调用 fixedHeight 或 dynamicHeight 方法来明确定义这种行为：

php
/**
 * 获取可满足要求的卡片。
 *
 * @param  \Laravel\Nova\Http\Requests\NovaRequest  $request
 * @return array
 */
public function cards(NovaRequest $request)
{
    return [
        (new Metrics\UsersPerDay)->width('full')->fixedHeight(),
        (new Metrics\UsersPerDay)->width('full')->dynamicHeight(),
    ];
}

指标 帮助文本/工具提示 ​

有时，指标需要向用户提供更多有关如何计算该值的上下文或与指标相关的其他细节。Nova 允许你定义帮助文本「tooltip」（工具提示），以类似于 字段帮助文本 的方式注册：

Metric Help Tooltip

要启用工具提示，请在注册指标时调用 help 方法。help 方法的唯一参数是帮助文本：

php
/**
 * 获取可满足要求的卡片。
 *
 * @param  \Laravel\Nova\Http\Requests\NovaRequest  $request
 * @return array
 */
public function cards(NovaRequest $request)
{
    return [
        (new TotalUsers)
            ->help('This is calculated using all users that are active and not banned.'),
    ];
}

在定义帮助文本时，你也可以使用 HTML。例如，你可以向 help 方法传递一个渲染过的 Blade 模板：

php
(new TotalUsers)
    ->help(view('nova.metrics.total-users.tooltip')->render()),

刷新指标 ​

Laravel Nova 会根据以下事件自动获取资源所附指标的更新结果（无需用户刷新页面）：

事件行为
资源删除自动更新
资源恢复自动更新
动作执行只有在注册时调用指标 refreshWhenActionsRun 方法时才会更新
过滤器更改只有在注册时调用度量的 refreshWhenFiltersChange 方法时才会更新

动作后刷新 ​

默认情况下，在用户未手动刷新页面的情况下，Nova 不会在动作执行后自动更新指标结果；不过，你可以在注册指标时调用 refreshWhenActionsRun 方法，指明指标应在动作执行后自动刷新：

php
public function cards(NovaRequest $request)
{
    return [
        TotalUsers::make()->refreshWhenActionsRun(),
    ];
}

过滤器更改后刷新 ​

同样，只有在注册指标时调用了指标的 refreshWhenFiltersChange 方法，页面所选过滤器发生变化时，Laravel Nova 才会自动更新指标：

php
public function cards(NovaRequest $request)
{
    return [
        TotalUsers::make()->refreshWhenFiltersChange(),
    ];
}