Query Functions

通过一系列实用工具和提供元编程能力的特殊指令，在 GraphQL query 中操作字段的值。

Field to Input

在同一个 query 中获取某个字段的值，对其进行操作，并将其作为输入传入另一个字段。

query {
  posts {
    excerpt
 
    # Referencing previous field with name "excerpt"
    isEmptyExcerpt: _isEmpty(value: $__excerpt)
 
    # Referencing previous field with alias "isEmptyExcerpt"
    isNotEmptyExcerpt: _not(value: $__isEmptyExcerpt)
  }
}

字段值的迭代与操作

向 GraphQL 模式添加元指令，用于迭代和操作数组字段与对象字段的值元素：

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem 使嵌套指令作用于数组中的特定元素。

在以下 query 中，分类名称数组中只有第一个元素被转换为大写：

query {
  posts {
    categoryNames
      @underArrayItem(index: 0)
        @strUpperCase
  }
}

...结果如下：

{
  "data": {
    "posts": {
      "categoryNames": [
        "NEWS",
        "sports"
      ]
    }
  }
}

Field on Field

添加 @applyField 指令，用于在已解析字段的值上执行指定字段。

应用于某个字段时，@applyField 指令可执行另一个字段（该字段在同一类型上可用，并作用于同一对象），并将结果值传递给另一个指令，或覆盖该字段的值。

在以下 query 中，对象的 Post.title 字段值为 "Hello world!"。通过添加 @applyField 执行 _strUpperCase 字段：

{
  post(by: { id: 1 }) {
    title
      @passOnwards(as: "input")
      @applyField(
        name: "_strUpperCase"
        arguments: {
          text: $input
        },
        setResultInResponse: true
      )
  }
}

...字段值被转换为大写，结果如下：

{
  "data": {
    "post": {
      "title": "HELLO WORLD!"
    }
  }
}

条件字段操作

向 GraphQL 模式添加元指令 @if 和 @unless，用于根据条件对字段执行嵌套指令。

@if 仅在条件值为 true 时执行其嵌套指令。

在以下 query 中，"Leo" 和 "Peter" 因为在"特殊用户"数组中，其名称被转换为大写，而 "Martin" 则不会：

query {
  users {
    name
      @passOnwards(as: "userName")
      @applyField(
        name: "_inArray"
        arguments: {
          value: $userName
          array: ["Leo", "John", "Peter"]
        }
        passOnwardsAs: "isSpecialUser"
      )
      @if(
        condition: $isSpecialUser
      )
        @strUpperCase
  }
}

...结果如下：

{
  "data": {
    "users": [
      {
        "name": "LEO"
      },
      {
        "name": "Martin"
      },
      {
        "name": "PETER"
      }
    ]
  }
}

字段默认值

添加 @default 指令，为值为 null 或空的字段设置默认值。

在以下示例中，当文章没有特色图片时，字段 featuredImage 返回 null：

{
  post(by: { id: 1 }) {
    featuredImage {
      id
      src
    }
  }
}

{
  "data": {
    "post": {
      "featuredImage": null
    }
  }
}

通过使用 @default，可以获取某张默认图片：

{
  post(by: { id: 1 }) {
    featuredImage @default(value: 55) {
      id
      src
    }
  }
}

{
  "data": {
    "post": {
      "featuredImage": {
        "id": 55,
        "src": "http://mysite.com/wp-content/uploads/my-default-image.webp"
      }
    }
  }
}

字段响应移除

向 GraphQL 模式添加 @remove 指令，将字段的输出从响应中移除。

在以下 query 中，通过拼接站点域名与 REST API 端点来生成发送 HTTP 请求的 URL。由于这些组件的值对我们来说并不重要，无需在响应中输出，可以用 @remove 将其移除：

query {
  siteURL: optionValue(name: "siteurl")
    @remove
 
  requestURL: _sprintf(
    string: "%s/wp-json/wp/v2/comments/11/?_fields=id,content,date",
    values: [$__siteURL]
  )
    @remove
 
  _sendJSONObjectItemHTTPRequest(
    input: {
      url: $__requestURL
    }
  )
}

...生成如下响应（注意字段 siteURL 和 requestURL 已被移除）：

{
  "data": {
    "_sendJSONObjectItemHTTPRequest": {
      "id": 11,
      "date": "2020-12-12T04:07:36",
      "content": {
        "rendered": "<p>Btw, I really like this stuff<\/p>\n"
      }
    }
  }
}

响应错误触发

向 GraphQL 模式添加全局字段 _fail 和指令 @fail，以在响应的 errors 属性中显式添加条目；以及全局字段 _warn 和指令 @warn，以在响应的 warnings 属性中添加条目。

字段 _fail 始终添加错误，而指令 @fail 仅在参数 condition 的条件满足时才添加错误：

query {
  _fail(message: "Some error")
  
  posts {
    featuredImage @fail(
      condition: IS_NULL,
      message: "The post does not have a featured image"
    ) {
      id
      src
    }
  }
  
  users {
    name @fail(
      condition: IS_EMPTY,
      message: "The retrieved user does not have a name"
    )
  }
}