Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/xie392/capacitor-keyboard
https://github.com/xie392/capacitor-keyboard
Last synced: 14 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/xie392/capacitor-keyboard
- Owner: xie392
- License: other
- Created: 2024-04-02T07:39:33.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2024-04-02T07:39:36.000Z (9 months ago)
- Last Synced: 2024-10-28T08:11:41.481Z (about 2 months ago)
- Language: Objective-C
- Size: 112 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @capacitor/keyboard
The Keyboard API provides keyboard display and visibility control, along with event tracking when the keyboard shows and hides.
## Install
```bash
npm install @capacitor/keyboard
npx cap sync
```
## Example
```typescript
import { Keyboard } from '@capacitor/keyboard';
Keyboard.addListener('keyboardWillShow', info => {
console.log('keyboard will show with height:', info.keyboardHeight);
});
Keyboard.addListener('keyboardDidShow', info => {
console.log('keyboard did show with height:', info.keyboardHeight);
});
Keyboard.addListener('keyboardWillHide', () => {
console.log('keyboard will hide');
});
Keyboard.addListener('keyboardDidHide', () => {
console.log('keyboard did hide');
});
```
## Configuration
On iOS, the keyboard can be configured with the following options:
| Prop | Type | Description | Default | Since |
| ------------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----- |
| **`resize`** | KeyboardResize | Configure the way the app is resized when the Keyboard appears. Only available on iOS. | native | 1.0.0 |
| **`style`** | KeyboardStyle | Override the keyboard style if your app doesn't support dark/light theme changes. If not set, the keyboard style will depend on the device appearance. Only available on iOS. | | 1.0.0 |
| **`resizeOnFullScreen`** | boolean | There is an Android bug that prevents the keyboard from resizing the WebView when the app is in full screen (i.e. if StatusBar plugin is used to overlay the status bar). This setting, if set to true, add a workaround that resizes the WebView even when the app is in full screen. Only available for Android | | 1.1.0 |
### Examples
In `capacitor.config.json`:
```json
{
"plugins": {
"Keyboard": {
"resize": "body",
"style": "DARK",
"resizeOnFullScreen": true
}
}
}
```
In `capacitor.config.ts`:
```ts
///
import { CapacitorConfig } from '@capacitor/cli';
import { KeyboardResize, KeyboardStyle } from '@capacitor/keyboard';
const config: CapacitorConfig = {
plugins: {
Keyboard: {
resize: KeyboardResize.Body,
style: KeyboardStyle.Dark,
resizeOnFullScreen: true,
},
},
};
export default config;
```
## Compatibility with `cordova-plugin-ionic-keyboard`
To maintain compatibility with
[`cordova-plugin-ionic-keyboard`](https://github.com/ionic-team/cordova-plugin-ionic-keyboard),
the following events also work with `window.addEventListener`:
- `keyboardWillShow`
- `keyboardDidShow`
- `keyboardWillHide`
- `keyboardDidHide`
## API
* [`show()`](#show)
* [`hide()`](#hide)
* [`setAccessoryBarVisible(...)`](#setaccessorybarvisible)
* [`setScroll(...)`](#setscroll)
* [`setStyle(...)`](#setstyle)
* [`setResizeMode(...)`](#setresizemode)
* [`getResizeMode()`](#getresizemode)
* [`addListener('keyboardWillShow', ...)`](#addlistenerkeyboardwillshow-)
* [`addListener('keyboardDidShow', ...)`](#addlistenerkeyboarddidshow-)
* [`addListener('keyboardWillHide', ...)`](#addlistenerkeyboardwillhide-)
* [`addListener('keyboardDidHide', ...)`](#addlistenerkeyboarddidhide-)
* [`removeAllListeners()`](#removealllisteners)
* [Interfaces](#interfaces)
* [Enums](#enums)
### show()
```typescript
show() => Promise
```
Show the keyboard. This method is alpha and may have issues.
This method is only supported on Android.
**Since:** 1.0.0
--------------------
### hide()
```typescript
hide() => Promise
```
Hide the keyboard.
**Since:** 1.0.0
--------------------
### setAccessoryBarVisible(...)
```typescript
setAccessoryBarVisible(options: { isVisible: boolean; }) => Promise
```
Set whether the accessory bar should be visible on the keyboard. We recommend disabling
the accessory bar for short forms (login, signup, etc.) to provide a cleaner UI.
This method is only supported on iPhone devices.
| Param | Type |
| ------------- | ------------------------------------ |
| **`options`** | { isVisible: boolean; } |
**Since:** 1.0.0
--------------------
### setScroll(...)
```typescript
setScroll(options: { isDisabled: boolean; }) => Promise
```
Programmatically enable or disable the WebView scroll.
This method is only supported on iOS.
| Param | Type |
| ------------- | ------------------------------------- |
| **`options`** | { isDisabled: boolean; } |
**Since:** 1.0.0
--------------------
### setStyle(...)
```typescript
setStyle(options: KeyboardStyleOptions) => Promise
```
Programmatically set the keyboard style.
This method is only supported on iOS.
| Param | Type |
| ------------- | --------------------------------------------------------------------- |
| **`options`** | KeyboardStyleOptions |
**Since:** 1.0.0
--------------------
### setResizeMode(...)
```typescript
setResizeMode(options: KeyboardResizeOptions) => Promise
```
Programmatically set the resize mode.
This method is only supported on iOS.
| Param | Type |
| ------------- | ----------------------------------------------------------------------- |
| **`options`** | KeyboardResizeOptions |
**Since:** 1.0.0
--------------------
### getResizeMode()
```typescript
getResizeMode() => Promise
```
Get the currently set resize mode.
This method is only supported on iOS.
**Returns:** Promise<KeyboardResizeOptions>
**Since:** 4.0.0
--------------------
### addListener('keyboardWillShow', ...)
```typescript
addListener(eventName: 'keyboardWillShow', listenerFunc: (info: KeyboardInfo) => void) => Promise
```
Listen for when the keyboard is about to be shown.
On Android keyboardWillShow and keyboardDidShow fire almost at the same time.
| Param | Type |
| ------------------ | ------------------------------------------------------------------------ |
| **`eventName`** | 'keyboardWillShow' |
| **`listenerFunc`** | (info: KeyboardInfo) => void |
**Returns:** Promise<PluginListenerHandle>
**Since:** 1.0.0
--------------------
### addListener('keyboardDidShow', ...)
```typescript
addListener(eventName: 'keyboardDidShow', listenerFunc: (info: KeyboardInfo) => void) => Promise
```
Listen for when the keyboard is shown.
On Android keyboardWillShow and keyboardDidShow fire almost at the same time.
| Param | Type |
| ------------------ | ------------------------------------------------------------------------ |
| **`eventName`** | 'keyboardDidShow' |
| **`listenerFunc`** | (info: KeyboardInfo) => void |
**Returns:** Promise<PluginListenerHandle>
**Since:** 1.0.0
--------------------
### addListener('keyboardWillHide', ...)
```typescript
addListener(eventName: 'keyboardWillHide', listenerFunc: () => void) => Promise
```
Listen for when the keyboard is about to be hidden.
On Android keyboardWillHide and keyboardDidHide fire almost at the same time.
| Param | Type |
| ------------------ | ------------------------------- |
| **`eventName`** | 'keyboardWillHide' |
| **`listenerFunc`** | () => void |
**Returns:** Promise<PluginListenerHandle>
**Since:** 1.0.0
--------------------
### addListener('keyboardDidHide', ...)
```typescript
addListener(eventName: 'keyboardDidHide', listenerFunc: () => void) => Promise
```
Listen for when the keyboard is hidden.
On Android keyboardWillHide and keyboardDidHide fire almost at the same time.
| Param | Type |
| ------------------ | ------------------------------ |
| **`eventName`** | 'keyboardDidHide' |
| **`listenerFunc`** | () => void |
**Returns:** Promise<PluginListenerHandle>
**Since:** 1.0.0
--------------------
### removeAllListeners()
```typescript
removeAllListeners() => Promise
```
Remove all native listeners for this plugin.
**Since:** 1.0.0
--------------------
### Interfaces
#### KeyboardStyleOptions
| Prop | Type | Description | Default | Since |
| ----------- | ------------------------------------------------------- | ---------------------- | ---------------------------------- | ----- |
| **`style`** | KeyboardStyle | Style of the keyboard. | KeyboardStyle.Default | 1.0.0 |
#### KeyboardResizeOptions
| Prop | Type | Description | Since |
| ---------- | --------------------------------------------------------- | ------------------------------------------------------- | ----- |
| **`mode`** | KeyboardResize | Mode used to resize elements when the keyboard appears. | 1.0.0 |
#### PluginListenerHandle
| Prop | Type |
| ------------ | ----------------------------------------- |
| **`remove`** | () => Promise<void> |
#### KeyboardInfo
| Prop | Type | Description | Since |
| -------------------- | ------------------- | ----------------------- | ----- |
| **`keyboardHeight`** | number | Height of the heyboard. | 1.0.0 |
### Enums
#### KeyboardStyle
| Members | Value | Description | Since |
| ------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Dark`** | 'DARK' | Dark keyboard. | 1.0.0 |
| **`Light`** | 'LIGHT' | Light keyboard. | 1.0.0 |
| **`Default`** | 'DEFAULT' | On iOS 13 and newer the keyboard style is based on the device appearance. If the device is using Dark mode, the keyboard will be dark. If the device is using Light mode, the keyboard will be light. On iOS 12 the keyboard will be light. | 1.0.0 |
#### KeyboardResize
| Members | Value | Description | Since |
| ------------ | --------------------- | -------------------------------------------------------------------------------------------------------------------- | ----- |
| **`Body`** | 'body' | Only the `body` HTML element will be resized. Relative units are not affected, because the viewport does not change. | 1.0.0 |
| **`Ionic`** | 'ionic' | Only the `ion-app` HTML element will be resized. Use it only for Ionic Framework apps. | 1.0.0 |
| **`Native`** | 'native' | The whole native Web View will be resized when the keyboard shows/hides. This affects the `vh` relative unit. | 1.0.0 |
| **`None`** | 'none' | Neither the app nor the Web View are resized. | 1.0.0 |