capacitor-keyboard

Capacitor でのキーボード処理

使用する場合

次の場合に使用します：

• フォーカス中の入力欄がキーボードに覆われる、またはページが予期せずスクロールする
• チャット入力欄／固定フッターがキーボードに追従しない
• キーボードの上に白または黒の帯が表示される（Android 15 以降のエッジツーエッジ、iOS の背景）
• キーボードを開くと 100vh／dvh のレイアウトが崩れる
• iOS で入力欄にズームする、またはQuickType／アクセサリバーの表示がおかしい
• キーボードイベントが発火しない、または二重に発火する

次の場合は使用しないでください：

• ノッチ／ホームインジケーター／ステータスバーのパディング：safe-area-handling
• Ionic の ion-input、ion-footer のスタイル設定：ionic-design
• ラベル、フォーカス順序、スクリーンリーダー：capacitor-accessibility

プラットフォームのモデル（重要な判断ポイント）

	iOS	Android
サイズ変更の担当	resize モードごとにプラグイン	OS と WebView。resize 設定は無視されます
イベント	アニメーション前に keyboardWillShow、後に keyboardDidShow	Will／Did はほぼ同時に発火します
JS からの制御	setResizeMode、getResizeMode、setScroll、setStyle、setAccessoryBarVisible（iPhone のみ）	show()（Android のみ）、hide()

iOS の resize モード（KeyboardResize enum）：

モード	効果	使用する場面
native（デフォルト）	WebView 全体が縮小し、vh の値が変化します	シンプルな Web アプリ。最も簡単です
body	<body> の高さのみが変化し、vh は変化しません	安定した vh を前提とするレイアウト
ionic	ion-app のみがサイズ変更されます	Ionic Framework アプリのみ
none	サイズ変更しません。キーボードの高さを使って配置します	カスタムのチャット UI、細かな制御が必要な場合

ワークフロー

1. 確認：capacitor.config.* の plugins.Keyboard、@capacitor/keyboard のバージョン（8.0.4 以降には iOS 26 と Android SystemBars の修正が含まれます）、Ionic の使用有無、@capacitor/status-bar／SystemBars の設定、問題が発生する画面の CSS（position: fixed、100vh）を確認します。
2. デバイスで再現します（シミュレーターではハードウェアキーボードが使われていることがあります：iOS Simulator -> I/O -> Keyboard -> Toggle Software Keyboard）。
3. 表から iOS の resize モードを選び、実行時にモードを変更する必要がある画面がない限り、ランタイムではなく設定に指定します。
4. Android は個別に修正します（以下を参照）。
5. 検証します。

設定

// capacitor.config.ts
import { KeyboardResize, KeyboardStyle } from '@capacitor/keyboard';

plugins: {
  Keyboard: {
    resize: KeyboardResize.Body,      // iOS only
    style: KeyboardStyle.Default,     // iOS only; JSON value is "DARK" | "LIGHT" | "DEFAULT"
    // resizeOnFullScreen: omit on Capacitor 8+ (SystemBars handles insets; see Android notes)
    autoBackdropColor: 'auto',        // iOS, 8.0.4+: 'off' (default) | 'auto' | 'dom'
  },
},

JSON 設定の文字列値では、style は大文字（"DARK"）、resize は小文字（"body"）です。

カスタム配置（resize: none またはチャット UI）

import { Capacitor } from '@capacitor/core';
import { Keyboard } from '@capacitor/keyboard';

if (Capacitor.isNativePlatform()) {
  Keyboard.addListener('keyboardWillShow', ({ keyboardHeight }) => {
    document.documentElement.style.setProperty('--kb', `${keyboardHeight}px`);
  });
  Keyboard.addListener('keyboardWillHide', () => {
    document.documentElement.style.setProperty('--kb', '0px');
  });
}

.composer {
  position: fixed;
  inset-inline: 0;
  bottom: max(var(--kb, 0px), env(safe-area-inset-bottom));
}

+ ではなく max() を使用してください。キーボードが表示されている間は、ホームインジケーターのインセットがすでに覆われているためです。

Android に関する注意点

• Android 15 以降（targetSdk 35）ではエッジツーエッジが必須です。Android 16（targetSdk 36、Capacitor 8 のデフォルト）ではオプトアウトができなくなります。WebView はシステムバーの下にも描画されるようになったため、キーボードのインセットを処理する必要があります。@capacitor/keyboard 7.0.2 では Android 15 以降でキーボード上部に余白ができる問題が修正され、8.0.3 では SystemBars コアプラグインとの相互作用が修正されました。回避策を書く前にプラグインを更新してください。
• resizeOnFullScreen: true は、フルスクリーン／ステータスバーのオーバーレイに対する Capacitor 7 以前の回避策でした。Capacitor 8 以降では SystemBars コアプラグインが IME インセットを処理するため、SystemBars.insetsHandling が disable でない限り、You should omit `Keyboard.resizeOnFullScreen` in your `capacitor.config.json`. Other values can lead to unexpected behavior. と記録されます。この設定は削除してください。
• 重なりを修正するために android:windowSoftInputMode="adjustPan" を追加しないでください。ウィンドウ全体がパンされ、固定ヘッダーが崩れます。テンプレートではこれを省略しています（デフォルトのサイズ変更動作が使われます）。
• env(keyboard-inset-height) と interactive-widget viewport meta は Chromium の機能です。これらに依存する前に、対象の Android System WebView バージョンでテストしてください。また、iOS では決して使用しないでください。

iOS に関する注意事項

• 計算後の font-size が 16px 未満の入力欄では、フォーカス時に iOS でズームが発生します。入力欄には font-size: 16px（またはそれ以上）を指定してください。アクセシビリティに悪影響を及ぼすため、ユーザーによるズームを全体的に無効にしないでください（maximum-scale=1）。
• setAccessoryBarVisible({ isVisible: false }) は iPhone の前へ／次へ／完了バーを非表示にします。iPad には影響しません。
• setScroll({ isDisabled: true }) は、キーボードが開いたときに WebView のスクロールビューがバウンスするのを防ぎます。カスタムレイアウトでは resize: none と組み合わせてください。
• iOS 26 のキーボードの回帰問題と、iPad の Magic Keyboard 使用時に QuickType バーが黒くなる問題は、@capacitor/keyboard 8.0.4 で修正されました。キーボードの背後に黒または白の帯が表示される場合は、autoBackdropColor: 'auto'（設定の backgroundColor を使用し、設定がない場合は DOM の body 背景を使用）または 'dom' を設定してください。

動作確認

1. npx cap sync を実行し、実機の iPhone と Android 15 以降／16 のデバイスで実行します。
2. 各フォーム画面で、最初と最後の入力欄にフォーカスします。フォーカス中のフィールドが表示されたままであること、フッターがキーボード上に配置されること、キーボードの上に隙間がないこと、キーボードを開いたまま画面を回転してもレイアウトが維持されることを確認します。
3. スワイプまたは戻るボタンで閉じます。keyboardWillHide が発生し、--kb が 0 に戻ることを確認します。
4. iOS：フォーカス時にズームしないこと、アクセサリバーの状態がデザインと一致することを確認します。
5. バージョンを確認します：npm ls @capacitor/keyboard @capacitor/core。

エラー処理

症状／メッセージ	原因	修正方法
"Keyboard" plugin is not implemented on web または "Keyboard.setAccessoryBarVisible()" is not implemented on android	そのプラットフォームではプラグイン／メソッドを使用できない	Capacitor.getPlatform() === 'ios' でガードします
iOS で show() を呼び出しても何も起きない	show() は Android 専用	ユーザー操作をきっかけに入力欄へフォーカスします
キーボードを閉じた後、フッターが画面中央に浮く（Android）	アニメーションなしでキーボードが非表示になったとき、WebView の高さがリセットされない	@capacitor/keyboard 8.0.4 以降に更新します
Android 15 以降でキーボードの上に白い帯が表示される	エッジツーエッジのインセットと古いプラグインの組み合わせ	プラグインを更新します（7.0.2 以降／8.0.3 以降）。Capacitor 8 では resizeOnFullScreen を削除します
Logcat SystemBars: You should omit `Keyboard.resizeOnFullScreen` ...	古い設定が SystemBars のインセット処理と競合している	設定から resizeOnFullScreen を削除します
iOS で vh ベースの画面が縮む	resize: native によってビューポートが変化する	body または none に切り替えます
Ionic のコンテンツが 2 回ジャンプする	resize: native／body と Ionic 独自の処理が併用されている	resize: 'ionic' を使用します
画面遷移後にリスナーが 2 回発火する	ページのマウントごとにリスナーが追加され、削除されていない	返されたハンドルを保持し、アンマウント時に await handle.remove() を呼び出します
ハードウェアキーボードを接続した iPad で QuickType バーが黒くなる	8.0.4 より前のプラグインの不具合	プラグインを更新します

リソース

• キーボードプラグイン API：https://capacitorjs.com/docs/apis/keyboard
• プラグインの変更履歴：https://github.com/ionic-team/capacitor-keyboard/blob/main/CHANGELOG.md
• System Bars（エッジツーエッジ）：https://capacitorjs.com/docs/apis/system-bars