Kolumna śledzenia postępów łączy wszystkie kolumny statusu na tablicy, aby obliczyć postęp wyrażony w procentach. Wartość procentowa odzwierciedla udział kolumn statusu, które mają stan „zrobione” dla danego elementu. Wagę każdej uwzględnianej kolumny statusu można ustawić osobno.

Za pomocą API kolumna śledzenia postępów obsługuje odczyt, filtrowanie i tworzenie.

Typ kolumny	Typ implementacji	Obsługiwane operacje
progress	ProgressValue	Odczyt: Tak Filtrowanie: Tak Tworzenie: Tak Aktualizacja: Nie Czyszczenie: Nie

---

Zapytania

Kolumny śledzenia postępów można pobierać za pomocą pola column_values obiektu items, używając wbudowanego fragmentu.

ProgressValue

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on ProgressValue {
        id
        text
        value
        type
        is_leaf
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on ProgressValue {
          id
          text
          value
          type
          is_leaf
        }
      }
    }
  }
`;

const variables = { itemIds: [1234567890, 9876543210] };

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

Pola

Za pomocą poniższych pól możesz określić, jakie informacje zwróci implementacja ProgressValue.

Pole	Opis
column Column!	Kolumna, do której należy wartość.
id ID!	Unikalny identyfikator kolumny.
is_leaf Boolean!	Określa, czy ten element jest liściem (nie ma podelementów).
text String	Wartość kolumny w postaci tekstu. Zwraca null, jeśli kolumna nie ma wartości.
type ColumnType!	Typ kolumny (progress).
value JSON	Surowa wartość kolumny w postaci ciągu JSON. W przypadku kolumn śledzenia postępów zwraca null, ponieważ ich wartość jest obliczana.

Przykładowa odpowiedź

{
  "data": {
    "items": [
      {
        "name": "Project Alpha",
        "column_values": [
          {
            "id": "progress",
            "text": "",
            "value": null,
            "type": "progress",
            "is_leaf": false
          }
        ]
      }
    ]
  }
}

---

Filtrowanie

Możesz filtrować elementy według wartości w kolumnie śledzenia postępów za pomocą obiektu items_page. Kolumna śledzenia postępów obsługuje następujące operatory:

Operator	Wartość porównania	Opis
any_of	Tablica wartości progowych	Zwraca elementy, których postęp osiąga lub przekracza określony próg. Obsługiwane wartości: 0 (poniżej 20%), "20" (co najmniej 20%), "50" (co najmniej 50%), "80" (co najmniej 80%), "100" (ukończone), "" (puste).
not_any_of	Tablica wartości progowych	Wyklucza elementy, których postęp osiąga lub przekracza określony próg. Używa tych samych wartości progowych co any_of.

Wartości porównania

Wartość	Znaczenie
0	Elementy ukończone w mniej niż 20%
"20"	Elementy ukończone w co najmniej 20%
"50"	Elementy ukończone w co najmniej 50%
"80"	Elementy ukończone w co najmniej 80%
"100"	Elementy ukończone w 100%
""	Elementy z pustymi wartościami

Przykłady

Filtrowanie według progu postępu

Ten przykład zwraca wszystkie elementy ukończone w co najmniej 80%.

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

Filtrowanie ukończonych elementów

Ten przykład zwraca wszystkie elementy ukończone w 100%.

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

Wykluczanie elementów z dużym postępem

Ten przykład zwraca wszystkie elementy, które NIE są ukończone w co najmniej 80%.

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

Filtrowanie elementów bez postępu

Ten przykład zwraca wszystkie elementy z pustymi wartościami postępu (żadna kolumna statusu nie ma stanu „zrobione”).

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

---

Mutacje

Tworzenie

Wymagany zakres uprawnień: boards:write

Możesz utworzyć kolumnę śledzenia postępów za pomocą mutacji create_column. Kolumna automatycznie wykrywa i uwzględnia wszystkie kolumny statusu na tablicy.

mutation {
  create_column(
    board_id: 1234567890
    column_type: progress
    title: "Project Progress"
  ) {
    id
    title
    type
    settings
  }
}

Argumenty

Argument	Typ	Opis
board_id	ID!	Unikalny identyfikator tablicy.
column_type	ColumnType!	Musi mieć wartość progress.
title	String!	Tytuł kolumny.
description	String	Opis kolumny.
defaults	JSON	Ustawienia konfiguracji właściwe dla kolumny, w postaci ciągu JSON.

Przykładowa odpowiedź

{
  "data": {
    "create_column": {
      "id": "columns_battery_xxxxxx",
      "title": "Project Progress",
      "type": "progress",
      "settings": {"related_columns":{"isNormalized":false,"columns":{"status":{"isSelected":true,"percentage":50},"color_1":{"isSelected":true,"percentage":50}}}}
    }
  }
}

---

Odczytywanie konfiguracji kolumny

Aby sprawdzić konfigurację kolumny śledzenia postępów, możesz pobrać jej ustawienia za pomocą pola settings kolumny.

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

Struktura odpowiedzi settings

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

Klucz	Typ	Opis
related_columns	Object	Konfiguracja kolumn statusu uwzględnianych przy obliczaniu postępu.
related_columns.isNormalized	Boolean	Określa, czy wartości procentowe powiązanych kolumn mają być normalizowane.
related_columns.columns	Object	Mapuje identyfikator każdej kolumny statusu na stan wyboru i wagę.
related_columns.columns.{id}.isSelected	Boolean	Określa, czy kolumna jest uwzględniana przy obliczaniu postępu.
related_columns.columns.{id}.percentage	Integer	Procentowa waga kolumny (0–100).

Przykładowa odpowiedź settings

{
  "related_columns": {
    "isNormalized": false,
    "columns": {
      "status": {
        "isSelected": true,
        "percentage": 50
      },
      "color_1": {
        "isSelected": true,
        "percentage": 50
      }
    }
  }
}

---

Pobieranie schematu typu kolumny

Możesz programowo pobrać schemat JSON ustawień kolumny śledzenia postępó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: progress
  )
}

{
  "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": {
              "related_columns": {
                "type": "object",
                "description": "Configuration for related columns contributing to the battery",
                "properties": {
                  "isNormalized": {
                    "type": "boolean",
                    "description": "Whether to normalize percentages across related columns"
                  },
                  "columns": {
                    "type": "object",
                    "description": "Mapping of column identifier to selection and weight",
                    "additionalProperties": {
                      "type": "object",
                      "properties": {
                        "isSelected": {
                          "type": "boolean",
                          "description": "Whether the column is included in the battery calculation"
                        },
                        "percentage": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 100,
                          "description": "Weight percentage for the column (0-100)"
                        }
                      },
                      "additionalProperties": false
                    }
                  }
                },
                "additionalProperties": false
              }
            },
            "additionalProperties": false
          }
        }
      }
    }
  }
}

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 walidacji ustawień kolumn, dynamicznego generowania interfejsów lub przekazywania kontekstu agentom AI. Dowiedz się więcej o formacie odpowiedzi schematu.