Nova 的 metrics 可以幫助您快速了解應(yīng)用的關(guān)鍵業(yè)務(wù)指標。例如，您可以定義一個 metrics，用來顯示每天添加到應(yīng)用中的用戶總數(shù)或每周銷售額。

Nova 提供三種類型的內(nèi)置 metrics：值 metrics、趨勢 metrics 和分區(qū) metrics。下面我們將學(xué)習(xí)每種類型的 metrics 并在演示它們的用法。

Value Metrics

Value metrics 可以展示單個值，如果需要，也可以顯示與上個周期間隔的比值。 例如，一個 value metric 想顯示前三十天新用戶和 上個三十天新用戶的比值：

Value metrics 可以使用 nova:value Artisan 命令生成。默認 所有新生成的 metrics 都會在 app/Nova/Metrics 目錄中：

php artisan nova:value NewUsers

一旦生成值 metric 類后，您就可以對其進行自定義了。每個值 metric 都有一個 calculate 方法，該方法返回了一個 Laravel\Nova\Metrics\ValueResult 對象。Nova 附帶了各種幫助程序，可以快速生成結(jié)果。

下面的例子，我們使用 count 助手自動對選定范圍的 Eloquent 模型執(zhí)行 count 查詢，并自動對 “上一個” 索引范圍計數(shù)。

<?php

namespace App\Nova\Metrics;

use App\User;
use Illuminate\Http\Request;
use Laravel\Nova\Metrics\Value;

class NewUsers extends Value
{
    /**
     * 計算 metric 的值。
     *
     * @param  \Illuminate\Http\Request  $request
     * @return mixed
     */
    public function calculate(Request $request)
    {
        return $this->count($request, User::class);
    }

    /**
     * 獲取 metric 的時間范圍。
     *
     * @return array
     */
    public function ranges()
    {
        return [
            30 => '30 Days',
            60 => '60 Days',
            365 => '365 Days',
            'MTD' => 'Month To Date',
            'QTD' => 'Quarter To Date',
            'YTD' => 'Year To Date',
        ];
    }

    /**
     * 獲取 metric 的 URI 鍵。
     *
     * @return string
     */
    public function uriKey()
    {
        return 'new-users';
    }
}

值查詢類型

值 metrics 不只是附帶一個 count 助手。在構(gòu)建 metric 時，您還可以在構(gòu)建 metric 時使用各種其他聚合函數(shù)。

Average

average 方法可用于計算給定列與前一個時間間隔 / 范圍相比的平均值：

return $this->average($request, Post::class, 'word_count');

Sum

sum 方法可用于計算給定列與前一時間間隔 / 范圍的總和：

return $this->sum($request, Order::class, 'price');

Max

max 方法可用于計算給定列相對于前一時間間隔 / 范圍的最大值：

return $this->max($request, Order::class, 'total');

Min

min 方法可用于計算給定列相對于前一時間間隔 / 范圍的最小值：

return $this->min($request, Order::class, 'total');

值范圍

每個值度量類都包含一個 ranges 方法。此方法確定值度量的范圍選擇菜單中的可用的范圍。數(shù)組的鍵確定應(yīng)包含在查詢中的天數(shù)，而值確定將放置在范圍選擇菜單中的「可讀的」文本。當然，您根本不需要定義任何范圍：

/**
 * 獲取指標可用范圍。
 *
 * @return array
 */
public function ranges()
{
    return [
        5 => '5 Days',
        10 => '10 Days',
        15 => '15 Days',
        'MTD' => 'Month To Date',
        'QTD' => 'Quarter To Date',
        'YTD' => 'Year To Date',
    ];
}

MTD / QTD / YTD 范圍鍵

您可以定制這些范圍以滿足您的需求；但是，如果您使用內(nèi)置的「月度至今」、「季度至今」、或 「年度至今」范圍，則不應(yīng)更改它們的鍵。

手動構(gòu)建結(jié)果值

如果你不能使用自帶的查詢助手構(gòu)建您的 metric 值，你可以使用 result 和 previous 方法手動為 metric 提供最終值：

return $this->result(100)->previous(50);

趨勢 Metrics

趨勢 metrics 通過折線圖顯示隨著時間變化的值。例如，趨勢 metric 可能會顯示過去 30 天內(nèi)每天創(chuàng)建的新用戶數(shù)：

趨勢指標可以使用 nova:trend Artisan 命令生成。默認情況下，所有新指標都將放在 app/Nova/Metrics 目錄中：

php artisan nova:trend UsersPerDay

生成趨勢度量類后，您就可以對其進行自定義了。每個趨勢度量類都包含一個 calculate 方法。這個方法應(yīng)該返回一個 Laravel\Nova\Metrics\TrendResult 對象。不用擔心，Nova 附帶了各種幫助程序，可以快速生成結(jié)果。

在這個例子中，我們使用了 countByDays 幫助器，它會自動對指定的 Eloquent 模型執(zhí)行一個 count 查詢，用于選定的范圍和選定的間隔單位 (在這種情況下，天)：

<?php

namespace App\Nova\Metrics;

use App\User;
use Illuminate\Http\Request;
use Laravel\Nova\Metrics\Trend;

class UsersPerDay extends Trend
{
    /**
     * Calculate the value of the metric.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return mixed
     */
    public function calculate(Request $request)
    {
        return $this->countByDays($request, User::class);
    }

    /**
     * Get the ranges available for the metric.
     *
     * @return array
     */
    public function ranges()
    {
        return [
            30 => '30 Days',
            60 => '60 Days',
            90 => '90 Days',
        ];
    }

    /**
     * Get the URI key for the metric.
     *
     * @return string
     */
    public function uriKey()
    {
        return 'users-per-day';
    }
}

趨勢查詢類型

趨勢 metrics 不只是附帶一個 countByDays 助手。在構(gòu)建 metric 時，您還可以使用各種其他聚合函數(shù)和時間間隔。

Count

count 方法可用于計算給定列隨著時間變化的計數(shù)：

return $this->countByMonths($request, User::class);
return $this->countByWeeks($request, User::class);
return $this->countByDays($request, User::class);
return $this->countByHours($request, User::class);
return $this->countByMinutes($request, User::class);

Average

average 方法可用于計算給定列隨著時間變化的平均值：

return $this->averageByMonths($request, Post::class, 'word_count');
return $this->averageByWeeks($request, Post::class, 'word_count');
return $this->averageByDays($request, Post::class, 'word_count');
return $this->averageByHours($request, Post::class, 'word_count');
return $this->averageByMinutes($request, Post::class, 'word_count');

Sum

sum 方法可用于計算給定列隨著時間變化的總和：

return $this->sumByMonths($request, Order::class, 'price');
return $this->sumByWeeks($request, Order::class, 'price');
return $this->sumByDays($request, Order::class, 'price');
return $this->sumByHours($request, Order::class, 'price');
return $this->sumByMinutes($request, Order::class, 'price');

Max

max 方法可用于計算給定列隨著時間變化的最大值：

return $this->maxByMonths($request, Order::class, 'total');
return $this->maxByWeeks($request, Order::class, 'total');
return $this->maxByDays($request, Order::class, 'total');
return $this->maxByHours($request, Order::class, 'total');
return $this->maxByMinutes($request, Order::class, 'total');

Min

min 方法可用于計算給定列隨著時間變化的最小值：

return $this->minByMonths($request, Order::class, 'total');
return $this->minByWeeks($request, Order::class, 'total');
return $this->minByDays($request, Order::class, 'total');
return $this->minByHours($request, Order::class, 'total');
return $this->minByMinutes($request, Order::class, 'total');

趨勢范圍

每個趨勢度量標準類都包含一個 范圍 方法。此方法確定將在趨勢市度量標準范圍選擇菜單中提供的范圍。數(shù)組的密鑰確定應(yīng)在查詢中包含的時間間隔單位 (月，周，天等) 的數(shù)量，而值確定將放置在范圍選擇菜單中的「可讀的」文本。當然，您無需定義任何范圍：

/**
 * Get the ranges available for the metric.
 *
 * @return array
 */
public function ranges()
{
    return [
        5 => '5 Days',
        10 => '10 Days',
        15 => '15 Days',
    ];
}

格式化趨勢值

有時，您可能希望添加一個前綴或后綴到趨勢值。為了實現(xiàn)這一點，您可以使用 prefix 和 suffix 方法：

return $this->countByDays($request, User::class)
            ->prefix(');

如果你的趨勢 metric 是顯示一個貨幣值，您可以使用 dollars 和 euros 快捷方法快速在趨勢值前添加美元或歐元符號：

return $this->countByDays($request, User::class)
            ->dollars();

顯示當前值

有時，您可能希望突出最新時間間隔的值。例如，在這個截圖中，在最后一天創(chuàng)建了 6 個用戶：

您可以使用 showLatestValue 方法完成這個：

return $this->countByDays($request, User::class)
            ->showLatestValue();

手動構(gòu)建趨勢結(jié)果

如果您無法使用包含的查詢助手來構(gòu)建趨勢指標，您可以手動構(gòu)建 Laravel\Nova\Metrics\TrendResult 對象并從指標的 calculate 方法中返回它：

return (new TrendResult)->trend([
    'July 1' => 100,
    'July 2' => 150,
    'July 3' => 200,
]);

分區(qū)指標

分區(qū)指標顯示值的餅圖。例如，分區(qū)指標可能會顯示應(yīng)用程序提供的每個計費計劃的用戶總數(shù)：

可以使用 nova：partition artisan 命令生成分區(qū)度量。默認情況下，所有新指標都將放在 app/nova/metrics 目錄中：

php artisan nova:partition UsersPerPlan

一旦生成了分區(qū)度量類，您就可以自定義了它。每個分區(qū)度量類包含一個 calculate 方法。此方法應(yīng)返回一個 laravel\nova\metrics\partitionResult 對象。別擔心，Nova 提供了各種各樣的助手，可以快速生成結(jié)果

在此示例中，我們正在使用 count 助手程序，它將自動執(zhí)行針對指定的 eloquent 模型的 count 查詢，并檢索屬于指定的每個不同值的模型數(shù)量「group by」列：

<?php

namespace App\Nova\Metrics;

use App\User;
use Illuminate\Http\Request;
use Laravel\Nova\Metrics\Partition;

class UsersPerPlan extends Partition
{
    /**
     * 計算度量標準的值。
     *
     * @param  \Illuminate\Http\Request  $request
     * @return mixed
     */
    public function calculate(Request $request)
    {
        return $this->count($request, User::class, 'stripe_plan');
    }

    /**
     * 獲取度量標準的URI鍵。
     *
     * @return string
     */
    public function uriKey()
    {
        return 'users-by-plan';
    }
}

分區(qū)查詢類型

分區(qū)度量不只附帶 count 幫助器。在構(gòu)建指標時，您還可以使用各種其他聚合函數(shù)。

平均值

average 方法可用于計算不同組中給定列的平均值。例如，以下對 average 方法的調(diào)用將顯示一個餅形圖，其中包含公司每個部門的平均訂單價格：

return $this->average($request, Order::class, 'price', 'department');

求和

sum 方法可用于計算不同組中給定列的總和。例如，以下對 sum 方法的調(diào)用將顯示一個餅圖，其中包含公司每個部門的所有訂單價格的總和：

return $this->sum($request, Order::class, 'price', 'department');

最大值

max 方法可用于計算不同組中給定列的最大值。例如，以下對 max 方法的調(diào)用將顯示一個餅圖，其中包含公司每個部門的最高訂單價格：

return $this->max($request, Order::class, 'price', 'department');

Min

min 方法可用于計算不同組內(nèi)給定列的最小值。例如下面的 min 方法將顯示一個餅圖，其中包含公司每個部門的最低訂單價格：

return $this->min($request, Order::class, 'price', 'department');

自定義分區(qū)標簽

通常，將分區(qū) metrics 指標分組的列值將是最簡單的鍵，而不是 “友好” 的東西?；蛘?，如果您要顯示布爾值列分組的分區(qū) metric，Nova 會將您的組標簽顯示為 “0” 和 "1"。因此，Nova 允許您提供一個 Closure 將標簽格式化為更具有可讀性的內(nèi)容：

/**
 * 計算 metric 的值。
 *
 * @param  \Illuminate\Http\Request  $request
 * @return mixed
 */
public function calculate(Request $request)
{
    return $this->count($request, User::class, 'stripe_plan')
            ->label(function ($value) {
                switch ($value) {
                    case null:
                        return 'None';
                    default:
                        return ucfirst($value);
                }
            });
}

手動生成分區(qū)結(jié)果

如果您無法使用內(nèi)置的查詢助手構(gòu)建你的分區(qū) metric，您可以使用 result 方法手動為 metric 提供最終值：

return $this->result([
    'Group 1' => 100,
    'Group 2' => 200,
    'Group 3' => 300,
]);

緩存

有時 metric 值的計算可能會很慢且成本很高。因此，所有 Nova metrics 都包含一個 cacheFor 方法，該方法允許您指定 metric 結(jié)果的緩存時長：

/**
 * 指定 metric 應(yīng)緩存多少分鐘。
 *
 * @return  \DateTimeInterface|\DateInterval|float|int
 */
public function cacheFor()
{
    return now()->addMinutes(5);
}