Livewire v3 wire:loading

wire:loading

ローディングインジケーターは、優れたユーザーインターフェイスを作成する上で重要な要素です。サーバにリクエストが送信されている際に、ユーザーに視覚的なフィードバックを提供し、処理の完了を待っていることを知らせます。Loading indicators are an important part of crafting good user interfaces. They give users visual feedback when a request is being made to the server, so they know they are waiting for a process to complete.

基本的な使用法Basic usage

Livewireは、ローディングインジケーターを制御するためのシンプルかつ非常に強力な構文を提供します。それが wire:loading です。wire:loading を任意の要素に追加すると、デフォルトでその要素は非表示になり（CSSで display: none を使用）、リクエストがサーバに送信されると表示されます。Livewire provides a simple yet extremely powerful syntax for controlling loading indicators: wire:loading. Adding wire:loading to any element will hide it by default (using display: none in CSS) and show it when a request is sent to the server.

以下は、CreatePost コンポーネントのフォームで wire:loading を使用してローディングメッセージを切り替える基本的な例です。Below is a basic example of a CreatePost component's form with wire:loading being used to toggle a loading message:

<form wire:submit="save">
    <!-- ... -->

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

    <div wire:loading> <!-- [tl! highlight:2] -->
        Saving post...
    </div>
</form>

ユーザーが「Save」を押すと、「save」アクションが実行されている間、ボタンの下に「Saving post...」というメッセージが表示されます。メッセージは、サーバからの応答が受信され、Livewireによって処理されると消えます。When a user presses "Save", the "Saving post..." message will appear below the button while the "save" action is being executed. The message will disappear when the response is received from the server and processed by Livewire.

要素の削除Removing elements

あるいは、逆の効果を得るために .remove を追加して、要素をデフォルトで表示し、サーバへのリクエスト中に非表示にすることができます。Alternatively, you can append .remove for the inverse effect, showing an element by default and hiding it during requests to the server:

<div wire:loading.remove>...</div>

クラスの切り替えToggling classes

要素の表示/非表示を切り替えるだけでなく、サーバへのリクエスト中にCSSクラスをオン/オフすることで、既存の要素のスタイルを変更すると便利なことがよくあります。このテクニックは、背景色の変更、不透明度の低下、スピニングアニメーションのトリガーなどに使用できます。In addition to toggling the visibility of entire elements, it's often useful to change the styling of an existing element by toggling CSS classes on and off during requests to the server. This technique can be used for things like changing background colors, lowering opacity, triggering spinning animations, and more.

以下は、Tailwind クラス opacity-50 を使用して、フォームの送信中に「Save」ボタンを薄くする簡単な例です。Below is a simple example of using the Tailwind[https://tailwindcss.com/] class opacity-50 to make the "Save" button fainter while the form is being submitted:

<button wire:loading.class="opacity-50">Save</button>

要素の切り替えと同様に、wire:loading ディレクティブに .remove を追加することで、逆のクラス操作を実行できます。以下の例では、「Save」ボタンが押されると、ボタンの bg-blue-500 クラスが削除されます。Like toggling an element, you can perform the inverse class operation by appending .remove to the wire:loading directive. In the example below, the button's bg-blue-500 class will be removed when the "Save" button is pressed:

<button class="bg-blue-500" wire:loading.class.remove="bg-blue-500">
    Save
</button>

属性の切り替えToggling attributes

デフォルトでは、フォームが送信されると、Livewireは自動的に送信ボタンを無効にし、フォームの処理中に各入力要素に readonly 属性を追加します。By default, when a form is submitted, Livewire will automatically disable the submit button and add the readonly attribute to each input element while the form is being processed.

ただし、このデフォルトの動作に加えて、Livewireは .attr 修飾子を提供し、要素の他の属性を切り替えたり、フォーム外の要素の属性を切り替えたりすることができます。However, in addition to this default behavior, Livewire offers the .attr modifier to allow you to toggle other attributes on an element or toggle attributes on elements that are outside of forms:

<button
    type="button"
    wire:click="remove"
    wire:loading.attr="disabled"
>
    Remove
</button>

上記のボタンは送信ボタンではないため、押してもLivewireのデフォルトのフォーム処理動作によって無効にされることはありません。代わりに、この動作を実現するために wire:loading.attr="disabled" を手動で追加しました。Because the button above isn't a submit button, it won't be disabled by Livewire's default form handling behavior when pressed. Instead, we manually added wire:loading.attr="disabled" to achieve this behavior.

特定のアクションをターゲットにするTargeting specific actions

デフォルトでは、wire:loading はコンポーネントがサーバにリクエストを行うたびにトリガーされます。By default, wire:loading will be triggered whenever a component makes a request to the server.

ただし、サーバリクエストをトリガーできる複数の要素を持つコンポーネントでは、ローディングインジケーターを個々のアクションに絞り込む必要があります。However, in components with multiple elements that can trigger server requests, you should scope your loading indicators down to individual actions.

たとえば、次の「Save post」フォームを考えてみましょう。フォームを送信する「Save」ボタンに加えて、コンポーネントで「remove」アクションを実行する「Remove」ボタンもあるかもしれません。For example, consider the following "Save post" form. In addition to a "Save" button that submits the form, there might also be a "Remove" button that executes a "remove" action on the component.

次の wire:loading 要素に wire:target を追加することで、「Remove」ボタンがクリックされたときにのみローディングメッセージを表示するようにLivewireに指示できます。By adding wire:target to the following wire:loading element, you can instruct Livewire to only show the loading message when the "Remove" button is clicked:

<form wire:submit="save">
    <!-- ... -->

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

    <button type="button" wire:click="remove">Remove</button>

    <div wire:loading wire:target="remove">  <!-- [tl! highlight:2] -->
        Removing post...
    </div>
</form>

上記の「Remove」ボタンが押されると、「Removing post...」というメッセージがユーザーに表示されます。ただし、「Save」ボタンが押された場合は、メッセージは表示されません。When the above "Remove" button is pressed, the "Removing post..." message will be displayed to the user. However, the message will not be displayed when the "Save" button is pressed.

複数のアクションをターゲットにするTargeting multiple actions

ページ上のいくつかのアクションに対してのみ wire:loading を反応させたい場合があります。このような場合は、コンマで区切られた複数のアクションを wire:target に渡すことができます。例：You may find yourself in a situation where you would like wire:loading to react to some, but not all, actions on a page. In these cases you can pass multiple actions into wire:target separated by a comma. For example:

<form wire:submit="save">
    <input type="text" wire:model.blur="title">

    <!-- ... -->

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

    <button type="button" wire:click="remove">Remove</button>

    <div wire:loading wire:target="save, remove">  <!-- [tl! highlight:2] -->
        Updating post...
    </div>
</form>

ローディングインジケーター（「Updating post...」）は、「Remove」または「Save」ボタンが押されたときにのみ表示され、$title フィールドがサーバに送信されているときは表示されなくなります。The loading indicator ("Updating post...") will now only be shown when the "Remove" or "Save" button are pressed, and not when the $title field is being sent to the server.

アクションパラメーターをターゲットにするTargeting action parameters

ページ上の複数の場所から同じアクションが異なるパラメーターでトリガーされる状況では、追加のパラメーターを渡すことによって、wire:target を特定のアクションにさらに絞り込むことができます。たとえば、ページ上の各投稿に「Remove」ボタンが存在する次のシナリオを考えてみましょう。In situations where the same action is triggered with different parameters from multiple places on a page, you can further scope wire:target to a specific action by passing in additional parameters. For example, consider the following scenario where a "Remove" button exists for each post on the page:

<div>
    @foreach ($posts as $post)
        <div wire:key="{{ $post->id }}">
            <h2>{{ $post->title }}</h2>

            <button wire:click="remove({{ $post->id }})">Remove</button>

            <div wire:loading wire:target="remove({{ $post->id }})">  <!-- [tl! highlight:2] -->
                Removing post...
            </div>
        </div>
    @endforeach
</div>

{{ $post->id }} を wire:target="remove" に渡さないと、ページ上のいずれかのボタンがクリックされたときに「Removing post...」というメッセージが表示されます。Without passing {{ $post->id }} to wire:target="remove", the "Removing post..." message would show when any of the buttons on the page are clicked.

ただし、wire:target の各インスタンスに一意のパラメーターを渡しているため、Livewireは、一致するパラメーターが「remove」アクションに渡された場合にのみ、ローディングメッセージを表示します。However, because we are passing in unique parameters to each instance of wire:target, Livewire will only show the loading message when the matching parameters are passed to the "remove" action.

warning Warning! 複数のアクションパラメーターはサポートされていません 現時点では、Livewireは、単一のメソッド/パラメーターペアによるローディングインジケーターのターゲット設定のみをサポートしています。たとえば、wire:target="remove(1)" はサポートされていますが、wire:target="remove(1), add(1)" はサポートされていません。[!warning] Multiple action parameters aren't supported At this time, Livewire only supports targeting a loading indicator by a single method/parameter pair. For example wire:target="remove(1)" is supported, however wire:target="remove(1), add(1)" is not.

プロパティの更新をターゲットにするTargeting property updates

Livewireでは、プロパティの名前を wire:target ディレクティブに渡すことによって、特定のコンポーネントプロパティの更新をターゲットにすることもできます。Livewire also allows you to target specific component property updates by passing the property's name to the wire:target directive.

ユーザーが入力するときにリアルタイム検証に wire:model.live を使用する username という名前のフォーム入力の次の例を考えてみましょう。Consider the following example where a form input named username uses wire:model.live for real-time validation as a user types:

<form wire:submit="save">
    <input type="text" wire:model.live="username">
    @error('username') <span>{{ $message }}</span> @enderror

    <div wire:loading wire:target="username"> <!-- [tl! highlight:2] -->
        Checking availability of username...
    </div>

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

ユーザーが入力フィールドに入力すると、新しいユーザー名でサーバが更新されたときに、「Checking availability...」というメッセージが表示されます。The "Checking availability..." message will show when the server is updated with the new username as the user types into the input field.

特定のローディングターゲットを除外するExcluding specific loading targets

特定のプロパティまたはアクションを除く、すべてのLivewireリクエストに対してローディングインジケーターを表示したい場合があります。このような場合は、次のように wire:target.except 修飾子を使用できます。Sometimes you may wish to display a loading indicator for every Livewire request except a specific property or action. In these cases you can use the wire:target.except modifier like so:

<div wire:loading wire:target.except="download">...</div>

上記のローディングインジケーターは、コンポーネント上の「download」アクションを除く、すべてのLivewire更新リクエストに対して表示されるようになります。The above loading indicator will now be shown for every Livewire update request on the component except the "download" action.

CSSのdisplayプロパティのカスタマイズCustomizing CSS display property

wire:loading が要素に追加されると、Livewireは要素のCSS display プロパティを更新して、要素の表示と非表示を切り替えます。デフォルトでは、Livewireは非表示に none を、表示に inline-block を使用します。When wire:loading is added to an element, Livewire updates the CSS display property of the element to show and hide the element. By default, Livewire uses none to hide and inline-block to show.

次の例のように、flex などの inline-block 以外の表示値を使用する要素を切り替える場合は、wire:loading に .flex を追加できます。If you are toggling an element that uses a display value other than inline-block, like flex in the following example, you can append .flex to wire:loading:

<div class="flex" wire:loading.flex>...</div>

以下は、使用可能な表示値の完全なリストです。Below is the complete list of available display values:

<div wire:loading.inline-flex>...</div>
<div wire:loading.inline>...</div>
<div wire:loading.block>...</div>
<div wire:loading.table>...</div>
<div wire:loading.flex>...</div>
<div wire:loading.grid>...</div>

ローディングインジケーターの遅延Delaying a loading indicator

高速な接続では、更新が非常に迅速に行われるため、ローディングインジケーターは画面に短時間だけ表示されてから削除されることがよくあります。このような場合、インジケーターは役立つアフォーダンスというよりも、気を散らすものになります。On fast connections, updates often happen so quickly that loading indicators only flash briefly on the screen before being removed. In these cases, the indicator is more of a distraction than a helpful affordance.

このため、Livewireには、インジケーターの表示を遅延させる .delay 修飾子が用意されています。たとえば、次のように wire:loading.delay を要素に追加するとします。For this reason, Livewire provides a .delay modifier to delay the showing of an indicator. For example, if you add wire:loading.delay to an element like so:

<div wire:loading.delay>...</div>

上記要素は、リクエストに200ミリ秒以上かかる場合にのみ表示されます。リクエストがそれより前に完了した場合、ユーザーはインジケーターを見ることはありません。The above element will only appear if the request takes over 200 milliseconds. The user will never see the indicator if the request completes before then.

ローディングインジケーターを遅延させる時間をカスタマイズするには、Livewireの便利なインターバルエイリアスのいずれかを使用できます。To customize the amount of time to delay the loading indicator, you can use one of Livewire's helpful interval aliases:

<div wire:loading.delay.shortest>...</div> <!-- 50ms -->
<div wire:loading.delay.shorter>...</div>  <!-- 100ms -->
<div wire:loading.delay.short>...</div>    <!-- 150ms -->
<div wire:loading.delay>...</div>          <!-- 200ms -->
<div wire:loading.delay.long>...</div>     <!-- 300ms -->
<div wire:loading.delay.longer>...</div>   <!-- 500ms -->
<div wire:loading.delay.longest>...</div>  <!-- 1000ms -->