Skip to main content
Version: Next

Troubleshooting

Частые вопросы (FAQ)​

Общие вопросы​

Q: С чего начать кастомизацию чата?​

Воспользуйтесь маршрутами в зависимости от задачи. Для большинства сценариев достаточно изменить ChatColors и применить ChatTheme.

Q: В чём разница между ChatComponents и ChatFlows?​

ChatComponents — глобальные стили, общие для всего SDK. ChatFlows — переопределение компонентов для конкретного экрана (чат или поиск). Правило: начинайте с ChatComponents, переходите к ChatFlows только если нужно разное поведение на разных экранах.

Q: Как применить одну тему для светлой и другую для тёмной?​

chatCenterSDK.theme = lightTheme
chatCenterSDK.darkTheme = darkTheme

Если darkTheme не задан, SDK использует theme в обоих режимах.

Цвета​

Q: Изменил цвет, но он не применился​

Проверьте по чеклисту:

  1. Тема задана до getChat()? 
    chatCenterSDK.theme = myTheme  // ← сначала тема
    let chatController = try chatCenterSDK.getChat()
  2. Правильный токен? link — основная ссылка/акцент; linkLight — светлая вариация (для тёмного фона).
  3. Компонент не переопределяет токен? Если components.navigationBarStyle.titleTextStyle.color задан явно — токен typography.title на него не влияет.
  4. Тёмная тема задана отдельно? colors.link = .red в светлой теме не затрагивает darkTheme.
  5. apply vs build? Изменение компонента в Flow через apply может затронуть все экраны. Используйте build для точечного переопределения (см. Стили -> Типичные ошибки).
  6. Тема пересоздаётся перед каждым открытием? Создавайте ChatTheme один раз при инициализации SDK — не перед каждым вызовом getChat().

Q: Как задать разные цвета для светлой и тёмной темы в рамках одной ChatColors?​

Используйте динамический UIColor:

let adaptiveColor = UIColor { traitCollection in
    traitCollection.userInterfaceStyle == .dark ? .white : .black
}
colors.main = adaptiveColor

Либо создайте две отдельные ChatColors и назначьте через theme / darkTheme.

Q: Как проверить контрастность моих кастомных цветов?​

  • Xcode → Accessibility Inspector → Color Contrast Calculator
  • iOS Settings → Accessibility → Increase Contrast (тест на устройстве)

Подробнее: Доступность в разделе Цветовая схема.

Шрифты​

Q: Изменил typography.body, но шрифт в пузырях не изменился​

Текст в пузырях чата использует токен typography.message (14pt Regular), а не body. Это особенность SDK, не имеющая прямого аналога в Figma Foundation.

fonts.message = .systemFont(ofSize: 15, weight: .regular)

Q: Кастомный шрифт не применяется к заголовку в навигационной панели​

Заголовок навигационной панели управляется через NavigationBarStyle, а не через токен ChatTypography.title:

components.navigationBarStyle.titleTextStyle.font = myFont
components.navigationBarStyle.titleTextStyle.color = .white

Компоненты​

Q: Изменение компонента в одном Flow влияет на все экраны​

Это известное ограничение: компоненты из ChatComponents — разделяемые объекты. Решение — создавать новый экземпляр компонента:

// Меняет глобально
theme.flows.chatFlow.apply {
    $0.inputViewStyle.sendButtonStyle.image = myImage
}

// Точечное переопределение
let customInput = ChatInputStyle.build(with: components) {
    $0.sendButtonStyle.image = myImage
}
theme.flows.chatFlow.inputViewStyle = customInput

Q: Как изменить цвет фона пузырей сообщений?​

Для входящих (от оператора) и исходящих (от клиента) сообщений по отдельности:

theme.flows.chatFlow.incomeMessages.bubbleTintColor = .systemBlue
theme.flows.chatFlow.outcomeMessages.bubbleTintColor = .systemGreen

Q: Как скрыть аватар только в исходящих сообщениях?​

theme.flows.chatFlow.outcomeMessages.showAvatar = false
theme.flows.chatFlow.incomeMessages.showAvatar = true

Q: Как изменить иконку отправки голосового сообщения (не записи)?​

let images = ChatImages()
images.voiceSendButtonImage = ChatImage(system: "paperplane.fill", tintColor: .white)
let theme = ChatTheme(images: images)

Полная таблица иконок: Изображения.

Тёмная тема​

Q: Тёмная тема не применяется при смене userInterfaceStyle​

Убедитесь, что:

  1. darkTheme задан явно: chatCenterSDK.darkTheme = darkTheme
  2. Смена темы происходит до открытия чата, или SDK перезапущен после смены

Q: Часть элементов не меняет цвет в тёмной теме​

Некоторые цвета (link, linkLight, positive, warning) одинаковы для светлой и тёмной темы по умолчанию. Для разных значений создайте отдельную ChatColors для тёмной темы и назначьте через darkTheme.

Иконки и изображения​

Q: Как использовать кастомную иконку из ассетов приложения вместо SF Symbol?​

images.sendButtonImage = ChatImage(
    named: "my_custom_send",
    bundle: .main,
    tintColor: .white
)

Q: Иконка SF Symbol слишком маленькая / большая​

Используйте конструктор с указанием размера:

images.attachButtonImage = ChatImage(system: "plus.circle", size: 24, tintColor: .systemBlue)

Поиск​

Q: Как настроить внешний вид экрана поиска?​

Используйте SearchFlow:

theme.flows.searchFlow.apply {
    $0.searchMessageStyle.matchTextStyle.color = .systemOrange
    $0.notFoundTextStyle = ChatTextStyle(font: typography.body, color: .secondaryLabel)
    $0.navigationBarStyle.hidden = false
}

Граничные случаи​

Q: Задал прозрачный цвет — текст пропал​

ChatColors не проверяет цвет на прозрачность. Если задать .clear, элемент станет невидимым без ошибки.

// Текст будет невидим
colors.main = .clear

// Полупрозрачность — только если это намеренно
colors.main = .label.withAlphaComponent(0.8)

Q: Изменил theme пока чат уже открыт — UI не обновился​

ChatTheme считывается при открытии чата. Изменение chatCenterSDK.theme после вызова getChat() не обновляет уже отображаемые компоненты.

Вариант 1 — перезапустить чат (наиболее надёжно):

chatCenterSDK.theme = newTheme
let chatController = try chatCenterSDK.getChat()  // открыть заново
navigationController?.pushViewController(chatController, animated: true)

Вариант 2 — динамические цвета (обновляются автоматически при смене Light/Dark):

colors.main = UIColor { trait in
    trait.userInterfaceStyle == .dark ? .white : .black
}

Q: Поддерживается ли автоматическая смена Light/Dark без перезапуска чата?​

Да — если используются динамические UIColor(dynamicProvider:). При смене системной темы такие цвета применяются к уже открытому чату автоматически.

Статические цвета (HEX-значения, .systemBlue, UIColor(named:) без adaptive) не меняются без перезапуска.

Ошибки конфигурации​

Q: Иконка не отображается — как диагностировать?​

ChatImage(named:) не выбрасывает ошибку если ассет не найден — иконка просто не отображается (внутри подставляется пустой UIImage()). Убедитесь, что имя ассета и бандл указаны верно:

// Кастомная иконка из бандла приложения
images.sendButtonImage = ChatImage(named: "my_icon", bundle: .main, tintColor: .white)

// Или SF Symbol (всегда доступен, не требует ассета)
images.sendButtonImage = ChatImage(system: "paperplane.fill", tintColor: .white)
tip

Если не уверены в наличии ассета, проверьте его в Asset Catalog вашего проекта. ChatImage(named:) всегда возвращает объект — при ненайденном ассете иконка будет пустой без ошибки.

Для проверки доступных SF Symbols используйте приложение SF Symbols (доступно на developer.apple.com/sf-symbols).

Q: Кастомный шрифт не загружается — как проверить?​

Шрифт должен быть зарегистрирован в Info.plist под ключом UIAppFonts и использоваться по PostScript-имени:

// Диагностика: вывести все зарегистрированные PostScript-имена
for family in UIFont.familyNames.sorted() {
    for name in UIFont.fontNames(forFamilyName: family) {
        print(name)  // ← ищите "YourFont-Regular" в выводе
    }
}

// Всегда с fallback
typography.message = UIFont(name: "YourFont-Regular", size: 15)
    ?? .systemFont(ofSize: 15)

UIFont(name:size:) вернёт nil без ошибки если шрифт не найден — приложение не упадёт, но будет использован системный шрифт.

Отладка​

Q: Как проверить, что тема применилась?​

  1. Точка останова в отладчике — добавьте breakpoint после chatCenterSDK.theme = myTheme и проверьте свойства объекта
  2. Xcode View Hierarchy (Debug → View Hierarchy) — выберите нужный элемент, цвет и шрифт видны в инспекторе справа
  3. Логирование — убедитесь что код выполняется в нужном порядке: 
    let theme = ChatTheme(colors: colors)
    print("Theme ready, link color: \(colors.link)")
    chatCenterSDK.theme = theme  // ← до getChat()
    let chatController = try chatCenterSDK.getChat()

Q: Тема создана, но визуально ничего не изменилось​

Самая распространённая причина — тема установлена после вызова getChat():

// Правильно — тема до открытия
chatCenterSDK.theme = myTheme
let chatController = try chatCenterSDK.getChat()
navigationController?.pushViewController(chatController, animated: true)

// Неправильно — тема после открытия, может не применяться
let chatController = try chatCenterSDK.getChat()
chatCenterSDK.theme = myTheme

Не нашли ответ?​

Обратитесь в поддержку или посмотрите:

  • API Reference — полный список классов и свойств
  • Figma UIKit — визуальное представление компонентов
  • Демо-приложение → MainViewController+Custom.swift — актуальные рабочие примеры
Last updated on