Регистрация
Контакт Войти Регистрация
Статус системы

Создайте поля выбора страны с проверкой кода страны ISO

Пользовательские поля страны позволяют вам хранить и управлять информацией о странах для записей. Поле поддерживает как названия стран, так и коды стран ISO Alpha-2.

Важно: Проверка и поведение преобразования стран значительно различаются между мутациями:

  • createTodo: Автоматически проверяет и преобразует названия стран в коды ISO
  • setTodoCustomField: Принимает любое значение без проверки

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

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

mutation CreateCountryField {
  createCustomField(input: {
    name: "Country of Origin"
    type: COUNTRY
    projectId: "proj_123"
  }) {
    id
    name
    type
  }
}

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

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

mutation CreateDetailedCountryField {
  createCustomField(input: {
    name: "Customer Location"
    type: COUNTRY
    projectId: "proj_123"
    description: "Primary country where the customer is located"
    isActive: true
  }) {
    id
    name
    type
    description
    isActive
  }
}

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

CreateCustomFieldInput

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

Примечание: projectId не передается во входных данных, но определяется контекстом GraphQL (обычно из заголовков запроса или аутентификации).

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

Поля страны хранят данные в двух полях базы данных:

  • countryCodes: Хранит коды стран ISO Alpha-2 в виде строки, разделенной запятыми, в базе данных (возвращается как массив через API)
  • text: Хранит текст отображения или названия стран в виде строки

Понимание параметров

Мутация setTodoCustomField принимает два необязательных параметра для полей страны:

Параметр Тип Обязательный Описание Что это делает
todoId String! ✅ Да ID записи для обновления -
customFieldId String! ✅ Да ID пользовательского поля страны -
countryCodes [String!] Нет Массив кодов стран ISO Alpha-2 Stored in the countryCodes field
text String Нет Текст отображения или названия стран Stored in the text field

Важно:

  • В setTodoCustomField: Оба параметра являются необязательными и хранятся независимо
  • В createTodo: Система автоматически устанавливает оба поля на основе вашего ввода (вы не можете управлять ими независимо)

Вариант 1: Использование только кодов стран

Храните проверенные коды ISO без текста отображения:

mutation SetCountryByCode {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    countryCodes: ["US"]
  })
}

Результат: countryCodes = ["US"], text = null

Вариант 2: Использование только текста

Храните текст отображения без проверенных кодов:

mutation SetCountryByText {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    text: "United States"
  })
}

Результат: countryCodes = null, text = "United States"

Примечание: При использовании setTodoCustomField проверка не происходит независимо от того, какой параметр вы используете. Значения хранятся точно так, как предоставлены.

Вариант 3: Использование обоих (Рекомендуется)

Храните как проверенные коды, так и текст отображения:

mutation SetCountryComplete {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    countryCodes: ["US"]
    text: "United States"
  })
}

Результат: countryCodes = ["US"], text = "United States"

Несколько стран

Храните несколько стран, используя массивы:

mutation SetMultipleCountries {
  setTodoCustomField(input: {
    todoId: "todo_123"
    customFieldId: "field_456"
    countryCodes: ["US", "CA", "MX"]
    text: "North American Markets"  # Can be any descriptive text
  })
}

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

При создании записей мутация createTodo автоматически проверяет и преобразует значения страны. Это единственная мутация, которая выполняет проверку страны:

mutation CreateRecordWithCountry {
  createTodo(input: {
    title: "International Client"
    todoListId: "list_123"
    customFields: [{
      customFieldId: "country_field_id"
      value: "France"  # Can use country name or code
    }]
  }) {
    id
    title
    customFields {
      id
      customField {
        name
        type
      }
      text
      countryCodes
    }
  }
}

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

Тип ввода Пример Результат
Country Name "United States" Stored as US
ISO Alpha-2 Code "GB" Stored as GB
Multiple (comma-separated) "US, CA" Не поддерживается - рассматривается как одно недопустимое значение
Mixed format "United States, CA" Не поддерживается - рассматривается как одно недопустимое значение

Поля ответа

Ответ TodoCustomField

Поле Тип Описание
id String! Уникальный идентификатор для значения поля
customField CustomField! Определение пользовательского поля
text String Текст отображения (названия стран)
countryCodes [String!] Массив кодов стран ISO Alpha-2
todo Todo! Запись, к которой принадлежит это значение
createdAt DateTime! Когда значение было создано
updatedAt DateTime! Когда значение было в последний раз изменено

Стандарты стран

Blue использует стандарт ISO 3166-1 Alpha-2 для кодов стран:

  • Двухбуквенные коды стран (например, US, GB, FR, DE)
  • Проверка с использованием библиотеки i18n-iso-countries происходит только в createTodo
  • Поддерживает все официально признанные страны

Примеры кодов стран

Страна Код ISO
United States US
United Kingdom GB
Canada CA
Germany DE
France FR
Japan JP
Australia AU
Brazil BR

Для полного официального списка кодов стран ISO 3166-1 alpha-2 посетите ISO Online Browsing Platform.

Проверка

Проверка происходит только в мутации createTodo:

  1. Действительный код ISO: Принимает любой действительный код ISO Alpha-2
  2. Название страны: Автоматически преобразует распознаваемые названия стран в коды
  3. Недопустимый ввод: Вызывает CustomFieldValueParseError для нераспознанных значений

Примечание: Мутация setTodoCustomField не выполняет проверку и принимает любое строковое значение.

Пример ошибки

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

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

Поля поиска

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

Автоматизация

Используйте значения стран в условиях автоматизации:

  • Фильтровать действия по конкретным странам
  • Отправлять уведомления на основе страны
  • Направлять задачи на основе географических регионов

Формы

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

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

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

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

Недопустимое значение страны

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

Несоответствие типа поля

{
  "errors": [{
    "message": "Field type mismatch: expected COUNTRY",
    "extensions": {
      "code": "INVALID_FIELD_TYPE"
    }
  }]
}

Рекомендации по лучшим практикам

Обработка ввода

  • Используйте createTodo для автоматической проверки и преобразования
  • Используйте setTodoCustomField осторожно, так как он обходит проверку
  • Рассмотрите возможность проверки вводимых данных в вашем приложении перед использованием setTodoCustomField
  • Отображайте полные названия стран в интерфейсе для ясности

Качество данных

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

Несколько стран

  • Используйте поддержку массивов в setTodoCustomField для нескольких стран
  • Несколько стран в createTodo не поддерживаются через поле значения
  • Храните коды стран как массив в setTodoCustomField для правильной обработки

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

  1. Управление клиентами

    • Местоположение головного офиса клиента
    • Места доставки
    • Налоговые юрисдикции

  2. Отслеживание проектов

    • Местоположение проекта
    • Местоположения членов команды
    • Целевые рынки

  3. Соответствие и право

    • Регуляторные юрисдикции
    • Требования к местоположению данных
    • Контроль экспорта

  4. Продажи и маркетинг

    • Назначения территорий
    • Сегментация рынка
    • Целевое назначение кампаний

Ограничения

  • Поддерживает только коды ISO 3166-1 Alpha-2 (двухбуквенные коды)
  • Нет встроенной поддержки для подразделений стран (штатов/провинций)
  • Нет автоматических значков флагов стран (только текстовые)
  • Не может проверять исторические коды стран
  • Нет встроенной группировки по регионам или континентам
  • Проверка работает только в createTodo, не в setTodoCustomField
  • Несколько стран не поддерживаются в поле значения createTodo
  • Коды стран хранятся как строка, разделенная запятыми, а не как настоящий массив

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

© Blue | Разработано с ❤ по всему

AI Ассистент

Ответы генерируются с использованием ИИ и могут содержать ошибки.

Как я могу вам помочь?

Спросите меня о чем угодно, связанном с Blue или этой документацией.

Введите для отправки • Shift+Enter для новой строки • ⌘I для открытия