מסמך עזר בנושא מאפייני כלים (תצוגות)

מושגים והטמעה של Jetpack Compose

‫Android Studio תומך במגוון מאפייני XML במרחב השמות tools שמאפשרים תכונות בזמן התכנון, כמו הפריסה שתוצג בקטע, או התנהגויות בזמן הקימפול, כמו מצב הכיווץ שיוחל על משאבי ה-XML. כשאתם יוצרים את האפליקציה, כלי ה-build מסירים את המאפיינים האלה כדי שלא תהיה להם השפעה על גודל ה-APK או על ההתנהגות בזמן הריצה.

כדי להשתמש במאפיינים האלה, מוסיפים את מרחב השמות tools לרכיב הבסיס של כל קובץ XML שבו רוצים להשתמש בהם, כמו שמוצג כאן:

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

מאפיינים לטיפול בשגיאות

המאפיין הבא עוזר להסתיר הודעות אזהרה של Lint:

tools:targetApi

מיועד ל: כל רכיב

בשימוש על ידי: Lint

המאפיין הזה פועל כמו ההערה @TargetApi בקוד Java. הוא מאפשר לציין את רמת ה-API (כמספר שלם או כשם קוד) שתומכת ברכיב הזה.

כך הכלים יודעים שאתם חושבים שהרכיב הזה וכל הצאצאים שלו משמשים רק ברמת ה-API שצוינה או ברמה גבוהה יותר. כך, כלי ה-lint לא יציג אזהרה אם הרכיב או המאפיינים שלו לא זמינים ברמת ה-API שציינתם בתור minSdkVersion.

לדוגמה, יכול להיות שתשתמשו במאפיין הזה כי GridLayout זמין רק ברמת API‏ 14 ומעלה, אבל אתם יודעים שהפריסה הזו לא משמשת בקוד שלכם בגרסאות קודמות:

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

(עם זאת, מומלץ להשתמש ב-GridLayout מספריית התמיכה).

מאפייני תצוגה בזמן העיצוב

המאפיינים הבאים מגדירים מאפייני פריסה שגלויים רק בתצוגה המקדימה של הפריסה ב-Android Studio.

tools: במקום android:

מיועד ל: <View>

בשימוש על ידי: עורך הפריסה של Android Studio

אתם יכולים להוסיף נתונים לדוגמה בתצוגה המקדימה של הפריסה באמצעות הקידומת tools: במקום android: עם כל מאפיין <View> ממסגרת Android. האפשרות הזו שימושית כשערך המאפיין לא מאוכלס עד לזמן הריצה, ואתם רוצים לראות את ההשפעה בתצוגה המקדימה של הפריסה.

לדוגמה, אם ערך המאפיין android:text מוגדר בזמן הריצה, או אם רוצים לראות את הפריסה עם ערך שונה מברירת המחדל, אפשר להוסיף את tools:text כדי לציין טקסט כלשהו לתצוגה המקדימה של הפריסה בלבד.

המאפיין tools:text מגדיר את Google Voice כערך של התצוגה המקדימה של הפריסה
תרשים 1. המאפיין tools:text מגדיר את "Google Voice" כערך של התצוגה המקדימה של הפריסה.

אפשר להוסיף גם את מאפיין מרחב השמות android:, שמשמש בזמן הריצה, וגם את המאפיין התואם tools:, שמחליף את המאפיין של זמן הריצה בתצוגה המקדימה של הפריסה בלבד.

אפשר גם להשתמש במאפיין tools: כדי לבטל הגדרת מאפיין בתצוגה המקדימה של הפריסה בלבד. לדוגמה, אם יש לכם FrameLayout עם שני רכיבי צאצא, אבל אתם רוצים לראות רק אחד מהם בתצוגה המקדימה של הפריסה, אתם יכולים להגדיר שאחד מהם לא יהיה גלוי בתצוגה המקדימה של הפריסה, כמו שמוצג כאן:

<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"  />

כשמשתמשים ב-Layout Editor בתצוגת עיצוב, החלון Properties מאפשר לערוך חלק ממאפייני התצוגה בזמן העיצוב. כל מאפיין של זמן עיצוב מסומן בסמל של מפתח ברגים סמל מפתח הברגים
לצד שם המאפיין, כדי להבדיל אותו מהמאפיין האמיתי עם אותו שם.

tools:context

מיועד ל: כל שורש <View>

בשימוש על ידי: Lint,‏ Android Studio Layout Editor

המאפיין הזה מצהיר לאיזו פעילות הפריסה הזו משויכת כברירת מחדל. כך אפשר להפעיל תכונות בעורך או בתצוגה המקדימה של הפריסה שדורשות ידע על הפעילות, כמו העיצוב של הפריסה בתצוגה המקדימה ואיפה להוסיף רכיבי handler של onClick שנוצרו מתיקון מהיר, כמו שמוצג באיור 2.

התיקון המהיר של המאפיין onClick פועל רק אם הגדרתם את tools:context
איור 2. התיקון המהיר של המאפיין onClick פועל רק אם הגדרת את tools:context.

אפשר לציין את שם המחלקה של הפעילות באמצעות אותה קידומת נקודה כמו בקובץ המניפסט (לא כולל שם החבילה המלא).

לדוגמה:

<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

מיועד ל: <RecyclerView>

בשימוש על ידי: Android Studio Layout Editor

עבור RecyclerView נתון, המאפיין הזה מציין את מספר הפריטים ש-Layout Editor צריך לעבד בחלון Preview.

לדוגמה:

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

tools:layout

מיועד ל: <fragment>

בשימוש על ידי: Layout Editor ב-Android Studio

המאפיין הזה מצהיר על הפריסה שאתם רוצים שהתצוגה המקדימה של הפריסה תשרטט בתוך הפרגמנט, כי התצוגה המקדימה של הפריסה לא יכולה להריץ את קוד הפעילות שבדרך כלל מחיל את הפריסה.

לדוגמה:

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

tools:listitem, tools:listheader, tools:listfooter

מיועד ל: <AdapterView> (ומחלקות משנה כמו <ListView>)

בשימוש על ידי: Layout Editor ב-Android Studio

המאפיינים האלה מציינים איזו פריסה להציג בתצוגה המקדימה של הפריסה לפריטים, לכותרת העליונה ולכותרת התחתונה של הרשימה. כל שדות הנתונים בפריסה מלאים בתוכן מספרי, כמו "פריט 1", כדי שהפריטים ברשימה לא יחזרו על עצמם.

לדוגמה:

<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

מיועד ל: כל רכיב <View> ברמה הבסיסית בפריסה שאליו מפנה רכיב <include>

בשימוש על ידי: Layout Editor ב-Android Studio

המאפיין הזה מאפשר להפנות לפריסה שמשתמשת בפריסה הזו באמצעות <include>, כדי שתוכלו לראות תצוגה מקדימה של הקובץ ולערוך אותו כפי שהוא מופיע כשהוא מוטמע בפריסת האם שלו.

לדוגמה:

<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" />

עכשיו בתצוגה המקדימה של הפריסה מוצגת הפריסה TextView כפי שהיא מופיעה בתוך הפריסה activity_main.

tools:menu

מיועד ל: כל שורש <View>

בשימוש על ידי: Layout Editor ב-Android Studio

המאפיין הזה מציין איזה תפריט מוצג בתצוגה המקדימה של הפריסה בסרגל האפליקציה. הערך הוא מזהה תפריט אחד או יותר, מופרדים בפסיקים, בלי @menu/ או כל קידומת מזהה אחרת ובלי הסיומת .xml.

לדוגמה:

<?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

מיועד ל: <NumberPicker>

בשימוש על ידי: Layout Editor ב-Android Studio

המאפיינים האלה מגדירים את ערכי המינימום והמקסימום של תצוגת NumberPicker.

לדוגמה:

<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

מיועד ל: <DrawerLayout>

בשימוש על ידי: Layout Editor ב-Android Studio

המאפיין הזה מאפשר לפתוח DrawerLayout בתצוגה המקדימה.

אפשר גם לשנות את האופן שבו Layout Editor מעבד את הפריסה על ידי העברת אחד מהערכים הבאים:

טבלה 1. ערכים לשינוי האופן שבו Layout Editor מעבד DrawerLayout

קבועערךתיאור
end800005העברת האובייקט לסוף הקונטיינר שלו, בלי לשנות את הגודל שלו.
left3דחיפת האובייקט לצד שמאל של המאגר שלו, בלי לשנות את הגודל שלו.
right5דחיפת האובייקט לצד שמאל של הקונטיינר שלו, בלי לשנות את הגודל שלו.
start800003העברת האובייקט לתחילת הקונטיינר שלו, בלי לשנות את הגודל שלו.

לדוגמה:

<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" />

"@tools:sample/*" משאבים

מיועד ל: כל תצוגה שתומכת בטקסט או בתמונות בממשק המשתמש

בשימוש על ידי: Android Studio Layout Editor

המאפיין הזה מאפשר להוסיף נתונים או תמונות של פלייסהולדר לתצוגה. לדוגמה, כדי לבדוק איך הפריסה מתנהגת עם טקסט לפני שסיימתם לכתוב את הטקסט של ממשק המשתמש באפליקציה, אתם יכולים להשתמש בטקסט לדוגמה באופן הבא:

<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" />

בטבלה הבאה מתוארים סוגי הנתונים של פלייסהולדרים שאפשר להוסיף לפריסות:

טבלה 2. נתוני פלייסהולדר לפריסות

ערך מאפייןתיאור של נתוני פלייסהולדר
@tools:sample/full_names שמות מלאים שנוצרו באופן אקראי מהשילוב של @tools:sample/first_names ושל @tools:sample/last_names
@tools:sample/first_names שמות פרטיים נפוצים
@tools:sample/last_names שמות משפחה נפוצים
@tools:sample/cities שמות של ערים מרחבי העולם
@tools:sample/us_zipcodes מספרי מיקוד בארה"ב שנוצרו באופן אקראי
@tools:sample/us_phones מספרי טלפון שנוצרו באופן אקראי בפורמט הבא: (800) 555-xxxx
@tools:sample/lorem טקסט לדוגמה בלטינית
@tools:sample/date/day_of_week תאריכים ושעות אקראיים בפורמט שצוין
@tools:sample/date/ddmmyy
@tools:sample/date/mmddyy
@tools:sample/date/hhmm
@tools:sample/date/hhmmss
@tools:sample/avatars פריטים גרפיים וקטוריים שניתן לשרטט, שאפשר להשתמש בהם כאווטארים בפרופיל
@tools:sample/backgrounds/scenic תמונות שאפשר להשתמש בהן כרקעים