版本：v18.0.0

Docblock 格式

Relay 解析器讓您在 GraphQL Schema 中定義由客戶端資料支援的其他類型和欄位。為了實現這一點，Relay 編譯器會在您的程式碼中尋找特殊的 @RelayResolver docblock。這些 docblock 定義了您 Schema 中的類型和欄位，並告知 Relay 在哪裡可以找到實作它們的解析器函式。

如需 Relay 解析器及其概念的概述，請參閱Relay 解析器指南。此頁面記錄了 Relay 編譯器尋找的不同 docblock 標籤，以及如何使用它們。

Relay 編譯器只會查看包含以下內容的 docblock：

@RelayResolver 標籤。任何其他 docblock 都會被忽略。

`@RelayResolver TypeName`

@RelayResolver 標籤後跟一個名稱，會在您的 Schema 中定義一個新的 GraphQL 類型。預設情況下，它應該後跟一個導出的函式，其名稱與類型名稱相符。該函式應接受一個 ID 作為其唯一參數，並傳回 JavaScript 模型/物件，即該類型的支援資料。請參閱@weak，以了解定義類型支援資料的替代方法。

Docblock

/**
 * @RelayResolver User
 */
export function User(id): UserModel {
  return UserModel.getById(id);
}

/**
 * @RelayResolver
 */
export function User(id): UserModel {
  return UserModel.getById(id);
}

請參閱定義類型指南，以取得更多資訊。

`@RelayResolver TypeName.fieldName: FieldTypeName`

如果 @RelayResolver 標籤中的 typename 後面跟著一個點，然後是欄位定義，它會在類型上定義一個新的欄位。. 後面的部分預期會遵循 GraphQL 的Schema 定義語言。

欄位定義預期會後跟一個導出的函式，其名稱與欄位名稱相符。該函式應接受類型解析器傳回的模型/物件作為其唯一參數，並傳回欄位的值。

Docblock

/**
 * @RelayResolver User.name: String
 */
export function name(user: UserModel): string {
  return user.name;
}

/**
 * @RelayResolver
 */
export function name(user: UserModel): string {
  return user.name;
}

請參閱定義欄位指南，以取得更多資訊。

`@rootFragment`

Relay 解析器也可以用於建立從圖表中其他資料衍生而來的資料模型。當它們所依賴的資料發生變更時，這些欄位會由 Relay 自動重新計算。

若要定義衍生欄位，請在現有的欄位定義上使用 @rootFragment 標籤，然後在其後跟一個片段的名稱，該片段定義欄位所依賴的資料。欄位的解析器函式會傳遞一個片段鍵，可用於使用 readFragment() 讀取片段資料。

Docblock

import {readFragment} from 'relay-runtime';

/**
 * @RelayResolver User.fullName: String
 * @rootFragment UserFullNameFragment
 */
export function fullName(key: UserFullNameFragment$key): string {
  const user = readFragment(
    graphql`
      fragment UserFullNameFragment on User {
        firstName
        lastName
      }
    `,
    key,
  );
  return `${user.firstName} ${user.lastName}`;
}

import {readFragment} from 'relay-runtime';

/**
 * @RelayResolver
 */
export function fullName(key: UserFullNameFragment$key): string {
  const user = readFragment(
    graphql`
      fragment UserFullNameFragment on User {
        firstName
        lastName
      }
    `,
    key,
  );
  return `${user.firstName} ${user.lastName}`;
}

請參閱衍生欄位，以取得更多資訊。

`@live`

在建立可能會隨著時間變化的用戶端狀態模型時，傳回單一值的解析器函式是不夠的。為了容納這一點，Relay 解析器可讓您定義一個欄位，該欄位會隨著時間傳回值的串流。這可透過將 @live 標籤新增至欄位或類型定義來完成。

@live 解析器必須傳回具有 LiveStateValue 形狀的物件，以允許 Relay 讀取目前值並訂閱變更。

Docblock

import type {LiveState} from 'relay-runtime';

/**
* @RelayResolver Query.counter: Int
* @live
*/
export function counter(): LiveState<number> {
  return {
    read: () => store.getState().counter,
    subscribe: cb => {
      return store.subscribe(cb);
    },
  };
}

import type {LiveState} from 'relay-runtime';

/**
* @RelayResolver
*/
export function counter(): LiveState<number> {
  return {
    read: () => store.getState().counter,
    subscribe: cb => {
      return store.subscribe(cb);
    },
  };
}

請參閱即時欄位指南，以取得更多資訊。

`@weak`

預設情況下，Relay 解析器預期類型的支援資料由解析器函式傳回。但是，在某些情況下，給定類型的物件可能沒有識別碼。在這種情況下，您可以使用上述 @RelayResolver TypeName 語法，然後使用標籤 @weak 來定義「弱」類型。

弱類型宣告預期會後跟一個導出的類型定義，其名稱與類型名稱相符。

Docblock

/**
* @RelayResolver ProfilePicture
* @weak
*/
export type ProfilePicture = {
  url: string;
  width: number;
  height: number;
};

/**
* @RelayResolver
*/
export type ProfilePicture = {
  url: string;
  width: number;
  height: number;
};

請參閱[弱類型](/docs/guides/relay-resolvers/defining-types/#Defining a “weak” type) 指南，以取得更多資訊，包括如何定義連至弱類型的邊緣。

`@deprecated`

就像 GraphQL Schema 定義語言一樣，Relay 解析器支援 @deprecated 標籤，以將欄位標記為已過時。標籤後面可以跟一個字串，該字串將用作過時原因。如果您使用Relay VSCode 擴充功能，過時的欄位將會在編輯器中獲得特殊待遇。

/**
 * @RelayResolver User.name: String
 * @deprecated Use `fullName` instead.
 */
export function name(user: UserModel): string {
  return user.name;
}

請參閱已過時指南，以取得更多資訊。

描述

docblock 中的任何自由文字（未跟隨標籤的文字）將會用作類型或欄位的描述。如果您使用Relay VSCode 擴充功能，此描述將會顯示在編輯器中。

/**
 * @RelayResolver User.name: String
 *
 * What's in a name? That which we call a rose by any other name would smell
 * just as sweet.
 */
export function name(user: UserModel): string {
  return user.name;
}

請參閱描述指南，以取得更多資訊。

@RelayResolver TypeName​

@RelayResolver TypeName.fieldName: FieldTypeName​

@rootFragment​

@live​

@weak​

@deprecated​

描述​