开始使用 Apollo 客户端

你好！本简短教程将帮助你开始使用 Apollo 客户端。

步骤 1：设置

要开始此教程，请执行以下操作之一

• 在本地区域使用 Vite创建一个新的 React 项目，或者
• 在 CodeSandbox创建一个新的 React 沙盒。

步骤 2：安装依赖项

使用 Apollo 客户端的程序需要两个顶级依赖项：Apollo 客户端：此单一包包含设置 Apollo 客户端所需的所有内容。它包括内存缓存、本地状态管理、错误处理以及基于 React 的视图层。

• @apollo/client：此包提供了解析 GraphQL 查询的逻辑。
• graphql

运行以下命令以安装这两个包

1
npm install @apollo/client graphql

我们的示例应用将使用来自Apollo Odyssey的FlyBy GraphQL API。此API提供了星际旅行地点列表及其详细信息 👽

步骤 3：初始化 ApolloClient

在配置好依赖项后，我们现在可以初始化一个ApolloClient实例。

在main.jsx中，让我们首先从@apollo/client导入所需的符号：

1
import { ApolloClient, InMemoryCache, ApolloProvider, gql } from '@apollo/client';

接下来，我们将初始化 ApolloClient，将一个包含 uri 和 cache 字段的配置对象传递给其构造函数：

1
const client = new ApolloClient({
2
  uri: 'https://flyby-router-demo.herokuapp.com/',
3
  cache: new InMemoryCache(),
4
});

• uri指定了我们的 GraphQL 服务器的 URL。
• cache是 InMemoryCache的实例，Apollo Client 使用它来缓存在获取查询结果后 查询结果。

就是这样！我们的 client已经准备好开始获取数据了。现在在我们开始使用 Apollo Client 与 React 之前，让我们先尝试使用原生 JavaScript 发送一个 query。

在同一个 main.jsx文件中，使用以下显示的 query 字符串（用 gql模板文字括起来）调用 client.query：

1
// const client = ...
2

3
client
4
  .query({
5
    query: gql`
6
      query GetLocations {
7
        locations {
8
          id
9
          name
10
          description
11
          photo
12
        }
13
      }
14
    `,
15
  })
16
  .then((result) => console.log(result));

运行此代码，打开您的控制台，并检查结果对象。您应该看到一个带有 locations及其他属性（如 loading 和 networkStatus）的 data属性。太棒了！

虽然像这样直接执行 GraphQL 操作可能很有用，但 Apollo Client 在与如 React 这样的视图层集成时才能发挥出其最佳作用。您可以将查询绑定到您的 UI，并在获取新数据时自动更新它。

我们来看看它是如何工作的！

第4步：将客户端连接到 React

您可以使用 Apollo Client 组件来将 Apollo Client 连接到 React，类似于 React 的 Context.Provider，ApolloProvider包装您的 React 应用程序，并在上下文中设置 Apollo Client，使您能够在组件树中的任何位置访问它。

在 main.jsx 文件中，让我们用 ApolloProvider 包装我们的 React 应用。我们建议将 ApolloProvider 放在您应用程序的高层位置，位于可能需要访问 GraphQL 数据的任何组件之上。

1
import React from 'react';
2
import * as ReactDOM from 'react-dom/client';
3
import { ApolloClient, InMemoryCache, ApolloProvider } from '@apollo/client';
4
import App from './App';
5

6
const client = new ApolloClient({
7
  uri: 'https://flyby-router-demo.herokuapp.com/',
8
  cache: new InMemoryCache(),
9
});
10

11
// Supported in React 18+
12
const root = ReactDOM.createRoot(document.getElementById('root'));
13

14
root.render(
15
  <ApolloProvider client={client}>
16
    <App />
17
  </ApolloProvider>,
18
);

第5步：使用 useQuery 获取数据

连接 ApolloProvider 后，您可以使用 useQuery 开始请求数据。 useQuery 钩子是一个 React 钩子，它在您的 UI 中共享 GraphQL 数据。

现在切换到我们的 App.jsx 文件，我们首先会将现有文件内容替换为以下代码片段：

1
// Import everything needed to use the `useQuery` hook
2
import { useQuery, gql } from '@apollo/client';
3

4
export default function App() {
5
  return (
6
    <div>
7
      <h2>My first Apollo app 🚀</h2>
8
    </div>
9
  );
10
}

我们可以通过在 gql 模板字面量中包装来定义我们想要执行的查询。

1
const GET_LOCATIONS = gql`
2
  query GetLocations {
3
    locations {
4
      id
5
      name
6
      description
7
      photo
8
    }
9
  }
10
`;

接下来，让我们定义一个名为 DisplayLocations 的组件，该组件将在 useQuery 钩子中使用我们的 GET_LOCATIONS 查询：

1
function DisplayLocations() {
2
  const { loading, error, data } = useQuery(GET_LOCATIONS);
3

4
  if (loading) return <p>Loading...</p>;
5
  if (error) return <p>Error : {error.message}</p>;
6

7
  return data.locations.map(({ id, name, description, photo }) => (
8
    <div key={id}>
9
      <h3>{name}</h3>
10
      <img width="400" height="250" alt="location-reference" src={`${photo}`} />
11
      <br />
12
      <b>About this location:</b>
13
      <p>{description}</p>
14
      <br />
15
    </div>
16
  ));
17
}

每次此组件渲染时， useQuery 钩子将自动执行我们的查询，并返回一个包含 loading、 error 和 data 属性的结果对象：

• Apollo Client 自动跟踪查询的加载和错误状态，这些状态反映了在 loading 和 error 属性中。
• 当查询的结果返回时，它会被附加到 data 属性。

最后，我们将 DisplayLocations 添加到现有的组件树中：

1
export default function App() {
2
  return (
3
    <div>
4
      <h2>My first Apollo app 🚀</h2>
5
      <br/>
6
      <DisplayLocations />
7
    </div>
8
  );
9
}

当您的应用程序重新加载时，您应该会先看到一个加载指示器，然后是一个位置列表以及这些位置的相关详情！如果没有，您可以将您的代码与 CodeSandbox 上的 完整应用程序 进行比较。

恭喜您，您刚刚创建了第一个用于渲染来自 Apollo Client 的 GraphQL 数据的组件！ 🎉 现在您可以尝试构建更多使用 useQuery 的组件，并实验您刚刚学到的概念。

下一步

现在您已经学会了如何使用 Apollo Client 获取数据，您可以深入了解创建更复杂的查询和 突变。本节之后，我们建议继续学习以下内容：

• 查询：了解如何使用 参数 获取查询，并深入了解配置选项。要查看完整的选项列表，请参阅 useQuery 的 API 参考。
• 突变：了解如何使用 mutations 更新数据以及何时需要更新 Apollo 缓存。要查看完整的选项列表，请参阅 useMutation 的 API 参考。
• Apollo 客户端 API：有时，您可能需要直接访问客户端，就像我们在上面的纯 JavaScript 示例中所做的那样。访问 API 参考，查看完整的选项列表。