Процентное пользовательское поле

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

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

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

Создайте простое процентное поле:

mutation CreatePercentField {
  createCustomField(input: {
    name: "Completion Rate"
    type: PERCENT
  }) {
    id
    name
    type
  }
}

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

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

mutation CreatePercentField {
  createCustomField(input: {
    name: "Success Rate"
    type: PERCENT
    description: "Percentage of successful outcomes for this process"
  }) {
    id
    name
    type
    description
  }
}

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

CreateCustomFieldInput

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

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

Примечание: ПОЛЯ PERCENT не поддерживают ограничения min/max или форматирование префиксов, как ПОЛЯ NUMBER.

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

Процентные поля хранят числовые значения с автоматическим управлением символом %:

С символом процента

mutation SetPercentWithSymbol {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    number: 75.5
  }) {
    id
    customField {
      value  # Returns { number: 75.5 }
    }
  }
}

Прямое числовое значение

mutation SetPercentNumeric {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    number: 100
  }) {
    id
    customField {
      value  # Returns { number: 100.0 }
    }
  }
}

Параметры SetTodoCustomFieldInput

Параметр	Тип	Обязательный	Описание
`todoId`	String!	✅ Да	ID записи для обновления
`customFieldId`	String!	✅ Да	ID процентного пользовательского поля
`number`	Float	Нет	Числовое процентное значение (например, 75.5 для 75.5%)

Хранение и отображение значений

Формат хранения

Внутреннее хранение: Сырое числовое значение (например, 75.5)
База данных: Хранится как Decimal в столбце number
GraphQL: Возвращается как Float тип

Формат отображения

Пользовательский интерфейс: Клиентские приложения должны добавлять символ % (например, "75.5%")
Графики: Отображается с символом % при типе вывода PERCENTAGE
Ответы API: Сырое числовое значение без символа % (например, 75.5)

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

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

mutation CreateRecordWithPercent {
  createTodo(input: {
    title: "Marketing Campaign"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "success_rate_field_id"
      value: "85.5%"
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
        value  # Percent is accessed here as { number: 85.5 }
      }
    }
  }
}

Поддерживаемые форматы ввода

Формат	Пример	Результат
With % symbol	`"75.5%"`	Stored as 75.5
Without % symbol	`"75.5"`	Stored as 75.5
Integer percentage	`"100"`	Stored as 100.0
Decimal percentage	`"33.333"`	Stored as 33.333

Примечание: Символ % автоматически удаляется из ввода и добавляется обратно во время отображения.

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

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

query GetRecordWithPercent {
  todo(id: "todo_123") {
    id
    title
    customFields {
      id
      customField {
        name
        type
        value  # For PERCENT type, contains { number: 75.5 }
      }
    }
  }
}

Ответ будет включать процент как сырое число:

{
  "data": {
    "todo": {
      "customFields": [{
        "customField": {
          "name": "Completion Rate",
          "type": "PERCENT",
          "value": {
            "number": 75.5
          }
        }
      }]
    }
  }
}

Поля ответа

Ответ TodoCustomField

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

Важно: Процентные значения доступны через поле customField.value.number. Символ % не включается в хранимые значения и должен быть добавлен клиентскими приложениями для отображения.

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

Процентные поля поддерживают такую же фильтрацию, как и ПОЛЯ NUMBER:

query FilterByPercentRange {
  todos(filter: {
    customFields: [{
      customFieldId: "completion_rate_field_id"
      operator: GTE
      number: 80
    }]
  }) {
    id
    title
    customFields {
      number
    }
  }
}

Поддерживаемые операторы

Оператор	Описание	Пример
`EQ`	Равно	`percentage = 75`
`NE`	Не равно	`percentage ≠ 75`
`GT`	Больше чем	`percentage > 75`
`GTE`	Больше или равно	`percentage ≥ 75`
`LT`	Меньше чем	`percentage < 75`
`LTE`	Меньше или равно	`percentage ≤ 75`
`IN`	Значение в списке	`percentage in [50, 75, 100]`
`NIN`	Значение не в списке	`percentage not in [0, 25]`
`IS`	Проверка на null с `values: null`	`percentage is null`
`NOT`	Проверка на not null с `values: null`	`percentage is not null`

Фильтрация по диапазону

Для фильтрации по диапазону используйте несколько операторов:

query FilterHighPerformers {
  todos(filter: {
    customFields: [{
      customFieldId: "success_rate_field_id"
      operator: GTE
      number: 90
    }]
  }) {
    id
    title
    customFields {
      customField {
        value  # Returns { number: 95.5 } for example
      }
    }
  }
}

Диапазоны процентных значений

Общие диапазоны

Диапазон	Описание	Случай использования
`0-100`	Стандартный процент	Completion rates, success rates
`0-∞`	Неограниченный процент	Growth rates, performance metrics
`-∞-∞`	Любое значение	Change rates, variance

Примеры значений

Ввод	Хранится	Отображается
`"50%"`	`50.0`	`50%`
`"100"`	`100.0`	`100%`
`"150.5"`	`150.5`	`150.5%`
`"-25"`	`-25.0`	`-25%`

Аггрегация графиков

Процентные поля поддерживают агрегацию в графиках и отчетах на панели инструментов. Доступные функции включают:

AVERAGE - Среднее процентное значение
COUNT - Количество записей с значениями
MIN - Наименьшее процентное значение
MAX - Наибольшее процентное значение
SUM - Сумма всех процентных значений

Эти агрегации доступны при создании графиков и панелей инструментов, а не в прямых запросах GraphQL.

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

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

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

Неверный формат процента

{
  "errors": [{
    "message": "Invalid percentage value",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

Не число

{
  "errors": [{
    "message": "Value is not a valid number",
    "extensions": {
      "code": "CUSTOM_FIELD_VALUE_PARSE_ERROR"
    }
  }]
}

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

Управление проектами
- Уровни завершения задач
- Прогресс проекта
- Использование ресурсов
- Скорость спринта
Отслеживание производительности
- Уровни успеха
- Уровни ошибок
- Метрики эффективности
- Оценки качества
Финансовые метрики
- Темпы роста
- Прибыльность
- Суммы скидок
- Проценты изменений
Аналитика
- Уровни конверсии
- Уровни кликов
- Метрики вовлеченности
- Показатели производительности

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

С формулами

Ссылайтесь на ПОЛЯ PERCENT в расчетах
Автоматическое форматирование символа % в выводах формул
Объединяйте с другими числовыми полями

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

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

С поисками

Агрегируйте проценты из связанных записей
Рассчитывайте средние уровни успеха
Находите наилучшие/наихудшие показатели

С графиками

Создавайте визуализации на основе процентов
Отслеживайте прогресс с течением времени
Сравнивайте показатели производительности

Отличия от ПОЛЕЙ NUMBER

В чем разница

Обработка ввода: Автоматически удаляет символ %
Отображение: Автоматически добавляет символ %
Ограничения: Нет проверки min/max
Форматирование: Нет поддержки префиксов

Что одинаково

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

Ограничения

Нет ограничений на значения min/max
Нет вариантов форматирования префиксов
Нет автоматической проверки диапазона 0-100%
Нет конвертации между форматами процентов (например, 0.75 ↔ 75%)
Значения свыше 100% допустимы

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

Обзор пользовательских полей - Общие концепции пользовательских полей
Числовое пользовательское поле - Для сырых числовых значений
API автоматизации - Создайте автоматизации на основе процентов