Laravel Nova 字段

定義字段

每個 Nova 資源均包含一個 fields 方法。此方法返回一個字段數(shù)組，每個字段通常繼承了 Laravel\Nova\Fields\{Field} 類。Nova 提供了各種開箱即用的字段，包括文本輸入、布爾、日期、文件上傳、 Markdown 等多種字段。

要向資源添加字段，我們只需將它加入到資源的 fields 方法內(nèi)。此方法會接受幾個參數(shù)；但是，通常只需傳遞一個「易于閱讀的」字段名稱。Nova 對此名稱應(yīng)用「蛇形命名法（下劃線命名法）」以確定對應(yīng)的底層數(shù)據(jù)庫列：

use Laravel\Nova\Fields\ID;
use Laravel\Nova\Fields\Text;

/**
 * 獲取資源顯示的字段。
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
public function fields(Request $request)
{
    return [
        ID::make()->sortable(),
        Text::make('Name')->sortable(),
    ];
}

字段列名約定

如上所述，Nova 對字段的展示名稱應(yīng)用「蛇形命名法（下劃線命名法）」 ，以確定底層的數(shù)據(jù)庫列。但如果需要，你可以將列名作為第二個參數(shù)傳遞給字段的 make 方法：

Text::make('Name', 'name_column')

顯示 / 隱藏字段

你經(jīng)常會在某些場景下只想顯示某個字段。例如，你通常有一個在查詢列表中無需顯示的 Password 字段。同樣地，你也想在「創(chuàng)建 / 更新表單」里只顯示 Created At 字段。Nova 可以輕松實(shí)現(xiàn)在屏幕上顯示 / 隱藏字段。

下面的方法可在顯示的上下文里展示 / 隱藏字段：

• hideFromIndex
• hideFromDetail
• hideWhenCreating
• hideWhenUpdating
• onlyOnIndex
• onlyOnDetail
• onlyOnForms
• exceptOnForms

你可以在字段定義時鏈?zhǔn)秸{(diào)用這些方法，以指示 Nova 在哪里可以顯示 / 隱藏字段：

Text::make('Name')->hideFromIndex()

字段面板

如果你的資源包含很多字段，屏幕上資源的「詳情頁」會很擁擠。鑒于此，你可以選擇把字段組拆分到它們自己的「面板」里：

你也可以通過在資源的 fields 方法里創(chuàng)建一個 Panel 實(shí)例實(shí)現(xiàn)此目的。每個 Panel 實(shí)例需要一個名稱和一個屬于它的字段數(shù)組：

use Laravel\Nova\Panel;

/**
 * 獲取資源要展示的字段。
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
public function fields(Request $request)
{
    return [
        ID::make()->sortable(),

        new Panel('Address Information', $this->addressFields()),
    ];
}

/**
 * 獲取資源的所有地址字段。
 *
 * @return array
 */
protected function addressFields()
{
    return [
        Place::make('Address', 'address_line_1')->hideFromIndex(),
        Text::make('Address Line 2')->hideFromIndex(),
        Text::make('City')->hideFromIndex(),
        Text::make('State')->hideFromIndex(),
        Text::make('Postal Code')->hideFromIndex(),
        Country::make('Country')->hideFromIndex(),
    ];
}

可排序字段

當(dāng)向資源添加一個字段時，你可以使用 sortable 方法指示資源列表可以按照給定的字段排序：

Text::make('Name', 'name_column')->sortable()

字段類型

關(guān)聯(lián)字段

這部分文檔只討論非關(guān)聯(lián)字段。

Nova 提供了豐富的字段類型。那么，讓我們?yōu)g覽一下所有的類型和相應(yīng)選項：

Avatar 字段

Avatar 字段繼承了 Image 字段 ，接受相同配置選項：

use Laravel\Nova\Fields\Avatar;

Avatar::make('Avatar')

如果一個資源包含 Avatar 字段，此字段會展示在搜索結(jié)果的資源標(biāo)題旁邊：

Boolean 字段

Boolean 字段可以用來表示布爾或「短整數(shù)」型的數(shù)據(jù)庫列。例如，假設(shè)你的數(shù)據(jù)庫有一個叫做 active 的布爾型列，你就可以給資源添加一個 Boolean 字段，就像這樣：

use Laravel\Nova\Fields\Boolean;

Boolean::make('Active')

自定義 True / False 值

如果使用 true、false、1 或 0 以外的值來表示「true」或「false」，可以指示 Nova 使用應(yīng)用程序可識別的自定義值。為此，請在定義 Boolean 字段時鏈?zhǔn)秸{(diào)用 trueValue 和  falseValue 方法：

Boolean::make('Active')
        ->trueValue('On')
        ->falseValue('Off');

Code 字段

Code 字段為 Nova 后臺管理面板提供了一個漂亮的代碼編輯器。通常，Code 字段應(yīng)該添加在 Text 型的數(shù)據(jù)庫列上。然而，也可以把它添加在 JSON 型的數(shù)據(jù)庫列上：

use Laravel\Nova\Fields\Code;

Code::make('Snippet')

查詢列表里的 Code 字段

默認(rèn)地，Nova 在資源的查詢列表里不顯示 Code 字段。

編輯 JSON

如果打算對給定的一個 Code 字段實(shí)例只編輯 JSON，可以在字段定義時鏈?zhǔn)秸{(diào)用 json 方法：

Code::make('Options')->json()

語法高亮

你可以使用 language 方法自定義 Code 字段相應(yīng)語言的語法高亮：

Code::make('Snippet')->language('php')

Code 字段當(dāng)前支持高亮的語言是：

• dockerfile
• javascript
• markdown
• nginx
• php
• ruby
• sass
• shell
• vue
• xml
• yaml

Country 字段

Country 字段會生成一個包含了所有國家列表的 Select 字段 。這個字段存儲的是指代具體國家的二維數(shù)字碼。

use Laravel\Nova\Fields\Country;

Country::make('Country', 'country_code')

Currency 字段

Currency 字段會生成一個 Number 字段，使用 PHP 的 money_format 函數(shù)自動展示 。 你也可以使用 format 方法指定顯示格式； 否者默認(rèn)使用 %i 格式：

use Laravel\Nova\Fields\Currency;

Currency::make('Price')

Currency::make('Price')->format('%.2n');

Date 字段

Date 存儲日期值（不包括時間）。

use Laravel\Nova\Fields\Date;

Date::make('Birthday')

DateTime 字段

DateTime 字段可以用來存儲日期時間值。

use Laravel\Nova\Fields\DateTime;

DateTime::make('Updated At')->hideFromIndex()

File 字段

use Laravel\Nova\Fields\File;

File::make('Attachment')

Gravatar 字段

Gravatar 字段不對應(yīng)于應(yīng)用程序數(shù)據(jù)庫的任何一種列類型。相反，它可以顯示與模型關(guān)聯(lián)的「Gravatar」頭像。

默認(rèn)地，Gravatar URL 基于模型的 email 列生成。但是，如果用戶的郵箱地址不存儲在 email 列，你可以給字段的 make 方法傳遞一個自定義列名：

use Laravel\Nova\Fields\Gravatar;

// 使用「email」列……
Gravatar::make()

// 使用「email_address」列……
Gravatar::make('Avatar', 'email_address')

ID 字段

ID 表示資源的數(shù)據(jù)庫表主鍵。通常你定義的每個 Nova 資源都應(yīng)該包含 ID 字段。默認(rèn)情況下，ID 字段假定基礎(chǔ)數(shù)據(jù)庫列名為 id:

use Laravel\Nova\Fields\ID;

// 使用 "id" 作為列名...
ID::make()

// 使用 "id_column" 作為列名...
ID::make('ID', 'id_column')

Image 字段

Image 字段繼承于 File 字段 ，接受相同的參數(shù)和配置。與 File 字段的區(qū)別在于， Image 字段將在查看資源時顯示基礎(chǔ)圖像的縮列圖預(yù)覽：

use Laravel\Nova\Fields\Image;

Image::make('Photo')

Markdown 字段

Markdown 字段為它對應(yīng)的數(shù)據(jù)庫列提供了一個「所見即所得」的 Markdown 編輯器。通常，該字段對應(yīng)一個 TEXT 型的數(shù)據(jù)庫列。Markdown 字段將在與其對應(yīng)的數(shù)據(jù)庫列里存儲原生 Markdown 文本：

use Laravel\Nova\Fields\Markdown;

Markdown::make('Biography')

Number 字段

Number 字段提供了一個 input 控件，其 type 屬性值為 number：

use Laravel\Nova\Fields\Number;

Number::make('price')

你可以在生成的 input 控件上，使用 min、max 和 step 方法設(shè)置相應(yīng)屬性：

Number::make('price')->min(1)->max(1000)->step(0.01)

Password 字段

Password 字段提供了一個 input 控件，其 type 屬性值為 password：

use Laravel\Nova\Fields\Password;

Password::make('Password')

當(dāng)輸入密碼為空時，Password 字段會自動保留存儲在數(shù)據(jù)庫中的密碼。因此，典型的密碼字段定義看起來就像下面這樣：

Password::make('Password')
    ->onlyOnForms()
    ->creationRules('required', 'string', 'min:6')
    ->updateRules('nullable', 'string', 'min:6'),

Place 字段

Place 字段利用「Algolia Places API 」的強(qiáng)大功能提供超快的地址搜索和自動完成功能。使用這個字段不必?fù)碛?Algolia 賬號。

典型地，一個 Place 字段與其他相關(guān)地址字段一起被定義。在這個例子中，為了保持我們的資源整潔，我們將用 merge 方法將地址字段定義提取到他們自己的方法中：

use Laravel\Nova\Fields\Place;

/**
 * 獲取資源顯示的字段
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
public function fields(Request $request)
{
    return [
        ID::make()->sortable(),
        $this->addressFields(),
    ];
}

/**
 * 獲取資源中的地址字段
 *
 * @return \Illuminate\Http\Resources\MergeValue
 */
protected function addressFields()
{
    return $this->merge([
        Place::make('Address', 'address_line_1')->hideFromIndex(),
        Text::make('Address Line 2')->hideFromIndex(),
        Text::make('City')->hideFromIndex(),
        Text::make('State')->hideFromIndex(),
        Text::make('Postal Code')->hideFromIndex(),
        Country::make('Country')->hideFromIndex(),
    ]);
}

搜索國家

默認(rèn)情況下， Place 字段會搜索全世界范圍內(nèi)的地址。如果你想限制搜索的國家，可以使用 countries 方法：

Place::make('Address', 'address_line_1')->countries(['US', 'CA'])

搜索城市

如果你想用 Place 字段來搜索城市而不是地址的話，你可以使用 onlyCities 方法讓結(jié)果中只列出城市：

Place::make('City')->onlyCities()

城市自動補(bǔ)全

當(dāng)使用 Place 字段搜索城市時， state 和 country 字段依然會自動補(bǔ)全， postal_code 則不會。

配置字段自動完成

默認(rèn)時，Place 字段將根據(jù)他們的名字，自動完成相關(guān)地址字段。Place 字段將自動填充的字段名包括： address_line_2， city， state，postal_code 和  country。然而，你可能使用以下方法來自定義應(yīng)該自動完成的字段：

• secondAddressLine($column)
• city($column)
• state($column)
• postalCode($column)
• country($column)

示例：

Place::make('Address', 'address_line_1')
    ->secondAddressLine('address_2')
    ->city('city_name')
    ->state('state_code')
    ->postalCode('zip_code')
    ->country('country_code')

Select 字段

Select 字段用于生成下拉選擇菜單?？梢允褂?nbsp;options 方法定義菜單選項：

use Laravel\Nova\Fields\Select;

Select::make('Size')->options([
    'S' => 'Small',
    'M' => 'Medium',
    'L' => 'Large',
])

在資源的索引和詳情界面，將顯示 Select 字段的鍵值。 如果你想要顯示標(biāo)簽，可以使用 displayUsingLabels 方法：

Select::make('Size')->options([
    'S' => 'Small',
    'M' => 'Medium',
    'L' => 'Large',
])->displayUsingLabels()

Status 字段

Status 字段用于顯示 “進(jìn)度狀態(tài)”。Nova 使用 Status 字段指示排隊操作的當(dāng)前狀態(tài)（等待，運(yùn)行中，已完成）。 你可以根據(jù)具體情況定義這個字段：

loadingWhen 和 failedWhen 方法用于定義指示 “加載” 和 “失敗” 的文字。 例如，我們定義數(shù)據(jù)庫列的 “加載” 指示符為 waiting 或 running：

use Laravel\Nova\Fields\Status;

Status::make('Status')
        ->loadingWhen(['waiting', 'running'])
        ->failedWhen(['failed'])

Text 字段

Text 字段提供了一個 type 屬性為 text 的 input 控件：

use Laravel\Nova\Fields\Text;

Text::make('name')

Textarea 字段

Textarea 字段提供一個 textarea 控件：

use Laravel\Nova\Fields\Textarea;

Textarea::make('Biography')

時區(qū)字段

時區(qū)字段 生成一個包含世界時區(qū)的 下拉框 字段：

use Laravel\Nova\Fields\Timezone;

Timezone::make('Timezone')

Trix 字段

Trix 字段為其關(guān)聯(lián)的字段提供一個 Trix 編輯器。通常，這個字段將和你數(shù)據(jù)庫中的 Text 列對應(yīng)。Trix 字段將為其對應(yīng)的數(shù)據(jù)列存儲對應(yīng)的 Html：

use Laravel\Nova\Fields\Trix;

Trix::make('Biography')

文件上傳

Nova 當(dāng)前不支持在 Trix 字段中嵌入文件上傳。

Computed 字段

除了顯示與數(shù)據(jù)庫中的列關(guān)聯(lián)的字段外， Nova 還支持我們創(chuàng)建 "computed 字段"。Computed 字段用于顯示與數(shù)據(jù)庫列無關(guān)的計算值。 由于它們與數(shù)據(jù)庫列無關(guān)，因此計算字段可能無法 排序。通過將調(diào)用名（而不是列名）作為第二個參數(shù)傳遞給字段的 make 方法來創(chuàng)建計算字段：

Text::make('Name', function () {
    return $this->first_name.' '.$this->last_name;
})

訪問模型屬性

正如上面示例使用到的一樣，你可以用 $this 來訪問資源的基礎(chǔ)屬性和關(guān)聯(lián)。

自定義字段

字段解析 / 格式化

resolveUsing 方法允許在數(shù)據(jù)庫中檢索到字段后，且在將字段發(fā)送到 Nova 前端之前自定義字段格式。該方法從底層數(shù)據(jù)庫中獲取到原始記錄后接受回調(diào)：

Text::make('Name')->resolveUsing(function ($name) {
    return strtoupper($name);
})

如果僅在資源的索引或詳情頁展示自定義格式，可以使用 displayUsing 方法。就像 resolveUsing 方法，該方法接受一個簡單的回調(diào)：

Text::make('Name')->displayUsing(function ($name) {
    return strtoupper($name);
})