Praca z kolumną zależności

Kolumna zależności pozwala określać relacje między elementami na tej samej tablicy - na przykład: „Zadanie B nie może się rozpocząć, dopóki nie zostanie ukończone zadanie A”. Relacje te można wizualizować w widokach Gantta, wykorzystywać w automatyzacjach osi czasu i dat oraz w automatyzacjach opartych na zależnościach.

W tym przewodniku dowiesz się, jak odczytywać wartości zależności, ustawiać je za pomocą mutacji, rozumieć tryby konfiguracji kolumny i filtrować elementy według ich zależności.

---

Wymagania wstępne

• Tablica z kolumną zależności
• Identyfikatory elementów, które chcesz połączyć
• Identyfikator kolumny zależności (np. "dependent_on")

Aby znaleźć identyfikator kolumny, pobierz listę kolumn tablicy:

query {
  boards(ids: [1234567890]) {
    columns {
      id
      title
      type
    }
  }
}

---

Odczytywanie wartości zależności

Odpytaj kolumnę zależności, używając fragmentu inline dla typu DependencyValue:

query {
  items(ids: [9876543210]) {
    name
    column_values(types: dependency) {
      ... on DependencyValue {
        id
        display_value
        linked_item_ids
        linked_items {
          id
          name
        }
        updated_at
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values(types: dependency) {
        ... on DependencyValue {
          id
          display_value
          linked_item_ids
          linked_items {
            id
            name
          }
          updated_at
        }
      }
    }
  }
`;

const variables = { itemIds: [9876543210] };
const response = await mondayApiClient.request(query, variables);

Najważniejsze pola:

Pole	Opis
display_value	Nazwy elementów, od których zależy dany element, oddzielone przecinkami. Pusty ciąg, jeśli nie ma zależności.
linked_item_ids	Tablica identyfikatorów elementów, od których zależy dany element.
linked_items	Pełne obiekty elementów (id + name) dla każdej zależności.
updated_at	Data ostatniej zmiany zależności. null, jeśli nie została jeszcze ustawiona.

---

Ustawianie zależności

Użyj change_multiple_column_values, aby ustawić zależności. Przekaż tablicę item_ids z identyfikatorami elementów, od których zależy dany element.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"dependent_on\": {\"item_ids\": [\"1111111111\", \"2222222222\"]}}"
  ) {
    id
  }
}

const mutation = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) {
    change_multiple_column_values(
      item_id: $itemId
      board_id: $boardId
      column_values: $columnValues
    ) {
      id
    }
  }
`;

const variables = {
  boardId: 1234567890,
  itemId: 9876543210,
  columnValues: JSON.stringify({
    dependent_on: {
      item_ids: ["1111111111", "2222222222"]
    }
  }),
};

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

Dodawanie zależności bez zastępowania istniejących

// 1. Read current dependencies
const readQuery = `
  query ($itemId: [ID!]) {
    items(ids: $itemId) {
      column_values(types: dependency) {
        ... on DependencyValue {
          linked_item_ids
        }
      }
    }
  }
`;

const readResult = await mondayApiClient.request(readQuery, { itemId: [9876543210] });
const existing = readResult.data.items[0].column_values[0].linked_item_ids;

// 2. Append new dependency and write back
const newId = "3333333333";
const updatedIds = [...existing, newId];

const updateMutation = `
  mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) {
    change_multiple_column_values(
      item_id: $itemId
      board_id: $boardId
      column_values: $columnValues
    ) { id }
  }
`;

await mondayApiClient.request(updateMutation, {
  boardId: 1234567890,
  itemId: 9876543210,
  columnValues: JSON.stringify({ dependent_on: { item_ids: updatedIds } }),
});

---

Ustawianie zależności podczas tworzenia elementu

Możesz ustawić wartości zależności podczas tworzenia elementu:

mutation {
  create_item(
    board_id: 1234567890
    item_name: "Deploy backend"
    column_values: "{\"dependent_on\": {\"item_ids\": [\"9876543210\"]}}"
  ) {
    id
    name
  }
}

---

Usuwanie zależności

Przekaż null lub pusty obiekt jako wartość kolumny, aby usunąć wszystkie zależności:

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"dependent_on\": null}"
  ) {
    id
  }
}

---

Odczytywanie konfiguracji kolumny

Aby sprawdzić konfigurację kolumny zależności, odpytaj pole settings kolumny:

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

Przykładowa odpowiedź:

{
  "id": "dependent_on",
  "title": "Dependency",
  "settings": {
    "boardIds": [1234567890],
    "dependencyNewInfra": true,
    "allowMultipleItems": true,
    "dependency_mode": "flexible"
  }
}

Tryby zależności

Ustawienie dependency_mode określa, co stanie się z powiązaną kolumną Data (Date) lub Oś czasu (Timeline) po ukończeniu elementu, od którego zależy inny element:

Tryb	Działanie
flexible	Powiązana data lub oś czasu przesuwa się automatycznie, ale dopuszcza częściowe nakładanie się poprzedzających i następujących po nich elementów.
strict	Obowiązuje ścisła kolejność - zależny element nie może się rozpocząć, dopóki poprzedzający go element nie zostanie w pełni ukończony.
no_action	Zmiana statusu zależności nie powoduje automatycznych zmian dat ani osi czasu.

---

Filtrowanie według zależności

Użyj items_page, aby filtrować elementy według stanu zależności. Kolumna zależności obsługuje cztery operatory:

Operator	Wartość porównania	Zwraca
any_of	Tablica identyfikatorów elementów	Elementy, które zależą od dowolnego ze wskazanych elementów.
not_any_of	Tablica identyfikatorów elementów	Elementy, które nie zależą od żadnego ze wskazanych elementów.
is_empty	[]	Elementy, dla których nie ustawiono zależności.
is_not_empty	[]	Elementy, dla których ustawiono co najmniej jedną zależność.

Znajdowanie wszystkich elementów zależnych od określonego elementu

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

Znajdowanie wszystkich elementów bez zależności

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

---

Typy relacji zależności

monday.com obsługuje cztery typy relacji zależności, które określają sposób powiązania dwóch elementów:

Typ	Skrót	Opis
Koniec–początek	FS	Element B nie może się rozpocząć, dopóki nie zakończy się element A. To najczęściej używany typ.
Początek–początek	SS	Element B nie może się rozpocząć, dopóki nie rozpocznie się element A.
Koniec–koniec	FF	Element B nie może się zakończyć, dopóki nie zakończy się element A.
Początek–koniec	SF	Element B nie może się zakończyć, dopóki nie rozpocznie się element A. Ten typ jest rzadko używany.

Te typy ustawia się dla każdej relacji zależności w interfejsie monday.com podczas wybierania zależności.

---

Typowe zastosowania

Wyświetlanie łańcucha zależności

To zapytanie pobiera wszystkie elementy na tablicy wraz z pełnymi danymi o zależnościach - przyda się do wizualizacji łańcuchów lub sprawdzania kolejności:

query {
  boards(ids: [1234567890]) {
    items_page {
      items {
        id
        name
        column_values(types: dependency) {
          ... on DependencyValue {
            linked_item_ids
            display_value
          }
        }
      }
    }
  }
}

Sprawdzanie, czy nie ma cyklicznych zależności

API nie wykrywa cykli. Jeśli tworzysz narzędzie, które programowo dodaje zależności, zaimplementuj po stronie klienta wykrywanie cykli. Przed zapisaniem zmian przejdź graf linked_item_ids.

---

Powiązane materiały

• Dokumentacja kolumny zależności
• Dokumentacja kolumny osi czasu
• Odpytanie elementów tablicy
• change_multiple_column_values