# @gravity-ui/data-source 中文文档

规范地址：https://npmcn.com/package/%40gravity-ui/data-source/

版本：0\.10\.0
npm 元数据更新时间：2026-07-09T15:45:53.114Z
中文译文更新时间：2026-11-17T00:59:35.248Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gravity-ui/data-source
原文对照：https://npmcn.com/package/%40gravity-ui/data-source/?lang=original
项目主页：https://github.com/gravity-ui/data-source#readme
源码仓库：https://github.com/gravity-ui/data-source

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：614 kB，514 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 24
- 运行依赖：7 个
- peer 依赖：@tanstack/react-query ^5\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2024-07-29T08:05:11.616Z
- 最新版本发布：2026-07-09T15:45:52.984Z
- 近 30 天下载量：13705（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 21 个）

## 中文简介

环绕数据获取

## 安装

```sh
npm install @gravity-ui/data-source
```

也可以使用：`pnpm add @gravity-ui/data-source`、`yarn add @gravity-ui/data-source`、`bun add @gravity-ui/data-source`

## README

# 数据来源 [![npm version](https://img.shields.io/npm/v/@gravity-ui/data-source?logo=npm&label=version)](https://www.npmjs.com/package/@gravity-ui/data-source) [![ci](https://img.shields.io/github/actions/workflow/status/gravity-ui/data-source/ci.yml?branch=main&label=ci&logo=github)](https://github.com/gravity-ui/data-source/actions/workflows/ci.yml?query=branch:main)

**数据来源** 是一个围绕数据采集的简单包装。 这是一种"端口"在 [清洁建筑](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html)。它允许您根据您的使用大小写来为数据采集工作做包装. **数据来源** 用途 [反应-平滑](https://tanstack.com/query/latest) 在引擎盖下.

## 安装

```bash
npm install @gravity-ui/data-source @tanstack/react-query
```

`@tanstack/react-query` 是同级依赖.

## 快速启动

### 1\. 设置数据管理器

第一,创建并提供 `DataManager` 在申请中:

```tsx
import React from 'react';
import {ClientDataManager, DataManagerContext} from '@gravity-ui/data-source';

const dataManager = new ClientDataManager({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutes
      retry: 3,
    },
    // ... other react-query options
  },
});

function App() {
  return (
    <DataManagerContext.Provider value={dataManager}>
      <YourApplication />
    </DataManagerContext.Provider>
  );
}
```

### 2\. 定义错误类型和打包器

定义出错类型,并根据默认构造器为数据源制作构建器 :

```ts
import {makePlainQueryDataSource as makePlainQueryDataSourceBase} from '@gravity-ui/data-source';

export interface ApiError {
  code: number;
  title: string;
  description?: string;
}

export const makePlainQueryDataSource = <TParams, TRequest, TResponse, TData, TError = ApiError>(
  config: Omit<PlainQueryDataSource<TParams, TRequest, TResponse, TData, TError>, 'type'>,
): PlainQueryDataSource<TParams, TRequest, TResponse, TData, TError> => {
  return makePlainQueryDataSourceBase(config);
};
```

### 3\. 创建自定义数据记录组件

写一个 `DataLoader` 基于默认定义您显示装入状态和错误的组件 :

```tsx
import {
  DataLoader as DataLoaderBase,
  DataLoaderProps as DataLoaderPropsBase,
  ErrorViewProps,
} from '@gravity-ui/data-source';

export interface DataLoaderProps
  extends Omit<DataLoaderPropsBase<ApiError>, 'LoadingView' | 'ErrorView'> {
  LoadingView?: ComponentType;
  ErrorView?: ComponentType<ErrorViewProps<ApiError>>;
}

export const DataLoader: React.FC<DataLoaderProps> = ({
  LoadingView = YourLoader, // You can use your own loader component
  ErrorView = YourError, // You can use your own error component
  ...restProps
}) => {
  return <DataLoaderBase LoadingView={LoadingView} ErrorView={ErrorView} {...restProps} />;
};
```

### 4\. 定义您的第一个数据来源

```ts
import {skipContext} from '@gravity-ui/data-source';

// Your API function
import {fetchUser} from './api';

export const userDataSource = makePlainQueryDataSource({
  // Keys have to be unique. Maybe you should create a helper for making names of data sources
  name: 'user',
  // skipContext is a helper to skip 2 first parameters in the function (context and fetchContext)
  fetch: skipContext(fetchUser),
  // Optional: generate tags for advanced cache invalidation
  tags: (params) => [`user:${params.userId}`, 'users'],
});
```

### 5\. 组件的使用

```tsx
import {useQueryData} from '@gravity-ui/data-source';

export const UserProfile: React.FC<{userId: number}> = ({userId}) => {
  const {data, status, error, refetch} = useQueryData(userDataSource, {userId});

  return (
    <DataLoader status={status} error={error} errorAction={refetch}>
      {data && <UserCard user={data} />}
    </DataLoader>
  );
};
```

## 核心概念

### 数据源类型

该图书馆提供两种主要的数据来源:

#### 普通查询数据源

对于简单的请求/响应模式:

```ts
const userDataSource = makePlainQueryDataSource({
  name: 'user',
  fetch: skipContext(async (params: {userId: number}) => {
    const response = await fetch(`/api/users/${params.userId}`);
    return response.json();
  }),
});
```

#### 无限查询数据源

对于平面和无限卷轴:

```ts
const postsDataSource = makeInfiniteQueryDataSource({
  name: 'posts',
  fetch: skipContext(async (params: {page: number; limit: number}) => {
    const response = await fetch(`/api/posts?page=${params.page}&limit=${params.limit}`);
    return response.json();
  }),
  next: (lastPage, allPages) => {
    if (lastPage.hasNext) {
      return {page: allPages.length + 1, limit: 20};
    }
    return undefined;
  },
});
```

### 状况管理

库将查询状态正常化为三个简单状态:

-   `loading` - 实际数据加载。 一样 `isLoading` 在反应查询中
-   `success` - 可用数据(可用闲置跳过)
-   `error` - 获取数据失败

### 空闲概念

图书馆提供特别服务 `idle` 用于跳过查询执行的符号 :

```ts
import {idle} from '@gravity-ui/data-source';

const UserProfile: React.FC<{userId?: number}> = ({userId}) => {
  // Query won't execute if userId is not defined
  const {data, status} = useQueryData(userDataSource, userId ? {userId} : idle);

  return (
    <DataLoader status={status} error={null}>
      {data && <UserCard user={data} />}
    </DataLoader>
  );
};
```

当参数相等时 `idle`数字 :

-   查询不执行
-   现状 `success`
-   数据尚存 `undefined`
-   组件无需加载即可安全渲染

**效益 `idle`数字 :**

1.  **类型安全** - TypeScript正确推断有条件参数的类型
2.  **业绩** - 避免不必要的服务器请求
3.  **逻辑简化** - 不需要管理额外的 `enabled` 状态
4.  **一致性** - 所有有条件查询的统一办法

这对有条件的查询特别有用,因为要在特定条件下装入数据,同时保持类型安全.

## API 参考

### 创建数据源

#### `makePlainQueryDataSource(config)`

为简单的请求/响应模式创建纯查询数据源.

```ts
const dataSource = makePlainQueryDataSource({
  name: 'unique-name',
  fetch: skipContext(fetchFunction),
  transformParams: (params) => transformedRequest,
  transformResponse: (response) => transformedData,
  tags: (params) => ['tag1', 'tag2'],
  options: {
    staleTime: 60000,
    retry: 3,
    // ... other react-query options
  },
});
```

**参数:**

-   `name` - 数据来源的独特标识符
-   `fetch` - 执行实际数据采集的函数
-   `transformParams` (可选) - 在请求前转换输入参数
-   `transformResponse` (可选) - 变换响应数据
-   `tags` (可选) - 生成无效的缓存标记
-   `options` (可选) - 重复查询选项

#### `makeInfiniteQueryDataSource(config)`

创建无限查询数据源,用于页码和无限滚动模式.

```ts
const infiniteDataSource = makeInfiniteQueryDataSource({
  name: 'infinite-data',
  fetch: skipContext(fetchFunction),
  next: (lastPage, allPages) => nextPageParam || undefined,
  prev: (firstPage, allPages) => prevPageParam || undefined,
  // ... other options same as plain
});
```

**补充参数:**

-   `next` - 确定下一页参数的函数
-   `prev` (可选) - 确定上一个页面参数的函数

### 反应钩

#### `useQueryData(dataSource, params, options?)`

用数据源获取数据的主钩.

```ts
const {data, status, error, refetch, ...rest} = useQueryData(
  userDataSource,
  {userId: 123},
  {
    enabled: true,
    refetchInterval: 30000,
  },
);
```

**回返情况:**

-   `data` - 获取的数据
-   `status` - 当前状态(“ 装入” QQ“ 成功” QQ“ 错误” )
-   `error` - 如果请求失败,则错误对象
-   `refetch` - 手动调试数据的功能
-   其他反应查询属性

#### `useQueryResponses(responses)`

将多个查询回复合并为一个状态.

```ts
const user = useQueryData(userDataSource, {userId});
const posts = useQueryData(postsDataSource, {userId});

const {status, error, refetch, refetchErrored} = useQueryResponses([user, posts]);
```

**回返情况:**

-   `status` - 所有查询的综合情况
-   `error` - 第一次遇到错误
-   `refetch` - 调试所有查询的功能
-   `refetchErrored` - 仅调试失败查询的函数

#### `useRefetchAll(states)`

创建回调以调试多个查询.

```ts
const refetchAll = useRefetchAll([user, posts, comments]);
// refetchAll() will trigger refetch for all queries
```

#### `useRefetchErrored(states)`

创建回调只检查失败的查询 .

```ts
const refetchErrored = useRefetchErrored([user, posts, comments]);
// refetchErrored() will only refetch queries with errors
```

#### `useDataManager()`

从上下文返回数据管理器.

```ts
const dataManager = useDataManager();
await dataManager.invalidateTag('users');
```

#### `useQueryContext()`

返回查询上下文(用于在反应-query上建立自定义数据钩子基础).

### 反应组件

#### `<DataLoader />`

处理加载状态和错误的组件 .

```tsx
<DataLoader
  status={status}
  error={error}
  errorAction={refetch}
  LoadingView={SpinnerComponent}
  ErrorView={ErrorComponent}
  loadingViewProps={{size: 'large'}}
  errorViewProps={{showDetails: true}}
>
  {data && <YourContent data={data} />}
</DataLoader>
```

**道具 :**

-   `status` - 当前装入状态
-   `error` - 错误对象
-   `errorAction` - 用于重试错误的函数或动作配置
-   `LoadingView` - 装入时要显示的组件
-   `ErrorView` - 错误时要显示的组件
-   `loadingViewProps` - 向装入视频的道具
-   `errorViewProps` - 给错误查看的道具

#### `<DataInfiniteLoader />`

用于无限查询的专门组件.

```tsx
<DataInfiniteLoader
  status={status}
  error={error}
  hasNextPage={hasNextPage}
  fetchNextPage={fetchNextPage}
  isFetchingNextPage={isFetchingNextPage}
  LoadingView={SpinnerComponent}
  ErrorView={ErrorComponent}
  MoreView={LoadMoreButton}
>
  {data.map((item) => (
    <Item key={item.id} data={item} />
  ))}
</DataInfiniteLoader>
```

**附加道具 :**

-   `hasNextPage` - 是否有更多网页可供使用
-   `fetchNextPage` - 要获取下一页的函数
-   `isFetchingNextPage` - 是否正在获取下页
-   `MoreView` - “再装入”按钮组件

#### `withDataManager(Component)`

输入 DataManager 作为道具的HOC.

```tsx
const MyComponent = withDataManager<Props>(({dataManager, ...props}) => {
  // Component has access to dataManager
  return <div>...</div>;
});
```

### 数据管理

#### `ClientDataManager`

数据管理主课.

```ts
const dataManager = new ClientDataManager({
  defaultOptions: {
    queries: {
      staleTime: 300000, // 5 minutes
      retry: 3,
      refetchOnWindowFocus: false,
    },
  },
});
```

**方法:**

##### `invalidateTag(tag, options?)`

以特定标记取消所有查询.

```ts
await dataManager.invalidateTag('users');
await dataManager.invalidateTag('posts', {
  repeat: {count: 3, interval: 1000}, // Retry invalidation
});
```

##### `invalidateTags(tags, options?)`

无效所有指定标记的查询 .

```ts
await dataManager.invalidateTags(['user', 'profile']);
```

##### `invalidateSource(dataSource, options?)`

无效所有数据源查询.

```ts
await dataManager.invalidateSource(userDataSource);
```

##### `invalidateParams(dataSource, params, options?)`

取消带有精确参数的特定查询.

```ts
await dataManager.invalidateParams(userDataSource, {userId: 123});
```

##### `resetSource(dataSource)`

为数据源重置( 清除) 所有缓存数据 .

```ts
await dataManager.resetSource(userDataSource);
```

##### `resetParams(dataSource, params)`

重置特定参数的缓存数据 .

```ts
await dataManager.resetParams(userDataSource, {userId: 123});
```

##### `invalidateSourceTags(dataSource, params, options?)`

基于数据源生成的标记的查询无效 .

```ts
await dataManager.invalidateSourceTags(userDataSource, {userId: 123});
```

### 公用事业

#### `skipContext(fetchFunction)`

用于将现有的获取函数调整到数据源接口的功能.

```ts
// Existing function
async function fetchUser(params: {userId: number}) {
  // ...
}

// Adapted for data source
const dataSource = makePlainQueryDataSource({
  name: 'user',
  fetch: skipContext(fetchUser), // Skips context and fetchContext params
});
```

#### `withCatch(fetchFunction, errorHandler)`

添加标准化错误处理以获取函数 .

```ts
const safeFetch = withCatch(fetchUser, (error) => ({error: true, message: error.message}));
```

#### `withCancellation(fetchFunction)`

添加取消支持以获取函数 .

```ts
const cancellableFetch = withCancellation(fetchFunction);
// Automatically handles AbortSignal from React Query
```

#### `getProgressiveRefetch(options)`

创建渐进回溯间隔函数.

```ts
const progressiveRefetch = getProgressiveRefetch({
  minInterval: 1000, // Start with 1 second
  maxInterval: 30000, // Max 30 seconds
  multiplier: 2, // Double each time
});

const dataSource = makePlainQueryDataSource({
  name: 'data',
  fetch: skipContext(fetchData),
  options: {
    refetchInterval: progressiveRefetch,
  },
});
```

#### `normalizeStatus(status, fetchStatus)`

将 React 查询状态转换为 DataLoader 状态 .

```ts
const status = normalizeStatus('pending', 'fetching'); // 'loading'
```

#### 状态和错误

```ts
// Get combined status from multiple states
const status = getStatus([user, posts, comments]);

// Get first error from multiple states
const error = getError([user, posts, comments]);

// Merge multiple statuses
const combinedStatus = mergeStatuses(['loading', 'success', 'error']); // 'error'

// Check if query key has a tag
const hasUserTag = hasTag(queryKey, 'users');
```

#### 关键组成

```ts
// Compose cache key for a data source
const key = composeKey(userDataSource, {userId: 123});

// Compose full key including tags
const fullKey = composeFullKey(userDataSource, {userId: 123});
```

#### 常数

```ts
import {idle} from '@gravity-ui/data-source';

// Special symbol for skipping query execution
const params = shouldFetch ? {userId: 123} : idle;

// Type-safe alternative to enabled: false
// Instead of:
const {data} = useQueryData(userDataSource, {userId: userId || ''}, {enabled: Boolean(userId)});

// Use:
const {data} = useQueryData(userDataSource, userId ? {userId} : idle);
// TypeScript correctly infers types for both branches
```

#### 查询选项组成

```ts
// Compose React Query options for plain queries
const plainOptions = composePlainQueryOptions(context, dataSource, params, options);

// Compose React Query options for infinite queries
const infiniteOptions = composeInfiniteQueryOptions(context, dataSource, params, options);
```

**说明:** 这些功能主要用于创建自定义数据源执行时的内部.

## 高级图案

### 带离子的有条件查询

使用 `idle` 以创建条件查询 :

```ts
import {idle} from '@gravity-ui/data-source';

const ConditionalDataComponent: React.FC<{
  userId?: number;
  shouldLoadPosts: boolean;
}> = ({userId, shouldLoadPosts}) => {
  // Load user only if userId is defined
  const user = useQueryData(
    userDataSource,
    userId ? {userId} : idle
  );

  // Load posts only if user is loaded and flag is enabled
  const posts = useQueryData(
    userPostsDataSource,
    user.data && shouldLoadPosts ? {userId: user.data.id} : idle
  );

  const combined = useQueryResponses([user, posts]);

  return (
    <DataLoader status={combined.status} error={combined.error}>
      <div>
        {user.data && <UserInfo user={user.data} />}
        {posts.data && <UserPosts posts={posts.data} />}
      </div>
    </DataLoader>
  );
};
```

### 数据转换

变换请求参数和响应数据 :

```ts
const apiDataSource = makePlainQueryDataSource({
  name: 'api-data',
  transformParams: (params: {id: number}) => ({
    userId: params.id,
    apiVersion: 'v2',
    format: 'json',
  }),
  transformResponse: (response: ApiResponse) => ({
    user: response.data.user,
    metadata: response.meta,
  }),
  fetch: skipContext(apiFetch),
});
```

### 基于标记的缓存无效化

高级缓存管理使用标签 :

```ts
const userDataSource = makePlainQueryDataSource({
  name: 'user',
  tags: (params) => [`user:${params.userId}`, 'users', 'profiles'],
  fetch: skipContext(fetchUser),
});

const userPostsDataSource = makePlainQueryDataSource({
  name: 'user-posts',
  tags: (params) => [`user:${params.userId}`, 'posts'],
  fetch: skipContext(fetchUserPosts),
});

// Invalidate all data for specific user
await dataManager.invalidateTag('user:123');

// Invalidate all user-related data
await dataManager.invalidateTag('users');
```

### 类型处理出错

创建类型安全错误处理 :

```ts
interface ApiError {
  code: number;
  message: string;
  details?: Record<string, unknown>;
}

const ErrorView: React.FC<ErrorViewProps<ApiError>> = ({error, action}) => (
  <div className="error">
    <h3>Error {error?.code}</h3>
    <p>{error?.message}</p>
    {action && (
      <button onClick={action.handler}>
        {action.children || 'Retry'}
      </button>
    )}
  </div>
);
```

### 带有复杂插座的无限查询

处理复杂的平面图:

```ts
interface PaginationParams {
  cursor?: string;
  limit?: number;
  filters?: Record<string, unknown>;
}

interface PaginatedResponse<T> {
  data: T[];
  nextCursor?: string;
  hasMore: boolean;
}

const infiniteDataSource = makeInfiniteQueryDataSource({
  name: 'paginated-data',
  fetch: skipContext(async (params: PaginationParams) => {
    const response = await fetch(`/api/data?${new URLSearchParams(params)}`);
    return response.json() as PaginatedResponse<DataItem>;
  }),
  next: (lastPage) => {
    if (lastPage.hasMore && lastPage.nextCursor) {
      return {cursor: lastPage.nextCursor, limit: 20};
    }
    return undefined;
  },
});
```

### 合并多个数据源

综合多个来源的数据:

```ts
const UserProfile: React.FC<{userId: number}> = ({userId}) => {
  const user = useQueryData(userDataSource, {userId});
  const posts = useQueryData(userPostsDataSource, {userId});
  const followers = useQueryData(userFollowersDataSource, {userId});

  const combined = useQueryResponses([user, posts, followers]);

  return (
    <DataLoader
      status={combined.status}
      error={combined.error}
      errorAction={combined.refetchErrored} // Only retry failed requests
      LoadingView={ProfileSkeleton}
      ErrorView={ProfileError}
    >
      {user && posts && followers && (
        <div>
          <UserInfo user={user.data} />
          <UserPosts posts={posts.data} />
          <UserFollowers followers={followers.data} />
        </div>
      )}
    </DataLoader>
  );
};
```

## 类型脚本支持

库用TypeScript-first方法构建,并提供完整的类型推论:

```ts
// Types are automatically inferred
const userDataSource = makePlainQueryDataSource({
  name: 'user',
  fetch: skipContext(async (params: {userId: number}): Promise<User> => {
    // Return type is inferred as User
  }),
});

// Hook return type is automatically typed
const {data} = useQueryData(userDataSource, {userId: 123});
// data is typed as User | undefined
```

### 自定义出错类型

定义和使用自定义错误类型 :

```ts
interface ValidationError {
  field: string;
  message: string;
}

interface ApiError {
  type: 'network' | 'validation' | 'server';
  message: string;
  validation?: ValidationError[];
}

const typedDataSource = makePlainQueryDataSource<
  {id: number}, // Params type
  {id: number}, // Request type
  ApiResponse, // Response type
  User, // Data type
  ApiError // Error type
>({
  name: 'typed-user',
  fetch: skipContext(fetchUser),
});
```

## 捐款

请阅读 [捐款额](https://npmcn.com/package/%40gravity-ui/data-source/CONTRIBUTING.md) 详细介绍我们的行为守则和提交拉动请求的程序.

## 许可证

MIT许可证。 见 [自由主义](https://npmcn.com/package/%40gravity-ui/data-source/LICENSE) 详细文件.

## 常见问题

### @gravity-ui/data-source 是什么？

环绕数据获取

### 如何安装 @gravity-ui/data-source？

在项目目录运行 npm install @gravity-ui/data-source，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@tanstack/react-query（^5\.0\.0）、react（^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gravity-ui/data-source 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gravity-ui/data-source 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @gravity-ui/data-source 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @gravity-ui/data-source 可以商用吗？

@gravity-ui/data-source 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gravity-ui/data-source 的下载量有多少？

根据 npm 官方下载统计，@gravity-ui/data-source 在 2026/10/17 – 2026/11/15 这 30 天内被下载 13,705 次，日均约 457 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gravity-ui/data-source 还在维护吗？

最新版本 0\.10\.0 发布于 2026/07/09（4 个月前）；至今共发布 39 个版本，其中过去 12 个月发布了 21 个；首次发布于 2024/07/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

