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ı. İçeriğini görüntülemek 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ını kullanmanızı öneririz. Aşağıdaki tabloda, bu metin alanı türleri arasındaki farklar ve duruma dayalı metin alanlarının sunduğu temel avantajlar açıklanmaktadı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 değerini güncellemek sizin sorumluluğunuzdadır.

Metin girişi durumunu (değer, seçim ve oluşturma) 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 ekleyemezsiniz.
  • Durum; yeniden oluşturma, yapılandırma ve işlem sonlandırma işlemlerinden etkilenmez.

Görsel dönüşüm

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

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

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ı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ı ü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üyle birlikte sunulur.

Bu sayfada, TextField öğesini nasıl uygulayabileceğiniz, TextField girişine nasıl stil verebileceğ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

İki TextField uygulama düzeyi vardır:

  1. TextField, Materyal Tasarım uygulamasıdır. Materyal Tasarım kurallarına uygun olduğu için bu uygulamayı seçmenizi öneririz:
  2. BasicTextField, kullanıcıların donanım veya yazılım klavyesini kullanarak metin 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 metin alanı 

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

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

Stil TextField

TextField ve BasicTextField, özelleştirme için birçok ortak parametre paylaşır. TextField için tam liste TextField kaynak kodunda bulunabilir. Aşağıda, yararlı parametrelerden bazılarının 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 etiket içeren çok satırlı TextField

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

Brush API ile stil girişi

TextField uygulamanızda daha gelişmiş stiller 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.

Metinlere stil uygulamak için Brush API'yi kullanma hakkında daha fazla bilgi edinmek isterseniz 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 seçtiğiniz fırçayı TextField için TextStyle olarak ayarlayın. Bu örnekte, metin TextField alanına yazılırken gökkuşağı gradyan efektini görüntülemek için linearGradient içeren 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 metinde gökkuşağı gradyan efekti gösteriliyor.
Şekil 1. TextField içerikleri için gökkuşağı gradyan 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ılabilecek şekilde tasarlanmıştır. TextFieldState tarafından sağlanan 2 ana özellik vardır:

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

TextFieldState, onValueChange geri çağırma gibi diğer yaklaşımlardan farklı olarak TextFieldState tüm giriş akışını tamamen kapsar. Bu, doğru destekleyici veri yapılarını kullanmayı, filtreleri ve biçimlendiricileri satır içine almayı ve farklı kaynaklardan gelen tüm düzenlemeleri senkronize etmeyi içerir.

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ırlandığından emin olur ve yerleşik kaydetme ve geri yükleme işlevi sağlar:

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 iletilen bir başlangıç değerine sahip olabilir. 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ında "Kullanıcı adı" metninin göründüğü bir TextField.
Şekil 2. TextField (başlangıç metni "Kullanıcı adı" olarak ayarlanmış).

TextFieldBuffer ile metni değiştirme

TextFieldBuffer, StringBuilder ile benzer işleve sahip, düzenlenebilir bir metin kapsayıcısıdır. Bu nesne, hem metin içeriğini hem de seçimle ilgili bilgileri barındırır.

TextFieldBuffer, genellikle TextFieldState.edit, InputTransformation.transformInput veya OutputTransformation.transformOutput gibi işlevlerde alıcı kapsamı olarak kullanılır. Bu işlevlerde, TextFieldBuffer değerini gerektiği gibi okuyabilir veya güncelleyebilirsiniz. Ardından bu değişiklikler TextFieldState için uygulanır veya OutputTransformation için 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çimin kendisi, başlangıç dizininin dahil ve bitiş dizininin hariç olduğu bir TextRange ile temsil edilir. Başlangıç ve bitiş değerleri aynı olan bir TextRange (ör. (3, 3)), karakter seçilmemiş bir imleç konumunu belirtir.

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 metni düzenleme

Durumu doğrudan durum değişkeniniz aracılığıyla düzenlemenize olanak tanıyan birkaç yöntem vardır:

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

    // 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: Mevcut metni temizler, verilen metinle değiştirir ve imleci sona getirir.

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

  • clearText: Tüm metni 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üşümü, kullanıcı yazarken TextField girişini filtrelemenize olanak tanır. Çıkış dönüşümü 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 filtrelemenize olanak tanır. Örneğin, TextField bir Amerikan 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() yöntemini çağırı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 öğesini 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ş dönüşümleri

Metin girişinize birden fazla filtre eklemek için then uzantı işlevini kullanarak InputTransformation'leri zincirleyin. Filtreler sırayla uygulanır. En iyi uygulama olarak, en seçici filtreleri önce uygulayarak sonuçta filtrelenecek veriler üzerinde gereksiz dönüşümler yapılmasını önleyin.

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

Giriş dönüşümleri eklendikten sonra TextField girişi en fazla 10 basamak kabul eder.

Girişi görüntülenmeden önce biçimlendirme

OutputTransformation, kullanıcı girişini ekranda oluşturulmadan önce biçimlendirmenize olanak tanır. InputTransformation aracının aksine, OutputTransformation aracılığıyla yapılan biçimlendirme TextFieldState aracına kaydedilmez. Önceki telefon numarası örneğini temel alarak, uygun yerlere parantez ve tire eklemeniz gerekir:

Parantez, kısa çizgi ve ilgili dizinlerle doğru şekilde biçimlendirilmiş bir ABD telefon numarası.
Şekil 3. Doğru biçimlendirmeye ve ilgili dizinlere sahip bir ABD telefon numarası.

Bu, değere dayalı TextField'lerde VisualTransformation'leri işlemenin güncellenmiş yöntemidir. Temel 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() {
    }
}

Bir telefon numarasını biçimlendirmek için OutputTransformation değişkeninize 0 dizinine bir açma parantezi, 4 dizinine bir kapatma parantezi ve 8 dizinine bir 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 uygulamasına ekleyin:

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

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

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

Metin girişinin metin çıkışına dönüşmeden önce nasıl dönüşümlerden geçtiğini gösteren bir görselleştirme.
Şekil 4. Metin girişinin metin çıkışına dönüşmeden önce nasıl dönüşümlerden geçtiğini gösteren bir diyagram.
  1. Giriş, giriş kaynağından alınır.
  2. Giriş, TextFieldState'e kaydedilen bir InputTransformation aracılığıyla filtrelenir.
  3. Giriş, biçimlendirme için bir OutputTransformation üzerinden 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 sunulan seçeneklere uymuyorsa bazı seçenekler garanti edilemeyebilir. Desteklenen klavye seçeneklerinin listesini aşağıda bulabilirsiniz:

  • capitalization
  • autoCorrect
  • keyboardType
  • imeAction

Ek kaynaklar