よくある質問

1. easycom 設定を変更しても反映されない

現象：pages.json に easycom ルールを追加した、またはルールを変更したのに、テンプレートの <lh-xxx> が依然として「コンポーネントが登録されていません」と報告する。

原因：uni-app はコンパイル性能の都合上、pages.json の easycom を変更しても再コンパイルがトリガーされません。

解決策：ルールを変更した後、いずれかのページの内容を少し変更（スペースを 1 つ入れて保存するだけで可）して再コンパイルをトリガーするか、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 にレコードを push するだけで、マウントポイントコンポーネントがそれをレンダリングします。

解決策：必要なページ（または常駐するルートラップコンポーネント）にマウントポイントを置きます：

vue

<lh-config-provider>
  <view><!-- コンテンツ --></view>
  <lh-message />
  <lh-loading />
</lh-config-provider>

警告は意図的な設計です —— 無言のフォールバックを行わず、「呼び出しは効いているように見えて実際には何も起きない」という隠れた bug を避けます。

4. スタイルが効かない / クラス名はあるのにスタイルが欠けている

確認手順：

2 つの CSS 成果物をインポートしているか確認する：@lh-ui/uniapp/src/theme/index.css と @lh-ui/uniapp/src/icon/iconfont.css。テーマ変数のインポートが漏れていると、すべての var(--lh-*) がデフォルト値にフォールバックします（色も角丸もすべて正しくなくなる）。
コンポーネントレベルの styleIsolation を上書きしていないか確認する。コンポーネント SFC は styleIsolation: 'shared' + addGlobalClass: true を自前で持ちます。プロジェクトレベルの設定でより厳しい分離を強制していると、コンポーネントスタイルが相互に不可視になります。
カスタムスタイルは 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 に付与してグローバルにはならず、本ライブラリのスコープはラップするノードに従います）。

よくある質問 ​

1. easycom 設定を変更しても反映されない ​

2. ref でコンポーネントを取得できない / 計測結果が空 ​

3. 命令的サービス（message / loading）を呼んでも反応がない ​

4. スタイルが効かない / クラス名はあるのにスタイルが欠けている ​

5. ミニプログラムのパッケージサイズに iconfont の base64 があるのはなぜか ​

6. H5 ではポップアップの位置が正常だが、ミニプログラムではずれる ​

7. ダークモードが効かない ​