Получите постраничный список пользовательских полей для проекта или нескольких проектов с параметрами фильтрации и сортировки
Список всех пользовательских полей
Пользовательские поля позволяют вам расширить стандартную структуру записей Blue дополнительными полями данных, специфичными для ваших бизнес-потребностей. Этот конечный пункт получает пользовательские поля, доступные в ваших проектах, с фильтрацией по типу поля и поддержкой постраничного вывода.
Простой пример
query ListCustomFields {
customFields(
filter: { projectId: "project_123" }
sort: position_ASC
take: 20
) {
items {
id
uid
name
type
position
}
pageInfo {
totalItems
hasNextPage
}
}
}
Расширенный пример
query ListCustomFieldsAdvanced {
customFields(
filter: {
projectId: "project_123"
types: [TEXT_SINGLE, NUMBER, SELECT_SINGLE]
}
sort: name_ASC
skip: 20
take: 50
) {
items {
id
uid
name
type
position
description
# Type-specific fields
min # For NUMBER, RATING, PERCENT
max # For NUMBER, RATING, PERCENT
currency # For CURRENCY type
prefix # For UNIQUE_ID type
isDueDate # For DATE type
formula # For FORMULA type
# Validation settings
editable
metadata
# For SELECT types
customFieldOptions {
id
title
color
position
}
}
pageInfo {
totalItems
hasNextPage
hasPreviousPage
}
}
}
Входные параметры
| Параметр |
Тип |
Обязательный |
Описание |
projectId |
String |
Нет |
Фильтр по конкретному ID проекта |
types |
[CustomFieldType!] |
Нет |
Фильтр по типам пользовательских полей |
Значения CustomFieldSort
| Значение |
Описание |
name_ASC |
Сортировать по имени по возрастанию (A-Z) |
name_DESC |
Сортировать по имени по убыванию (Z-A) |
createdAt_ASC |
Сортировать по дате создания (сначала старые) |
createdAt_DESC |
Сортировать по дате создания (сначала новые) |
position_ASC |
Сортировать по позиции (по умолчанию) |
position_DESC |
Сортировать по позиции по убыванию |
Значения CustomFieldType
| Значение |
Описание |
TEXT_SINGLE |
Поле для ввода текста в одну строку |
TEXT_MULTI |
Многострочная текстовая область |
SELECT_SINGLE |
Выпадающий список с одним выбором |
SELECT_MULTI |
Выпадающий список с несколькими выборами |
CHECKBOX |
Поле для флажка (логическое значение) |
RATING |
Оценка по звёздам (1-5 или пользовательский диапазон) |
PHONE |
Номер телефона с проверкой |
NUMBER |
Числовой ввод |
CURRENCY |
Сумма в валюте |
PERCENT |
Процентное значение |
EMAIL |
Адрес электронной почты с проверкой |
URL |
URL веб-сайта с проверкой |
UNIQUE_ID |
Авто-сгенерированный уникальный идентификатор |
LOCATION |
Географическое местоположение (широта/долгота) |
FILE |
Прикреплённый файл |
DATE |
Выбор даты |
COUNTRY |
Выбор страны |
FORMULA |
Вычисляемое поле на основе других полей |
REFERENCE |
Ссылка на записи в другом проекте |
LOOKUP |
Получение данных из ссылочных записей |
TIME_DURATION |
Поле для отслеживания времени |
BUTTON |
Поле для активной кнопки |
CURRENCY_CONVERSION |
Поле для конвертации валюты |
Параметры постраничного вывода
| Параметр |
Тип |
Обязательный |
Описание |
skip |
Int |
Нет |
Количество элементов для пропуска (по умолчанию: 0) |
take |
Int |
Нет |
Количество элементов для возврата (по умолчанию: 20, максимум: 500) |
Поля ответа
CustomField
| Поле |
Тип |
Описание |
id |
String! |
Уникальный идентификатор |
uid |
String! |
Уникальный удобочитаемый ID |
name |
String! |
Отображаемое имя поля |
type |
CustomFieldType! |
Тип пользовательского поля |
position |
Float! |
Позиция сортировки |
description |
String |
Описание поля (необязательно) |
min |
Float |
Минимальное значение (NUMBER, RATING, PERCENT) |
max |
Float |
Максимальное значение (NUMBER, RATING, PERCENT) |
currency |
String |
Код валюты (тип CURRENCY) |
prefix |
String |
Префикс для генерации UNIQUE_ID |
isDueDate |
Boolean |
Является ли поле DATE датой выполнения |
formula |
JSON |
Конфигурация формулы (тип FORMULA) |
editable |
Boolean |
Может ли текущий пользователь редактировать это поле |
metadata |
JSON |
Дополнительная конфигурация поля |
customFieldOptions |
[CustomFieldOption!] |
Доступные варианты для типов SELECT |
CustomFieldOption
| Поле |
Тип |
Описание |
id |
String! |
Уникальный идентификатор |
title |
String! |
Отображаемый текст для варианта |
color |
String! |
Шестнадцатеричный код цвета |
position |
Float! |
Позиция сортировки |
PageInfo
| Поле |
Тип |
Описание |
totalItems |
Int |
Общее количество пользовательских полей |
hasNextPage |
Boolean! |
Существуют ли дополнительные страницы |
hasPreviousPage |
Boolean! |
Существуют ли предыдущие страницы |
endCursor |
String |
Курсор для постраничного вывода (устарело - используйте постраничный вывод на основе смещения) |
Необходимые разрешения
Пользовательские поля доступны в зависимости от вашей роли в проекте. Если у вас есть пользовательская роль с ограниченным доступом к полям, будут возвращены только поля, отмеченные как редактируемые для вашей роли.
| Роль |
Может перечислить пользовательские поля |
OWNER |
✅ Да (все поля) |
ADMIN |
✅ Да (все поля) |
MEMBER |
✅ Да (в зависимости от разрешений роли) |
CLIENT |
✅ Да (в зависимости от разрешений роли) |
Ответы на ошибки
Проект не найден
{
"errors": [{
"message": "Project not found.",
"extensions": {
"code": "PROJECT_NOT_FOUND"
}
}]
}
Неверный тип поля
{
"errors": [{
"message": "Variable \"$filter\" got invalid value \"INVALID_TYPE\" at \"filter.types[0]\"; Value \"INVALID_TYPE\" does not exist in \"CustomFieldType\" enum.",
"extensions": {
"code": "GRAPHQL_VALIDATION_FAILED"
}
}]
}
Важные заметки
- Пользовательские поля ограничены проектами - вы должны указать
projectId в фильтре
- Параметр
take ограничен 500 элементами на запрос для повышения производительности
- Поля возвращаются в зависимости от разрешений пользователя - пользовательские роли могут иметь ограниченный доступ
- Порядок сортировки по умолчанию - по
position по возрастанию, что отражает порядок, показанный в интерфейсе
- Этот запрос поддерживает фильтрацию по одному проекту - для многопроектных запросов используйте вложенный интерфейс CustomFieldQueries
- Некоторые типы полей (например, FORMULA и REFERENCE) могут включать дополнительные вложенные структуры данных
- Поле
editable указывает, может ли текущий пользователь изменять значения для этого пользовательского поля
Связанные конечные точки