Laravel Nova 字段

概述

Nova 提供了很多不同类型的字段；然而，有的时候你需要的字段 Nova 并不包含。 由于这个原因， Nova 允许你创建自定义字段。自定义的字段由三个 Vue 组件构成，这些组件决定了字段在不同的情景下将如何呈现。

定义字段

自定义字段可以用 nova:field Artisan 命令生成。默认情况下，所有新的字段会被放在应用程序的 nova-components 文件夹下。当你使用 nova:field 命令生成新字段的时候，字段的命名应该遵循 Composer vendor/package 格式。因此，如果我们创建一个 color-picker 字段，我们可以执行下面的命令：

php artisan nova:field acme/color-picker

当生成一个新字段的时候，Nova 会提示你安装字段的 NPM 依赖包，编译它的资源，和更新应用程序的 composer.json 文件。所有的自定义字段会被注册为一个 Composer 「path」 代码库。

Nova 字段包含了所有必要的脚手架去帮助你创建自己的字段。 每个字段甚至拥有它自己的 composer.json 文件，所以它可以在 github 或者其它源代码控制平台上直接地被分享。

注册字段

Nova 字段可能被注册在资源的 fields 方法中。这个方法会返回一个可以被资源读取的字段数组。想要注册你的字段，只需要把该字段加入到返回的数组中即可：

use Acme\ColorPicker\ColorPicker;

/**
 * 获取被资源呈现的字段。
 *
 * @param  \Illuminate\Http\Request  $request
 * @return array
 */
public function fields(Request $request)
{
    return [
        ID::make('ID', 'id')->sortable(),

        ColorPicker::make('Color'),
    ];
}

字段选项

通常，你将允许字段的使用者在运行交互时能够自定义配置选项，这可以通过开放字段类的方法来实现。这些方法会调用字段底层的 withMeta 方法将信息添加到元数据中，从而能够在 Vue 组件中 被读取。withMeta 方法的参数为一组键 / 值选项的关联数组：

<?php

namespace Acme\ColorPicker;

use Laravel\Nova\Fields\Field;

class ColorPicker extends Field
{
    /**
     * 字段的组件
     *
     * @var string
     */
    public $component = 'color-picker';

    /**
     * 设置选色器选中的色调
     *
     * @param  array  $hues
     * @return $this
     */
    public function hues(array $hues)
    {
        return $this->withMeta(['hues' => $hues]);
    }
}

创建字段

Nova 生成的每个字段都包含自己的服务提供者和「字段」类。以 color-picker 字段为例，它的类会被保存在：src/ColorPicker.php。

字段类的服务提供者同样存储在 src 文件夹下，并且在字段的 composer.json 文件中被注册，所以它会被 Laravel 自动加载。

字段首页

当 Nova 生成字段时，它会创建一个 resources/js/components/IndexField.vue Vue 组件。这个组件包含了该字段在资源首页被显示时所需要的模版和逻辑。默认情况下，这个组件仅在 <span> 元素中简单地输出了字段的值；然而，你可以随意按需编辑该组件。

字段页面

当字段被生成时，Nova 同样会创建一个 resources/js/components/DetailField.vue Vue 组件。这个组件包含了该字段在资源页面被显示时所需要的模版和逻辑。默认情况下，这个模版包含了必要的元素去显示所有字段的值。然而，你可以按照你的项目需求随意更新这个模版。

字段表格

最后，Nova 还创建了一个 resources/js/components/FormField.vue Vue 组件。这个组件包含了创建或者更新资源时所需要的模版和逻辑。默认情况下，该模版包含了一个简单的 input 控制去更新字段的值；然而，你可以随意自定义这个模版。举个例子，我们可以在模版中加入一个选色器控制：

<template>
    <default-field :field="field">
        <template slot="field">
            <input :id="field.name" type="color"
                class="w-full form-control form-input form-input-bordered"
                :class="errorClasses"
                :placeholder="field.name"
                v-model="value"
            />

            <p v-if="hasError" class="my-2 text-danger">
                {{ firstError }}
            </p>
        </template>
    </default-field>
</template>

设置表单值

在创建或更新资源前，Nova 要求表单上的每个字段用键 / 值对填充传出的 FormData 对象。每个字段可以根据需要添加任意数量的元素到 FormData。这可以在您的 FormField.vue 文件的  fill 方法中完成：

/**
 * 用字段内部值填充给定的 FormData 对象
 */
fill(formData) {
  formData.append(this.field.attribute, this.value || '')
}

水合模型

默认情况下，保存模型时，字段类只会将传入表单字段值复制到字段的关联模型属性中。但是，您可以自定义您的字段合并资源模型的方式。为此，请重写字段类的 fillAttributeFromRequest 方法：

<?php

namespace Otwell\ColorPicker;

use Laravel\Nova\Fields\Field;

class ColorPicker extends Field
{
    /**
     * 字段的组成部分。
     *
     * @var string
     */
    public $component = 'color-picker';

    /**
     * 根据传入的请求水合模型上的给定属性。
     *
     * @param  \Laravel\Nova\Http\Requests\NovaRequest  $request
     * @param  string  $requestAttribute
     * @param  object  $model
     * @param  string  $attribute
     * @return void
     */
    protected function fillAttributeFromRequest(NovaRequest $request,
                                                $requestAttribute,
                                                $model,
                                                $attribute)
    {
        if ($request->exists($requestAttribute)) {
            $model->{$attribute} = $request[$requestAttribute];
        }
    }
}

此方法接收你个参数。当然，它接收传入的 HTTP 请求和正在更新的模型。该方法还接收 $requestAttribute，他是 HTTP 请求中传入表单字段的名称。此外，它还接收 $attribute，这是字段值放置在其中的模型属性的名称。

Assets

当 Nova 生成您的字段时，会为您生成 resources/js 和 resources/sass 目录。这些目录包含您字段的 JavaScript 和 Sass 样式表。

字段属性

您字段的 Vue 组件接收一个 field Vue prop。field 属性提供对任何可用字段 options 的访问。

const hues = this.field.hues;

注册 Assets

您 Nova 字段的服务提供注册您字段编译的 assets，以便他们可供 Nova 前端使用：

/**
 * 引导任何应用程序服务。
 *
 * @return void
 */
public function boot()
{
    Nova::serving(function (ServingNova $event) {
        Nova::script('stripe-inspector', __DIR__.'/../dist/js/field.js');
        Nova::style('stripe-inspector', __DIR__.'/../dist/css/field.css');
    });
}

JavaScript 引导 & 路由

您的组件已引导并在 resources/js/field.js 文件中注册。您可以根据需要自由修改此文件或在此处注册其它组件。

编译资源

Nova 生成字段的同时也为其创建了一个 webpack.mix.js 文件。你可以使用 NPM dev 和 prod 命令编译字段：

// 在本地开发环境编译资源...
npm run dev

// 编译并压缩资源...
npm run prod

此外，你可以运行 NPM watch 命令来实现文件改动后的自动编译：

npm run watch