Поле пользовательского выбора с одним вариантом

Создайте поля с одним вариантом, чтобы позволить пользователям выбрать один вариант из заранее определенного списка

Поля пользовательского выбора с одним вариантом позволяют пользователям выбрать ровно один вариант из заранее определенного списка. Они идеально подходят для полей статуса, категорий, приоритетов или любого сценария, где следует сделать только один выбор из контролируемого набора вариантов.

Простой пример

Создайте простое поле с одним вариантом:

mutation CreateSingleSelectField {
  createCustomField(input: {
    name: "Project Status"
    type: SELECT_SINGLE
    projectId: "proj_123"
  }) {
    id
    name
    type
  }
}

Расширенный пример

Создайте поле с одним вариантом с заранее определенными вариантами:

mutation CreateDetailedSingleSelectField {
  createCustomField(input: {
    name: "Priority Level"
    type: SELECT_SINGLE
    projectId: "proj_123"
    description: "Set the priority level for this task"
    customFieldOptions: [
      { title: "Low", color: "#28a745" }
      { title: "Medium", color: "#ffc107" }
      { title: "High", color: "#fd7e14" }
      { title: "Critical", color: "#dc3545" }
    ]
  }) {
    id
    name
    type
    description
    customFieldOptions {
      id
      title
      color
      position
    }
  }
}

Параметры ввода

CreateCustomFieldInput

Параметр	Тип	Обязательный	Описание
`name`	String!	✅ Да	Отображаемое имя поля с одним вариантом
`type`	CustomFieldType!	✅ Да	Должен быть `SELECT_SINGLE`
`description`	String	Нет	Текст помощи, показываемый пользователям
`customFieldOptions`	[CreateCustomFieldOptionInput!]	Нет	Начальные варианты для поля

CreateCustomFieldOptionInput

Параметр	Тип	Обязательный	Описание
`title`	String!	✅ Да	Отображаемый текст для варианта
`color`	String	Нет	Шестнадцатеричный код цвета для варианта

Добавление вариантов в существующие поля

Добавьте новые варианты в существующее поле с одним вариантом:

mutation AddSingleSelectOption {
  createCustomFieldOption(input: {
    customFieldId: "field_123"
    title: "Urgent"
    color: "#6f42c1"
  }) {
    id
    title
    color
    position
  }
}

Установка значений с одним вариантом

Чтобы установить выбранный вариант в записи:

mutation SetSingleSelectValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    customFieldOptionId: "option_789"
  })
}

Параметры SetTodoCustomFieldInput

Параметр	Тип	Обязательный	Описание
`todoId`	String!	✅ Да	ID записи для обновления
`customFieldId`	String!	✅ Да	ID пользовательского поля с одним вариантом
`customFieldOptionId`	String	Нет	ID варианта для выбора (предпочтительно для выбора с одним вариантом)
`customFieldOptionIds`	[String!]	Нет	Массив ID вариантов (использует первый элемент для выбора с одним вариантом)

Запрос значений с одним вариантом

Запросите значение с одним вариантом записи:

query GetRecordWithSingleSelect {
  todo(id: "todo_123") {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      value  # For SELECT_SINGLE, contains: {"id": "opt_123", "title": "High", "color": "#dc3545", "position": 3}
    }
  }
}

Поле value возвращает объект JSON с деталями выбранного варианта.

Создание записей со значениями с одним вариантом

При создании новой записи со значениями с одним вариантом:

mutation CreateRecordWithSingleSelect {
  createTodo(input: {
    title: "Review user feedback"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "priority_field_id"
      customFieldOptionId: "option_high_priority"
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      value  # Contains the selected option object
    }
  }
}

Полевые ответы

Ответ TodoCustomField

Поле	Тип	Описание
`id`	String!	Уникальный идентификатор для значения поля
`customField`	CustomField!	Определение пользовательского поля
`value`	JSON	Содержит объект выбранного варианта с id, заголовком, цветом, позицией
`todo`	Todo!	Запись, к которой принадлежит это значение
`createdAt`	DateTime!	Когда значение было создано
`updatedAt`	DateTime!	Когда значение было в последний раз изменено

Ответ CustomFieldOption

Поле	Тип	Описание
`id`	String!	Уникальный идентификатор для варианта
`title`	String!	Отображаемый текст для варианта
`color`	String	Шестнадцатеричный код цвета для визуального представления
`position`	Float	Порядок сортировки для варианта
`customField`	CustomField!	Пользовательское поле, к которому принадлежит этот вариант

Ответ CustomField

Поле	Тип	Описание
`id`	String!	Уникальный идентификатор для поля
`name`	String!	Отображаемое имя поля с одним вариантом
`type`	CustomFieldType!	Всегда `SELECT_SINGLE`
`description`	String	Текст помощи для поля
`customFieldOptions`	[CustomFieldOption!]	Все доступные варианты

Формат значения

Формат ввода

API Параметр: Используйте customFieldOptionId для ID одного варианта
Альтернатива: Используйте customFieldOptionIds массив (берет первый элемент)
Очистка выбора: Пропустите оба поля или передайте пустые значения

Формат вывода

Ответ GraphQL: Объект JSON в поле value, содержащий {id, title, color, position}
Журнал активности: Заголовок варианта как строка
Данные автоматизации: Заголовок варианта как строка

Поведение выбора

Исключительный выбор

Установка нового варианта автоматически удаляет предыдущий выбор
В одно время может быть выбран только один вариант
Установка null или пустого значения очищает выбор

Логика резервирования

Если предоставлен массив customFieldOptionIds, используется только первый вариант
Это обеспечивает совместимость с форматами ввода для множественного выбора
Пустые массивы или нулевые значения очищают выбор

Управление вариантами

Обновление свойств варианта

mutation UpdateOption {
  editCustomFieldOption(input: {
    id: "option_123"
    title: "Updated Priority"
    color: "#ff6b6b"
  }) {
    id
    title
    color
  }
}

Удаление варианта

mutation DeleteOption {
  deleteCustomFieldOption(id: "option_123")
}

Примечание: Удаление варианта очистит его из всех записей, где он был выбран.

Изменение порядка вариантов

mutation ReorderOptions {
  reorderCustomFieldOptions(input: {
    customFieldId: "field_123"
    optionIds: ["option_1", "option_3", "option_2"]
  }) {
    id
    position
  }
}

Правила валидации

Валидация варианта

Предоставленный ID варианта должен существовать
Вариант должен принадлежать указанному пользовательскому полю
Может быть выбран только один вариант (автоматически контролируется)
Нулевые/пустые значения допустимы (без выбора)

Валидация поля

Должно быть определено хотя бы одно значение, чтобы быть использованным
Заголовки вариантов должны быть уникальными в пределах поля
Цветовые коды должны быть в допустимом шестнадцатеричном формате (если предоставлены)

Необходимые разрешения

Действие	Необходимое разрешение
Create single-select field	Company role: `OWNER` or `ADMIN`
Update single-select field	Company role: `OWNER` or `ADMIN`
Add/edit options	Company role: `OWNER` or `ADMIN`
Set selected value	Any company role (`OWNER`, `ADMIN`, `MEMBER`, `CLIENT`) or custom project role with edit permission
View selected value	Standard record view permissions

Ответы на ошибки

Неверный ID варианта

{
  "errors": [{
    "message": "Custom field option was not found.",
    "extensions": {
      "code": "CUSTOM_FIELD_OPTION_NOT_FOUND"
    }
  }]
}

Вариант не принадлежит полю

{
  "errors": [{
    "message": "Option does not belong to this custom field",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

Поле не найдено

{
  "errors": [{
    "message": "Custom field was not found.",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Невозможно разобрать значение

{
  "errors": [{
    "message": "Unable to parse custom field value.",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Распространенные случаи использования

Статус и рабочий процесс
- Статус задачи (К выполнению, В процессе, Выполнено)
- Статус одобрения (В ожидании, Одобрено, Отклонено)
- Фаза проекта (Планирование, Разработка, Тестирование, Выпущено)
- Статус разрешения проблемы
Классификация и категоризация
- Уровни приоритета (Низкий, Средний, Высокий, Критический)
- Типы задач (Ошибка, Функция, Улучшение, Документация)
- Категории проектов (Внутренний, Клиентский, Исследовательский)
- Назначения по департаментам
Качество и оценка
- Статус обзора (Не начато, На обзоре, Одобрено)
- Оценки качества (Плохо, Удовлетворительно, Хорошо, Отлично)
- Уровни риска (Низкий, Средний, Высокий)
- Уровни уверенности
Назначение и владение
- Назначения команде
- Владение департаментом
- Назначения на основе ролей
- Региональные назначения

Интеграционные функции

С автоматизацией

Запуск действий при выборе определенных вариантов
Направление работы на основе выбранных категорий
Отправка уведомлений о изменениях статуса
Создание условных рабочих процессов на основе выборов

С поиском

Фильтрация записей по выбранным вариантам
Ссылка на данные варианта из других записей
Создание отчетов на основе выборов вариантов
Группировка записей по выбранным значениям

С формами

Элементы управления выпадающим списком
Интерфейсы с радиокнопками
Валидация и фильтрация вариантов
Условное отображение полей на основе выборов

Отслеживание активности

Изменения поля с одним вариантом автоматически отслеживаются:

Показывает старые и новые выборы вариантов
Отображает заголовки вариантов в журнале активности
Временные метки для всех изменений выбора
Атрибуция пользователя для модификаций

Отличия от множественного выбора

Функция	Выбор с одним вариантом	Множественный выбор
Selection Limit	Exactly 1 option	Multiple options
Input Parameter	`customFieldOptionId`	`customFieldOptionIds`
Response Field	`value` (single option object)	`value` (array of option objects)
Storage Behavior	Replaces existing selection	Adds to existing selections
Common Use Cases	Status, category, priority	Tags, skills, categories

Ограничения

В одно время может быть выбран только один вариант
Нет иерархической или вложенной структуры вариантов
Варианты общие для всех записей, использующих поле
Нет встроенной аналитики вариантов или отслеживания использования
Цветовые коды предназначены только для отображения, не оказывают функционального влияния
Невозможно установить разные разрешения для каждого варианта

Связанные ресурсы

Поля множественного выбора - Для выборов с несколькими вариантами
Поля с флажками - Для простых булевых выборов
Текстовые поля - Для ввода текста произвольной формы
Обзор пользовательских полей - Общие концепции