Livewire 中文文档

主题

文件上传 ​

Livewire 为在组件中上传文件提供了强大的支持。

首先，将 WithFileUploads trait 添加到你的组件中。一旦将此 trait 添加到组件中，你就可以像使用任何其他输入类型一样在文件输入上使用 wire:model，Livewire 将处理其余的工作。

以下是处理照片上传的简单组件示例：

php
<?php // resources/views/components/⚡upload-photo.blade.php

use Livewire\Attributes\Validate;
use Livewire\WithFileUploads;
use Livewire\Component;

new class extends Component
{
    use WithFileUploads;

    #[Validate('image|max:1024')] // 1MB Max
    public $photo;

    public function save()
    {
        $this->photo->store(path: 'photos');
    }
};
blade
<form wire:submit="save">
    <input type="file" wire:model="photo">

    @error('photo') <span class="error">{{ $message }}</span> @enderror

    <button type="submit">Save photo</button>
</form>

"upload" 方法是保留的

请注意，上面的示例使用 "save" 方法而不是 "upload" 方法。这是一个常见的"陷阱"。"upload" 一词被 Livewire 保留。你不能将其用作组件中的方法或属性名称。

从开发者的角度来看，处理文件输入与处理任何其他输入类型没有什么不同：将 wire:model 添加到 <input> 标签，其他一切都会为你处理。

然而，在幕后发生了更多的事情来使文件上传在 Livewire 中工作。以下是用户选择要上传的文件时发生的情况：

  1. 当选择新文件时，Livewire 的 JavaScript 向服务器上的组件发出初始请求，以获取临时的"签名"上传 URL。
  2. 一旦收到 URL，JavaScript 将实际"上传"到签名 URL，将上传存储在 Livewire 指定的临时目录中，并返回新临时文件的唯一哈希 ID。
  3. 一旦文件上传并生成唯一哈希 ID，Livewire 的 JavaScript 向服务器上的组件发出最终请求，告诉它将所需的公共属性"设置"为新的临时文件。
  4. 现在，公共属性（在本例中为 $photo）设置为临时文件上传，并准备好在任何时候存储或验证。

存储上传的文件 ​

前面的示例演示了最基本的存储场景：将临时上传的文件移动到应用程序默认文件系统磁盘上的 "photos" 目录。

但是，你可能希望自定义存储文件的文件名，甚至指定一个特定的存储"磁盘"来保存文件（例如 S3）。

原始文件名

你可以通过调用临时上传的 ->getClientOriginalName() 方法来访问其原始文件名。

Livewire 遵循 Laravel 用于存储上传文件的相同 API，因此请随意查阅 Laravel 的文件上传文档。但是，以下是一些常见的存储场景和示例：

php
public function save()
{
    // Store the file in the "photos" directory of the default filesystem disk
    $this->photo->store(path: 'photos');

    // Store the file in the "photos" directory in a configured "s3" disk
    $this->photo->store(path: 'photos', options: 's3');

    // Store the file in the "photos" directory with the filename "avatar.png"
    $this->photo->storeAs(path: 'photos', name: 'avatar');

    // Store the file in the "photos" directory in a configured "s3" disk with the filename "avatar.png"
    $this->photo->storeAs(path: 'photos', name: 'avatar', options: 's3');

    // Store the file in the "photos" directory, with "public" visibility in a configured "s3" disk
    $this->photo->storePublicly(path: 'photos', options: 's3');

    // Store the file in the "photos" directory, with the name "avatar.png", with "public" visibility in a configured "s3" disk
    $this->photo->storePubliclyAs(path: 'photos', name: 'avatar', options: 's3');
}

处理多个文件 ​

Livewire 通过检测 <input> 标签上的 multiple 属性自动处理多个文件上传。

例如，下面是一个具有名为 $photos 的数组属性的组件。通过在表单的文件输入中添加 multiple，Livewire 将自动将新文件追加到此数组：

php
<?php // resources/views/components/⚡upload-photos.blade.php

use Livewire\Attributes\Validate;
use Livewire\WithFileUploads;
use Livewire\Component;

new class extends Component
{
    use WithFileUploads;

    #[Validate(['photos.*' => 'image|max:1024'])]
    public $photos = [];

    public function save()
    {
        foreach ($this->photos as $photo) {
            $photo->store(path: 'photos');
        }
    }
};
blade
<form wire:submit="save">
    <input type="file" wire:model="photos" multiple>

    @error('photos.*') <span class="error">{{ $message }}</span> @enderror

    <button type="submit">Save photo</button>
</form>

文件验证 ​

如我们所讨论的，使用 Livewire 验证文件上传与从标准 Laravel 控制器处理文件上传相同。

确保 S3 已正确配置

许多与文件相关的验证规则需要访问文件。当直接上传到 S3 时，如果 S3 文件对象不可公开访问，这些验证规则将失败。

有关文件验证的更多信息，请查阅 Laravel 的文件验证文档。

临时预览 URL ​

在用户选择文件后，通常应在他们提交表单并存储文件之前向他们显示该文件的预览。

Livewire 通过在上传的文件上使用 ->temporaryUrl() 方法使这变得微不足道。

临时 URL 仅限于图片

出于安全原因，临时预览 URL 仅支持具有图片 MIME 类型的文件。

让我们探索一个带有图片预览的文件上传示例：

php
<?php // resources/views/components/⚡upload-photo.blade.php

use Livewire\Attributes\Validate;
use Livewire\WithFileUploads;
use Livewire\Component;

new class extends Component
{
    use WithFileUploads;

    #[Validate('image|max:1024')]
    public $photo;

    // ...
};
blade
<form wire:submit="save">
    @if ($photo) <!-- [tl! highlight:2] -->
        <img src="{{ $photo->temporaryUrl() }}">
    @endif

    <input type="file" wire:model="photo">

    @error('photo') <span class="error">{{ $message }}</span> @enderror

    <button type="submit">Save photo</button>
</form>

如前所述，Livewire 将临时文件存储在非公共目录中；因此，通常没有简单的方法向用户公开临时公共 URL 以进行图片预览。

但是，Livewire 通过提供一个临时的签名 URL 来解决此问题，该 URL 假装是上传的图片，以便你的页面可以向用户显示图片预览。

此 URL 受保护，不会显示临时目录上层目录中的文件。而且，因为它是签名的，用户无法滥用此 URL 来预览系统上的其他文件。

S3 临时签名 URL

如果你已配置 Livewire 使用 S3 进行临时文件存储，调用 ->temporaryUrl() 将直接生成指向 S3 的临时签名 URL，以便图片预览不会从 Laravel 应用服务器加载。

测试文件上传 ​

你可以使用 Laravel 现有的文件上传测试辅助函数来测试文件上传。

以下是使用 Livewire 测试 UploadPhoto 组件的完整示例：

php
<?php

namespace Tests\Feature\Livewire;

use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Storage;
use App\Livewire\UploadPhoto;
use Livewire\Livewire;
use Tests\TestCase;

class UploadPhotoTest extends TestCase
{
    public function test_can_upload_photo()
    {
        Storage::fake('avatars');

        $file = UploadedFile::fake()->image('avatar.png');

        Livewire::test(UploadPhoto::class)
            ->set('photo', $file)
            ->call('upload', 'uploaded-avatar.png');

        Storage::disk('avatars')->assertExists('uploaded-avatar.png');
    }
}

以下是使前面的测试通过所需的 upload-photo 组件示例：

php
<?php // resources/views/components/⚡upload-photo.blade.php

use Livewire\WithFileUploads;
use Livewire\Component;

new class extends Component
{
    use WithFileUploads;

    public $photo;

    public function upload($name)
    {
        $this->photo->storeAs('/', $name, disk: 'avatars');
    }

    // ...
};

有关测试文件上传的更多信息，请查阅 Laravel 的文件上传测试文档。

直接上传到 Amazon S3 ​

如前所述，Livewire 将所有文件上传存储在临时目录中，直到开发者永久存储文件。

默认情况下，Livewire 使用默认的文件系统磁盘配置（通常是 local），并将文件存储在 livewire-tmp/ 目录中。

因此，文件上传始终使用你的应用服务器，即使你选择稍后将上传的文件存储在 S3 存储桶中也是如此。

如果你希望绕过应用服务器，而是将 Livewire 的临时上传存储在 S3 存储桶中，可以在应用程序的 config/livewire.php 配置文件中配置该行为。首先，将 livewire.temporary_file_upload.disk 设置为 s3（或使用 s3 驱动程序的另一个自定义磁盘）：

php
return [
    // ...
    'temporary_file_upload' => [
        'disk' => 's3',
        // ...
    ],
];

现在，当用户上传文件时，文件实际上永远不会存储在你的服务器上。相反，它将直接上传到 S3 存储桶内的 livewire-tmp/ 子目录。

发布 Livewire 的配置文件

在自定义文件上传磁盘之前，你必须首先通过运行以下命令将 Livewire 的配置文件发布到应用程序的 /config 目录：

shell
php artisan livewire:publish --config

配置自动文件清理 ​

Livewire 的临时上传目录将很快被文件填满；因此，必须配置 S3 来清理超过 24 小时的文件。

要配置此行为，请从正在使用 S3 存储桶进行文件上传的环境运行以下 Artisan 命令：

shell
php artisan livewire:configure-s3-upload-cleanup

现在，任何超过 24 小时的临时文件都将由 S3 自动清理。

INFO

如果你不使用 S3 进行文件存储，Livewire 将自动处理文件清理，无需运行上述命令。

加载指示器 ​

尽管文件上传的 wire:model 在幕后的工作方式与其他 wire:model 输入类型不同，但显示加载指示器的界面保持不变。

你可以显示范围限定为文件上传的加载指示器，如下所示：

blade
<input type="file" wire:model="photo">

<div wire:loading wire:target="photo">Uploading...</div>

现在，在文件上传时，将显示"Uploading..."消息，然后在上传完成时隐藏。

有关加载状态的更多信息，请查看我们全面的加载状态文档。

进度指示器 ​

每个 Livewire 文件上传操作都会在相应的 <input> 元素上分发 JavaScript 事件，允许自定义 JavaScript 拦截事件：

事件描述
livewire-upload-start在上传开始时分发
livewire-upload-finish如果上传成功完成则分发
livewire-upload-cancel如果上传被过早取消则分发
livewire-upload-error如果上传失败则分发
livewire-upload-progress包含上传进度百分比的事件，随着上传的进行而更新

以下是将 Livewire 文件上传包装在 Alpine 组件中以显示上传进度条的示例：

blade
<form wire:submit="save">
    <div
        x-data="{ uploading: false, progress: 0 }"
        x-on:livewire-upload-start="uploading = true"
        x-on:livewire-upload-finish="uploading = false"
        x-on:livewire-upload-cancel="uploading = false"
        x-on:livewire-upload-error="uploading = false"
        x-on:livewire-upload-progress="progress = $event.detail.progress"
    >
        <!-- File Input -->
        <input type="file" wire:model="photo">

        <!-- Progress Bar -->
        <div x-show="uploading">
            <progress max="100" x-bind:value="progress"></progress>
        </div>
    </div>

    <!-- ... -->
</form>

取消上传 ​

如果上传时间过长，用户可能希望取消它。你可以使用 Livewire 的 JavaScript $cancelUpload() 函数提供此功能。

以下是在 Livewire 组件中创建"取消上传"按钮的示例，使用 wire:click 处理点击事件：

blade
<form wire:submit="save">
    <!-- File Input -->
    <input type="file" wire:model="photo">

    <!-- Cancel upload button -->
    <button type="button" wire:click="$cancelUpload('photo')">Cancel Upload</button>

    <!-- ... -->
</form>

当按下"取消上传"时，文件上传请求将被中止，文件输入将被清除。用户现在可以尝试使用不同的文件进行另一次上传。

或者，你可以从 Alpine 中调用 cancelUpload(...)，如下所示：

blade
<button type="button" x-on:click="$wire.cancelUpload('photo')">Cancel Upload</button>

JavaScript 上传 API ​

与第三方文件上传库集成通常需要比简单的 <input type="file" wire:model="..."> 元素更多的控制。

对于这些场景，Livewire 公开了专用的 JavaScript 函数。

这些函数存在于 JavaScript 组件对象上，可以使用 Livewire 方便的 $wire 对象从 Livewire 组件的模板中访问：

blade
@script
<script>
    let file = $wire.el.querySelector('input[type="file"]').files[0]

    // Upload a file...
    $wire.upload('photo', file, (uploadedFilename) => {
        // Success callback...
    }, () => {
        // Error callback...
    }, (event) => {
        // Progress callback...
        // event.detail.progress contains a number between 1 and 100 as the upload progresses
    }, () => {
        // Cancelled callback...
    })

    // Upload multiple files...
    $wire.uploadMultiple('photos', [file], successCallback, errorCallback, progressCallback, cancelledCallback)

    // Remove single file from multiple uploaded files...
    $wire.removeUpload('photos', uploadedFilename, successCallback)

    // Cancel an upload...
    $wire.cancelUpload('photos')
</script>
@endscript

配置 ​

由于 Livewire 将所有文件上传存储在临时目录中，直到开发者永久存储文件，因此它假设所有文件上传的默认处理行为。

全局验证 ​

默认情况下，Livewire 将使用以下规则验证所有临时文件上传：file|max:12288（必须是小于 12MB 的文件）。

如果你希望自定义这些规则，可以在应用程序的 config/livewire.php 配置文件中进行：

php
'temporary_file_upload' => [
    // ...
    'rules' => 'file|mimes:png,jpg,pdf|max:102400', // (100MB max, and only accept PNGs, JPEGs, and PDFs)
],

全局中间件 ​

临时文件上传端点默认分配了一个节流中间件。你可以通过以下配置选项自定义此端点使用的中间件：

php
'temporary_file_upload' => [
    // ...
    'middleware' => 'throttle:5,1', // Only allow 5 uploads per user per minute
],

临时上传目录 ​

临时文件上传到指定磁盘的 livewire-tmp/ 目录。你可以通过以下配置选项自定义此目录：

php
'temporary_file_upload' => [
    // ...
    'directory' => 'tmp',
],