Query Functions

Thao tác các giá trị của các trường trong GraphQL query, thông qua bộ tiện ích và các directive đặc biệt cung cấp khả năng lập trình meta.

Field to Input

Lấy giá trị của một trường, thao tác nó, và truyền vào một trường khác, tất cả trong cùng một query.

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

Lặp và Thao tác Giá trị Trường

Bổ sung các meta directive vào GraphQL schema, để lặp và thao tác các phần tử giá trị của các trường mảng và đối tượng:

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem làm cho directive lồng bên trong được áp dụng trên một phần tử cụ thể của mảng.

Trong query dưới đây, chỉ phần tử đầu tiên trong mảng chứa tên danh mục được chuyển thành chữ hoa:

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

...tạo ra kết quả:

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

Field on Field

Bổ sung directive @applyField, để thực thi một trường nhất định trên giá trị của trường đã được phân giải.

Khi áp dụng cho một trường, directive @applyField cho phép thực thi một trường khác (có sẵn trên cùng kiểu và được áp dụng trên cùng đối tượng), và truyền giá trị kết quả đó sang directive khác, hoặc ghi đè giá trị của trường.

Trong query dưới đây, trường Post.title của đối tượng có giá trị "Hello world!". Bằng cách thêm @applyField để thực thi trường _strUpperCase:

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

...giá trị trường được chuyển thành chữ hoa, tạo ra:

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

Thao tác Trường có Điều kiện

Bổ sung các meta directive @if và @unless vào GraphQL schema, để thực thi có điều kiện một directive lồng bên trong trên trường.

@if thực thi các directive lồng bên trong của nó chỉ khi điều kiện có giá trị true.

Trong query này, người dùng "Leo" và "Peter" có tên được chuyển thành chữ hoa, vì họ nằm trong mảng "người dùng đặc biệt", trong khi "Martin" thì không:

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

...tạo ra kết quả:

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

Giá trị Mặc định của Trường

Bổ sung directive @default, để gán giá trị cho các trường null hoặc rỗng.

Trong ví dụ dưới đây, khi một bài viết không có ảnh đại diện, trường featuredImage trả về null:

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

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

Bằng cách sử dụng @default, chúng ta có thể lấy một ảnh mặc định:

{
  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"
      }
    }
  }
}

Loại bỏ Trường khỏi Phản hồi

Bổ sung directive @remove vào GraphQL schema, giúp loại bỏ đầu ra của một trường khỏi phản hồi.

Trong query dưới đây, chúng ta tạo URL để gửi yêu cầu HTTP bằng cách ghép nối tên miền của trang web và endpoint của REST API. Vì các giá trị của các thành phần này không cần thiết đối với chúng ta, không cần in chúng trong phản hồi, và chúng ta có thể dùng @remove để loại bỏ chúng:

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
    }
  )
}

...tạo ra phản hồi này (lưu ý rằng các trường siteURL và requestURL đã bị loại bỏ):

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

Kích hoạt Lỗi trong Phản hồi

Bổ sung trường toàn cục _fail và directive @fail vào GraphQL schema, để thêm một mục rõ ràng vào thuộc tính errors trong phản hồi, và trường toàn cục _warn cùng directive @warn, để thêm một mục vào thuộc tính warnings trong phản hồi.

Trường _fail luôn thêm lỗi, còn directive @fail thêm lỗi khi điều kiện được chỉ định trong đối số condition được đáp ứng:

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"
    )
  }
}