Kolumna godziny przechowuje konkretną wartość czasu. Wewnętrznie używa formatu GG:MM i zapisu 24-godzinnego. Jest często używana do planowania, rejestrowania czasu lub ustawiania terminów w ciągu dnia.

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

Typ kolumny	Typ implementacji	Obsługiwane operacje
hour	HourValue	Odczyt: tak Filtrowanie: tak Aktualizowanie: tak Czyszczenie: tak

---

Zapytania

Kolumny godziny można odpytywać za pomocą pola column_values w zapytaniach items, używając wbudowanego fragmentu dla HourValue.

query {
  items(ids: [1234567890, 9876543210]) {
    name
    column_values {
      ... on HourValue {
        id
        hour
        minute
        text
        value
        updated_at
      }
    }
  }
}

const query = `
  query ($itemIds: [ID!]) {
    items(ids: $itemIds) {
      name
      column_values {
        ... on HourValue {
          id
          hour
          minute
          text
          value
          updated_at
        }
      }
    }
  }
`;

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

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

Pola

Za pomocą następujących pól możesz określić, jakie informacje zwróci implementacja HourValue.

Pole	Opis
column Column!	Kolumna, do której należy wartość.
hour Int	Wartość godziny (0–23, format 24-godzinny). Zwraca null, jeśli kolumna jest pusta.
id ID!	Unikalny identyfikator kolumny.
minute Int	Wartość minut (0–59). Zwraca null, jeśli kolumna jest pusta.
text String	Wartość kolumny w sformatowanym tekście, np. "02:30 PM". Zwraca "", jeśli kolumna nie zawiera wartości.
type ColumnType!	Typ kolumny.
updated_at Date	Data ostatniej aktualizacji kolumny.
value JSON	Surowa wartość kolumny w formacie JSON. Zwraca {"hour": N, "minute": N} albo null, jeśli kolumna jest pusta.

Przykładowa odpowiedź

{
  "data": {
    "items": [
      {
        "name": "Task A",
        "column_values": [
          {
            "id": "hour",
            "hour": 14,
            "minute": 30,
            "text": "02:30 PM",
            "value": "{\"hour\":14,\"minute\":30}",
            "updated_at": null
          }
        ]
      },
      {
        "name": "Task B",
        "column_values": [
          {
            "id": "hour",
            "hour": null,
            "minute": null,
            "text": "",
            "value": null,
            "updated_at": null
          }
        ]
      }
    ]
  }
}

---

Filtrowanie

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

Operator	Wartość porównania	Opis
any_of	Tablica etykiet zakresów czasu, np. ["Afternoon"]	Zwraca elementy, których wartość godziny przypada w jednym z podanych zakresów czasu.
not_any_of	Tablica etykiet zakresów czasu, np. ["Morning"]	Wyklucza elementy, których wartość godziny przypada w którymkolwiek z podanych zakresów czasu.
is_empty	[]	Zwraca elementy, których wartość godziny jest pusta (nieustawiona).
is_not_empty	[]	Zwraca elementy, dla których ustawiono wartość godziny.

Wartości porównania

Filtry kolumny godziny korzystają z predefiniowanych etykiet zakresów czasu, zgodnych z interfejsem. Wartości te zależą od ustawień strefy czasowej użytkownika w chwili wysłania zapytania API.

Etykieta	Zakres czasu
Early morning	4:00 – 7:00 AM
Morning	7:00 AM – 12:00 PM
Afternoon	12:00 – 8:00 PM
Evening	8:00 – 11:00 PM
Night	11:00 PM – 4:00 AM

Przykłady

Filtrowanie według zakresu czasu

Ten przykład zwraca elementy, których wartość kolumny godziny mieści się w zakresie Afternoon:

query {
  boards(ids: 1234567890) {
    items_page(
      query_params: {
        rules: [
          {
            column_id: "hour"
            compare_value: ["Afternoon"]
            operator: any_of
          }
        ]
      }
    ) {
      items {
        id
        name
        column_values {
          ... on HourValue {
            hour
            minute
            text
          }
        }
      }
    }
  }
}

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: "hour",
  compareValue: ["Afternoon"],
  operator: "any_of"
};

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

Filtrowanie według kilku zakresów czasu

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

Filtrowanie według pustej wartości godziny

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

---

Mutacje

Tworzenie kolumny

Możesz utworzyć kolumnę godziny za pomocą ogólnej mutacji create_column.

mutation {
  create_column(
    board_id: 1234567890
    title: "Meeting Time"
    column_type: hour
    description: "Scheduled meeting time"
  ) {
    id
    title
    description
  }
}

Możesz też przekazać argument defaults, aby ustawić format wyświetlania:

mutation {
  create_column(
    board_id: 1234567890
    title: "Meeting Time (24H)"
    column_type: hour
    defaults: "{\"format\": \"24H\"}"
  ) {
    id
    title
  }
}

Aktualizowanie wartości

Możesz zaktualizować kolumnę godziny za pomocą change_multiple_column_values, przekazując obiekt JSON z kluczami hour i minute. Pole hour używa formatu 24-godzinnego (0–23), a pole minute przyjmuje wartości od 0 do 59.

mutation {
  change_multiple_column_values(
    item_id: 9876543210
    board_id: 1234567890
    column_values: "{\"hour\": {\"hour\": 16, \"minute\": 42}}"
  ) {
    id
  }
}

const query = `
  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({
    hour: {
      hour: 16,
      minute: 42
    }
  })
};

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

Format wartości

Klucz	Typ	Wymagane	Opis
hour	Int	Tak	Wartość godziny w formacie 24-godzinnym (0–23).
minute	Int	Tak	Wartość minut (0–59).

Ustawianie wartości podczas tworzenia elementu

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

mutation {
  create_item(
    board_id: 1234567890
    item_name: "Morning standup"
    column_values: "{\"hour\": {\"hour\": 9, \"minute\": 0}}"
  ) {
    id
    name
  }
}

Czyszczenie wartości

Możesz wyczyścić kolumnę godziny za pomocą change_multiple_column_values, przekazując null w column_values.

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

const query = `
  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({
    hour: null
  })
};

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

---

Odczytywanie konfiguracji kolumny

Aby sprawdzić format wyświetlania kolumny godziny, odczytaj jej ustawienia za pomocą pola settings.

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

Struktura odpowiedzi settings

Pole settings zwraca typowany obiekt JSON. Może zawierać następujący klucz:

Klucz	Typ	Opis
format	String	Format wyświetlania czasu: "24H" lub "12H". Jeśli nie zostanie podany, domyślnie używany jest "12H".

Przykładowa odpowiedź settings

Kolumna skonfigurowana do wyświetlania czasu w formacie 24-godzinnym:

{
  "format": "24H"
}

Domyślna kolumna (wyświetlanie czasu w formacie 12-godzinnym) zwraca pusty obiekt:

{}

---

Pobieranie schematu typu kolumny

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

{
  "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": {
              "format": {
                "type": "string",
                "description": "Time display format",
                "enum": [
                  "24H",
                  "12H"
                ]
              }
            },
            "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 jej użyć 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.