Частые вопросы

1. Изменение настройки easycom не вступает в силу

Симптом: в pages.json добавлено правило easycom или изменено существующее, но <lh-xxx> в шаблоне всё равно выдаёт «компонент не зарегистрирован».

Причина: ради производительности компиляции uni-app не запускает пересборку при изменении easycom в pages.json.

Решение: после изменения правила измените содержимое любой страницы (достаточно поставить пробел и сохранить), чтобы запустить пересборку; либо просто перезапустите dev server.

2. ref не достаёт компонента / измерения возвращают пустое

Симптом: методы компонента через ref вызываются в onLoad, или вызываются getLhRect / возможности useLhPopper, а возвращается undefined или пустой прямоугольник.

Причина: на этапе onLoad компоненты ещё не до конца созданы — дочерние экземпляры и узлы ещё не готовы.

Решение: все вызовы ref и измерения узлов выполняйте после onReady (onReady соответствует завершению первого рендера страницы):

import { onReady } from '@dcloudio/uni-app'

onReady(() => {
  // Здесь уже безопасно обращаться к дочерним ref / измерять узлы
})

3. Императивные сервисы (message / loading) не реагируют на вызов

Симптом: useLhMessage().success(...) вызван, в консоли есть предупреждение console.error, но сообщение на странице не появляется.

Причина: Mini Program не может создавать DOM из JS, императивные сервисы используют паттерн точки монтирования — на странице нужно сначала разместить <lh-message /> / <lh-loading />; вызов лишь помещает запись в store-одиночку, а рендерит её компонент-точка монтирования.

Решение: разместите точку монтирования на нужной странице (или в постоянно живущем корневом оборачивающем компоненте):

<lh-config-provider>
  <view><!-- Содержимое --></view>
  <lh-message />
  <lh-loading />
</lh-config-provider>

Предупреждение — сознательное решение: никакой молчаливой деградации, чтобы «вызов вроде сработал, но реакции нет» не стал скрытым багом.

4. Стили не применяются / классы есть, а стили отсутствуют

Порядок проверки:

1. Убедитесь, что подключены оба CSS-артефакта: @lh-ui/uniapp/src/theme/index.css и @lh-ui/uniapp/src/icon/iconfont.css. Если переменные темы не подключены, все var(--lh-*) откатываются к значениям по умолчанию (цвета и скругления будут неправильными).
2. Убедитесь, что вы не переопределяете компонентный styleIsolation. SFC компонента несёт styleIsolation: 'shared' + addGlobalClass: true; если на уровне проекта задана более строгая изоляция, стили компонента и страницы перестают видеть друг друга.
3. Передавайте свои стили через props custom-class / custom-style, а не пишите в странице внутренние BEM-имена классов компонента (внутренние классы вроде .lh-button__text не являются публичным API).

5. Откуда в размере сборки Mini Program base64 от iconfont

Это шрифт с иконками (порядка десятков килобайт), он встранивается в CSS и уезжает со сборкой. Mini Program не поддерживает тег <svg>, поэтому иконки обязаны идти через шрифт; base64 нужен, потому что @font-face в Mini Program не может ссылаться на локальный файл шрифта (в wxss url(...) поддерживает только сетевой адрес или base64). Это стандартный подход к иконкам в uni-app.

6. На H5 слой на месте, а в Mini Program смещён

Позиционирование слоя идёт по таймлайну «измерение за два кадра → позиционирование → показ» (сначала прозрачный рендер для замера, затем позиционирование и лишь потом показ, чтобы не было мерцания). Если слой смещён, как правило, проблема в тайминге вызова: убедитесь, что позиционирование запускается после onReady, а узел trigger уже завершил вёрстку. Кроме того, getLhRect в Mini Program асинхронный — нельзя рассчитывать получить результат синхронно.

7. Тёмная тема не работает

Тёмные переменные висят на page.dark, .dark и переключаются добавлением класса dark на оборачивающий узел ConfigProvider. Убедитесь, что <lh-config-provider :theme="dark"> действительно оборачивает ту область, где нужна тёмная тема (в отличие от web-стороны, где переменные вешаются на document.documentElement и действуют глобально, здесь область действия определяется оборачивающим узлом).