Tài liệu tham khảo về thuộc tính công cụ

Android Studio hỗ trợ nhiều thuộc tính XML trong không gian tên tools, cho phép bật các tính năng tại thời điểm thiết kế (chẳng hạn như bố cục để hiển thị trong một mảnh) hoặc hành vi trong thời gian biên dịch (chẳng hạn như chế độ thu nhỏ để áp dụng cho tài nguyên XML của bạn). Khi bạn tạo ứng dụng, công cụ bản dựng sẽ xoá các thuộc tính này để không làm ảnh hưởng đến kích thước APK hoặc hành vi trong thời gian chạy.

Để sử dụng các thuộc tính này, hãy thêm không gian tên tools vào thành phần gốc của mỗi tệp XML mà bạn muốn sử dụng như sau:

<RootTag xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools" >

Thuộc tính xử lý lỗi

Các thuộc tính sau đây giúp ngăn chặn thông báo cảnh báo về tìm lỗi mã nguồn:

tools:ignore

Dành cho: Mọi phần tử

Được dùng bởi: Công cụ Tìm lỗi mã nguồn

Thuộc tính này chấp nhận một danh sách được phân tách bằng dấu phẩy gồm các mã sự cố tìm lỗi mã nguồn mà bạn muốn các công cụ bỏ qua trên phần tử này hoặc bất kỳ thành phần con cháu nào.

Ví dụ: bạn có thể yêu cầu các công cụ bỏ qua lỗi MissingTranslation:

<string name="show_all_apps" tools:ignore="MissingTranslation">All</string>

tools:targetApi

Dành cho: Mọi phần tử

Được dùng bởi: Công cụ tìm lỗi mã nguồn

Thuộc tính này hoạt động giống như chú giải @TargetApi trong mã Java: cho phép bạn chỉ định cấp độ API (dưới dạng số nguyên hoặc tên mã) hỗ trợ phần tử này.

Thuộc tính này thông báo với các công cụ là bạn tin rằng phần tử này (và bất kỳ phần tử con nào) sẽ chỉ được dùng ở cấp API đã chỉ định trở lên. Điều này sẽ ngăn công cụ tìm lỗi mã nguồn gửi cảnh báo cho bạn nếu phần tử đó hoặc các thuộc tính của phần tử đó không có ở cấp API mà bạn chỉ định làm minSdkVersion.

Ví dụ: bạn có thể dùng thuộc tính này vì GridLayout chỉ có trên API cấp 14 trở lên, nhưng bạn biết rằng mã của bạn sẽ không dùng bố cục này đối với mọi phiên bản thấp hơn:

<GridLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    tools:targetApi="14" >

(Tuy nhiên, hãy lưu ý rằng bạn nên sử dụng GridLayout từ thư viện hỗ trợ.)

tools:locale

Dành cho: <resources>

Được sử dụng bởi: Công cụ tìm lỗi mã nguồn, trình chỉnh sửa Android Studio

Thuộc tính này cho các công cụ biết ngôn ngữ hoặc khu vực mặc định của các tài nguyên trong phần tử <resources> nhất định để tránh nhận cảnh báo từ trình kiểm tra lỗi chính tả. Nếu không, công cụ này sẽ giả định ngôn ngữ là tiếng Anh.

Giá trị này phải là một bộ hạn định ngôn ngữ hợp lệ.

Ví dụ: bạn có thể thêm đoạn giá trị này vào tệp values/strings.xml mặc định để cho biết ngôn ngữ dùng cho các chuỗi mặc định là tiếng Tây Ban Nha chứ không phải tiếng Anh:

<resources xmlns:tools="http://schemas.android.com/tools"
    tools:locale="es">

Thuộc tính khung hiển thị tại thời điểm thiết kế

Các thuộc tính sau đây xác định đặc điểm bố cục chỉ hiển thị trong bản xem trước bố cục của Android Studio.

tools: thay vì android:

Dành cho: <View>

Được dùng bởi: Layout Editor của Android Studio

Bạn có thể chèn dữ liệu mẫu vào bản xem trước bố cục bằng cách sử dụng tiền tố tools: thay vì android: với bất kỳ thuộc tính <View> nào từ khung Android. Điều này rất hữu ích khi giá trị của thuộc tính chưa được điền cho đến thời gian chạy và bạn muốn xem hiệu ứng trong bản xem trước bố cục.

Ví dụ: nếu đặt giá trị thuộc tính android:text tại thời gian chạy hoặc muốn xem bố cục với một giá trị khác so với giá trị mặc định, thì bạn có thể thêm tools:text để ghi rõ một số văn bản chỉ dành cho mục đích xem trước bố cục.

Bạn có thể thêm cả thuộc tính không gian tên android: (được dùng tại thời gian chạy) và thuộc tính tools: phù hợp (chỉ ghi đè thuộc tính thời gian chạy trong bản xem trước bố cục).

Bạn cũng có thể dùng thuộc tính tools: để chỉ huỷ chế độ cài đặt thuộc tính cho bản xem trước bố cục. Ví dụ: nếu bạn có FrameLayout có 2 thành phần con nhưng chỉ muốn xem 1 thành phần con trong bản xem trước bố cục, thì bạn có thể thiết lập để một trong số các thành phần con đó không hiển thị trong bản xem trước bố cục, như ví dụ dưới đây:

<Button
    android:id="@+id/button"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="First" />

<Button
    android:id="@+id/button2"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:text="Second"
    tools:visibility="invisible"  />

Khi sử dụng Layout Editor trong khung hiển thị bản thiết kế, cửa sổ Properties (Thuộc tính) sẽ cho phép bạn chỉnh sửa một số thuộc tính của khung hiển thị tại thời điểm thiết kế. Mỗi thuộc tính tại thời điểm thiết kế được biểu thị bằng biểu tượng cờ lê bên cạnh tên thuộc tính để phân biệt thuộc tính này với thuộc tính thực cùng tên.

tools:context

Dành cho: Mọi <View> gốc

Được sử dụng bởi: Công cụ tìm lỗi mã nguồn, Layout Editor của Android Studio

Thuộc tính này khai báo hoạt động nào liên kết với bố cục này theo mặc định. Điều này giúp bật các tính năng trong trình chỉnh sửa hoặc bản xem trước bố cục cần biết thông tin về hoạt động, chẳng hạn như chủ đề bố cục nào có trong bản xem trước và vị trí cần chèn trình xử lý onClick được tạo từ quá trình sửa nhanh, như trình bày trong hình 2.

Bạn có thể chỉ định tên lớp hoạt động bằng cách sử dụng cùng tiền tố dấu chấm như trong tệp kê khai (không bao gồm tên gói đầy đủ).

Ví dụ:

<android.support.constraint.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    tools:context=".MainActivity" >

tools:itemCount

Dành cho: <RecyclerView>

Được dùng bởi: Layout Editor của Android Studio

Đối với một RecyclerView nhất định, thuộc tính này quy định số lượng mục mà Layout Editor cần kết xuất trong cửa sổ Preview (Xem trước).

Ví dụ:

<androidx.recyclerview.widget.RecyclerView
    android:id="@+id/recyclerView"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:itemCount="3"/>

tools:layout

Dành cho: <fragment>

Được dùng bởi: Layout Editor của Android Studio

Thuộc tính này khai báo bố cục mà bạn muốn bản xem trước bố cục vẽ bên trong mảnh (vì bản xem trước bố cục không thể thực thi mã hoạt động thường áp dụng bố cục đó).

Ví dụ:

<fragment android:name="com.example.main.ItemListFragment"
    tools:layout="@layout/list_content" />

tools:listitem, tools:listheader, tools:listfooter

Dành cho: <AdapterView> (và các lớp con như <ListView>)

Được dùng bởi: Layout Editor của Android Studio

Các thuộc tính này chỉ định bố cục cần hiển thị trong bản xem trước bố cục cho các mục, tiêu đề và phần chân trang của danh sách. Bất kỳ trường dữ liệu nào trong bố cục đều được điền nội dung dạng số, chẳng hạn như "Mục 1" để các mục trong danh sách không lặp lại.

Ví dụ:

<ListView xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@android:id/list"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:listitem="@layout/sample_list_item"
    tools:listheader="@layout/sample_list_header"
    tools:listfooter="@layout/sample_list_footer" />

tools:showIn

Dành cho: Mọi <View> gốc trong bố cục được <include> tham chiếu

Được dùng bởi: Layout Editor của Android Studio

Thuộc tính này cho phép bạn dùng <include> để trỏ đến một bố cục sử dụng bố cục này, nhờ đó, bạn có thể xem trước và chỉnh sửa tệp này khi tệp xuất hiện trong lúc được nhúng vào bố cục mẹ.

Ví dụ:

<TextView xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:text="@string/hello_world"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    tools:showIn="@layout/activity_main" />

Giờ đây, bản xem trước bố cục hiển thị bố cục TextView này vì bố cục này xuất hiện bên trong bố cục activity_main.

tools:menu

Dành cho: Mọi <View> gốc

Được dùng bởi: Layout Editor của Android Studio

Thuộc tính này chỉ định trình đơn mà bản xem trước bố cục hiển thị trong thanh ứng dụng. Giá trị có thể là một hoặc nhiều mã trình đơn, được phân tách bằng dấu phẩy (không có @menu/ hay bất kỳ tiền tố mã nào tương tự và không có đuôi .xml).

Ví dụ:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:menu="menu1,menu2" />

tools:minValue, tools:maxValue

Dành cho: <NumberPicker>

Được dùng bởi: Layout Editor của Android Studio

Các thuộc tính này đặt giá trị tối thiểu và tối đa cho khung hiển thị NumberPicker.

Ví dụ:

<NumberPicker xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/numberPicker"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    tools:minValue="0"
    tools:maxValue="10" />

tools:openDrawer

Dành cho: <DrawerLayout>

Được dùng bởi: Layout Editor của Android Studio

Thuộc tính này cho phép bạn mở DrawerLayout trong bản xem trước.

Bạn cũng có thể sửa đổi cách Layout Editor kết xuất bố cục bằng cách truyền một trong các giá trị sau:

Bảng 1. Các giá trị có tác dụng sửa đổi cách Layout Editor kết xuất DrawerLayout

Ví dụ:

<androidx.drawerlayout.widget.DrawerLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/drawer_layout"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:openDrawer="start" />

Các tài nguyên "@tools:sample/*"

Dành cho: Mọi khung hiển thị hỗ trợ hình ảnh hoặc văn bản giao diện người dùng

Được dùng bởi: Layout Editor của Android Studio

Thuộc tính này cho phép bạn chèn hình ảnh hoặc dữ liệu giữ chỗ vào khung hiển thị của mình. Ví dụ: để thử xem bố cục hoạt động như thế nào với văn bản trước khi có văn bản giao diện người dùng hoàn thiện cho ứng dụng của bạn, bạn có thể sử dụng văn bản giữ chỗ như sau:

<TextView xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    tools:text="@tools:sample/lorem" />

Bảng sau đây mô tả các loại dữ liệu giữ chỗ mà bạn có thể chèn vào bố cục:

Bảng 2. Dữ liệu giữ chỗ cho bố cục

Thuộc tính rút gọn tài nguyên

Các thuộc tính sau cho phép bạn bật tính năng kiểm tra tham chiếu nghiêm ngặt và khai báo xem cần giữ lại hay huỷ một số tài nguyên nhất định khi sử dụng tính năng rút gọn tài nguyên.

Để bật tính năng rút gọn tài nguyên, hãy thiết lập thuộc tính shrinkResources thành true trong tệp build.gradle (cùng với minifyEnabled để bật tính năng rút gọn mã).

Ví dụ:

android {
    ...
    buildTypes {
        release {
            shrinkResources true
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'),
                    'proguard-rules.pro'
        }
    }
}

android {
    ...
    buildTypes {
        getByName("release") {
            isShrinkResources = true
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android.txt"),
                "proguard-rules.pro"
            )
        }
    }
}

tools:shrinkMode

Dành cho: <resources>

Được dùng bởi: Công cụ xây dựng có tính năng rút gọn tài nguyên

Thông qua thuộc tính này, bạn có thể chỉ định xem các công cụ xây dựng có nên áp dụng những chế độ sau đây hay không:

• Chế độ an toàn: Giữ lại tất cả tài nguyên được trích dẫn rõ ràng và có thể được tham chiếu động bằng một lệnh gọi đến Resources.getIdentifier().
• Chế độ nghiêm ngặt: Chỉ giữ lại các tài nguyên được trích dẫn rõ ràng trong mã hoặc trong các tài nguyên khác.

Tuỳ chọn mặc định là sử dụng chế độ an toàn (shrinkMode="safe"). Để sử dụng chế độ nghiêm ngặt, hãy thêm shrinkMode="strict" vào thẻ <resources> như minh hoạ dưới đây:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:shrinkMode="strict" />

Khi bật chế độ nghiêm ngặt, bạn có thể phải sử dụng tools:keep để giữ lại tài nguyên đã bị xoá mà bạn thực sự cần đến, cũng như sử dụng tools:discard để xoá nhiều tài nguyên hơn nữa.

Để biết thêm thông tin, hãy xem phần Rút gọn tài nguyên của bạn.

tools:keep

Dành cho: <resources>

Được dùng bởi: Công cụ xây dựng có tính năng rút gọn tài nguyên

Khi sử dụng tính năng rút gọn tài nguyên để xoá các tài nguyên không sử dụng, thuộc tính này cho phép bạn chỉ định các tài nguyên cần giữ lại (thường là vì chúng được tham chiếu theo cách gián tiếp trong thời gian chạy, chẳng hạn như bằng cách truyền tên tài nguyên đã tạo đến Resources.getIdentifier() một cách linh động).

Để sử dụng, hãy tạo tệp XML trong thư mục tài nguyên của bạn (ví dụ: tại res/raw/keep.xml) với thẻ <resources> và chỉ định từng tài nguyên cần giữ lại trong tools:keep ở dạng danh sách được phân tách bằng dấu phẩy. Bạn có thể sử dụng ký tự dấu hoa thị làm ký tự đại diện.

Ví dụ:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@layout/used_1,@layout/used_2,@layout/*_3" />

Để biết thêm thông tin, hãy xem phần Rút gọn tài nguyên của bạn.

tools:discard

Dành cho: <resources>

Được dùng bởi: Công cụ xây dựng có tính năng rút gọn tài nguyên

Khi sử dụng tính năng rút gọn tài nguyên để loại bỏ các tài nguyên không sử dụng, thuộc tính này cho phép bạn chỉ định các tài nguyên mà bạn muốn loại bỏ theo cách thủ công (thường là do tài nguyên được tham chiếu nhưng theo một cách không ảnh hưởng đến ứng dụng của bạn hoặc vì trình bổ trợ Gradle đã suy luận sai rằng tài nguyên đó được tham chiếu).

Để sử dụng, hãy tạo tệp XML trong thư mục tài nguyên của bạn (ví dụ: tại res/raw/keep.xml) với thẻ <resources> và chỉ định từng tài nguyên cần giữ lại trong tools:discard ở dạng danh sách được phân tách bằng dấu phẩy. Bạn có thể sử dụng ký tự dấu hoa thị làm ký tự đại diện.

Ví dụ:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:discard="@layout/unused_1" />

Để biết thêm thông tin, hãy xem phần Rút gọn tài nguyên của bạn.