Parámetros de consulta de URL

Livewire le permite almacenar propiedades del componente en la cadena de consulta de la URL. Por ejemplo, puede querer que una propiedad $search de su componente se incluya en la URL: https://ejemplo.com/users?search=bob. Esto es particularmente útil para cosas como filtrar, ordenar y paginar, ya que permite a los usuarios compartir y marcar estados específicos de una página.

Uso básico

A continuación se muestra un componente ShowUsers que le permite buscar usuarios por su nombre a través de una simple entrada de texto:

<?php

namespace App\Livewire;

use Livewire\Attributes\Url;
use Livewire\Component;
use App\Models\User;

class ShowUsers extends Component
{
    public $search = '';

    public function render()
    {
        return view('livewire.show-users', [
            'users' => User::search($this->search)->get(),
        ]);
    }
}

<div>
    <input type="text" wire:model.live="search">

    <ul>
        @foreach ($users as $user)
            <li wire:key="{{ $user->id }}">{{ $user->name }}</li>
        @endforeach
    </ul>
</div>

Como puedes ver, debido a que la entrada de texto utiliza wire:model.live="search", a medida que un usuario escribe en el campo, se enviarán peticiones de red para actualizar la propiedad $search y mostrar un conjunto filtrado de usuarios en la página.

Sin embargo, si el visitante actualiza la página, el valor de búsqueda y los resultados se perderán.

Para preservar el valor de búsqueda a lo largo de las cargas de página, de forma que el visitante pueda actualizar la página o compartir la URL, podemos almacenar el valor de búsqueda en la cadena de consulta de la URL añadiendo el atributo #[Url] sobre la propiedad $search de la siguiente forma:

<?php

namespace App\Livewire;

use Livewire\Attributes\Url;
use Livewire\Component;
use App\Models\User;

class ShowUsers extends Component
{
    #[Url]
    public $search = '';

    public function render()
    {
        return view('livewire.show-users', [
            'posts' => User::search($this->search)->get(),
        ]);
    }
}

Ahora, si un usuario escribe “bob” en el campo de búsqueda, aparecerá la barra de URL en el navegador:

https://ejemplo.com/users?search=bob

Si ahora cargan esta URL desde una nueva ventana del navegador, “bob” aparecerá en el campo de búsqueda, y los resultados del usuario se filtrarán en consecuencia.

Inicializando propiedades desde la URL

Como ha visto en el ejemplo anterior, cuando una propiedad utiliza #[Url], no sólo almacena su valor actualizado en la cadena de consulta de la URL, sino que también hace referencia a cualquier valor de cadena de consulta existente al cargar la página.

Por ejemplo, si un usuario visita la URL https://ejemplo.com/users?search=bob, Livewire establecerá el valor inicial de $search en “bob”.

use Livewire\Attributes\Url;
use Livewire\Component;

class ShowUsers extends Component
{
    #[Url]
    public $search = ''; //  Se pondrá en "bob"...

    // ...
}

Propiedades anulables (Nullable)

Por defecto, si una página se carga con una entrada de cadena de consulta vacía como ?search=, Livewire tratará ese valor como una cadena vacía. En muchos casos, esto es lo esperado, sin embargo, hay ocasiones en las que se desea que ?search= sea tratado como null.

En estos casos, puede utilizar un typehint nullable como este:

use Livewire\Attributes\Url;
use Livewire\Component;

class ShowUsers extends Component
{
    #[Url]
    public ?string $search;

    // ...
}

Debido a que ? está presente en el typehint anterior, Livewire verá ?search= y establecerá $search como null en lugar de una cadena vacía.

Esto también funciona a la inversa, si establece $this->search = null en su aplicación, se representará en la cadena de consulta como ?search=.

Usando un alias

Livewire le da control total sobre qué nombre se muestra en la cadena de consulta de la URL. Por ejemplo, puede tener una propiedad $search pero desea ofuscar el nombre real de la propiedad o acortarlo a q.

Puede especificar un alias de cadena de consulta proporcionando el parámetro as al atributo #[Url]:

use Livewire\Attributes\Url;
use Livewire\Component;

class ShowUsers extends Component
{
    #[Url(as: 'q')]
    public $search = '';

    // ...
}

Ahora, cuando un usuario escriba “bob” en el campo de búsqueda, la URL mostrará: https://ejemplo.com/users?q=bob en lugar de ?search=bob.

Excluyendo ciertos valores

Por defecto, Livewire sólo pondrá una entrada en la cadena de consulta cuando su valor haya cambiado de lo que era en la inicialización. La mayoría de las veces, este es el comportamiento deseado, sin embargo, hay ciertos escenarios en los que puede querer más control sobre qué valor excluye Livewire de la cadena de consulta. En estos casos puede utilizar el parámetro except.

Por ejemplo, en el componente de abajo, el valor inicial de $search se modifica en mount(). Para asegurar que el navegador sólo excluirá search de la cadena de consulta si el valor de search es una cadena vacía, se ha añadido el parámetro except a #[Url]:

use Livewire\Attributes\Url;
use Livewire\Component;

class ShowUsers extends Component
{
    #[Url(except: '')]
    public $search = '';

    public function mount() {
        $this->search = auth()->user()->username;
    }

    // ...
}

Sin except en el ejemplo anterior, Livewire eliminaría la entrada search de la cadena de consulta cada vez que el valor de search fuera igual al valor inicial de auth()->user()->username. En cambio, como se ha utilizado except: '', Livewire conservará todos los valores de la cadena de consulta excepto cuando search sea una cadena vacía.

Mostrar al cargar la página

Por defecto, Livewire sólo mostrará un valor en la cadena de consulta después de que el valor haya sido cambiado en la página. Por ejemplo, si el valor por defecto para $search es una cadena vacía: "", cuando la entrada de búsqueda real esté vacía, no aparecerá ningún valor en la URL.

Si desea que la entrada ?search se incluya siempre en la cadena de consulta, incluso cuando el valor esté vacío, puede proporcionar el parámetro keep al atributo #[Url]:

use Livewire\Attributes\Url;
use Livewire\Component;

class ShowUsers extends Component
{
    #[Url(keep: true)]
    public $search = '';

    // ...
}

Ahora, cuando la página se cargue, la URL cambiará a la siguiente: https://ejemplo.com/users?search=

Almacenando en el historial

Por defecto, Livewire utiliza history.replaceState() para modificar la URL en lugar de history.pushState(). Esto significa que cuando Livewire actualiza la cadena de consulta, modifica la entrada actual en el estado del historial del navegador en lugar de añadir una nueva.

Dado que Livewire “sustituye” el historial actual, al pulsar el botón “atrás” en el navegador se irá a la página anterior en lugar de al valor ?search= anterior.

Para forzar a Livewire a utilizar history.pushState al actualizar la URL, puede proporcionar el parámetro history al atributo #[Url]:

use Livewire\Attributes\Url;
use Livewire\Component;

class ShowUsers extends Component
{
    #[Url(history: true)]
    public $search = '';

    // ...
}

n el ejemplo anterior, cuando un usuario cambia el valor de búsqueda de “bob” a “frank” y, a continuación, pulsa el botón de retroceso del navegador, el valor de búsqueda (y la URL) volverá a ser “bob” en lugar de navegar a la página visitada anteriormente.

Utilización del método queryString

La cadena de consulta también puede definirse como un método del componente. Esto puede ser útil si algunas propiedades tienen opciones dinámicas.

use Livewire\Component;

class ShowUsers extends Component
{
    // ...

    protected function queryString()
    {
        return [
            'search' => [
                'as' => 'q',
            ],
        ];
    }
}

Hooks para Rasgos (trait)

vewire también ofrece hooks para cadenas de consulta.

trait WithSorting
{
    // ...

    protected function queryStringWithSorting()
    {
        return [
            'sortBy' => ['as' => 'sort'],
            'sortDirection' => ['as' => 'direction'],
        ];
    }
}