Kullanıcı girişini işleme

TextField, kullanıcıların metin girmesine ve değiştirmesine olanak tanır. Bu sayfada TextField uygulamasını nasıl uygulayabileceğiniz, TextField girişini nasıl biçimlendirebileceğiniz ve klavye seçenekleri ile kullanıcı girişini görsel olarak dönüştürme gibi diğer TextField seçeneklerini nasıl yapılandırabileceğiniz açıklanmaktadır.

TextField uygulamasını seçin

TextField uygulamasının iki düzeyi vardır:

  1. TextField, Materyal Tasarım uygulamasıdır. Bu uygulamayı Materyal Tasarım yönergelerine uygun olduğundan seçmenizi öneririz:
  2. BasicTextField, kullanıcıların donanım veya yazılım klavyesi aracılığıyla metni düzenlemesine olanak tanır, ancak ipucu veya yer tutucu gibi süslemeler sağlamaz.

@Composable
fun SimpleFilledTextFieldSample() {
    var text by remember { mutableStateOf("Hello") }

    TextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}

Kelimeyi içeren düzenlenebilir metin alanı

@Composable
fun SimpleOutlinedTextFieldSample() {
    var text by remember { mutableStateOf("") }

    OutlinedTextField(
        value = text,
        onValueChange = { text = it },
        label = { Text("Label") }
    )
}

Mor kenarlık ve etiketli, düzenlenebilir metin alanı.

Stil TextField

TextField ve BasicTextField, bunları özelleştirmek için birçok ortak parametreye sahiptir. TextField öğesinin tam listesini TextField kaynak kodunda bulabilirsiniz. Bu, yararlı parametrelerden bazılarının kapsamlı olmayan bir listesidir:

  • singleLine
  • maxLines
  • textStyle

@Composable
fun StyledTextField() {
    var value by remember { mutableStateOf("Hello\nWorld\nInvisible") }

    TextField(
        value = value,
        onValueChange = { value = it },
        label = { Text("Enter text") },
        maxLines = 2,
        textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
        modifier = Modifier.padding(20.dp)
    )
}

İki düzenlenebilir satır ve etikete sahip çok satırlı bir TextField

Tasarımınız bir Material TextField veya OutlineTextField gerektirdiğinde BasicTextField yerine TextField kullanmanızı öneririz. Ancak Malzeme spesifikasyonundaki süslemelere ihtiyaç duymayan tasarımlarda BasicTextField kullanılmalıdır.

Brush API ile stil girişi

TextField cihazınızda daha gelişmiş stiller uygulamak için Fırça API'sini kullanabilirsiniz. Aşağıdaki bölümde, TextField girişine renkli bir renk geçişi eklemek için Fırçayı nasıl kullanabileceğiniz açıklanmaktadır.

Metin biçimlendirmek için Brush API'yi kullanma hakkında daha fazla bilgi için Brush API ile gelişmiş stili etkinleştirme bölümüne bakın.

TextStyle kullanarak renkli renk geçişleri uygulayın

TextField içinde yazarken renkli bir gradyan uygulamak için seçtiğiniz fırçayı TextField öğeniz için TextStyle olarak ayarlayın. Bu örnekte, TextField içine metin yazılırken gökkuşağı gradyanı efektini görüntülemek için linearGradient özelliğine sahip yerleşik bir fırça kullanıyoruz.

var text by remember { mutableStateOf("") }
val brush = remember {
    Brush.linearGradient(
        colors = rainbowColors
    )
}
TextField(
    value = text, onValueChange = { text = it }, textStyle = TextStyle(brush = brush)
)

Yalnızca bir metin parçasını özelleştirmek için buildAnnotatedString ve SpanStyle ile doğrusalGradient kullanılıyor.
Şekil 3. Yalnızca bir metin parçasını özelleştirmek için buildAnnotatedString ve SpanStyle ile linearGradient birlikte kullanılıyor.

Klavye seçeneklerini ayarlama

TextField, klavye düzeni gibi klavye yapılandırma seçeneklerini ayarlamanıza veya klavye tarafından destekleniyorsa otomatik düzeltmeyi etkinleştirmenize olanak tanır. Yazılım klavyesi burada belirtilen seçeneklere uymuyorsa bazı seçenekler garanti edilemeyebilir. Desteklenen klavye seçeneklerinin listesini burada bulabilirsiniz:

  • capitalization
  • autoCorrect
  • keyboardType
  • imeAction

Biçim girişi

TextField, giriş değerine VisualTransformation belirlemenize olanak tanır. Örneğin, şifreler için * karakterlerini değiştirebilir veya kredi kartı numarası için 4 hanede bir kısa çizgi girebilirsiniz:

@Composable
fun PasswordTextField() {
    var password by rememberSaveable { mutableStateOf("") }

    TextField(
        value = password,
        onValueChange = { password = it },
        label = { Text("Enter password") },
        visualTransformation = PasswordVisualTransformation(),
        keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password)
    )
}

Maskelenen bir şifre metni giriş alanı

VisualTransformationSamples kaynak kodunda daha fazla örnek bulabilirsiniz.

Girişi temizle

Metin düzenlenirken sık yapılan bir görev, baştaki karakterleri çıkarmak veya her değiştiğinde giriş dizesini başka bir şekilde dönüştürmektir.

Model olarak, klavyenin her bir onValueChange içinde rastgele ve büyük düzenlemeler yapabileceğini varsaymanız gerekir. Örneğin, kullanıcı otomatik düzeltme özelliğini kullandığında, bir kelimeyi emojiyle değiştirdiğinde veya başka akıllı düzenleme özellikleri kullandığında bu durum yaşanabilir. Bu işlemi doğru şekilde yapmak için onValueChange bölümüne iletilen mevcut metnin, onValueChange bölümüne geçirilecek önceki veya sonraki değerlerle ilişkisi olmadığını varsayarak dönüşüm mantığı yazın.

Baştaki sıfırlara izin vermeyen bir metin alanı uygulamak için bunu her değer değişikliğinde baştaki tüm sıfırları çıkararak yapabilirsiniz.

@Composable
fun NoLeadingZeroes() {
    var input by rememberSaveable { mutableStateOf("") }
    TextField(
        value = input,
        onValueChange = { newText ->
            input = newText.trimStart { it == '0' }
        }
    )
}

Metni temizlerken imleç konumunu kontrol etmek için durum kapsamında TextField TextFieldValue aşırı yüklemesini kullanın.

Eyalet ile ilgili en iyi uygulamalar

Aşağıda, uygulamanızdaki giriş sorunlarını önlemek için TextField durumunu tanımlayıp güncellemekle ilgili bir dizi en iyi uygulama bulunmaktadır.

  • TextField durumunu temsil etmek için MutableState kullanın: TextField durumunu temsil etmek için StateFlow gibi reaktif akışlar kullanmaktan kaçının. Aksi takdirde bu yapılar eşzamansız gecikmelere neden olabilir.

class SignUpViewModel : ViewModel() {

    var username by mutableStateOf("")
        private set

    /* ... */
}

  • Durumu güncellerken gecikmeyi önleyin: onValueChange öğesini çağırdığınızda TextField öğenizi eşzamanlı olarak ve hemen güncelleyin:

// SignUpViewModel.kt

class SignUpViewModel(private val userRepository: UserRepository) : ViewModel() {

    var username by mutableStateOf("")
        private set

    fun updateUsername(input: String) {
        username = input
    }
}

// SignUpScreen.kt

@Composable
fun SignUpScreen(/*...*/) {

    OutlinedTextField(
        value = viewModel.username,
        onValueChange = { username -> viewModel.updateUsername(username) }
        /*...*/
    )
}

  • Eyalet nerede tanımlanır: TextField eyaletiniz, siz yazarken işletme mantığı doğrulaması gerektiriyorsa durumu ViewModel öğesine eklemeniz doğrudur. Aksi takdirde, bilgi kaynağı olarak composable'ları veya eyalet sahipleri sınıfını kullanabilirsiniz. Eyaletinizi nereye kaldıracağınız hakkında daha fazla bilgi edinmek için eyalet kaldırma belgelerini inceleyin.