Kolumna listy rozwijanej pozwala wybrać jedną lub więcej opcji ze zdefiniowanej listy. Jest często używana do kategoryzowania, dodawania etykiet i tworzenia przepływów pracy z wielokrotnym wyborem.

Za pomocą API kolumna listy rozwijanej obsługuje odczyt, filtrowanie, tworzenie, aktualizowanie i czyszczenie wartości.

Typ kolumny	Typ implementacji	Obsługiwane operacje
dropdown	DropdownValue	Odczyt: Tak Filtrowanie: Tak Tworzenie: Tak Aktualizowanie: Tak Czyszczenie: Tak

---

Zapytania

Kolumny listy rozwijanej można odczytywać za pomocą pola column_values w obiekcie items. Użyj do tego wbudowanego fragmentu dla DropdownValue.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on DropdownValue {
        id
        text
        value
        values {
          id
          label
        }
        column {
          id
          title
        }
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!], $columnType: [ColumnType!]) {
    items(ids: $itemIds) {
      name
      column_values(types: $columnType) {
        ... on DropdownValue {
          id
          text
          value
          values {
            id
            label
          }
          column {
            id
            title
          }
        }
      }
    }
  }
`;

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

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 DropdownValue.

Pole	Opis
column Column!	Kolumna, do której należy wartość.
id ID!	Unikalny identyfikator kolumny listy rozwijanej.
text String	Wartość kolumny w postaci tekstu (etykiety oddzielone przecinkami). Zwraca null, jeśli kolumna nie ma wartości.
type ColumnType!	Typ kolumny (dropdown).
value JSON	Surowa wartość kolumny jako ciąg JSON. Zwraca {"ids": [1, 3]}, gdzie tablica zawiera identyfikatory wybranych etykiet.
values [DropdownValueOption!]!	Wybrane opcje listy rozwijanej dla tego elementu. Każda opcja zawiera pola id i label.

DropdownValueOption

Każda wybrana opcja w tablicy values zawiera:

Pole	Opis
id ID!	Unikalny identyfikator opcji listy rozwijanej.
label String!	Tekst wyświetlany dla opcji listy rozwijanej.

Przykładowa odpowiedź

{
  "data": {
    "items": [
      {
        "name": "Project Alpha",
        "column_values": [
          {
            "id": "dropdown",
            "text": "Marketing, Design",
            "value": "{\"ids\":[1,3]}",
            "values": [
              { "id": "1", "label": "Marketing" },
              { "id": "3", "label": "Design" }
            ],
            "column": {
              "id": "dropdown",
              "title": "Category"
            }
          }
        ]
      }
    ]
  }
}

---

Filtrowanie

Możesz filtrować elementy według wartości z kolumny listy rozwijanej za pomocą obiektu items_page. Kolumna listy rozwijanej obsługuje następujące operatory:

Operator	Wartość porównawcza	Opis
any_of	Tablica identyfikatorów etykiet listy rozwijanej (np. [1, 2])	Zwraca elementy, w których wybrano dowolną z podanych etykiet listy rozwijanej. Użyj identyfikatorów etykiet z ustawień kolumny.
not_any_of	Tablica identyfikatorów etykiet listy rozwijanej (np. [1, 2])	Pomija elementy, w których wybrano dowolną z podanych etykiet listy rozwijanej.
contains_text	Część lub cała treść etykiety jako ciąg tekstowy (np. "Marketing")	Zwraca elementy, których etykiety listy rozwijanej zawierają podany tekst.
not_contains_text	Część lub cała treść etykiety jako ciąg tekstowy (np. "Sales")	Pomija elementy, których etykiety listy rozwijanej zawierają podany tekst.
is_empty	[]	Zwraca elementy, w których nie wybrano żadnych etykiet listy rozwijanej.
is_not_empty	[]	Zwraca elementy, w których wybrano co najmniej jedną etykietę listy rozwijanej.

Przykłady

Filtrowanie według identyfikatora etykiety

Ten przykład zwraca wszystkie elementy, w których wybrano etykietę listy rozwijanej o identyfikatorze 1.

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "dropdown"
            compare_value: [1]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on DropdownValue {
            values {
              id
              label
            }
          }
        }
      }
    }
  }
}

Filtrowanie według tekstu etykiety

Ten przykład zwraca wszystkie elementy, których etykiety listy rozwijanej zawierają tekst „Marketing”.

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

const query = `
  query ($boardId: [ID!], $columnId: ID!, $operator: ItemsQueryRuleOperator!, $compareValue: CompareValue!) {
    boards(ids: $boardId) {
      items_page(
        query_params: {
          rules: [
            { column_id: $columnId, compare_value: $compareValue, operator: $operator }
          ]
        }
      ) {
        items { id name }
      }
    }
  }
`;

const variables = {
  boardId: 1234567890,
  columnId: "dropdown",
  compareValue: ["Marketing"],
  operator: "contains_text",
};

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

Filtrowanie pustej listy rozwijanej

Ten przykład zwraca wszystkie elementy, w których nie wybrano żadnych etykiet listy rozwijanej.

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

---

Mutacje

Tworzenie

Wymagany zakres uprawnień: boards:write

Mutacja create_dropdown_column tworzy nową kolumnę listy rozwijanej z ustawieniami o określonych typach. Możesz wskazać, które pola mają zostać zwrócone w odpowiedzi mutacji.

mutation {
  create_dropdown_column(
    board_id: 1234567890
    id: "project_category"
    title: "Project Category"
    defaults: {
      labels: [
        { label: "Marketing" }
        { label: "Engineering" }
        { label: "Design" }
        { label: "Sales" }
        { label: "HR" }
      ]
      limit_select: true
      label_limit_count: 2
    }
    description: "The project's category."
  ) {
    id
    title
    description
    settings
  }
}

Argumenty

Argument	Typ	Opis
board_id	ID!	Unikalny identyfikator tablicy.
id	String	Niestandardowy identyfikator kolumny. Jeśli go nie podasz, zostanie wygenerowany automatycznie.
title	String!	Tytuł kolumny.
description	String	Opis kolumny.
after_column_id	ID	Identyfikator kolumny, za którą ma zostać wstawiona nowa kolumna.
defaults CreateDropdownColumnSettingsInput	Object	Konfiguracja etykiet kolumny i wyboru. Zobacz pola poniżej.

Pola wejściowe ustawień (CreateDropdownColumnSettingsInput)

Pole	Typ	Wymagane	Opis
labels	[CreateDropdownLabelInput!]!	Tak	Tablica obiektów etykiet. Każdy obiekt musi zawierać pole label (ciąg tekstowy).
limit_select	Boolean	Nie	Określa, czy wybór ma być ograniczony do określonej liczby etykiet.
label_limit_count	Int	Nie	Maksymalna liczba etykiet, które można wybrać, gdy włączono limit_select.

Aktualizowanie ustawień kolumny

Wymagany zakres uprawnień: boards:write

Mutacja update_dropdown_column aktualizuje ustawienia istniejącej kolumny listy rozwijanej, w tym jej tytuł, opis, konfigurację etykiet i limity wyboru.

mutation {
  update_dropdown_column(
    board_id: 1234567890
    id: "dropdown"
    revision: "replace_with_current_revision"
    title: "Project Category"
    settings: {
      labels: [
        { id: 1, label: "Marketing" }
        { id: 2, label: "Engineering" }
        { id: 3, label: "Design" }
        { id: 4, label: "Sales" }
        { id: 5, label: "HR" }
        { id: 6, label: "Old Label", is_deactivated: true }
      ]
      limit_select: true
      label_limit_count: 3
    }
  ) {
    id
    title
    settings
  }
}

Argumenty

Argument	Typ	Wymagane	Opis
board_id	ID!	Tak	Unikalny identyfikator tablicy.
id	String!	Tak	Unikalny identyfikator kolumny.
revision	String!	Tak	Bieżąca wersja kolumny, używana do wykrywania konfliktów.
title	String	Nie	Nowy tytuł kolumny.
description	String	Nie	Nowy opis kolumny.
width	Int	Nie	Szerokość kolumny w pikselach.
settings UpdateDropdownColumnSettingsInput	Object	Nie	Zaktualizowana konfiguracja etykiet kolumny i wyboru.

Pola wejściowe aktualizacji etykiet (UpdateDropdownLabelInput)

Pole	Typ	Wymagane	Opis
label	String!	Tak	Tekst wyświetlany dla etykiety.
id	Int	Nie	Unikalny identyfikator etykiety. Wymagany podczas aktualizowania istniejącej etykiety.
is_deactivated	Boolean	Nie	Określa, czy etykieta jest wyłączona (ukryta w interfejsie). Domyślnie false.

Aktualizowanie wartości

Wartość kolumny listy rozwijanej możesz zaktualizować za pomocą mutacji change_simple_column_value lub change_multiple_column_values. W zależności od wybranej mutacji możesz przesłać wartości jako zwykłe ciągi tekstowe lub obiekty JSON.

change_simple_column_value

Przekaż identyfikatory etykiet lub ich tekst jako ciąg wartości oddzielonych przecinkami w polu value.

Jeśli etykieta nie istnieje, API zwróci błąd zawierający listę istniejących etykiet. Aby automatycznie tworzyć brakujące etykiety, użyj create_labels_if_missing: true.

Aktualizowanie według identyfikatorów

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "dropdown"
    value: "1,2"
  ) {
    id
  }
}

Aktualizowanie według etykiet

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "dropdown"
    value: "Marketing, Engineering"
  ) {
    id
  }
}

change_multiple_column_values

Przekaż identyfikatory listy rozwijanej lub tekst etykiet jako obiekt JSON w polu column_values.

JSON z identyfikatorami

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"dropdown\": {\"ids\": [1, 2]}}"
  ) {
    id
  }
}

JSON z etykietami

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"dropdown\": {\"labels\": [\"Marketing\", \"Engineering\"]}}"
  ) {
    id
  }
}

Dodawanie nowej etykiety listy rozwijanej

Możesz utworzyć nową etykietę listy rozwijanej i przypisać ją do elementu, używając create_labels_if_missing: true. Działa to zarówno z change_simple_column_value, jak i change_multiple_column_values.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "dropdown"
    value: "New Category"
    create_labels_if_missing: true
  ) {
    id
  }
}

Ustawianie wartości listy rozwijanej podczas tworzenia elementu

Możesz ustawić wartości listy rozwijanej podczas tworzenia elementu, przekazując wartość kolumny w argumencie column_values.

Tworzenie z identyfikatorami etykiet

mutation {
  create_item(
    board_id: 1234567890
    item_name: "New task"
    column_values: "{\"dropdown\": {\"ids\": [1, 3]}}"
  ) {
    id
    name
  }
}

Tworzenie z tekstem etykiet

mutation {
  create_item(
    board_id: 1234567890
    item_name: "New task"
    column_values: "{\"dropdown\": {\"labels\": [\"Marketing\", \"Design\"]}}"
  ) {
    id
    name
  }
}

Czyszczenie wartości

Możesz wyczyścić wartość kolumny listy rozwijanej za pomocą mutacji change_simple_column_value lub change_multiple_column_values.

change_simple_column_value

Przekaż pusty ciąg tekstowy w polu value.

mutation {
  change_simple_column_value(
    item_id: 9876543210
    board_id: 1234567890
    column_id: "dropdown"
    value: ""
  ) {
    id
  }
}

change_multiple_column_values

Przekaż null lub pustą tablicę etykiet w polu column_values.

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

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"dropdown\": {\"labels\": []}}"
  ) {
    id
  }
}

---

Odczytywanie konfiguracji kolumny

Aby sprawdzić dostępne etykiety i ustawienia wyboru w kolumnie listy rozwijanej, odczytaj jej ustawienia za pomocą pola settings kolumny.

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

Struktura odpowiedzi settings

Pole	Typ	Opis
labels	DropdownLabel[]	Tablica obiektów etykiet reprezentujących dostępne opcje listy rozwijanej.

DropdownLabel

Pole	Typ	Wymagane	Opis
id	number	Tak	Unikalny identyfikator numeryczny etykiety.
label	string	Tak	Tekst wyświetlany dla opcji listy rozwijanej.
is_deactivated	boolean	Nie	Określa, czy etykieta jest wyłączona (ukryta w interfejsie). Domyślnie false.

Przykładowa odpowiedź

{
  "settings": {
    "labels": [
      { "id": 1, "label": "Marketing", "is_deactivated": false },
      { "id": 2, "label": "Engineering", "is_deactivated": false },
      { "id": 3, "label": "Design", "is_deactivated": false },
      { "id": 4, "label": "Sales", "is_deactivated": false },
      { "id": 5, "label": "HR", "is_deactivated": false }
    ]
  }
}

---

Pobieranie schematu typu kolumny

Możesz programowo pobrać schemat JSON ustawień kolumny listy rozwijanej 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: dropdown
  )
}

{
  "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": {
              "type": {
                "type": "string",
                "description": "The type of column (dropdown)"
              },
              "labels": {
                "type": "array",
                "description": "Array of dropdown labels",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "integer",
                      "description": "The unique identifier for the label"
                    },
                    "label": {
                      "type": "string",
                      "description": "The display text for the label"
                    },
                    "is_deactivated": {
                      "type": "boolean",
                      "description": "Whether the label is deactivated"
                    }
                  },
                  "required": [
                    "label"
                  ],
                  "additionalProperties": false
                }
              },
              "limit_select": {
                "type": "boolean",
                "description": "Whether to limit selection to a single value"
              },
              "label_limit_count": {
                "type": "integer",
                "description": "Maximum number of labels that can be selected"
              }
            },
            "additionalProperties": false,
            "required": [
              "labels"
            ]
          }
        }
      }
    }
  }
}

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