Многофункциональное настраиваемое поле

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

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

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

Создайте простое многофункциональное поле:

mutation CreateMultiSelectField {
  createCustomField(input: {
    name: "Project Categories"
    type: SELECT_MULTI
    projectId: "proj_123"
  }) {
    id
    name
    type
  }
}

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

Создайте многофункциональное поле, а затем добавьте варианты отдельно:

# Step 1: Create the multi-select field
mutation CreateMultiSelectField {
  createCustomField(input: {
    name: "Required Skills"
    type: SELECT_MULTI
    projectId: "proj_123"
    description: "Select all skills required for this task"
  }) {
    id
    name
    type
    description
  }
}

# Step 2: Add options to the field
mutation AddOptions {
  createCustomFieldOptions(input: [
    { customFieldId: "field_123", title: "JavaScript", color: "#f7df1e" }
    { customFieldId: "field_123", title: "React", color: "#61dafb" }
    { customFieldId: "field_123", title: "Node.js", color: "#339933" }
    { customFieldId: "field_123", title: "GraphQL", color: "#e10098" }
  ]) {
    id
    title
    color
    position
  }
}

Входные параметры

CreateCustomFieldInput

Параметр	Тип	Обязательный	Описание
`name`	String!	✅ Да	Отображаемое имя многофункционального поля
`type`	CustomFieldType!	✅ Да	Должен быть `SELECT_MULTI`
`description`	String	Нет	Текст помощи, отображаемый пользователям
`projectId`	String!	✅ Да	ID проекта для этого поля

CreateCustomFieldOptionInput

Параметр	Тип	Обязательный	Описание
`customFieldId`	String!	✅ Да	ID настраиваемого поля
`title`	String!	✅ Да	Отображаемый текст для варианта
`color`	String	Нет	Цвет для варианта (любая строка)
`position`	Float	Нет	Порядок сортировки для варианта

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

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

mutation AddMultiSelectOption {
  createCustomFieldOption(input: {
    customFieldId: "field_123"
    title: "Python"
    color: "#3776ab"
  }) {
    id
    title
    color
    position
  }
}

Установка значений многофункционального поля

Чтобы установить несколько выбранных вариантов в записи:

mutation SetMultiSelectValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    customFieldOptionIds: ["option_1", "option_2", "option_3"]
  })
}

Параметры SetTodoCustomFieldInput

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

Создание записей с многофункциональными значениями

При создании новой записи с многофункциональными значениями:

mutation CreateRecordWithMultiSelect {
  createTodo(input: {
    title: "Develop new feature"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "skills_field_id"
      value: "option1,option2,option3"
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      selectedOptions {
        id
        title
        color
      }
    }
  }
}

Поля ответа

Ответ TodoCustomField

Поле	Тип	Описание
`id`	String!	Уникальный идентификатор для значения поля
`customField`	CustomField!	Определение настраиваемого поля
`selectedOptions`	[CustomFieldOption!]	Массив выбранных вариантов
`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_MULTI`
`description`	String	Текст помощи для поля
`customFieldOptions`	[CustomFieldOption!]	Все доступные варианты

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

Входной формат

API Параметр: Массив ID вариантов (["option1", "option2", "option3"])
Строковый формат: ID вариантов, разделенные запятыми ("option1,option2,option3")

Выходной формат

Ответ GraphQL: Массив объектов CustomFieldOption
Журнал активности: Заголовки вариантов, разделенные запятыми
Данные автоматизации: Массив заголовков вариантов

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

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

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

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

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

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

# Update position values to reorder options
mutation UpdateOptionPosition {
  editCustomFieldOption(input: {
    id: "option_123"
    position: 1.5  # Position between 1.0 and 2.0
  }) {
    id
    position
  }
}

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

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

Все предоставленные ID вариантов должны существовать
Варианты должны принадлежать указанному настраиваемому полю
Только поля SELECT_MULTI могут иметь несколько выбранных вариантов
Пустой массив допустим (без выборов)

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

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

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

Действие	Необходимое разрешение
Create multi-select field	`OWNER` or `ADMIN` role at project level
Update multi-select field	`OWNER` or `ADMIN` role at project level
Add/edit options	`OWNER` or `ADMIN` role at project level
Set selected values	Standard record edit permissions
View selected values	Standard record view permissions

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

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

{
  "errors": [{
    "message": "Custom field option 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": "CustomField not found",
    "extensions": {
      "code": "CUSTOM_FIELD_NOT_FOUND"
    }
  }]
}

Несколько вариантов в неполном поле

{
  "errors": [{
    "message": "custom fields can only have one option",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

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

Управление проектами
- Категории и теги задач
- Уровни и типы приоритета
- Назначения членов команды
- Индикаторы статуса
Управление контентом
- Категории и темы статей
- Типы и форматы контента
- Каналы публикации
- Рабочие процессы утверждения
Поддержка клиентов
- Категории и типы проблем
- Затронутые продукты или услуги
- Методы разрешения
- Сегменты клиентов
Разработка продукта
- Категории функций
- Технические требования
- Тестовые среды
- Каналы выпуска

Функции интеграции

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

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

С поисками

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

С формами

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

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

Изменения многофункционального поля автоматически отслеживаются:

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

Ограничения

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

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

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