翻译进度
12
分块数量
1
参与人数

Precognition
12.x
12.x 11.x 10.x 9.x 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel 12 中文文档 /

这是一篇协同翻译的文章，你可以点击『我来翻译』按钮来参与翻译。

Precognition

介绍

Laravel Precognition 允许你预测未来 HTTP 请求的结果。Precognition 的一个主要使用场景是，在不需要在前端重复编写后端验证规则的情况下，为你的前端 JavaScript 应用提供“实时”验证。Precognition 与 Laravel 基于 Inertia 的 starter kits 配合效果尤其好。

当 Laravel 接收到一个“预测性请求（precognitive request）”时，它会执行该路由的所有中间件，并解析路由控制器的依赖项，包括验证 表单请求 —— 但它不会实际执行路由的控制器方法。

实时验证

使用 Vue

使用 Laravel Precognition，你可以为用户提供实时验证体验，而无需在前端 Vue 应用中重复验证规则。为了演示其工作方式，让我们构建一个用于在应用中创建新用户的表单。

首先，要为某个路由启用 Precognition，需要在路由定义中添加 HandlePrecognitiveRequests 中间件。同时，你应该创建一个 表单请求 来存放该路由的验证规则：

use App\Http\Requests\StoreUserRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;

Route::post('/users', function (StoreUserRequest $request) {
    // ...
})->middleware([HandlePrecognitiveRequests::class]);
无与伦比 翻译于 3周前
重译

接下来，你应该通过 NPM 为 Vue 安装 Laravel Precognition 的前端辅助工具：

npm install laravel-precognition-vue

安装 Laravel Precognition 包后，你现在可以使用 Precognition 的 useForm 函数创建一个表单对象，提供 HTTP 方法（post）、目标 URL（/users）以及初始表单数据。

然后，为了启用实时验证，在每个输入的 change 事件中调用表单的 validate 方法，并提供该输入的名称：

<script setup>
import { useForm } from 'laravel-precognition-vue';

const form = useForm('post', '/users', {
    name: '',
    email: '',
});

const submit = () => form.submit();
</script>

<template>
    <form @submit.prevent="submit">
        <label for="name">Name</label>
        <input
            id="name"
            v-model="form.name"
            @change="form.validate('name')"
        />
        <div v-if="form.invalid('name')">
            {{ form.errors.name }}
        </div>

        <label for="email">Email</label>
        <input
            id="email"
            type="email"
            v-model="form.email"
            @change="form.validate('email')"
        />
        <div v-if="form.invalid('email')">
            {{ form.errors.email }}
        </div>

        <button :disabled="form.processing">
            Create User
        </button>
    </form>
</template>

现在，当用户填写表单时，Precognition 将根据路由表单请求中的验证规则提供实时验证输出。当表单的输入发生变化时，会向你的 Laravel 应用发送一个防抖（debounced）的“预测性”验证请求。你可以通过调用表单的 setValidationTimeout 函数来配置防抖超时：

form.setValidationTimeout(3000);

当验证请求正在进行时，表单的 validating 属性将为 true：

<div v-if="form.validating">
    Validating...
</div>

在验证请求或表单提交期间返回的任何验证错误将自动填充到表单的 errors 对象中：

<div v-if="form.invalid('email')">
    {{ form.errors.email }}
</div>
无与伦比 翻译于 3周前
重译

你可以通过表单的 hasErrors 属性来判断表单是否有任何错误：

<div v-if="form.hasErrors">
    <!-- ... -->
</div>

你也可以通过将输入名称分别传给表单的 valid 和 invalid 函数，来判断某个输入是否通过或未通过验证：

<span v-if="form.valid('email')">
    ✅
</span>

<span v-else-if="form.invalid('email')">
    ❌
</span>

[!警告]
表单输入只有在其值发生变化并且收到验证响应后，才会显示为有效或无效。

如果你使用 Precognition 只验证表单的一部分输入，手动清除错误可能会很有用。你可以使用表单的 forgetError 函数实现这一点：

<input
    id="avatar"
    type="file"
    @change="(e) => {
        form.avatar = e.target.files[0]

        form.forgetError('avatar')
    }"
>

如前所述，你可以在输入的 change 事件中挂钩并验证用户交互的单个输入；但是，有时你可能需要验证用户尚未交互的输入。这在构建“向导（wizard）”时很常见，你希望在进入下一步之前验证所有可见的输入，无论用户是否已操作过它们。

使用 Precognition 实现这一点的方法是，调用 validate 方法，并将希望验证的字段名称传递给 only 配置键。你可以使用 onSuccess 或 onValidationError 回调来处理验证结果：

<button
    type="button"
    @click="form.validate({
        only: ['name', 'email', 'phone'],
        onSuccess: (response) => nextStep(),
        onValidationError: (response) => /* ... */,
    })"
>Next Step</button>

当然，你也可以在表单提交响应时执行代码。表单的 submit 函数会返回一个 Axios 请求的 promise。这提供了一种便捷方式来访问响应数据、在提交成功时重置表单输入，或者处理请求失败：

const submit = () => form.submit()
    .then(response => {
        form.reset();

        alert('User created.');
    })
    .catch(error => {
        alert('An error occurred.');
    });
无与伦比 翻译于 3周前
重译

你可以通过检查表单的 processing 属性来判断表单提交请求是否正在进行中：

<button :disabled="form.processing">
    Submit
</button>

使用 Vue 和 Inertia

[!注意]
如果你希望在使用 Vue 和 Inertia 开发 Laravel 应用时获得快速入门，可以考虑使用我们的 starter kits。Laravel 的 starter kits 为你的新应用提供了前后端的认证脚手架。

在将 Precognition 与 Vue 和 Inertia 一起使用之前，请务必查看我们关于 在 Vue 中使用 Precognition 的通用文档。使用 Vue 与 Inertia 时，你需要通过 NPM 安装与 Inertia 兼容的 Precognition 库：

npm install laravel-precognition-vue-inertia

安装完成后，Precognition 的 useForm 函数将返回一个 Inertia 表单助手，并增强了上述的验证功能。

表单助手的 submit 方法已被简化，不再需要指定 HTTP 方法或 URL。相反，你可以将 Inertia 的 访问选项 作为唯一参数传入。此外，submit 方法不会返回 Vue 示例中看到的 Promise。相反，你可以在传给 submit 方法的访问选项中提供 Inertia 支持的任意 事件回调：

<script setup>
import { useForm } from 'laravel-precognition-vue-inertia';

const form = useForm('post', '/users', {
    name: '',
    email: '',
});

const submit = () => form.submit({
    preserveScroll: true,
    onSuccess: () => form.reset(),
});
</script>

使用 React

使用 Laravel Precognition，你可以为用户提供实时验证体验，而无需在前端 React 应用中重复验证规则。为了演示其工作方式，让我们构建一个用于在应用中创建新用户的表单。

无与伦比 翻译于 3周前
重译

首先，要为某个路由启用 Precognition，需要在路由定义中添加 HandlePrecognitiveRequests 中间件。同时，你应该创建一个 表单请求 来存放该路由的验证规则：

use App\Http\Requests\StoreUserRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;

Route::post('/users', function (StoreUserRequest $request) {
    // ...
})->middleware([HandlePrecognitiveRequests::class]);

接下来，你应该通过 NPM 为 React 安装 Laravel Precognition 的前端辅助工具：

npm install laravel-precognition-react

安装 Laravel Precognition 包后，你现在可以使用 Precognition 的 useForm 函数创建一个表单对象，提供 HTTP 方法（post）、目标 URL（/users）以及初始表单数据。

为了启用实时验证，你应该监听每个输入的 change 和 blur 事件。在 change 事件处理器中，使用 setData 函数设置表单的数据，传入输入的名称和新值。然后，在 blur 事件处理器中调用表单的 validate 方法，并提供输入的名称：

import { useForm } from 'laravel-precognition-react';

export default function Form() {
    const form = useForm('post', '/users', {
        name: '',
        email: '',
    });

    const submit = (e) => {
        e.preventDefault();

        form.submit();
    };

    return (
        <form onSubmit={submit}>
            <label htmlFor="name">Name</label>
            <input
                id="name"
                value={form.data.name}
                onChange={(e) => form.setData('name', e.target.value)}
                onBlur={() => form.validate('name')}
            />
            {form.invalid('name') && <div>{form.errors.name}</div>}

            <label htmlFor="email">Email</label>
            <input
                id="email"
                value={form.data.email}
                onChange={(e) => form.setData('email', e.target.value)}
                onBlur={() => form.validate('email')}
            />
            {form.invalid('email') && <div>{form.errors.email}</div>}

            <button disabled={form.processing}>
                Create User
            </button>
        </form>
    );
};
无与伦比 翻译于 3周前
重译

现在，当用户填写表单时，Precognition 将根据路由表单请求中的验证规则提供实时验证输出。当表单的输入发生变化时，会发送一个经过防抖处理的“预知（precognitive）”验证请求到你的 Laravel 应用。你可以通过调用表单的 setValidationTimeout 函数来配置防抖超时时间：

form.setValidationTimeout(3000);

当验证请求正在进行中时，表单的 validating 属性将为 true：

{form.validating && <div>Validating...</div>}

在验证请求或表单提交期间返回的任何验证错误，将自动填充到表单的 errors 对象中：

{form.invalid('email') && <div>{form.errors.email}</div>}

你可以使用表单的 hasErrors 属性判断表单是否存在任何错误：

{form.hasErrors && <div><!-- ... --></div>}

你还可以通过将输入的名称传给表单的 valid 和 invalid 函数，分别判断该输入是否通过或未通过验证：

{form.valid('email') && <span>✅</span>}

{form.invalid('email') && <span>❌</span>}

[!警告]
一个表单输入只有在它发生变化并且接收到验证响应之后，才会显示为有效或无效。

如果你只对表单的一部分输入进行 Precognition 验证，手动清除错误可能会很有用。你可以使用表单的 forgetError 函数来实现：

<input
    id="avatar"
    type="file"
    onChange={(e) => {
        form.setData('avatar', e.target.value);

        form.forgetError('avatar');
    }}
>

如我们所见，你可以挂载输入的 blur 事件，在用户与其交互时验证单个输入；然而，你可能还需要验证用户尚未互动的输入。这在构建“向导（wizard）”时很常见，你希望在进入下一步之前，验证所有可见输入，无论用户是否已与其互动。

无与伦比 翻译于 3周前
重译

要使用 Precognition 实现这一点，你应该调用 validate 方法，并将希望验证的字段名称通过 only 配置键传入。你可以使用 onSuccess 或 onValidationError 回调处理验证结果：

<button
    type="button"
    onClick={() => form.validate({
        only: ['name', 'email', 'phone'],
        onSuccess: (response) => nextStep(),
        onValidationError: (response) => /* ... */,
    })}
>Next Step</button>

当然，你也可以在表单提交响应后执行相应的代码。表单的 submit 函数会返回一个 Axios 请求的 Promise。这提供了一种方便的方式来访问响应数据、在表单提交成功时重置表单输入，或处理请求失败：

const submit = (e) => {
    e.preventDefault();

    form.submit()
        .then(response => {
            form.reset();

            alert('User created.');
        })
        .catch(error => {
            alert('An error occurred.');
        });
};

你可以通过检查表单的 processing 属性来判断表单提交请求是否正在进行中：

<button disabled={form.processing}>
    提交
</button>

在 React 和 Inertia 中使用

[!注意]
如果你希望在使用 React 和 Inertia 开发 Laravel 应用时有一个快速起步，可以考虑使用我们的 starter kits。Laravel 的 starter kits 为你的新 Laravel 应用提供后端和前端的身份验证脚手架。

在 React 和 Inertia 中使用 Precognition 之前，请务必先查看我们关于 在 React 中使用 Precognition 的通用文档。当使用 React 和 Inertia 时，你需要通过 NPM 安装与 Inertia 兼容的 Precognition 库：

npm install laravel-precognition-react-inertia

安装完成后，Precognition 的 useForm 函数将返回一个增强了上述验证功能的 Inertia 表单助手。

无与伦比 翻译于 3周前
重译

表单助手的 submit 方法已经被简化，不再需要指定 HTTP 方法或 URL。相反，你可以将 Inertia 的 visit 选项 作为唯一参数传入。此外，submit 方法不像上面的 React 示例那样返回一个 Promise。相反，你可以在传给 submit 方法的访问选项中提供任何 Inertia 支持的 事件回调：

import { useForm } from 'laravel-precognition-react-inertia';

const form = useForm('post', '/users', {
    name: '',
    email: '',
});

const submit = (e) => {
    e.preventDefault();

    form.submit({
        preserveScroll: true,
        onSuccess: () => form.reset(),
    });
};

在 Alpine 和 Blade 中使用

使用 Laravel Precognition，你可以为用户提供实时验证体验，而无需在前端 Alpine 应用中重复你的验证规则。为了说明它的工作原理，让我们构建一个用于在应用中创建新用户的表单。

首先，为了在路由上启用 Precognition，需要将 HandlePrecognitiveRequests 中间件添加到路由定义中。同时，你应该创建一个 表单请求 来存放该路由的验证规则：

use App\Http\Requests\CreateUserRequest;
use Illuminate\Foundation\Http\Middleware\HandlePrecognitiveRequests;

Route::post('/users', function (CreateUserRequest $request) {
    // ...
})->middleware([HandlePrecognitiveRequests::class]);

接下来，你需要通过 NPM 安装用于 Alpine 的 Laravel Precognition 前端助手：

npm install laravel-precognition-alpine

然后，在你的 resources/js/app.js 文件中注册 Precognition 插件到 Alpine：

import Alpine from 'alpinejs';
import Precognition from 'laravel-precognition-alpine';

window.Alpine = Alpine;

Alpine.plugin(Precognition);
Alpine.start();
无与伦比 翻译于 3周前
重译

查看其他 1 个版本

在安装并注册 Laravel Precognition 包之后，你现在可以使用 Precognition 的 $form “魔法”创建一个表单对象，提供 HTTP 方法（post）、目标 URL（/users）以及初始表单数据。

为了启用实时验证，你应该将表单的数据绑定到对应的输入框，然后监听每个输入框的 change 事件。在 change 事件处理器中，你应该调用表单的 validate 方法，并提供输入框的名称：

<form x-data="{
    form: $form('post', '/register', {
        name: '',
        email: '',
    }),
}">
    @csrf
    <label for="name">姓名</label>
    <input
        id="name"
        name="name"
        x-model="form.name"
        @change="form.validate('name')"
    />
    <template x-if="form.invalid('name')">
        <div x-text="form.errors.name"></div>
    </template>

    <label for="email">邮箱</label>
    <input
        id="email"
        name="email"
        x-model="form.email"
        @change="form.validate('email')"
    />
    <template x-if="form.invalid('email')">
        <div x-text="form.errors.email"></div>
    </template>

    <button :disabled="form.processing">
        创建用户
    </button>
</form>

现在，当用户填写表单时，Precognition 将根据路由表单请求中的验证规则提供实时验证输出。当表单的输入发生变化时，会发送一个经过防抖处理的“预知（precognitive）”验证请求到你的 Laravel 应用。你可以通过调用表单的 setValidationTimeout 函数来配置防抖超时时间：

form.setValidationTimeout(3000);

当验证请求正在进行中时，表单的 validating 属性将为 true：

<template x-if="form.validating">
    <div>Validating...</div>
</template>

在验证请求或表单提交期间返回的任何验证错误，将自动填充到表单的 errors 对象中：

<template x-if="form.invalid('email')">
    <div x-text="form.errors.email"></div>
</template>
无与伦比 翻译于 3周前
重译

查看其他 1 个版本

你可以通过表单的 hasErrors 属性来判断表单是否有任何错误：

<template x-if="form.hasErrors">
    <div><!-- ... --></div>
</template>

你也可以通过将输入字段的名称传递给表单的 valid 和 invalid 函数，分别判断该输入是否验证通过或失败：

<template x-if="form.valid('email')">
    <span>✅</span>
</template>

<template x-if="form.invalid('email')">
    <span>❌</span>
</template>

[!警告]
表单输入只有在其值发生变化并且接收到验证响应后，才会显示为有效或无效。

正如我们所见，你可以挂钩输入的 change 事件，并在用户与输入交互时验证单个输入；然而，你可能需要验证用户尚未交互的输入。这在构建“向导”时很常见，你希望在进入下一步之前验证所有可见的输入，而不管用户是否与它们交互过。

要在 Precognition 中做到这一点，你应该调用 validate 方法，并将你想要验证的字段名称传递给 only 配置项。你可以使用 onSuccess 或 onValidationError 回调来处理验证结果：

<button
    type="button"
    @click="form.validate({
        only: ['name', 'email', 'phone'],
        onSuccess: (response) => nextStep(),
        onValidationError: (response) => /* ... */,
    })"
>Next Step</button>

你可以通过检查表单的 processing 属性来判断表单提交请求是否正在进行中：

<button :disabled="form.processing">
    Submit
</button>

重新填充旧的表单数据

在上面讨论的用户创建示例中，我们使用 Precognition 执行实时验证；然而，我们通过传统的服务端表单提交来提交表单。因此，表单应填充从服务端表单提交返回的任何“旧”输入和验证错误：

<form x-data="{
    form: $form('post', '/register', {
        name: '{{ old('name') }}',
        email: '{{ old('email') }}',
    }).setErrors({{ Js::from($errors->messages()) }}),
}">
无与伦比 翻译于 2周前
重译

或者，如果你想通过 XHR 提交表单，可以使用表单的 submit 函数，该函数会返回一个 Axios 请求的 promise：

<form
    x-data="{
        form: $form('post', '/register', {
            name: '',
            email: '',
        }),
        submit() {
            this.form.submit()
                .then(response => {
                    this.form.reset();

                    alert('User created.')
                })
                .catch(error => {
                    alert('An error occurred.');
                });
        },
    }"
    @submit.prevent="submit"
>

配置 Axios

Precognition 验证库使用 Axios HTTP 客户端向你的应用后端发送请求。为了方便起见，如果应用需要，可以自定义 Axios 实例。例如，当使用 laravel-precognition-vue 库时，你可以在应用的 resources/js/app.js 文件中为每个发出的请求添加额外的请求头：

import { client } from 'laravel-precognition-vue';

client.axios().defaults.headers.common['Authorization'] = authToken;

或者，如果你的应用已经有一个配置好的 Axios 实例，你可以让 Precognition 使用该实例：

import Axios from 'axios';
import { client } from 'laravel-precognition-vue';

window.axios = Axios.create()
window.axios.defaults.headers.common['Authorization'] = authToken;

client.use(window.axios)

[!警告]
Inertia 版本的 Precognition 库只会在验证请求中使用配置好的 Axios 实例。表单提交始终会由 Inertia 发送。

自定义验证规则

可以通过使用请求的 isPrecognitive 方法自定义在预感（precognitive）请求期间执行的验证规则。

例如，在用户创建表单中，我们可能只想在最终表单提交时验证密码是否“未泄露”。而对于预感验证请求，我们只需验证密码是必填的，并且至少有 8 个字符。通过使用 isPrecognitive 方法，我们可以自定义表单请求定义的规则：

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rules\Password;

class StoreUserRequest extends FormRequest
{
    /**
     * 获取适用于该请求的验证规则
     *
     * @return array
     */
    protected function rules()
    {
        return [
            'password' => [
                'required',
                $this->isPrecognitive()
                    ? Password::min(8)
                    : Password::min(8)->uncompromised(),
            ],
            // ...
        ];
    }
}
无与伦比 翻译于 2周前
重译

处理文件上传

默认情况下，Laravel Precognition 不会在预感（precognitive）验证请求期间上传或验证文件。这样可以确保大文件不会被不必要地多次上传。

由于这种行为，你应该确保你的应用 自定义对应表单请求的验证规则，以指定该字段仅在完整的表单提交时才是必填的：

/**
 * 获取适用于该请求的验证规则
 *
 * @return array
 */
protected function rules()
{
    return [
        'avatar' => [
            ...$this->isPrecognitive() ? [] : ['required'],
            'image',
            'mimes:jpg,png',
            'dimensions:ratio=3/2',
        ],
        // ...
    ];
}

如果你希望在每次验证请求中都包含文件，可以在客户端表单实例上调用 validateFiles 函数：

form.validateFiles();

管理副作用

当你将 HandlePrecognitiveRequests 中间件添加到路由时，你应该考虑是否存在其他中间件中的副作用需要在预感请求期间被跳过。

例如，你可能有一个中间件会增加用户与应用的“交互”总数，但你可能不希望预感请求被计为一次交互。为了实现这一点，我们可以在增加交互计数之前检查请求的 isPrecognitive 方法：

<?php

namespace App\Http\Middleware;

use App\Facades\Interaction;
use Closure;
use Illuminate\Http\Request;

class InteractionMiddleware
{
    /**
     * 处理传入的请求
     */
    public function handle(Request $request, Closure $next): mixed
    {
        if (! $request->isPrecognitive()) {
            Interaction::incrementFor($request->user());
        }

        return $next($request);
    }
}

测试

如果你希望在测试中发起预感请求，Laravel 的 TestCase 提供了一个 withPrecognition 辅助方法，它会添加 Precognition 请求头。

此外，如果你希望断言一个预感请求成功（例如：没有返回任何验证错误），你可以在响应上使用 assertSuccessfulPrecognition 方法：

it('validates registration form with precognition', function () {
    $response = $this->withPrecognition()
        ->post('/register', [
            'name' => 'Taylor Otwell',
        ]);

    $response->assertSuccessfulPrecognition();

    expect(User::count())->toBe(0);
});
public function test_it_validates_registration_form_with_precognition()
{
    $response = $this->withPrecognition()
        ->post('/register', [
            'name' => 'Taylor Otwell',
        ]);

    $response->assertSuccessfulPrecognition();
    $this->assertSame(0, User::count());
}
无与伦比 翻译于 2周前
重译

本文章首发在 LearnKu.com 网站上。

本文中的所有译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。
《L03 构架 API 服务器》
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程，JWT 概念及使用 和 API 开发相关的进阶知识。
《L01 基础入门》
《L01 基础入门》
我们将带你从零开发一个项目并部署到线上，本课程教授 Web 开发中专业、实用的技能，如 Git 工作流、Laravel Mix 前端工作流等。
贡献者：1
讨论数量: 0
发起讨论 只看当前版本


暂无话题~