Kolumna podelementów wyświetla podelementy zagnieżdżone pod elementem nadrzędnym. Pozwala podzielić elementy na mniejsze, konkretne zadania, zachowując powiązanie z elementem nadrzędnym.

Kolumna podelementów jest tylko do odczytu - nie można bezpośrednio zapisywać w niej wartości. Podelementami można zarządzać za pomocą mutacji create_subitem i delete_item.

Typ kolumny	Typ implementacji	Obsługiwane operacje
subtasks	SubtasksValue	Odczyt: Tak Filtrowanie: Tak Tworzenie: Tak (tylko kolumny) Aktualizacja: Nie (użyj create_subitem / delete_item) Czyszczenie: Nie

---

Zapytania

Kolumny podelementów można odpytywać za pomocą pola column_values w obiekcie items, używając wbudowanego fragmentu. Wartości kolumny podelementów są typu SubtasksValue.

Zachowanie kolumny zależy od tego, czy odpytywany element jest nadrzędny, czy liściowy: * Elementy nadrzędne (elementy z podelementami): is_leaf ma wartość false, a pola subitems i subitems_ids są wypełnione * Elementy liściowe (elementy bez podelementów lub same podelementy): is_leaf ma wartość true, a pola subitems i subitems_ids są puste

SubtasksValue

query {
  items(ids: [1234567890]) {
    name
    column_values {
      ... on SubtasksValue {
        id
        display_value
        is_leaf
        subitems_ids
        subitems {
          id
          name
        }
        text
        type
        value
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on SubtasksValue {
          id
          display_value
          is_leaf
          subitems_ids
          subitems {
            id
            name
          }
        }
      }
    }
  }
`;

const variables = { itemIds: [1234567890] };

const response = await mondayApiClient.request(query, variables);

Pola

Możesz użyć następujących pól, aby określić, jakie informacje zwróci implementacja SubtasksValue.

Pole	Opis
column Column!	Kolumna, do której należy wartość.
display_value String!	Ciąg znaków zawierający nazwy wszystkich podelementów, rozdzielone przecinkami. Zwraca pusty ciąg znaków, jeśli element nie ma podelementów.
id ID!	Unikalny identyfikator kolumny.
is_leaf Boolean!	Określa, czy element jest węzłem liściowym (nie ma podelementów). Zwraca true dla podelementów i elementów bez podelementów.
subitems [Item!]!	Podelementy danego elementu. Zwraca pustą tablicę, jeśli element nie ma podelementów.
subitems_ids [ID!]!	Tablica identyfikatorów podelementów. Zwraca pustą tablicę, jeśli element nie ma podelementów.
text String	Wartość kolumny w postaci tekstu. W przypadku kolumn podelementów zawsze zwraca null.
type ColumnType!	Typ kolumny (subtasks).
value JSON	Surowa wartość kolumny w formacie JSON. W przypadku kolumn podelementów zawsze zwraca null.

Przykładowa odpowiedź (element nadrzędny)

{
  "data": {
    "items": [
      {
        "name": "Project Alpha",
        "column_values": [
          {
            "id": "subitems",
            "display_value": "Design mockup, Write specs, Implement feature",
            "is_leaf": false,
            "subitems_ids": ["1234567891", "1234567892", "1234567893"],
            "subitems": [
              { "id": "1234567891", "name": "Design mockup" },
              { "id": "1234567892", "name": "Write specs" },
              { "id": "1234567893", "name": "Implement feature" }
            ],
            "text": null,
            "type": "subtasks",
            "value": null
          }
        ]
      }
    ]
  }
}

Przykładowa odpowiedź (element liściowy)

{
  "data": {
    "items": [
      {
        "name": "Design mockup",
        "column_values": [
          {
            "id": "subitems",
            "display_value": "",
            "is_leaf": true,
            "subitems_ids": [],
            "subitems": [],
            "text": null,
            "type": "subtasks",
            "value": null
          }
        ]
      }
    ]
  }
}

Bezpośrednie odpytywanie podelementów

Możesz też uzyskać dostęp do podelementów za pomocą pola subitems typu Item, bez korzystania z wartości kolumny podelementów:

query {
  items(ids: [1234567890]) {
    name
    subitems {
      id
      name
      column_values {
        id
        text
      }
    }
  }
}

---

Filtrowanie

Możesz filtrować elementy według tego, czy mają podelementy, używając obiektu items_page.

Operator	Wartość porównania	Opis
is_empty	[]	Zwraca elementy, które nie mają podelementów.
is_not_empty	[]	Zwraca elementy, które mają co najmniej jeden podelement.

Przykłady

Filtrowanie elementów z podelementami

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "subitems"
            compare_value: []
            operator: is_not_empty
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

Filtrowanie elementów bez podelementów

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "subitems"
            compare_value: []
            operator: is_empty
          }
        ]
      }
    ) {
      items {
        id
        name
      }
    }
  }
}

---

Mutacje

Kolumna podelementów jest tylko do odczytu - nie można bezpośrednio ustawiać ani czyścić jej wartości. Do zarządzania podelementami użyj następujących mutacji:

Tworzenie kolumny

Wymagany zakres uprawnień: boards:write

Możesz utworzyć kolumnę podelementów za pomocą ogólnej mutacji create_column. Nie ma typowanej mutacji create_subtasks_column.

mutation {
  create_column(
    board_id: 1234567890
    title: "Subitems"
    column_type: subtasks
  ) {
    id
    title
    type
  }
}

Tworzenie podelementu

Wymagany zakres uprawnień: boards:write

Użyj mutacji create_subitem, aby dodać podelement pod elementem nadrzędnym. Podelement automatycznie pojawi się w kolumnie podelementów elementu nadrzędnego.

mutation {
  create_subitem(
    parent_item_id: 1234567890
    item_name: "Design mockup"
  ) {
    id
    name
    board {
      id
    }
  }
}

const query = `
  mutation ($parentItemId: ID!, $itemName: String!) {
    create_subitem(
      parent_item_id: $parentItemId
      item_name: $itemName
    ) {
      id
      name
    }
  }
`;

const variables = {
  parentItemId: 1234567890,
  itemName: "Design mockup"
};

const response = await mondayApiClient.request(query, variables);

Argumenty

Argument	Typ	Opis
parent_item_id	ID!	Unikalny identyfikator elementu nadrzędnego.
item_name	String!	Nazwa nowego podelementu.
column_values	JSON	Wartości kolumn nowego podelementu w postaci ciągu JSON.
create_labels_if_missing	Boolean	Tworzy etykiety statusu/listy rozwijanej, jeśli jeszcze nie istnieją. Wymaga uprawnień do zmiany struktury tablicy.

Tworzenie podelementu z wartościami kolumn

mutation {
  create_subitem(
    parent_item_id: 1234567890
    item_name: "Implement login flow"
    column_values: "{\"status\": {\"label\": \"Working on it\"}, \"person\": {\"personsAndTeams\": [{\"id\": 9876543, \"kind\": \"person\"}]}}"
  ) {
    id
    name
  }
}

Usuwanie podelementu

Wymagany zakres uprawnień: boards:write

Użyj mutacji delete_item, aby usunąć podelement. Zostanie on też usunięty z kolumny podelementów elementu nadrzędnego.

mutation {
  delete_item(item_id: 9876543210) {
    id
  }
}

---

Odczytywanie konfiguracji kolumny

Możesz odpytać ustawienia kolumny podelementów za pomocą pola settings kolumny.

query {
  boards(ids: 1234567890) {
    columns(ids: ["subitems"]) {
      id
      title
      settings
    }
  }
}

Struktura odpowiedzi settings

Pole settings zwraca typowany obiekt JSON z następującymi kluczami:

Klucz	Typ	Opis
allowMultipleItems	boolean	Określa, czy kolumna pozwala na wiele podelementów.
itemTypeName	string	Wewnętrzna nazwa typu podelementów w tej kolumnie.
displayType	string	Sposób wyświetlania podelementów. Zazwyczaj "BOARD_INLINE".
boardIds	number[]	Identyfikatory tablic powiązanych z podelementami.

Przykładowa odpowiedź settings

{
  "allowMultipleItems": true,
  "itemTypeName": "column.subtasks.title",
  "displayType": "BOARD_INLINE",
  "boardIds": [1234567890]
}

---

Pobieranie schematu typu kolumny

Możesz programowo pobrać schemat JSON ustawień kolumny podelementów za pomocą zapytania get_column_type_schema. Zwraca ono strukturę, reguły walidacji i dostępne właściwości konfiguracji kolumny.

query {
  get_column_type_schema(
    type: subtasks
  )
}

{
  "data": {
    "get_column_type_schema": {
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
          "settings": {
            "type": "object",
            "description": "Column specific settings",
            "properties": {},
            "additionalProperties": false
          }
        }
      }
    }
  }
}

Schemat nie udostępnia konfigurowalnych ustawień kolumny podelementów. Jej działaniem zarządza struktura tablicy oraz mutacje dotyczące podelementów.

Odpowiedź zawiera nazwy właściwości, typy, ograniczenia (takie jak maksymalna długość i dozwolone wartości) oraz opisy poszczególnych ustawień. Możesz użyć tych informacji do sprawdzania poprawności ustawień kolumn, dynamicznego generowania interfejsów użytkownika lub przekazywania kontekstu agentom AI. Dowiedz się więcej o formacie odpowiedzi schematu.