@public-ui/components
Version:
Contains all web components that belong to KoliBri - The accessible HTML-Standard.
163 lines (109 loc) • 40.3 kB
Markdown
# InputText
Synonyme: Text Field
Der Input-Typ **Text** erzeugt ein Eingabefeld für normalen Text, Suchbegriffe, URLs oder Telefonnummern.
Die Komponente hat Known-Issues bezüglich Browserabhängigkeit und Barrierefreiheit. Näheres kann unter [KNOWN_ISSUES.md](https://github.com/public-ui/kolibri/blob/develop/KNOWN_ISSUES.md) nachgelssen werden.
## Konstruktion
### Code
```html
<kol-input-text
_type="text"
_label="Texteingabe"
_icons='{"left": "codicon codicon-arrow-left", "right": {"icon": "codicon codicon-arrow-right", "style": {"font-size": "200%"}}}'
></kol-input-text>
<kol-input-text _type="text" _label="Deaktiviert" _disabled></kol-input-text>
<kol-input-text _type="text" _label="Schreibgeschützt" _read-only></kol-input-text>
<kol-input-text
_type="text"
_label="Mit Button"
_smart-button='{"_icons": "codicon codicon-chrome-close", "_hideLabel": true, "_label": "Löschen"}'
></kol-input-text>
```
### Beispiel
<kol-input-text _type="text" _label="Texteingabe" _icons='{"left": "codicon codicon-arrow-left", "right": {"icon": "codicon codicon-arrow-right", "style": {"font-size": "200%"}}}'></kol-input-text>
<kol-input-text _type="text" _label="Deaktiviert" _disabled></kol-input-text>
<kol-input-text _type="text" _label="Schreibgeschützt" _read-only></kol-input-text>
<kol-input-text
_type="text"
_label="Mit Button"
_smart-button='{"_icons": "codicon codicon-chrome-close", "_hideLabel": true, "_label": "Löschen"}'></kol-input-text>
### Events
Events der Komponente können über eine `_on`-Property behandelt werden, die aus einem Objekt mit verschiedenen Callback-Funktionen besteht:
```js
kolibriElement._on = {
onFocus: (event) => {
/* Do something on focus */
},
onInput: (event, value) => {
/* Do something with value or event */
},
// ...
};
```
| Event | Auslöser | Value |
| -------- | -------------------------------------------------------------------------------------------- | ---------------------------- |
| onFocus | Element wird fokussiert | - |
| onClick | Element wird angeklickt | - |
| onInput | Eine Eingabe erfolgt (entspricht nativem `input`-Event) | Eingegebener Wert als String |
| onChange | Eingabe ist abgeschlossen und Eingabefeld verliert Fokus (entspricht nativem `change`-Event) | Eingegebener Wert als String |
| onBlur | Element verliert Fokus | - |
## Verwendung
### Best practices
- Achten sie darauf `id` und `name` korrekt zu setzen, damit die Daten beim Formular Absenden mitgesendet werden.
## Barrierefreiheit
### Tastatursteuerung
| Taste | Funktion |
| ----- | ------------------------------------- |
| `Tab` | Fokussiert das Eingabefeld. |
| `ESC` | Löscht den Inhalt (nur Typ = Search). |
## Links und Referenzen
- <kol-link _href="https://medium.com/@gavyn/til-autofocus-inputs-are-an-accessibility-problem-32ced60c3109" _target="_blank"></kol-link>
- <kol-link _href="https://www.jotform.com/blog/html5-datalists-what-you-need-to-know-78024/" _target="_blank"></kol-link>
<!-- Auto Generated Below -->
## Properties
| Property | Attribute | Description | Type | Default |
| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| `_accessKey` | `_access-key` | Defines which key combination can be used to trigger or focus the interactive element of the component. | `string` \| `undefined` | `undefined` |
| `_alert` | `_alert` | <span class="text-red-500">**[DEPRECATED]**</span> Will be removed in v3. Use automatic behaviour instead.<br/><br/>Defines whether the screen-readers should read out the notification. | `boolean` \| `undefined` | `undefined` |
| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `"off"` \| `"on"` \| `undefined` | `undefined` |
| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean` \| `undefined` | `false` |
| `_error` | `_error` | <span style="color:red">**[DEPRECATED]**</span> Will be removed in v3. Use `msg` instead.<br/><br/>Defines the error message text. | `string` \| `undefined` | `undefined` |
| `_hasCounter` | `_has-counter` | Shows the character count on the lower border of the input. | `boolean` \| `undefined` | `false` |
| `_hideError` | `_hide-error` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean` \| `undefined` | `false` |
| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean` \| `undefined` | `false` |
| `_hint` | `_hint` | Defines the hint text. | `string` \| `undefined` | `''` |
| `_icons` | `_icons` | Defines the icon classnames (e.g. `_icons="fa-solid fa-user"`). | `string` \| `undefined` \| `{ right?: IconOrIconClass` \| `undefined; left?: IconOrIconClass` \| `undefined; }` | `undefined` |
| `_id` | `_id` | Defines the internal ID of the primary component element. | `string` \| `undefined` | `undefined` |
| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |
| `_maxLength` | `_max-length` | Defines the maximum number of input characters. | `number` \| `undefined` | `undefined` |
| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `string` \| `undefined` \| `{} & { _level?: 0` \| `2` \| `1` \| `4` \| `3` \| `5` \| `6` \| `undefined; _on?: KoliBriAlertEventCallbacks` \| `undefined; _type?: "error"` \| `"default"` \| `"info"` \| `"success"` \| `"warning"` \| `undefined; _variant?: "card"` \| `"msg"` \| `undefined; _label?: string` \| `undefined; _alert?: boolean` \| `undefined; _hasCloser?: boolean` \| `undefined; } & { _description: string; }` | `undefined` |
| `_name` | `_name` | Defines the technical name of an input field. | `string` \| `undefined` | `undefined` |
| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput` \| `undefined` | `undefined` |
| `_pattern` | `_pattern` | Defines a validation pattern for the input field. | `string` \| `undefined` | `undefined` |
| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string` \| `undefined` | `undefined` |
| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean` \| `undefined` | `false` |
| `_required` | `_required` | Makes the input element required. | `boolean` \| `undefined` | `false` |
| `_shortKey` | `_short-key` | Adds a visual short key hint to the component. | `string` \| `undefined` | `undefined` |
| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string` \| `undefined` \| `{ _label: string; } & { _tabIndex?: number` \| `undefined; _value?: Stringified<StencilUnknown>; _ariaExpanded?: boolean` \| `undefined; _accessKey?: string` \| `undefined; _role?: "button"` \| `"link"` \| `"tab"` \| `"treeitem"` \| `undefined; _ariaControls?: string` \| `undefined; _ariaDescription?: string` \| `undefined; _ariaSelected?: boolean` \| `undefined; _on?: ButtonCallbacksPropType<StencilUnknown>` \| `undefined; _type?: "button"` \| `"reset"` \| `"submit"` \| `undefined; _variant?: "primary"` \| `"secondary"` \| `"normal"` \| `"tertiary"` \| `"danger"` \| `"ghost"` \| `"custom"` \| `undefined; _customClass?: string` \| `undefined; _disabled?: boolean` \| `undefined; _hideLabel?: boolean` \| `undefined; _icons?: IconsPropType` \| `undefined; _id?: string` \| `undefined; _name?: string` \| `undefined; _shortKey?: string` \| `undefined; _syncValueBySelector?: string` \| `undefined; _tooltipAlign?: AlignPropType` \| `undefined; }` | `undefined` |
| `_spellCheck` | `_spell-check` | Defines whether the browser should check the spelling and grammar. | `boolean` \| `undefined` | `undefined` |
| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[]` \| `string` \| `undefined` | `undefined` |
| `_tabIndex` | `_tab-index` | Defines which tab-index the primary element of the component has. (https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) | `number` \| `undefined` | `undefined` |
| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `"bottom"` \| `"left"` \| `"right"` \| `"top"` \| `undefined` | `'top'` |
| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean` \| `undefined` | `false` |
| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `"search"` \| `"tel"` \| `"text"` \| `"url"` \| `undefined` | `'text'` |
| `_value` | `_value` | Defines the value of the input. | `string` \| `undefined` | `undefined` |
## Methods
### `focus() => Promise<void>`
<span style="color:red">**[DEPRECATED]**</span> Use kolFocus instead.<br/><br/>
#### Returns
Type: `Promise<void>`
### `getValue() => Promise<string | undefined>`
#### Returns
Type: `Promise<string | undefined>`
### `kolFocus() => Promise<void>`
#### Returns
Type: `Promise<void>`
## Slots
| Slot | Description |
| ---- | ----------------------------------- |
| | Die Beschriftung des Eingabefeldes. |
----------------------------------------------