‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

יצירת כרטיסי מידע מותאמים אישית בהגדרות המהירות לאפליקציה

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

חלונית ההגדרות המהירות עם לחצן ה-VPN במצב מופעל ובמצב מושבת — **איור 1.** חלונית ההגדרות המהירות עם כפתור ה-VPN במצב מופעל וכבוי.

מתי כדאי ליצור משבצת

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

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

תרחישים לדוגמה של כרטיסי מידע באפליקציות כושר — **איור 2.** דוגמאות לכרטיסי מידע מומלצים ולא מומלצים לאפליקציית כושר.

כדי לשפר את החשיפה של המשבצת ואת נוחות השימוש בה, מומלץ להימנע משיטות מסוימות:

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

יצירת משבצת

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

הדוגמה של ההגדרות המהירות ממחישה איך ליצור ולנהל לחצן.

יצירת סמל בהתאמה אישית

צריך לספק סמל מותאם אישית שיוצג בלחצן בחלונית ההגדרות המהירות. (אתם תוסיפו את הסמל הזה כשתצהירו על TileService, כפי שמתואר בסעיף הבא). הסמל צריך להיות בצבע לבן אחיד עם רקע שקוף, בגודל 24x24dp ובפורמט VectorDrawable.

**איור 3.** דוגמה לפריט גרפי וקטורי שניתן לשרטוט.

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

יצירה והצהרה על TileService

יוצרים שירות למשבצת שמרחיב את המחלקה TileService.

class MyQSTileService : TileService() {

    // Called when the user adds your tile.
    override fun onTileAdded() {
        super.onTileAdded()
    }
    // Called when your app can update your tile.
    override fun onStartListening() {
        super.onStartListening()
    }

    // Called when your app can no longer update your tile.
    override fun onStopListening() {
        super.onStopListening()
    }

    // Called when the user taps on your tile in an active or inactive state.
    override fun onClick() {
        super.onClick()
    }
    // Called when the user removes your tile.
    override fun onTileRemoved() {
        super.onTileRemoved()
    }
}QuickSettingsTilesSnippets.kt

מצהירים על TileService בקובץ המניפסט של האפליקציה. מוסיפים את השם והתווית של TileService (עד 18 תווים ל-android:label), את הסמל המותאם אישית שיצרתם בקטע הקודם ואת ההרשאה המתאימה.

 <!-- 18-character limit for android:label. -->
 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"
     android:icon="@drawable/my_default_icon_label"
     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
     <intent-filter>
         <action android:name="android.service.quicksettings.action.QS_TILE" />
     </intent-filter>
 </service>

ניהול TileService

אחרי שיוצרים את TileService ומצהירים עליו בקובץ המניפסט של האפליקציה, צריך לנהל את המצב שלו.

‫TileService הוא שרת מאגד (bound service). ה-TileService שלך מקושר כשהאפליקציה מבקשת זאת או אם המערכת צריכה לתקשר איתו. מחזור חיים טיפוסי של שירות מאגד מכיל את ארבע שיטות הקריאה החוזרת הבאות: onCreate(),‏ onBind(),‏ onUnbind() ו-onDestroy(). המערכת מפעילה את השיטות האלה בכל פעם שהשירות נכנס לשלב חדש במחזור החיים.

סקירה כללית על מחזור החיים של TileService

בנוסף לקריאות החוזרות (callbacks) ששולטות במחזור החיים של השרת המאגד, צריך להטמיע שיטות אחרות שספציפיות למחזור החיים של TileService. יכול להיות שתישלח קריאה ל-methods האלה מחוץ ל-onCreate() ול-onDestroy(), כי הקריאה ל-methods של מחזור החיים של Service ול-methods של מחזור החיים של TileService נשלחת בשני שרשורים אסינכרוניים נפרדים.

מחזור החיים של TileService מכיל את השיטות הבאות, שמופעלות על ידי המערכת בכל פעם שה-TileService נכנס לשלב חדש במחזור החיים:

‫onTileAdded(): השיטה הזו נקראת רק כשהמשתמש מוסיף את המשבצת בפעם הראשונה, ואם המשתמש מסיר ומוסיף את המשבצת שוב. זה הזמן הכי טוב לבצע אתחול חד-פעמי. עם זאת, יכול להיות שזה לא יספיק לכל האתחול הנדרש.

הערה: לא מתבצעת קריאה ל-onTileAdded() בכל פעם שנוצרת משבצת. לדוגמה, לא מתבצעת קריאה ל-onTileAdded() כשהמכשיר מופעל מחדש או מופעל אם הלחצן נוסף ולא הוסר לפני שהמכשיר כובה.
‫onStartListening() ו-onStopListening(): השיטות האלה נקראות בכל פעם שהאפליקציה מעדכנת את המשבצת, והן נקראות לעיתים קרובות. ה-TileService נשאר מקושר בין onStartListening() ל-onStopListening(), וכך האפליקציה יכולה לשנות את המשבצת ולשלוח עדכונים.
‫onTileRemoved(): השיטה הזו נקראת רק אם המשתמש מסיר את המשבצת.

בחירת מצב האזנה

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

אל תניחו ש-TileService יתקיים מחוץ לצמד השיטות onStartListening() ו-onStopListening().

מצב פעיל (מומלץ)

משתמשים במצב פעיל בשביל TileService שמאזין למצב שלו ועוקב אחריו בתהליך משלו. TileService במצב פעיל מוגבלת ל-onTileAdded(), onTileRemoved(), אירועי הקשה, וכשהתהליך של האפליקציה מבקש זאת.

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

אפשר להפעיל את ה-method הסטטית TileService.requestListeningState() כדי לבקש את תחילת מצב ההאזנה ולקבל קריאה חוזרת (callback) אל onStartListening().

כדי להצהיר על מצב פעיל, מוסיפים את META_DATA_ACTIVE_TILE לקובץ המניפסט של האפליקציה.

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
       android:value="true" />
    ...
</service>

מצב לא פעיל

מצב לא פעיל הוא המצב הרגיל. ‫TileService נמצא במצב לא פעיל אם הוא מקושר בכל פעם שהמשבצת גלויה למשתמש. זה אומר שה-TileService עשוי להיווצר ולהיקשר שוב בזמנים שאינם בשליטתו. יכול להיות גם שהמשבצת תנותק ותושמד כשהמשתמש לא צופה בה.

האפליקציה מקבלת קריאה חוזרת (callback) אל onStartListening() אחרי שהמשתמש פותח את חלונית ההגדרות המהירות. אפשר לעדכן את האובייקט Tile כמה פעמים שרוצים בין onStartListening() ל-onStopListening().

לא צריך להצהיר על מצב לא פעיל: אל תוסיפו את META_DATA_ACTIVE_TILE לקובץ המניפסט של האפליקציה.

סקירה כללית של מצבי הלחצנים

אחרי שמשתמש מוסיף את המשבצת, היא תמיד נמצאת באחד מהמצבים הבאים.

‫STATE_ACTIVE: מציין מצב פעיל או מופעל. המשתמש יכול לבצע פעולות במשבצת כשהיא במצב הזה.

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

נחזור לדוגמה של כרטיס המידע של אפליקציית הכושר. כרטיס מידע ב-STATE_INACTIVE מציין שהמשתמש לא התחיל אימון, אבל הוא יכול לעשות את זה אם הוא רוצה.
‫STATE_UNAVAILABLE: מציין מצב של חוסר זמינות זמנית. המשתמש לא יכול לבצע פעולות במשבצת שלכם כשהיא במצב הזה.

לדוגמה, משבצת בצבע STATE_UNAVAILABLE מציינת שהיא לא זמינה כרגע למשתמש מסיבה כלשהי.

חשוב לדעת: השתמשו ב-STATE_UNAVAILABLE למשבצות שלא זמינות כרגע אבל יכול להיות שיהיו זמינות בהמשך. אם הרכיב לא יהיה זמין יותר למשתמש, מעבירים את הערך COMPONENT_ENABLED_STATE_DISABLED אל setComponentEnabledSetting().

המערכת מגדירה רק את המצב הראשוני של האובייקט Tile. אתם מגדירים את המצב של האובייקט Tile לאורך שאר מחזור החיים שלו.

המערכת עשויה לשנות את הצבע של סמל הלחצן והרקע כדי לשקף את המצב של אובייקט Tile. אובייקטים מסוג Tile שמוגדרים כ-STATE_ACTIVE הם הכהים ביותר, ואובייקטים מסוג STATE_INACTIVE ו-STATE_UNAVAILABLE בהירים יותר. הגוון המדויק תלוי ביצרן ובגרסה.

לחצן ה-VPN משנה את הצבע שלו בהתאם למצב האובייקט — **איור 4.** דוגמאות ללחצן שצבוע בגוון שמשקף את המצב שלו (פעיל, לא פעיל ולא זמין, בהתאמה).

עדכון המשבצת

אפשר לעדכן את המשבצת אחרי שמקבלים שיחה חוזרת אל onStartListening(). בהתאם למצב של המשבצת, אפשר לעדכן אותה לפחות פעם אחת עד לקבלת קריאה חוזרת (callback) אל onStopListening().

במצב פעיל, אפשר לעדכן את המשבצת פעם אחת בדיוק לפני שמקבלים קריאה חוזרת (callback) אל onStopListening(). במצב לא פעיל, אפשר לעדכן את המשבצת כמה פעמים שרוצים בין onStartListening() ל-onStopListening().

כדי לאחזר את האובייקט Tile, צריך להפעיל את getQsTile(). כדי לעדכן שדות ספציפיים באובייקט Tile, צריך להפעיל את השיטות הבאות:

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

data class StateModel(val enabled: Boolean, val label: String, val icon: Icon)

override fun onStartListening() {
    super.onStartListening()
    val state = getStateFromService()
    qsTile.label = state.label
    qsTile.contentDescription = state.label
    qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.icon = state.icon
    qsTile.updateTile()
}QuickSettingsTilesSnippets.kt

טיפול בלחיצות

המשתמשים יכולים ללחוץ על המשבצת כדי להפעיל פעולה אם המשבצת נמצאת ב-STATE_ACTIVE או ב-STATE_INACTIVE. לאחר מכן המערכת מפעילה את הקריאה החוזרת (callback) onClick() של האפליקציה.

אחרי שהאפליקציה מקבלת קריאה חוזרת (callback) אל onClick(), היא יכולה להפעיל תיבת דו-שיח או פעילות, להפעיל עבודה ברקע או לשנות את המצב של המשבצת.

var counter = 0
override fun onClick() {
    super.onClick()
    counter++
    qsTile.state = if (counter % 2 == 0) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.label = "Clicked $counter times"
    qsTile.contentDescription = qsTile.label
    qsTile.updateTile()
}QuickSettingsTilesSnippets.kt

פתיחת תיבת דו-שיח

showDialog() מכווץ את החלונית "הגדרות מהירות" ומציג תיבת דו-שיח. אם הפעולה דורשת קלט נוסף או הסכמה מהמשתמש, כדאי להשתמש בתיבת דו-שיח כדי להוסיף הקשר לפעולה.

איך מתחילים פעילויות

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

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

לחיצה ארוכה על משבצת פותחת את המסך פרטי האפליקציה. כדי לשנות את ההתנהגות הזו ולהפעיל פעילות להגדרת העדפות, מוסיפים <intent-filter> לאחת מהפעילויות עם ACTION_QS_TILE_PREFERENCES.

החל מ-Android API 28, ה-PendingIntent חייב לכלול את Intent.FLAG_ACTIVITY_NEW_TASK:

if (Build.VERSION.SDK_INT >= 28) {
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
}QuickSettingsTilesSnippets.kt

אפשר גם להוסיף את הדגל ב-AndroidManifest.xml בקטע הספציפי של Activity.

סימון הלחצן כניתן להחלפה

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

מגדירים את המטא-נתונים של TOGGLEABLE_TILE לערך true כדי לסמן את הלחצן כניתן להחלפה.

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

ביצוע פעולות בטוחות בלבד במכשירים שנעולים באופן מאובטח

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

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

אם הפעולה של הלחצן לא בטוחה, משתמשים ב-unlockAndRun() כדי לבקש מהמשתמש לבטל את נעילת המכשיר. אם הפעולה תצליח, המערכת תפעיל את האובייקט Runnable שאתם מעבירים ל-method הזו.

סיווג של כרטיס המידע

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

הטמעה

כדי לציין קטגוריה ל-TileService, מוסיפים שדה מטא-נתונים להצהרת השירות בקובץ AndroidManifest.xml:

ב-AndroidManifest.xml, בתוך הרכיב <service> של TileService, מוסיפים רכיב <meta-data>.
‫android:name: מגדירים את הערך הזה ל-android.service.quicksettings.TILE_CATEGORY.
‫android:value: מקצים אחד מהקבועים המוגדרים מראש של הקטגוריות, כמו android.service.quicksettings.CATEGORY_CONNECTIVITY או android.service.quicksettings.CATEGORY_DISPLAY.

כמו בדוגמה הבאה:

<service
    android:name=".MyConnectivityTileService"
    [...]
    >
    <meta-data android:name="android.service.quicksettings.TILE_CATEGORY"
        android:value="android.service.quicksettings.CATEGORY_CONNECTIVITY" />
</service>

ה-API מספק קבוצה של קטגוריות מוגדרות מראש שאפשר לבחור מתוכן. הקטגוריות האלה מוגדרות כקבועי מחרוזת בתוך המחלקה TileService.

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

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

למרות שבמכשירי Google Pixel נעשה שימוש בקטגוריות בהגדרות המהירות, יצרני ציוד מקורי (OEM) יכולים להשתמש במידע על הקטגוריות האלה או להתעלם ממנו בממשקי המשתמש של המערכות שלהם.

בקשה מהמשתמש להוסיף את המשבצת שלכם

כדי להוסיף את המשבצת באופן ידני, המשתמשים צריכים לבצע כמה שלבים:

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

המשתמש יכול גם להזיז או להסיר את המשבצת שלכם בכל שלב.

החל מ-Android 13, אתם יכולים להשתמש ב-method‏ requestAddTileService() כדי להקל על המשתמשים להוסיף את הלחצן שלכם למכשיר. בשיטה הזו, המשתמשים מקבלים בקשה להוסיף במהירות את הלחצן ישירות לחלונית ההגדרות המהירות. ההודעה כוללת את שם האפליקציה, התווית שסופקה והסמל.

**איור 5.** הנחיה של Quick Settings Placement API.

public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

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

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

המערכת יכולה להפסיק לעבד בקשות לComponentName מסוימת אם המשתמש דחה אותה מספיק פעמים בעבר. המשתמש נקבע לפי Context שמשמש לאחזור השירות הזה: הוא חייב להתאים למשתמש הנוכחי.