Поле пользовательского текста в одной строке

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

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

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

Создайте простое поле пользовательского текста в одной строке:

mutation CreateTextSingleField {
  createCustomField(input: {
    name: "Client Name"
    type: TEXT_SINGLE
  }) {
    id
    name
    type
  }
}

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

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

mutation CreateDetailedTextSingleField {
  createCustomField(input: {
    name: "Product SKU"
    type: TEXT_SINGLE
    description: "Unique product identifier code"
  }) {
    id
    name
    type
    description
  }
}

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

CreateCustomFieldInput

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

Примечание: Контекст проекта автоматически определяется из ваших заголовков аутентификации. Параметр projectId не требуется.

Установка текстовых значений

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

mutation SetTextSingleValue {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    text: "ABC-123-XYZ"
  }) {
    id
    customField {
      value  # Returns { text: "ABC-123-XYZ" }
    }
  }
}

Параметры SetTodoCustomFieldInput

Параметр	Тип	Обязательный	Описание
`todoId`	String!	✅ Да	ID записи для обновления
`customFieldId`	String!	✅ Да	ID пользовательского текстового поля
`text`	String	Нет	Содержимое текста в одной строке для хранения

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

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

mutation CreateRecordWithTextSingle {
  createTodo(input: {
    title: "Process Order"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "text_single_field_id"
      value: "ORD-2024-001"
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
        value  # Text is accessed here as { text: "ORD-2024-001" }
      }
    }
  }
}

Поля ответа

Ответ TodoCustomField

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

Важно: Текстовые значения доступны через поле customField.value.text, а не напрямую в TodoCustomField.

Запрос текстовых значений

При запросе записей с пользовательскими текстовыми полями доступ к тексту осуществляется через путь customField.value.text:

query GetRecordWithText {
  todo(id: "todo_123") {
    id
    title
    customFields {
      id
      customField {
        name
        type
        value  # For TEXT_SINGLE type, contains { text: "your text value" }
      }
    }
  }
}

Ответ будет включать текст в вложенной структуре:

{
  "data": {
    "todo": {
      "customFields": [{
        "customField": {
          "name": "Product SKU",
          "type": "TEXT_SINGLE",
          "value": {
            "text": "ABC-123-XYZ"
          }
        }
      }]
    }
  }
}

Проверка текста

Проверка формы

Когда поля текста в одной строке используются в формах:

Ведущие и завершающие пробелы автоматически удаляются
Применяется проверка обязательности, если поле помечено как обязательное
Специфическая проверка формата не применяется

Правила проверки

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

Типичные текстовые примеры

Product Name
SKU-123-ABC
Client Reference #2024-001
Version 1.2.3
Project Alpha
Status: Active

Важные заметки

Вместимость хранения

Хранится с использованием типа MySQL MediumText
Поддерживает до 16 МБ текстового содержимого
Идентичное хранение для многострочных текстовых полей
Кодировка UTF-8 для международных символов

Прямой API против Форм

Формы: Автоматическое удаление пробелов и проверка обязательных полей
Прямой API: Текст хранится точно так, как предоставлен
Рекомендация: Используйте формы для ввода от пользователей, чтобы обеспечить согласованное форматирование

TEXT_SINGLE против TEXT_MULTI

TEXT_SINGLE: Ввод текста в одной строке, идеально подходит для коротких значений
TEXT_MULTI: Ввод многострочного текстового поля, идеально подходит для более длинного содержимого
Бэкэнд: Оба используют идентичное хранение и проверку
Фронтэнд: Разные компоненты пользовательского интерфейса для ввода данных
Намерение: TEXT_SINGLE семантически предназначен для значений в одной строке

Обязательные разрешения

Действие	Необходимое разрешение
Create text field	`OWNER` or `ADMIN` role at project level
Update text field	`OWNER` or `ADMIN` role at project level
Set text value	Standard record edit permissions
View text value	Standard record view permissions

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

Проверка обязательного поля (только формы)

{
  "errors": [{
    "message": "This field is required",
    "extensions": {
      "code": "VALIDATION_ERROR"
    }
  }]
}

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

{
  "errors": [{
    "message": "Custom field not found",
    "extensions": {
      "code": "NOT_FOUND"
    }
  }]
}

Лучшие практики

Ввод данных

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

Соображения по производительности

Поля текста в одной строке легковесны и производительны
Рассмотрите возможность индексирования для часто ищущихся полей
Используйте соответствующие ширины отображения в вашем пользовательском интерфейсе
Следите за длиной содержимого для целей отображения

Фильтрация и поиск

Поиск по содержимому

Поля текста в одной строке поддерживают поиск подстрок:

query SearchTextSingle {
  todos(
    customFieldFilters: [{
      customFieldId: "text_single_field_id"
      operation: CONTAINS
      value: "SKU"
    }]
  ) {
    id
    title
    customFields {
      customField {
        value  # Access text via value.text
      }
    }
  }
}

Возможности поиска

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

Общие случаи использования

Идентификаторы и коды
- SKU продуктов
- Номера заказов
- Справочные коды
- Номера версий
Имена и названия
- Имена клиентов
- Названия проектов
- Названия продуктов
- Метки категорий
Краткие описания
- Краткие резюме
- Метки статуса
- Индикаторы приоритета
- Теги классификации
Внешние ссылки
- Номера билетов
- Ссылки на счета
- ID внешних систем
- Номера документов

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

С использованием справочников

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

С использованием форм

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

С использованием импорта/экспорта

Прямое сопоставление столбцов CSV
Автоматическое присвоение текстовых значений
Поддержка массового импорта данных
Экспорт в форматы таблиц

Ограничения

Ограничения автоматизации

Не доступно напрямую как триггерные поля автоматизации
Не может использоваться в обновлениях полей автоматизации
Может быть упомянуто в условиях автоматизации
Доступно в шаблонах электронной почты и вебхуках

Общие ограничения

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

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

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