Query Functions

Manipuluj wartościami pól w ramach zapytania GraphQL, korzystając z zestawu narzędzi i specjalnych dyrektyw zapewniających możliwości meta-programowania.

Field to Input

Pobierz wartość pola, zmanipuluj ją i przekaż jako dane wejściowe do innego pola — wszystko w ramach tego samego zapytania.

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

Iteracja i Manipulacja Wartościami Pól

Dodanie meta-dyrektyw do schematu GraphQL, służących do iterowania i manipulowania elementami wartości pól tablicowych i obiektowych:

@underArrayItem
@underJSONObjectProperty
@underEachArrayItem
@underEachJSONObjectProperty
@objectClone

@underArrayItem powoduje, że zagnieżdżona dyrektywa jest stosowana do konkretnego elementu tablicy.

W poniższym zapytaniu tylko pierwszy element tablicy z nazwami kategorii jest zamieniany na wielkie litery:

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

...dając wynik:

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

Pole na Polu

Dodanie dyrektywy @applyField, która wykonuje określone pole na wartości rozwiązanego pola.

Zastosowana do danego pola dyrektywa @applyField umożliwia wykonanie innego pola (dostępnego w tym samym typie i stosowanego na tym samym obiekcie), a następnie przekazanie wynikowej wartości dalej do innej dyrektywy lub nadpisanie wartości pola.

W poniższym zapytaniu pole Post.title dla obiektu ma wartość "Hello world!". Dodając @applyField w celu wykonania pola _strUpperCase:

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

...wartość pola jest zamieniana na wielkie litery, dając wynik:

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

Warunkowa Manipulacja Polami

Dodanie meta-dyrektyw @if i @unless do schematu GraphQL, umożliwiających warunkowe wykonanie zagnieżdżonej dyrektywy na polu.

@if wykonuje swoje zagnieżdżone dyrektywy tylko wtedy, gdy warunek ma wartość true.

W tym zapytaniu użytkownicy "Leo" i "Peter" mają swoje imiona zamienione na wielkie litery, ponieważ znajdują się w tablicy „specjalnych użytkowników", natomiast "Martin" nie:

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

...dając wynik:

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

Domyślna Wartość Pola

Dodanie dyrektywy @default, służącej do ustawiania wartości dla pól null lub pustych.

W poniższym przykładzie, gdy post nie ma wyróżnionego obrazu, pole featuredImage zwraca null:

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

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

Używając @default, możemy pobrać domyślny obraz:

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

Usuwanie Pola z Odpowiedzi

Dodanie dyrektywy @remove do schematu GraphQL, która usuwa dane wyjściowe pola z odpowiedzi.

W poniższym zapytaniu generujemy URL do wysłania żądania HTTP, łącząc domenę witryny z punktem końcowym REST API. Ponieważ wartości tych komponentów nie są dla nas istotne, nie ma potrzeby wyświetlania ich w odpowiedzi i możemy je usunąć za pomocą @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
    }
  )
}

...dając następującą odpowiedź (zauważ, że pola siteURL i requestURL zostały usunięte):

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

Wyzwalacz Błędu w Odpowiedzi

Dodanie globalnego pola _fail i dyrektywy @fail do schematu GraphQL, aby jawnie dodać wpis do właściwości errors w odpowiedzi, oraz globalnego pola _warn i dyrektywy @warn, aby dodać wpis do właściwości warnings w odpowiedzi.

Pole _fail dodaje błąd zawsze, a dyrektywa @fail — gdy warunek określony w argumencie condition jest spełniony:

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