Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Skeptick/input-mask-compose
https://github.com/Skeptick/input-mask-compose
Last synced: 21 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/Skeptick/input-mask-compose
- Owner: Skeptick
- License: apache-2.0
- Created: 2024-04-26T20:04:42.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2024-12-17T21:36:33.000Z (24 days ago)
- Last Synced: 2024-12-17T22:30:40.524Z (24 days ago)
- Language: Kotlin
- Size: 90.8 KB
- Stars: 11
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- mobile-awesome - input-mask-compose - Библиотека для форматирования вводимых пользователем значений с поддержкой Compose Multiplatform. (Multiplatform / Android samples)
README
# input-mask-compose
Библиотека для форматирования вводимых пользователем значений с поддержкой Compose Multiplatform.
## Использование
```kotlin
kotlin {
sourceSets {
commonMain {
dependencies {
implementation("io.github.skeptick.inputmask:inputmask-core:0.0.5")
implementation("io.github.skeptick.inputmask:inputmask-compose:0.0.5")
}
}
}
}
```
## Поддерживаемые платформы
`core` поддерживает все таргеты Kotlin, `compose` все таргеты Compose Multiplatform.
## Идея
Синтаксис масок вдохновлён небезызвестной библиотекой от RedMadRobot (
[Android](https://github.com/RedMadRobot/input-mask-android),
[iOS](https://github.com/RedMadRobot/input-mask-ios)
), но реализация гораздо более примитивная. В частности, не поддерживаются
[«родственные» маски](https://github.com/RedMadRobot/input-mask-android/wiki/2.1-Affine-Masks).
## Объявление масок
Детальнее [в документации RedMadRobot](https://github.com/RedMadRobot/input-mask-android/wiki/Mask-Syntax:-Basics).
Верхнеуровнево:
- в `[]` описываем то, что ожидаем от пользователя
- в `{}` любые символы, которые хотим получить в извлекаемом значении
- все символы за пределами `[]` и `{}` будут вставлены в процессе форматирования, но не попадут в извлекаемое значение
В `[]` поддерживаются следующие символы:
- `0` - обязательная цифра
- `9` - опциональная цифра
- `A` - обязательная буква
- `a` - опциональная буква
- `_` - обязательная буква или цифра
- `-` - опциональная буква или цифра
- `…` - неограниченное количество цифр или букв
- если перед `…` стоит `0` или `9`, то будут ожидаться цифровые символы
- если перед `…` стоит `A` или `a`, то будут ожидаться буквенные символы
- если перед `…` стоит `_` или `-`, или не стоит ничего, то будут ожидаться буквы или цифры
### Создание маски
```kotlin
val inputMask = InputMasks.getOrCreate("+{7} ([000]) [000]-[0000]")
```
Поддерживается создание с помощью простого DSL:
```kotlin
val inputMask = InputMasks.build {
fixedChar('+', extracted = false)
fixedChar('7', extracted = true)
fixedChar(' ', extracted = false)
fixedChar('(', extracted = false)
repeat(3) { singleDigit(required = true) }
fixedChar(')', extracted = false)
fixedChar(' ', extracted = false)
repeat(3) { singleDigit(required = true) }
fixedChar('-', extracted = false)
repeat(4) { singleDigit(required = true) }
}
```
### Использование
```kotlin
val result = inputMask.format("9001234567")
result.isComplete // -> true
result.formattedValue // -> +7 (900) 123-4567
result.extractedValue // -> 79001234567
```
Обратите внимание на параметр `replacePrefix`:
```kotlin
inputMask.format("79001234567", replacePrefix = true) // -> +7 (900) 123-4567
inputMask.format("79001234567", replacePrefix = false) // -> +7 (790) 012-3456
```
### Использование в Compose
Артефакт `compose` поставляет имлементации `VisualTransformation` для `TextField` принимающих `String` или `TextFieldValue`:
```kotlin
var text by remember { mutableStateOf("") }
val mask = "[000]-[000]"
val visualTransformation = remember { InputMaskVisualTransformation(mask) }
BasicTextField(
value = text,
onValueChange = { text = visualTransformation.sanitize(it) },
visualTransformation = visualTransformation,
)
```
Специальная вариация для форматирования телефона, обрабатывающая вставку в поле ввода номера как
с кодом страны, так и без:
```kotlin
var text by remember { mutableStateOf("") }
var mask = "+{7} ([000]) [000]-[0000]"
val visualTransformation = remember(mask) { PhoneInputMaskVisualTransformation(mask) }
BasicTextField(
value = value,
onValueChange = { text = visualTransformation.sanitize(it) },
visualTransformation = visualTransformation,
)
```
Обратите внимание, что если маска может измениться в процессе ввода (например, пользователю предоставляется
возможность выбрать страну во время авторизации), то нужно также обновить значение:
```kotlin
BasicTextField(
value = remember(text, mask) { visualTransformation.sanitize(value) },
// ...
)
```
Для полей ввода, построенных вокруг `TextFieldState` есть имплементации `InputTransformation` и `OutputTransformation`:
```kotlin
val textFieldState = remember { TextFieldState() }
val mask = "[000]-[000]"
BasicTextField(
state = textFieldState,
inputTransformation = remember(mask) { InputMaskInputTransformation(mask) },
outputTransformation = remember(mask) { InputMaskOutputTransformation(mask) },
)
```
И специальная вариация `InputTransformation` для телефонных номеров:
```kotlin
BasicTextField(
// ...
inputTransformation = remember(mask) { PhoneInputMaskInputTransformation(mask) },
// ...
)
```