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.

Hat sınırlarını yapılandırma

TextField bileşenleri, tek bir eksen boyunca kaydırmayı destekler. Kaydırma davranışı, lineLimits parametresi tarafından belirlenir. Tek satır için yapılandırılan TextField'ler yatay olarak kaydırılırken çok satırlı TextField'ler dikey olarak kaydırılır.

TextField için uygun hat yapılandırmasını seçmek üzere TextFieldLineLimits kullanın:

TextField(
    state = rememberTextFieldState(),
    lineLimits = TextFieldLineLimits.SingleLine
)

"Metin" metnini içeren tek satırlık bir metin alanı

SingleLine yapılandırması aşağıdaki özelliklere sahiptir:

  • Metin hiçbir zaman kaydırılmaz ve yeni satırlara izin verilmez.
  • TextField her zaman sabit bir yüksekliğe sahiptir.
  • Metin taşarsa yatay olarak kaydırılır.

TextField(
    state = rememberTextFieldState("Hello\nWorld\nHello\nWorld"),
    lineLimits = TextFieldLineLimits.MultiLine(1, 4)
)

Metin içeren çok satırlı metin alanı

MultiLine yapılandırması aşağıdaki özelliklere sahiptir:

  • İki parametre kabul eder: minHeightInLines ve maxHeightInLines.
  • Metin alanı en az minHeightInLines yüksekliğinde.
  • Metin taşarsa kaydırılır.
  • Metin daha fazla satır gerektiriyorsa alan maxHeightInLines yüksekliğine ulaşana kadar büyür ve dikey olarak kaydırılı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

KeyboardOptions sınıfı artık TextFieldState ile entegre edilmiş TextField bileşenleri için özel olarak kullandığınız yeni bir Boole parametresi olan showKeyboardOnFocus parametresini içeriyor. Bu seçenek, TextField doğrudan kullanıcı etkileşimi dışında bir yöntemle (ör. programatik olarak) odaklandığında yazılım klavyesinin davranışını yönetir.

KeyboardOptions.showKeyboardOnFocus, true değerine ayarlandığında TextField dolaylı olarak odaklanırsa yazılım klavyesi otomatik olarak görünmez. Bu gibi durumlarda, kullanıcının klavyeyi açmak için TextField öğesine açıkça dokunması gerekir.

Klavye etkileşim mantığını tanımlama

Android'in yazılım klavyesindeki işlem düğmesi, uygulamanızda etkileşimli yanıtlar verilmesini sağlar. İşlem düğmesini yapılandırma hakkında daha fazla bilgi için Klavye seçeneklerini ayarlama bölümüne bakın.

Kırmızı daire içine alınmış bir yazılım klavyesi işlem düğmesi (onay işareti simgesi).
Şekil 5. Yazılım klavyesi işlem düğmesi.

Kullanıcı bu işlem düğmesine dokunduğunda ne olacağını tanımlamak için onKeyboardAction parametresini kullanın. Bu parametre, KeyboardActionHandler adlı isteğe bağlı bir işlevsel arayüzü kabul eder. KeyboardActionHandler arayüzü tek bir yöntem içerir: onKeyboardAction(performDefaultAction: () -> Unit). Bu onKeyboardAction yöntemi için bir uygulama sağlayarak, kullanıcı klavyenin işlem düğmesine bastığında yürütülen özel mantık ekleyebilirsiniz.

Birkaç standart klavye işlemi türü, yerleşik varsayılan davranışlarla birlikte gelir. Örneğin, işlem türü olarak ImeAction.Next veya ImeAction.Previous seçildiğinde odak, varsayılan olarak sırasıyla sonraki veya önceki giriş alanına kaydırılır. Benzer şekilde, ImeAction.Done olarak ayarlanmış bir işlem düğmesi genellikle yazılım klavyesini kapatır. Bu varsayılan işlevler otomatik olarak yürütülür ve KeyboardActionHandler sağlamanız gerekmez.

Bu varsayılan işlemlere ek olarak özel davranışlar da uygulayabilirsiniz. KeyboardActionHandler değerinizi sağladığınızda onKeyboardAction yöntemi bir performDefaultAction işlevi alır. Mevcut IME işlemiyle ilişkili standart varsayılan davranışı da tetiklemek için özel mantığınızın herhangi bir noktasında bu performDefaultAction() işlevini çağırabilirsiniz.

TextField(
    state = textFieldViewModel.usernameState,
    keyboardOptions = KeyboardOptions(imeAction = ImeAction.Next),
    onKeyboardAction = { performDefaultAction ->
        textFieldViewModel.validateUsername()
        performDefaultAction()
    }
)

Bu snippet, kullanıcı adı alanı içeren bir kayıt ekranındaki yaygın kullanım alanını gösterir. Bu alanın klavye işlem düğmesi için ImeAction.Next seçildi. Bu seçim, bir sonraki şifre alanına hızlı ve sorunsuz bir şekilde geçiş yapmanızı sağlar.

Bu standart gezinmeye ek olarak, kullanıcı şifresini girmeye devam ederken kullanıcı adı için bir arka plan doğrulama işlemi başlatılması gerekir. ImeAction.Next öğesine özgü varsayılan odak değiştirme davranışının bu özel doğrulama mantığıyla birlikte korunmasını sağlamak için performDefaultAction() işlevi çağrılır. performDefaultAction() çağrısı, temel odak yönetimi sistemini dolaylı olarak tetikleyerek odağı bir sonraki uygun kullanıcı arayüzü öğesine taşır ve beklenen gezinme akışını korur.

Güvenli şifre alanı oluşturma

SecureTextField, şifre alanı yazmak için duruma dayalı metin alanları üzerine oluşturulmuş bir composable'dır. Karakter girişini varsayılan olarak gizlediği ve kesme ve kopyalama işlemlerini devre dışı bıraktığı için şifre metin alanları oluştururken SecureTextField kullanmanızı öneririz.

SecureTextField, kullanıcının karakter girişini nasıl göreceğini kontrol eden bir textObfuscationMode içerir. textObfuscationMode aşağıdaki seçeneklere sahiptir:

  • Hidden: Tüm girişleri gizler. Masaüstü platformlarda varsayılan davranış.

    Yazılan karakterlerin gizlendiği güvenli bir metin alanı.

  • Visible: Tüm girişleri gösterir.

    Yazılan karakterlerin görünür olduğu güvenli bir metin alanı.

  • RevealLastTyped: Son karakter hariç tüm girişleri gizler. Mobil cihazlarda varsayılan davranış.

    Yalnızca son yazılan karakterin kısa bir süre gösterildiği güvenli metin alanı.

Ek kaynaklar