Vue3 Touch Keyboard

The Keyboard component from the vue3-touch-keyboard package, based on the vue-touch-keyboard package by icebob, is a customizable touch keyboard for Vue 3 applications. It can be used to provide a touch interface for text input fields. Provided by 3POS / www.3pos.de

Installation

First, install the package using npm:

npm install vue3-touch-keyboard

Include style in your main.js

../node_modules/vue3-touch-keyboard/dist/style.css

Usage

Import the Keyboard component and use it in your Vue component:

import { Keyboard } from 'vue3-touch-keyboard';

export default {
  components: {
    Keyboard
  }
}

Then, use the Keyboard component in your template:

<Keyboard :input="myInput" :layout="myLayout" />

Props

The Keyboard component accepts the following props:

• input (HTMLInputElement|HTMLTextAreaElement): The input element to update with the keyboard input.
• layout (String|Object): The layout of the keyboard. Can be a string representing a predefined layout or an object defining a custom layout.
• defaultKeySet (String): The default key set to display on the keyboard. Default is 'default'.
• accept (Function): The function to call when the accept key is pressed.
• cancel (Function): The function to call when the cancel key is pressed.
• change (Function): The function to call when the input value changes.
• next (Function): The function to call when the next key is pressed.
• options (Object): Additional options for the keyboard.

Events

The Keyboard component emits a custom event when a key with a function is pressed. The name of the event is the function name of the key.

Methods

The Keyboard component provides several methods that can be used to interact with the keyboard:

• getLayout: Retrieves the layout object based on the layout prop.
• changeKeySet: Changes the current key set to the specified name.
• toggleKeySet: Toggles the current key set between the specified name and the default key set.
• getCaptionOfKey: Retrieves the caption of a key.
• getClassesOfKey: Retrieves the classes of a key.
• getKeyStyle: Retrieves the style of a key.
• supportsSelection: Checks if the input element supports text selection.
• getCaret: Retrieves the current caret position in the input element.
• backspace: Deletes the selected text or the character before the caret position.
• insertChar: Inserts a character at the caret position.
• mousedown: Handles the mousedown event on the keyboard.
• clickKey: Handles the click event on a key.
• setFocusToInput: Sets focus to the input element and updates the caret position.

Styles

The Keyboard component uses scoped CSS, which means that the styles are applied only to this component. You can customize the appearance of the keyboard by overriding the CSS classes in your own styles. The component uses the following CSS classes:

• vue3-touch-keyboard: The main class for the keyboard component.
• keyboard: The class for the keyboard itself.
• line: The class for a line of keys.
• key: The class for a key.
• placeholder: The class for a placeholder key.
• activated: The class for an activated key.

Example

Here's an example of how to use the Keyboard component:

<template>
  <div>
    <input ref="myInput" type="text" />
    <Keyboard :input="myInput" layout="default" @accept="onAccept" @cancel="onCancel" />
  </div>
</template>

<script>
import { Keyboard } from 'vue3-touch-keyboard';

export default {
  components: {
    Keyboard
  },
  methods: {
    onAccept(text) {
      console.log('Accepted: ' + text);
    },
    onCancel() {
      console.log('Cancelled');
    }
  }
}
</script>

In this example, the Keyboard component is linked to an input field. When the accept key is pressed, the onAccept method is called with the current text of the input field. When the cancel key is pressed, the onCancel method is called.

Vue3 Touch Keyboard Composable Documentation

This package provides a composable useTouchKeyboard for Vue 3 applications, allowing control over the Keyboard.vue component. This composable facilitates the integration of a touch keyboard into your Vue 3 application.

Usage

1. Import the composable

   Import the useTouchKeyboard composable in your component.

   import { useTouchKeyboard } from 'vue3-touch-keyboard';
      

2. Call the composable in your setup function

   Call the useTouchKeyboard function in your setup function.

   setup() {
     const touchKeyboard = useTouchKeyboard();
     // ...
     return {
       // ...
       touchKeyboard,
     };
   }
      

   You can now use the returned object to control the touch keyboard.

API

The useTouchKeyboard function returns an object with the following properties and methods:

• options: An object containing the current options for the touch keyboard component.
• keyboardLocale: The current locale of the keyboard. (uses localstorage to persist state)
• layouts: An object containing the available keyboard layouts.
• keyboardEnabled: A boolean indicating whether the touch keyboard is enabled. (uses localstorage to persist state)
• setLocalLayout(locale): A function to set the local layout based on the provided locale.
• toggleTouchKeyboard(isEnabled): A function to toggle the visibility of the touch keyboard.
• showTouchKeyboardWithoutEvent(): A function to show the touch keyboard without any event.
• showTouchKeyboard(e): A function to show the touch keyboard based on the focus event.
• hideTouchKeyboard(): A function to hide the touch keyboard.
• dismissOnScreenKeyboard(e): A function to dismiss the on-screen keyboard based on the provided event.
• getKeyBoardLayout(locale, layout): A function to get the keyboard layout based on the provided locale and layout.

Input Attributes

To use the touch keyboard composable with an input element, add the data-use-touch-keyboard attribute to it. Note that you need to use your own wrapper arround the Keyboard.vue component. You can also use showTouchKeyboard method in a focus event of the target input if you don't want to use data-use-touch-keyboard attribute, but both serve the same purpose

<input data-use-touch-keyboard>
or
<input @focus="showTouchKeyboard">

To set a specific layout for the keyboard, use the data-layout attribute:

<input data-use-touch-keyboard data-layout="normal">

The data-layout attribute can be set to any of the available layouts: 'normal', 'numeric', 'compact'. If the specified layout does not exist, it will default to 'normal'.

Vue3 Touch Keyboard - OnScreenKeyboard Component

The OnScreenKeyboard component is a wrapper around the Keyboard component. It uses useTouchKeyboard composable to manage the state of the keyboard and provides an interface to show and hide the keyboard. It is recommended to use this component as global as possible (for example in the App.vue if you want to make it available for all components), as it handles all the inputs that enables the touch keyboard via setting the data-use-touch-keyboard attribute in the target input

Usage

Import the OnScreenKeyboard component and use it in your Vue component:

import { OnScreenKeyboard } from 'vue3-touch-keyboard';

export default {
  components: {
    OnScreenKeyboard
  }
}

Then, use the OnScreenKeyboard component in your template:

<OnScreenKeyboard />

Composable

The OnScreenKeyboard component uses the useTouchKeyboard composable to manage the state of the keyboard.

Example

Here's an example of how to use the OnScreenKeyboard component:

<template>
  <div>
    <input type="text" data-use-touch-keyboard data-layout="compact" />
    <OnScreenKeyboard />
  </div>
</template>

<script setup>
import {OnScreenKeyboard} from 'vue3-touch-keyboard';
</script>

In this example, the OnScreenKeyboard component is linked to an input field. When the input field is focused

Notes

the OnScreenKeyboard component automatically manages the keyboard state through the useTouchKeyboard composable, providing a seamless touch keyboard experience.

Feel free to customize the use of the Keyboard.vue component in a wrapper by utilizing the useTouchKeyboard composable. This composable can also be employed as a utility to control any wrapper around the Keyboard.vue component. Additionally, persistent state variables such as keyboardLocale and keyboardEnabled are available for further customization.

<template>
  <div>
    <input ref="myInput" type="text" data-use-touch-keyboard data-layout="compact" />
    <OnScreenKeyboard />
  </div>
</template>

<script setup>
import { useTouchKeyboard, OnScreenKeyboard } from 'vue3-touch-keyboard';
const {keyboardLocale, keyboardEnabled, setLocalLayout, toggleTouchKeyboard} = useTouchKeyboard()
</script>

In this modified example, the useTouchKeyboard composable is utilized to control the state of the touch keyboard. The input field is tagged with the data-use-touch-keyboard attribute and a specific layout is set with the data-layout attribute.

This comprehensive approach allows for global usage of the touch keyboard, controlled by the useTouchKeyboard composable, and provides flexibility for customization in specific scenarios.