Back to Details

capacitor-keyboard

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Keyboard Handling in Capacitor

Capacitor应用中的键盘处理

Manage keyboard behavior in iOS and Android apps.
管理iOS和Android应用中的键盘行为。

When to Use This Skill

何时使用此技能

  • User has keyboard issues
  • User needs keyboard events
  • User wants to hide keyboard
  • User has scroll issues with keyboard
  • User wants keyboard accessory bar
  • 用户遇到键盘相关问题
  • 用户需要监听键盘事件
  • 用户需要隐藏键盘
  • 用户遇到键盘导致的滚动问题
  • 用户需要配置键盘辅助栏

Quick Start

快速开始

bash
bun add @capacitor/keyboard
bunx cap sync
bash
bun add @capacitor/keyboard
bunx cap sync

Basic Usage

基础用法

typescript
import { Keyboard } from '@capacitor/keyboard';

// Show keyboard
await Keyboard.show();

// Hide keyboard
await Keyboard.hide();

// Listen for keyboard events
Keyboard.addListener('keyboardWillShow', (info) => {
  console.log('Keyboard height:', info.keyboardHeight);
});

Keyboard.addListener('keyboardWillHide', () => {
  console.log('Keyboard hiding');
});
typescript
import { Keyboard } from '@capacitor/keyboard';

// 显示键盘
await Keyboard.show();

// 隐藏键盘
await Keyboard.hide();

// 监听键盘事件
Keyboard.addListener('keyboardWillShow', (info) => {
  console.log('Keyboard height:', info.keyboardHeight);
});

Keyboard.addListener('keyboardWillHide', () => {
  console.log('Keyboard hiding');
});

Configuration

配置说明

typescript
// capacitor.config.ts
plugins: {
  Keyboard: {
    resize: 'body',        // 'body' | 'ionic' | 'native' | 'none'
    style: 'dark',         // 'dark' | 'light' | 'default'
    resizeOnFullScreen: true,
  },
},
typescript
// capacitor.config.ts
plugins: {
  Keyboard: {
    resize: 'body',        // 'body' | 'ionic' | 'native' | 'none'
    style: 'dark',         // 'dark' | 'light' | 'default'
    resizeOnFullScreen: true,
  },
},

Resize Modes

调整模式

ModeDescription
body
Resize body element
ionic
Use Ionic's keyboard handling
native
Native WebView resize
none
No automatic resize
模式描述
body
调整body元素尺寸
ionic
使用Ionic的键盘处理逻辑
native
原生WebView调整尺寸
none
不自动调整尺寸

Handle Keyboard Height

处理键盘高度

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

if (Capacitor.isNativePlatform()) {
  Keyboard.addListener('keyboardWillShow', (info) => {
    document.body.style.setProperty(
      '--keyboard-height',
      `${info.keyboardHeight}px`
    );
  });

  Keyboard.addListener('keyboardWillHide', () => {
    document.body.style.setProperty('--keyboard-height', '0px');
  });
}
css
.chat-input {
  position: fixed;
  bottom: calc(var(--keyboard-height, 0px) + env(safe-area-inset-bottom));
  left: 0;
  right: 0;
}
typescript
import { Keyboard } from '@capacitor/keyboard';
import { Capacitor } from '@capacitor/core';

if (Capacitor.isNativePlatform()) {
  Keyboard.addListener('keyboardWillShow', (info) => {
    document.body.style.setProperty(
      '--keyboard-height',
      `${info.keyboardHeight}px`
    );
  });

  Keyboard.addListener('keyboardWillHide', () => {
    document.body.style.setProperty('--keyboard-height', '0px');
  });
}
css
.chat-input {
  position: fixed;
  bottom: calc(var(--keyboard-height, 0px) + env(safe-area-inset-bottom));
  left: 0;
  right: 0;
}

Scroll to Input

滚动到输入框

typescript
Keyboard.addListener('keyboardWillShow', async (info) => {
  const activeElement = document.activeElement as HTMLElement;

  if (activeElement) {
    // Wait for keyboard animation
    await new Promise((r) => setTimeout(r, 100));

    activeElement.scrollIntoView({
      behavior: 'smooth',
      block: 'center',
    });
  }
});
typescript
Keyboard.addListener('keyboardWillShow', async (info) => {
  const activeElement = document.activeElement as HTMLElement;

  if (activeElement) {
    // 等待键盘动画完成
    await new Promise((r) => setTimeout(r, 100));

    activeElement.scrollIntoView({
      behavior: 'smooth',
      block: 'center',
    });
  }
});

iOS Accessory Bar

iOS 键盘辅助栏

typescript
// Show/hide the toolbar above keyboard
await Keyboard.setAccessoryBarVisible({ isVisible: true });
typescript
// 显示/隐藏键盘上方的工具栏
await Keyboard.setAccessoryBarVisible({ isVisible: true });

Form Best Practices

表单最佳实践

typescript
// Prevent zoom on iOS (use font-size >= 16px)
input {
  font-size: 16px;
}

// Handle form submission
form.addEventListener('submit', async (e) => {
  e.preventDefault();
  await Keyboard.hide();
  // Process form
});

// Move to next field
input.addEventListener('keypress', (e) => {
  if (e.key === 'Enter') {
    const nextInput = getNextInput();
    if (nextInput) {
      nextInput.focus();
    } else {
      Keyboard.hide();
    }
  }
});
typescript
// 防止iOS上的页面缩放（使用字体大小≥16px）
input {
  font-size: 16px;
}

// 处理表单提交
form.addEventListener('submit', async (e) => {
  e.preventDefault();
  await Keyboard.hide();
  // 处理表单逻辑
});

// 切换到下一个输入框
input.addEventListener('keypress', (e) => {
  if (e.key === 'Enter') {
    const nextInput = getNextInput();
    if (nextInput) {
      nextInput.focus();
    } else {
      Keyboard.hide();
    }
  }
});

Troubleshooting

常见问题排查

IssueSolution
Content hiddenUse resize mode
Slow animationUse 
keyboardWillShow
iOS zoomUse 16px font-size
Android overlapSet 
windowSoftInputMode
问题解决方案
内容被遮挡使用合适的调整模式
动画卡顿使用
keyboardWillShow
事件
iOS页面缩放使用16px及以上的字体大小
Android内容重叠设置
windowSoftInputMode
属性

Resources

相关资源