Leptos Query

常见问题解答 | 示例 | 实时演示

关于

Leptos Query 是一个用于 Leptos 的异步状态管理库。

深受 Tanstack Query 的启发。

查询对于数据获取、缓存和与服务器状态的同步非常有用。

查询提供

• 缓存
• 请求去重
• 失效
• 后台重新获取
• 重新获取间隔
• 具有缓存生命周期的内存管理
• 取消
• 调试工具
• 乐观更新
• 客户端缓存持久化（localStorage、indexdb、自定义等）

使用查询的主要入口点包括

• create_query - 推荐：创建一个 QueryScope，它封装了 use_query 和其他用于管理查询的方法。
• [use_query][crate::use_query::use_query()] - 一个用于读取、缓存和重新获取数据的查询原语。

功能标志

• csr 客户端渲染：在客户端使用查询。
• ssr 服务器端渲染：在服务器上初始化查询。
• hydrate 活化：确保在服务器端渲染时客户端上的查询已活化。
• local_storage - 启用查询的本地存储持久化。
• index_db - 启用查询的索引数据库持久化。

Leptos 和 Leptos Query 的版本兼容性

下表显示了针对每个 leptos 版本的 leptos_query 的兼容版本。请确保您使用的是兼容版本，以避免潜在的问题。

安装

cargo add leptos_query

然后，将相关功能添加到您的 Cargo.toml 文件中。

[features]
hydrate = [
    "leptos_query/hydrate",
    # ...
]
ssr = [
    "leptos_query/ssr",
    # ...
 ]

快速入门

如果您使用 SSR，您可能需要在服务器的 main 函数中使用 supress_query_load。有关更多信息，请参阅 常见问题解答。

在您的应用程序的根目录中，如果您想覆盖默认选项，请使用 [provide_query_client] 或 [provide_query_client_with_options] 提供查询客户端。

use leptos_query::*;
use leptos::*;

#[component]
pub fn App() -> impl IntoView {
    // Provides Query Client for entire app.
    provide_query_client();

    // Rest of App...
}

然后使用 [create_query][crate::create_query::create_query()] 创建一个查询函数。

use leptos::*;
use leptos_query::*;


// Query for a track.
fn track_query() -> QueryScope<TrackId, TrackData> {
    create_query(
        get_track,
        QueryOptions::default(),
    )
}

// Make a key type.
#[derive(Debug, Clone, Hash, Eq, PartialEq)]
struct TrackId(i32);

// The result of the query fetcher.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
struct TrackData {
   name: String,
}

// Query fetcher.
async fn get_track(id: TrackId) -> TrackData {
    todo!()
}

现在您可以在应用程序的任何组件中使用这个查询。

use leptos::*;
use leptos_query::*;

#[component]
fn TrackView(id: TrackId) -> impl IntoView {
    let QueryResult {
        data,
        ..
    } = track_query().use_query(move|| id.clone());

    view! {
       <div>
           // Query data should be read inside a Transition/Suspense component.
           <Transition
               fallback=move || {
                   view! { <h2>"Loading..."</h2> }
               }>
               {move || {
                    data
                        .get()
                        .map(|track| {
                           view! { <h2>{track.name}</h2> }
                        })
               }}
           </Transition>
       </div>
    }
}

有关完整的工作示例，请参阅 示例目录

Devtools 快速入门

要使用 devtools，您需要添加 devtools crate。

cargo add leptos_query_devtools

然后在您的 cargo.toml 中启用 csr 功能。

Hydrate 示例

• 如果您的应用程序使用 SSR，则此内容应位于 "hydrate" 功能下。

[features]
hydrate = [
    "leptos_query_devtools/csr",
]

CSR 示例

• 如果您的应用程序使用 CSR，则此内容应位于 "csr" 功能下。

[features]
csr = [
    "leptos_query_devtools/csr",
]

然后在您的应用程序中渲染 devtools 组件。确保您也提供了查询客户端。

默认情况下，Devtools 只会在开发模式下显示。当您以发布模式构建应用程序时，它不会显示，也不会包含在二进制文件中。如果您想覆盖此行为，您可以启用 force 功能。

use leptos_query_devtools::LeptosQueryDevtools;
use leptos_query::*;
use leptos::*;

#[component]
fn App() -> impl IntoView {
    provide_query_client();

    view!{
        <LeptosQueryDevtools />
        // Rest of App...
    }
}