Sumber Daya String

Sumber daya string menyediakan string teks bagi aplikasi Anda dengan pemformatan dan penataan gaya teks opsional. Ada tiga tipe sumber daya yang bisa menyediakan string untuk aplikasi Anda:

String: Sumber daya XML yang menyediakan string tunggal.
Larik String: Sumber daya XML yang menyediakan larik string.
String Kuantitas (Jamak): Sumber daya XML yang membawa string berbeda untuk pluralisasi

Semua string mampu menerapkan beberapa argumen markup penataan gaya dan pemformatan. Untuk informasi tentang string penataan gaya dan pemformatan, lihat bagian tentang Pemformatan dan Penataan Gaya.

String

String tunggal yang bisa direferensikan dari aplikasi atau file sumber daya lain (misalnya layout XML).

Catatan: String adalah sumber daya sederhana yang direferensikan menggunakan nilai yang disediakan dalam atribut name (bukan nama file XML). Jadi, Anda bisa mengombinasikan sumber daya string dengan sumber daya sederhana lainnya dalam satu file XML, menggunakan satu elemen <resources>.

lokasi file:

res/values/filename.xml
Nama file bebas. Elemen <string> dengan name akan digunakan sebagai ID sumber daya.

jenis data sumber daya yang dikompilasi:

Penunjuk sumber daya ke String.

referensi sumber daya:

Dalam Java: R.string.string_name
Dalam XML:@string/string_name

sintaks:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string
        name="string_name"
        >text_string</string>
</resources>

elemen:

contoh berikut:

File XML yang disimpan di res/values/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Hello!</string>
</resources>

XML layout ini menerapkan string ke View:

<TextView
    android:layout_width="fill_parent"
    android:layout_height="wrap_content"
    android:text="@string/hello" />

Kode aplikasi ini mengambil sebuah string:

String string = getString(R.string.hello);

Anda bisa menggunakan getString(int) atau getText(int) untuk mengambil string. getText(int) akan mempertahankan penataan gaya teks yang kaya ke string.

Larik String

Larik string yang bisa direferensikan dari aplikasi.

Catatan: Larik string adalah sumber daya sederhana yang direferensikan menggunakan nilai yang disediakan dalam atribut name (bukan nama file XML). Dengan demikian, Anda bisa mengombinasikan sumber daya larik string dengan sumber daya sederhana lainnya dalam satu file XML, pada satu elemen <resources>.

lokasi file:

res/values/filename.xml
Nama file bebas. Elemen <string-array> dengan name akan digunakan sebagai ID sumber daya.

jenis data sumber daya yang dikompilasi:

Penunjuk sumber daya ke larik String.

referensi sumber daya:

Dalam Java: R.array.string_array_name

sintaks:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array
        name="string_array_name">
        <item
            >text_string</item>
    </string-array>
</resources>

elemen:

contoh berikut:

File XML yang disimpan di res/values/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array name="planets_array">
        <item>Mercury</item>
        <item>Venus</item>
        <item>Earth</item>
        <item>Mars</item>
    </string-array>
</resources>

Kode aplikasi ini mengambil sebuah larik string:

Resources res = getResources();
String[] planets = res.getStringArray(R.array.planets_array);

String Kuantitas (Jamak)

Bahasa yang berbeda memiliki aturan yang berbeda pula untuk kesepakatan gramatikal pada kuantitas. Dalam bahasa Inggris, misalnya, kuantitas 1 adalah kasus khusus. Kita menulis "1 book", namun untuk kuantitas lain kita akan menulis "n books". Perbedaan antara tunggal dan jamak sudah sangat umum, namun bahasa lain membuat perbedaan yang lebih tipis. Set lengkap yang didukung oleh Android adalah zero, one, two, few, many, dan other.

Aturan untuk memutuskan kasus mana yang akan digunakan untuk bahasa dan kuantitas yang diberikan boleh jadi akan sangat kompleks, jadi Android menyediakan beberapa metode seperti getQuantityString() untuk memilih sumber daya yang sesuai untuk Anda.

Walaupun secara historis disebut "string kuantitas" (dan tetap disebut demikian di API), string kuantitas hanya boleh digunakan untuk jamak. Akan salah bila menggunakan string kuantitas untuk mengimplementasikan sesuatu seperti "Inbox" versus "Inbox (12)" Gmail bila ada pesan belum dibaca, misalnya. Sepertinya mungkin praktis menggunakan string kuantitas sebagai ganti pernyataan if, namun perlu diperhatikan bahwa beberapa bahasa (seperti bahasa Cina) tidak membuat perbedaan gramatikal ini sama sekali, jadi Anda akan selalu mendapatkan string other.

Pemilihan string yang akan digunakan dilakukan semata-mata berdasarkan keperluan gramatikal. Dalam bahasa Inggris, string untuk zero akan diabaikan sekalipun kuantitasnya 0, karena 0 secara gramatikal tidak berbeda dengan 2, atau angka lain selain 1 ("zero books", "one book", "two books", dan seterusnya). Sebaliknya, dalam bahasa Korea hanya string other yang akan digunakan.

Jangan salah paham oleh fakta bahwa, misalnya, two seolah hanya bisa diterapkan pada kuantitas 2: suatu bahasa mungkin mengharuskan 2, 12, 102 (dan seterusnya) semua diperlakukan seperti satu sama lainnya namun secara berbeda untuk kuantitas lainnya. Percayakan pada penerjemah Anda untuk mengetahui perbedaan sesungguhnya dalam bahasa masing-masing.

Sering kali dimungkinkan untuk menghindari string kuantitas dengan menggunakan formulasi yang netral-kuantitas, misalnya "Books: 1". Ini akan membuat urusan Anda dan penerjemah Anda jadi lebih mudah, jika ini adalah gaya yang dipertahankan bersama aplikasi Anda.

Catatan: Kumpulan jamak adalah sumber daya sederhana yang direferensikan menggunakan nilai yang disediakan dalam atribut name (bukan nama file XML). Dengan demikian, Anda bisa mengombinasikan sumber daya jamak dengan sumber daya sederhana lainnya dalam satu file XML, pada satu elemen <resources>.

lokasi file:

res/values/filename.xml
Nama file bebas. Elemen <plurals> dengan name akan digunakan sebagai ID sumber daya.

referensi sumber daya:

Dalam Java: R.plurals.plural_name

sintaks:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <plurals
        name="plural_name">
        <item
            quantity=["zero" | "one" | "two" | "few" | "many" | "other"]
            >text_string</item>
    </plurals>
</resources>

elemen:

<resources>

Diperlukan. Ini harus berupa simpul akar.

Tidak ada atribut.

<plurals>

Kumpulan string, yang menjadi tempat menyediakan satu string, bergantung pada jumlah sesuatu. Berisi satu atau beberapa elemen <item>.

atribut:

name: String. Nama untuk pasangan string. Nama ini akan digunakan sebagai ID sumber daya.

<item>

String jamak atau tunggal. Nilai bisa berupa referensi ke sumber daya string lain. Harus berupa anak elemen <plurals>. Ketahuilah bahwa Anda harus mengurung tanda apostrof dan tanda petik. Lihat Memformat dan Menata Gaya, di bawah ini, untuk informasi tentang cara menata gaya dan memformat string Anda dengan benar.

atribut:

quantity

Kata kunci. Sebuah nilai yang menunjukkan kapan string ini harus digunakan. Nilai yang valid, dengan contoh yang belum selengkapnya dalam tanda kurung:

Nilai	Keterangan
`zero`	Bila suatu bahasa memerlukan perlakuan khusus atas bilangan 0 (seperti dalam bahasa Arab).
`one`	Bila suatu bahasa memerlukan perlakuan khusus atas bilangan seperti satu (sebagaimana dengan bilangan 1 dalam bahasa Inggris dan kebanyakan bahasa lainnya; dalam bahasa Rusia, bilangan yang diakhiri dengan 1 namun bukan diakhiri dengan 11 ada dalam kelas ini).
`two`	Bila suatu bahasa memerlukan perlakuan khusus atas bilangan seperti dua (sebagaimana dengan 2 dalam bahasa Welsh, atau 102 dalam bahasa Slovenia).
`few`	Bila suatu bahasa memerlukan perlakuan khusus atas bilangan "kecil" (sebagaimana dengan 2, 3, dan 4 dalam bahasa Cheska; atau bilangan yang berakhiran 2, 3, atau 4 namun bukan 12, 13, atau 14 dalam bahasa Polandia).
`many`	Bila suatu bahasa memerlukan perlakuan khusus atas bilangan "besar" (sebagaimana dengan bilangan yang berakhiran 11-99 dalam bahasa Malta).
`other`	Bila suatu bahasa tidak memerlukan perlakuan khusus atas kuantitas yang diberikan (sebagaimana dengan semua bilangan dalam bahasa Cina, atau 42 dalam bahasa Inggris).

contoh berikut:

File XML yang disimpan di res/values/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <plurals name="numberOfSongsAvailable">
        <!--
             As a developer, you should always supply "one" and "other"
             strings. Your translators will know which strings are actually
             needed for their language. Always include %d in "one" because
             translators will need to use %d for languages where "one"
             doesn't mean 1 (as explained above).
          -->
        <item quantity="one">%d song found.</item>
        <item quantity="other">%d songs found.</item>
    </plurals>
</resources>

File XML yang disimpan di res/values-pl/strings.xml:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <plurals name="numberOfSongsAvailable">
        <item quantity="one">Znaleziono %d piosenkę.</item>
        <item quantity="few">Znaleziono %d piosenki.</item>
        <item quantity="other">Znaleziono %d piosenek.</item>
    </plurals>
</resources>

Kode Java:

int count = getNumberOfsongsAvailable();
Resources res = getResources();
String songsFound = res.getQuantityString(R.plurals.numberOfSongsAvailable, count, count);

Saat menggunakan metode getQuantityString(), Anda perlu meneruskan count dua kali jika string berisi pemformatan string dengan angka. Misalnya, untuk string %d songs found, parameter pertama count akan memilih string jamak yang sesuai dan parameter kedua count akan dimasukkan ke dalam placeholder %d. Jika string jamak Anda tidak berisi pemformatan string, Anda tidak perlu meneruskan parameter ketiga ke getQuantityString.

Memformat dan Menata Gaya

Inilah beberapa hal penting yang harus Anda ketahui tentang cara yang benar untuk memformat dan menata gaya sumber daya string.

Mengurung tanda apostrof dan tanda kutip

Jika Anda memiliki tanda apostrof (') dalam string, Anda harus mengurungnya dengan backslash (\') atau mengurung string dalam tanda kutip ganda (""). Misalnya, inilah beberapa string yang bisa berhasil dan tidak bisa berhasil:

<string name="good_example">This\'ll work</string>
<string name="good_example_2">"This'll also work"</string>
<string name="bad_example">This doesn't work</string>
    <!-- Causes a compile error -->

Jika Anda memiliki tanda kutip ganda dalam string, Anda harus mengurungnya (\"). Mengurung string dengan tanda kutip tunggal tidak akan berhasil.

<string name="good_example">This is a \"good string\".</string>
<string name="bad_example">This is a "bad string".</string>
    <!-- Quotes are stripped; displays as: This is a bad string. -->
<string name="bad_example_2">'This is another "bad string".'</string>
    <!-- Causes a compile error -->

Memformat string

Jika Anda perlu memformat string menggunakan String.format(String, Object...), Anda bisa melakukannya dengan menempatkan argumen format dalam sumber daya string. Misalnya, dengan sumber daya berikut:

<string name="welcome_messages">Hello, %1$s! You have %2$d new messages.</string>

Dalam contoh ini, string format memiliki dua argumen: %1$s adalah string dan %2$d adalah bilangan desimal. Anda bisa memformat string dengan argumen dari aplikasi Anda seperti ini:

Resources res = getResources();
String text = String.format(res.getString(R.string.welcome_messages), username, mailCount);

Menata gaya dengan markup HTML

Anda bisa menambahkan penataan gaya ke string dengan markup HTML. Misalnya:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="welcome">Welcome to <b>Android</b>!</string>
</resources>

Elemen HTML yang didukung antara lain:

<b> untuk teks tebal.
<i> untuk teks miring.
<u> untuk teks garis bawah .

Kadang-kadang Anda mungkin ingin membuat sumber daya teks bergaya yang juga digunakan sebagai string format. Biasanya, ini tidak akan berhasil karena metode String.format(String, Object...) akan melucuti semua informasi gaya dari string. Solusinya adalah menuliskan tag HTML dengan entitas yang dikurung, yang nanti dipulihkan dengan fromHtml(String), setelah pemformatan dilakukan. Misalnya:

Simpan sumber daya teks bergaya sebagai string yang dikurung dengan HTML:
```
<resources>
  <string name="welcome_messages">Hello, %1$s! You have &lt;b>%2$d new messages&lt;/b>.</string>
</resources>
```
Dalam string yang diformat ini, elemen <b> telah ditambahkan. Perhatikan bahwa kurung buka adalah HTML yang dikurung, dengan menggunakan notasi <.

Kemudian format string tersebut seperti biasa, namun panggil juga fromHtml(String) untuk mengonversi teks HTML menjadi teks yang diberi gaya:

Resources res = getResources();
String text = String.format(res.getString(R.string.welcome_messages), username, mailCount);
CharSequence styledText = Html.fromHtml(text);

Karena metode fromHtml(String) akan memformat semua entitas HTML, pastikan mengurung semua karakter HTML yang memungkinkan dalam string yang Anda gunakan bersama teks berformat, menggunakan htmlEncode(String). Sebagai contoh, jika Anda akan meneruskan argumen string ke String.format() yang mungkin berisi karakter seperti "<" atau "&", maka harus dikurung sebelum memformat, jadi bila string berformat diteruskan melalui fromHtml(String), karakter akan luput dari maksud penulisannya semula. Misalnya:

String escapedUsername = TextUtil.htmlEncode(username);

Resources res = getResources();
String text = String.format(res.getString(R.string.welcome_messages), escapedUsername, mailCount);
CharSequence styledText = Html.fromHtml(text);

Menata Gaya dengan Spannable

Spannable adalah objek teks yang bisa Anda beri gaya dengan properti typeface seperti warna dan bobot font. Anda menggunakan SpannableStringBuilder untuk membangun teks kemudian menerapkan gaya yang didefinisikan dalam paket android.text.style ke teks.

Anda bisa menggunakan metode helper berikut untuk menyiapkan sebagian besar pekerjaan membuat teks spannable:

/**
 * Returns a CharSequence that concatenates the specified array of CharSequence
 * objects and then applies a list of zero or more tags to the entire range.
 *
 * @param content an array of character sequences to apply a style to
 * @param tags the styled span objects to apply to the content
 *        such as android.text.style.StyleSpan
 *
 */
private static CharSequence apply(CharSequence[] content, Object... tags) {
    SpannableStringBuilder text = new SpannableStringBuilder();
    openTags(text, tags);
    for (CharSequence item : content) {
        text.append(item);
    }
    closeTags(text, tags);
    return text;
}

/**
 * Iterates over an array of tags and applies them to the beginning of the specified
 * Spannable object so that future text appended to the text will have the styling
 * applied to it. Do not call this method directly.
 */
private static void openTags(Spannable text, Object[] tags) {
    for (Object tag : tags) {
        text.setSpan(tag, 0, 0, Spannable.SPAN_MARK_MARK);
    }
}

/**
 * "Closes" the specified tags on a Spannable by updating the spans to be
 * endpoint-exclusive so that future text appended to the end will not take
 * on the same styling. Do not call this method directly.
 */
private static void closeTags(Spannable text, Object[] tags) {
    int len = text.length();
    for (Object tag : tags) {
        if (len > 0) {
            text.setSpan(tag, 0, len, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE);
        } else {
            text.removeSpan(tag);
        }
    }
}

Metode bold, italic, dan color berikut ini menunjukkan cara memanggil metode helper untuk menerapkan gaya yang didefinisikan dalam paket android.text.style. Anda bisa membuat metode serupa untuk melakukan penataan gaya tipe teks lainnya.

/**
 * Returns a CharSequence that applies boldface to the concatenation
 * of the specified CharSequence objects.
 */
public static CharSequence bold(CharSequence... content) {
    return apply(content, new StyleSpan(Typeface.BOLD));
}

/**
 * Returns a CharSequence that applies italics to the concatenation
 * of the specified CharSequence objects.
 */
public static CharSequence italic(CharSequence... content) {
    return apply(content, new StyleSpan(Typeface.ITALIC));
}

/**
 * Returns a CharSequence that applies a foreground color to the
 * concatenation of the specified CharSequence objects.
 */
public static CharSequence color(int color, CharSequence... content) {
    return apply(content, new ForegroundColorSpan(color));
}

Inilah contoh cara merangkai metode ini untuk membuat urutan karakter dengan beragam tipe penataan gaya yang diterapkan pada masing-masing kata:

// Create an italic "hello, " a red "world",
// and bold the entire sequence.
CharSequence text = bold(italic(res.getString(R.string.hello)),
    color(Color.RED, res.getString(R.string.world)));