자주 묻는 질문

1. easycom 설정을 변경해도 적용되지 않음

현상: pages.json에 easycom 규칙을 추가하거나 규칙을 변경했는데, 템플릿의 <lh-xxx>가 여전히 "컴포넌트가 등록되지 않음" 오류를 보고합니다.

원인: uni-app은 컴파일 성능상 pages.json의 easycom 변경이 재컴파일을 트리거하지 않습니다.

해결: 규칙을 변경한 후 아무 페이지의 내용이나 수정하여(스페이스를 입력하고 저장만 해도 됨) 재컴파일을 트리거하거나, dev server를 재시작하십시오.

2. ref로 컴포넌트를 가져올 수 없음 / 측정이 빈 결과를 반환

현상: onLoad에서 컴포넌트 ref 메서드를 호출하거나 getLhRect / useLhPopper 관련 기능을 호출할 때 undefined나 빈 사각형을 받습니다.

원인: onLoad 단계에서는 아직 컴포넌트 생성이 완료되지 않아 자식 컴포넌트 인스턴스와 노드가 준비되지 않았습니다.

해결: 모든 ref 호출과 노드 측정은 onReady 이후에 하십시오(onReady는 페이지 첫 렌더링 완료에 해당):

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

onReady(() => {
  // 여기서야 자식 컴포넌트 ref / 측정 노드에 안전하게 접근할 수 있습니다
})

3. 명령형 서비스(message / loading) 호출 후 반응 없음

현상: useLhMessage().success(...)를 호출했고, 콘솔에 console.error 경고가 떴는데 페이지에 메시지가 나타나지 않습니다.

원인: 미니프로그램에서는 JS로 DOM을 생성할 수 없어 명령형 서비스는 마운트 지점 패턴을 사용합니다 — 페이지에 먼저 <lh-message /> / <lh-loading />를 배치해야 하며, 호출은 싱글톤 store에 레코드를 푸시하기만 하고 마운트 지점 컴포넌트가 렌더링합니다.

해결: 필요한 페이지(또는 상주하는 루트 감싸기 컴포넌트)에 마운트 지점을 배치하십시오:

<lh-config-provider>
  <view><!-- 내용 --></view>
  <lh-message />
  <lh-loading />
</lh-config-provider>

경고는 의도된 설계입니다 — 조용히 폴백하지 않아 "호출이 된 것처럼 보이나 실제로 반응이 없는" 숨은 버그를 피합니다.

4. 스타일이 적용되지 않음 / 클래스명은 있는데 스타일이 없음

확인 순서:

1. 두 CSS 산출물을 import했는지 확인: @lh-ui/uniapp/src/theme/index.css와 @lh-ui/uniapp/src/icon/iconfont.css. 테마 변수를 빠뜨리면 모든 var(--lh-*)가 기본값으로 폴백합니다(색상, 모서리 둥글기가 전부 달라집니다).
2. 컴포넌트 수준의 styleIsolation을 덮어쓰지 않았는지 확인. 컴포넌트 SFC는 자체적으로 styleIsolation: 'shared' + addGlobalClass: true를 선언하며, 프로젝트 수준 설정이 더 엄격한 격리를 강제하면 컴포넌트 스타일이 서로 보이지 않게 됩니다.
3. 커스텀 스타일은 custom-class / custom-style prop으로 전달하고, 페이지에서 컴포넌트 내부 BEM 클래스명을 직접 쓰지 마십시오(.lh-button__text 같은 내부 클래스명은 공개 API가 아닙니다).

5. 미니프로그램 패키지 용량에 iconfont base64가 있는 이유

그것은 아이콘 폰트(약 수십 KB)로, CSS에 인라인되어 패키지와 함께 배포됩니다. 미니프로그램은 <svg> 태그를 지원하지 않아 아이콘은 반드시 폰트 방식을 사용해야 합니다. base64 인라인을 사용하는 이유는 미니프로그램의 @font-face가 로컬 폰트 파일 참조를 허용하지 않기 때문입니다(wxss의 url(...)는 네트워크 주소나 base64만 지원). 이것은 uni-app 아이콘 방식의 일반적인 관행입니다.

6. H5에서는 레이어 위치가 정상인데 미니프로그램에서 어긋남

레이어 위치 지정은 "2프레임 측정 → 위치 지정 → 표시" 시퀀스로 동작합니다(먼저 투명하게 렌더링하여 크기를 재고, 위치를 지정한 뒤, 마지막에 표시하여 깜빡임을 방지). 어긋났다면 보통 호출 시퀀스 문제입니다: 위치 지정 트리거가 onReady 이후에 일어나는지, 그리고 trigger 노드의 레이아웃이 이미 완료되었는지 확인하십시오. 또한 미니프로그램의 getLhRect는 비동기이므로 동기적으로 결과를 받을 수 있다고 가정하면 안 됩니다.

7. 다크 모드가 적용되지 않음

다크 변수는 page.dark, .dark에 걸려 있으며, ConfigProvider의 감싸는 노드에 dark 클래스를 추가하는 것으로 전환됩니다. <lh-config-provider :theme="dark">가 다크가 필요한 내용 범위를 확실히 감싸고 있는지 확인하십시오 (web 버전처럼 document.documentElement에 걸어 전역으로 만드는 것이 아니라, 본 라이브러리의 스코프는 감싸는 노드를 따릅니다).