Metin alanlarını yapılandırma

TextField, kullanıcıların metin girmesine ve değiştirmesine olanak tanır. Kullanabileceğiniz iki tür metin alanı vardır: duruma dayalı metin alanları ve değere dayalı metin alanları. İçerik göstermek istediğiniz türü seçin:

TextField durumunu yönetmek için daha eksiksiz ve güvenilir bir yaklaşım sunduğundan duruma dayalı metin alanları kullanmanızı öneririz. Aşağıdaki tabloda, bu tür metin alanları arasındaki farklar özetlenmekte ve eyalet tabanlı metin alanlarının sunduğu temel avantajlar yer almaktadır:

Özellik

Değere dayalı metin alanları

Eyalete dayalı metin alanları

Eyalet bazlı avantaj

Durum yönetimi

onValueChange geri çağırma işleviyle metin alanı durumunu günceller. onValueChange tarafından bildirilen değişikliklere göre kendi eyaletinizdeki value bilgisini güncellemek sizin sorumluluğunuzdadır.

Metin girişi durumunu (değer, seçim ve kompozisyon) yönetmek için açıkça bir TextFieldState nesnesi kullanır. Bu durum hatırlanabilir ve paylaşılabilir.
  • onValueChange geri çağırma işlevi kaldırıldı. Bu nedenle, eşzamansız davranışlar uygulayamazsınız.
  • Durum, yeniden oluşturma, yapılandırma ve işlem sonlandırma işlemlerinden sonra da korunur.

Görsel dönüştürme

Gösterilen metnin görünümünü değiştirmek için VisualTransformation kullanılır. Bu işlev genellikle hem giriş hem de çıkış biçimlendirmesini tek bir adımda gerçekleştirir.

Kullanıcının girişi duruma işlenmeden önce değiştirmek için InputTransformation, temel durum verilerini değiştirmeden metin alanı içeriğini biçimlendirmek için OutputTransformation kullanılır.
  • Artık orijinal ham metin ile dönüştürülmüş metin arasındaki OutputTransformation ile ofset eşlemesini sağlamanız gerekmiyor.

Satır sınırları

Satır sayısını kontrol etmek için singleLine: Boolean, maxLines: Int ve minLines: Int değerlerini kabul eder.

Metin alanının kaplayabileceği minimum ve maksimum satır sayısını yapılandırmak için lineLimits: TextFieldLineLimits kullanılır.
  • TextFieldLineLimits türünde bir lineLimits parametresi sağlayarak satır sınırlarını yapılandırırken belirsizliği ortadan kaldırır.

Güvenli metin alanı

Yok

SecureTextField, şifre alanı yazmak için duruma dayalı metin alanlarının üzerine oluşturulmuş bir composable'dır.
  • Arka planda güvenlik için optimizasyon yapmanıza olanak tanır ve textObfuscationMode ile önceden tanımlanmış bir kullanıcı arayüzü içerir.

Bu sayfada, TextField nasıl uygulanacağı, TextField girişinin nasıl stillendirileceği ve klavye seçenekleri ile kullanıcı girişini görsel olarak dönüştürme gibi diğer TextField seçeneklerinin nasıl yapılandırılacağı açıklanmaktadır.

TextField uygulamasını seçin

İki TextField uygulama düzeyi vardır:

  1. TextField, Materyal Tasarım uygulamasıdır. Materyal Tasarım yönergelerine uygun olduğu için bu uygulamayı seçmenizi öneririz:
    • Varsayılan stil dolu'dur.
    • OutlinedTextField, ana hatlı stil sürümüdür.
  2. BasicTextField, kullanıcıların metni donanım veya yazılım klavyesini kullanarak düzenlemesine olanak tanır ancak ipucu veya yer tutucu gibi süslemeler sağlamaz.

TextField(
    state = rememberTextFieldState(initialText = "Hello"),
    label = { Text("Label") }
)

Kelimeyi içeren düzenlenebilir bir metin alanı 

OutlinedTextField(
    state = rememberTextFieldState(),
    label = { Text("Label") }
)

Mor kenarlıklı ve etiketli düzenlenebilir metin alanı.

Stil TextField

TextField ve BasicTextField, özelleştirme için birçok ortak parametreye sahiptir. TextField için tam liste, TextFieldkaynak kodunda mevcuttur. Aşağıda, bazı yararlı parametrelerin olası her örneğe yer vermeyen bir listesi verilmiştir:

  • textStyle
  • lineLimits

TextField(
    state = rememberTextFieldState("Hello\nWorld\nInvisible"),
    lineLimits = TextFieldLineLimits.MultiLine(maxHeightInLines = 2),
    placeholder = { Text("") },
    textStyle = TextStyle(color = Color.Blue, fontWeight = FontWeight.Bold),
    label = { Text("Enter text") },
    modifier = Modifier.padding(20.dp)
)

İki düzenlenebilir satır ve etiketi içeren çok satırlı bir TextField

Tasarımınızda Material TextField veya OutlinedTextField kullanılması gerektiğinde BasicTextField yerine TextField kullanmanızı öneririz. Ancak BasicTextField, Material spesifikasyonundaki süslemelere ihtiyaç duymayan tasarımlar oluşturulurken kullanılmalıdır.

Brush API ile giriş stilini belirleme

TextField öğenizde daha gelişmiş stil oluşturmak için Brush API'yi kullanabilirsiniz. Aşağıdaki bölümde, TextField girişine renkli bir gradyan eklemek için fırçayı nasıl kullanabileceğiniz açıklanmaktadır.

Metinleri stilize etmek için Brush API'yi kullanma hakkında daha fazla bilgi edinmek için Enable advanced styling with Brush API (Brush API ile gelişmiş stil oluşturmayı etkinleştirme) başlıklı makaleyi inceleyin.

TextStyle kullanarak renkli gradyanlar uygulama

TextField içinde yazarken renkli bir gradyan uygulamak için fırçanızı TextField için TextStyle olarak ayarlayın. Bu örnekte, TextField alanına metin girilirken gökkuşağı gradyan efektini görmek için linearGradient ile yerleşik bir fırça kullanıyoruz.

val brush = remember {
    Brush.linearGradient(
        colors = listOf(Color.Red, Color.Yellow, Color.Green, Color.Blue, Color.Magenta)
    )
}
TextField(
    state = rememberTextFieldState(), textStyle = TextStyle(brush = brush)
)

Metin alanına yazılan ve gökkuşağı gradyanı efekti gösteren metin.
Şekil 1. TextField içerikleri için gökkuşağı renk geçişi efekti.

Metin alanı durumunu yönetme

TextField, içeriği ve seçimi için TextFieldState adlı özel bir durum bilgisi depolayıcı sınıf kullanır. TextFieldState, mimarinize uygun olan her yerde kullanılacak şekilde tasarlanmıştır. TextFieldState tarafından sağlanan 2 temel özellik vardır:

  • initialText: TextField içeriği.
  • initialSelection: İmlecin veya seçimin nerede olduğunu gösterir.

TextFieldState'yı onValueChange geri çağırma gibi diğer yaklaşımlardan ayıran özellik, TextFieldState'nın giriş akışının tamamını kapsıyor olmasıdır. Bu kapsamda, doğru destekleyici veri yapılarını kullanma, filtreleri ve biçimlendiricileri satır içi yapma ve farklı kaynaklardan gelen tüm düzenlemeleri senkronize etme yer alır.

TextField içinde durumu yükseltmek için TextFieldState() kullanabilirsiniz. Bunun için rememberTextFieldState() işlevini kullanmanızı öneririz. rememberTextFieldState(), composable'ınızda TextFieldState örneğini oluşturur, durum nesnesinin hatırlanmasını sağlar ve yerleşik kaydetme ve geri yükleme işlevleri sunar:

val usernameState = rememberTextFieldState()
TextField(
    state = usernameState,
    lineLimits = TextFieldLineLimits.SingleLine,
    placeholder = { Text("Enter Username") }
)

rememberTextFieldState boş bir parametreye sahip olabilir veya başlatma sırasında metnin değerini temsil etmek için başlangıç değeri iletilebilir. Sonraki bir yeniden oluşturma işleminde farklı bir değer iletilirse durumun değeri güncellenmez. Durumu başlatıldıktan sonra güncellemek için TextFieldState üzerinde düzenleme yöntemlerini çağırın.

TextField(
    state = rememberTextFieldState(initialText = "Username"),
    lineLimits = TextFieldLineLimits.SingleLine,
)

Metin alanının içinde Kullanıcı adı metninin göründüğü bir TextField.
Şekil 2. TextField ile "Kullanıcı adı" ilk metin olarak.

Metni TextFieldBuffer ile değiştirme

TextFieldBuffer, StringBuilder işlevine benzer şekilde düzenlenebilir bir metin kapsayıcısı görevi görür. Hem metin içeriğini hem de seçimle ilgili bilgileri içerir.

TextFieldBuffer ile TextFieldState.edit, InputTransformation.transformInput veya OutputTransformation.transformOutput gibi işlevlerde alıcı kapsamı olarak sıkça karşılaşılır. Bu işlevlerde, TextFieldBuffer gerektiği şekilde okuyabilir veya güncelleyebilirsiniz. Ardından bu değişiklikler TextFieldState'ya işlenir veya OutputTransformation durumunda oluşturma ardışık düzenine aktarılır.

Arabelleğin içeriğini değiştirmek için append, insert, replace veya delete gibi standart düzenleme işlevlerini kullanabilirsiniz. Seçim durumunu değiştirmek için selection: TextRange değişkenini doğrudan ayarlayın veya placeCursorAtEnd ya da selectAll gibi yardımcı işlevleri kullanın. Seçim, başlangıç dizininin dahil, bitiş dizininin hariç olduğu bir TextRange ile gösterilir. TextRange, (3, 3) gibi aynı başlangıç ve bitiş değerlerine sahipse hiçbir karakterin seçilmediği bir imleç konumunu ifade eder.

val phoneNumberState = rememberTextFieldState("1234567890")

TextField(
    state = phoneNumberState,
    keyboardOptions = KeyboardOptions(
        keyboardType = KeyboardType.Phone
    ),
    inputTransformation = InputTransformation.maxLength(10).then {
        if (!asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    },
    outputTransformation = OutputTransformation {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
)

TextFieldState uygulamasında metin düzenleme

Durumu doğrudan durum değişkeniniz üzerinden düzenlemenize olanak tanıyan çeşitli yöntemler vardır:

  • edit: Durum içeriklerini düzenlemenize olanak tanır ve insert, replace, append gibi yöntemleri kullanabilmeniz için TextFieldBuffer işlevleri sunar.

    // Initial textFieldState text passed in is "I love Android"
// textFieldState.text : I love Android
// textFieldState.selection: TextRange(14, 14)
textFieldState.edit { insert(14, "!") }
// textFieldState.text : I love Android!
// textFieldState.selection: TextRange(15, 15)
textFieldState.edit { replace(7, 14, "Compose") }
// textFieldState.text : I love Compose!
// textFieldState.selection: TextRange(15, 15)
textFieldState.edit { append("!!!") }
// textFieldState.text : I love Compose!!!!
// textFieldState.selection: TextRange(18, 18)
textFieldState.edit { selectAll() }
// textFieldState.text : I love Compose!!!!
// textFieldState.selection: TextRange(0, 18)

  • setTextAndPlaceCursorAtEnd: Geçerli metni temizler, verilen metinle değiştirir ve imleci sona yerleştirir.

    textFieldState.setTextAndPlaceCursorAtEnd("I really love Android")
// textFieldState.text : I really love Android
// textFieldState.selection : TextRange(21, 21)

  • clearText: Tüm metinleri temizler.

    textFieldState.clearText()
// textFieldState.text :
// textFieldState.selection : TextRange(0, 0)

Diğer TextFieldState işlevleri için TextFieldState referansına bakın.

Kullanıcı girişini değiştirme

Aşağıdaki bölümlerde, kullanıcı girişinin nasıl değiştirileceği açıklanmaktadır. Giriş dönüştürme, kullanıcı yazarken TextField girişini filtrelemenize olanak tanır. Çıkış dönüştürme ise kullanıcı girişini ekranda gösterilmeden önce biçimlendirir.

Giriş dönüşümleriyle kullanıcı girişini filtreleme

Giriş dönüşümü, kullanıcıdan gelen girişi filtrelemenizi sağlar. Örneğin, TextField işleviniz ABD telefon numarası alıyorsa yalnızca 10 haneli numaraları kabul etmek istersiniz. InputTransformation sonuçları TextFieldState dosyasına kaydedilir.

Yaygın InputTransformation kullanım alanları için yerleşik filtreler vardır. Uzunluğu sınırlamak için InputTransformation.maxLength() numaralı telefonu arayın:

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine,
    inputTransformation = InputTransformation.maxLength(10)
)

Özel giriş dönüşümleri

InputTransformation, tek işlevli bir arayüzdür. Özel InputTransformation uygularken TextFieldBuffer.transformInput geçersiz kılmanız gerekir:

class CustomInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
    }
}

Telefon numarası için TextField alanına yalnızca rakam girilmesine izin veren özel bir giriş dönüşümü ekleyin:

class DigitOnlyInputTransformation : InputTransformation {
    override fun TextFieldBuffer.transformInput() {
        if (!asCharSequence().isDigitsOnly()) {
            revertAllChanges()
        }
    }
}

Zincir girişi dönüşümleri

Metin girişinize birden fazla filtre eklemek için then uzantı işlevini kullanarak InputTransformation'ları zincirleyin. Filtreler sırayla yürütülür. En iyi uygulama olarak, nihayetinde filtrelenecek verilerde gereksiz dönüşümleri önlemek için en seçici filtreleri önce uygulayın.

TextField(
    state = rememberTextFieldState(),
    inputTransformation = InputTransformation.maxLength(6)
        .then(CustomInputTransformation()),
)

Giriş dönüşümleri eklendikten sonra TextField girişi en fazla 10 basamaklı olabilir.

Girişi gösterilmeden önce biçimlendirme

OutputTransformation, kullanıcı girişini ekranda oluşturulmadan önce biçimlendirmenize olanak tanır. InputTransformation'dan farklı olarak, OutputTransformation aracılığıyla yapılan biçimlendirme TextFieldState'a kaydedilmez. Önceki telefon numarası örneğinden yola çıkarak parantez ve tireleri uygun yerlere eklemeniz gerekir:

Parantez, tire ve ilgili indekslerle uygun şekilde biçimlendirilmiş bir ABD telefon numarası.
Şekil 3. Uygun biçimlendirmeye ve karşılık gelen dizinlere sahip bir ABD telefon numarası.

Bu, değer tabanlı TextField VisualTransformations'nin işlenmesiyle ilgili güncellenmiş yöntemdir. En önemli fark, ofset eşlemelerini hesaplamanız gerekmemesidir.

OutputTransformation, tek bir soyut yöntem arayüzüdür. Özel bir OutputTransformation uygulamak için transformOutput yöntemini geçersiz kılmanız gerekir:

class CustomOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
    }
}

Telefon numarasını biçimlendirmek için OutputTransformation öğenize 0. dizinde açma parantezi, 4. dizinde kapatma parantezi ve 8. dizinde tire ekleyin:

class PhoneNumberOutputTransformation : OutputTransformation {
    override fun TextFieldBuffer.transformOutput() {
        if (length > 0) insert(0, "(")
        if (length > 4) insert(4, ")")
        if (length > 8) insert(8, "-")
    }
}

Ardından, OutputTransformation cihazınızı TextField cihazına ekleyin:

TextField(
    state = rememberTextFieldState(),
    outputTransformation = PhoneNumberOutputTransformation()
)

Dönüşümlerin birlikte işleyiş şekli

Aşağıdaki diyagramda, metin girişinden dönüşüme ve çıkışa kadar olan akış gösterilmektedir:

Metin girişinin, metin çıkışına dönüşmeden önce geçirdiği dönüşümlerin görselleştirilmesi.
Şekil 4. Metin girişinin, metin çıkışına dönüşmeden önce nasıl dönüştürüldüğünü gösteren bir diyagram.
  1. Giriş, giriş kaynağından alınır.
  2. Giriş, TextFieldState'te kaydedilen bir InputTransformation aracılığıyla filtrelenir.
  3. Giriş, biçimlendirme için OutputTransformation'dan geçirilir.
  4. Giriş, TextField içinde sunulur.

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 edilmeyebilir. Desteklenen klavye seçeneklerinin listesini aşağıda bulabilirsiniz:

  • capitalization
  • autoCorrect
  • keyboardType
  • imeAction

Ek kaynaklar