משתמשים אוהבים תמונות, סרטונים ותוכן נוסף שמאפשר להם להביע את עצמם, אבל לא תמיד קל להוסיף תוכן כזה לאפליקציות ולהעביר אותו. כדי להקל על אפליקציות מקבלים תוכן עשיר, גרסת Android 12 (רמת API 31) מציגה ממשק API מאוחד מאפשר לאפליקציה לקבל תוכן מכל מקור: לוח, מקלדת או גרירה.
אפשר לצרף ממשק, כמו OnReceiveContentListener
, לרכיבי ממשק המשתמש ולקבל קריאה חוזרת (callback) כשתוכן מוכנס דרך מנגנון כלשהו. הקריאה החוזרת (callback) הופכת למקום היחיד שבו הקוד שלך מטפל
לקבל את כל התוכן, החל מטקסט פשוט ומסוגנן ועד לתגי עיצוב, תמונות, סרטונים,
קובצי אודיו ואחרים.
לצורך תאימות לאחור עם גרסאות Android קודמות, ה-API הזה זמין ב-AndroidX, החל מ- Core 1.7 ו- Appcompat 1.4, שבו מומלץ להשתמש כאשר מטמיעים את הפונקציונליות הזו.
סקירה כללית
בממשקי API קיימים אחרים, לכל מנגנון בממשק המשתמש – כמו תפריט לחיצה ארוכה או גרירה – יש ממשק API תואם משלו. כלומר, צריך לשלב עם כל API בנפרד, ולהוסיף קוד דומה לכל מנגנון להוספת תוכן:
ממשק ה-API של OnReceiveContentListener
מביא לידי ביטוי את נתיבי הקוד השונים האלה על ידי יצירת API יחיד להטמעה, כך שתוכלו להתמקד בלוגיקה הספציפית לאפליקציה שלכם ולתת לפלטפורמה לטפל בשאר הדברים:
משמעות הגישה הזו גם היא שכשנוספים דרכים חדשות להוספת תוכן אין צורך לבצע שינויים נוספים בקוד כדי להפעיל את התמיכה. באפליקציה. ואם האפליקציה צריכה ליישם התאמה אישית מלאה מסוים, אפשר עדיין להשתמש בממשקי ה-API הקיימים, שממשיכים לפעול כמעט באותה הדרך.
הטמעה
ה-API הוא ממשק האזנה עם שיטה אחת,
OnReceiveContentListener
כדי לתמוך בגרסאות ישנות של פלטפורמת Android, מומלץ להשתמש
תואם
OnReceiveContentListener
בספריית AndroidX Core.
כדי להשתמש ב-API, מטמיעים את המאזין ומציינים את סוגי התוכן שהאפליקציה יכולה לטפל בהם:
object MyReceiver : OnReceiveContentListener { val MIME_TYPES = arrayOf("image/*", "video/*") // ... override fun onReceiveContent(view: View, payload: ContentInfoCompat): ContentInfoCompat? { TODO("Not yet implemented") } }
public class MyReceiver implements OnReceiveContentListener { public static final String[] MIME_TYPES = new String[] {"image/*", "video/*"}; // ... }
אחרי שמציינים את כל סוגי ה-MIME של התוכן שהאפליקציה תומכת בהם, מטמיעים את שאר הקוד של הבורר:
class MyReceiver : OnReceiveContentListener { override fun onReceiveContent(view: View, contentInfo: ContentInfoCompat): ContentInfoCompat { val split = contentInfo.partition { item: ClipData.Item -> item.uri != null } val uriContent = split.first val remaining = split.second if (uriContent != null) { // App-specific logic to handle the URI(s) in uriContent. } // Return anything that your app didn't handle. This preserves the // default platform behavior for text and anything else that you aren't // implementing custom handling for. return remaining } companion object { val MIME_TYPES = arrayOf("image/*", "video/*") } }
public class MyReceiver implements OnReceiveContentListener { public static final String[] MIME_TYPES = new String[] {"image/*", "video/*"}; @Override public ContentInfoCompat onReceiveContent(View view, ContentInfoCompat contentInfo) { Pair<ContentInfoCompat, ContentInfoCompat> split = contentInfo.partition( item -> item.getUri() != null); ContentInfo uriContent = split.first; ContentInfo remaining = split.second; if (uriContent != null) { // App-specific logic to handle the URI(s) in uriContent. } // Return anything that your app didn't handle. This preserves the // default platform behavior for text and anything else that you aren't // implementing custom handling for. return remaining; } }
אם האפליקציה שלכם כבר תומכת בשיתוף באמצעות כוונות, תוכלו לעשות שימוש חוזר בלוגיקה הספציפית לאפליקציה לטיפול ב-URI של תוכן. מחזירים את כל הנתונים הנותרים כדי להעביר את הטיפול בהם לפלטפורמה.
אחרי הטמעת ה-listener, מגדירים אותו ברכיבי ממשק המשתמש המתאימים ב- האפליקציה שלך:
class MyActivity : Activity() { public override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) // ... val myInput = findViewById(R.id.my_input) ViewCompat.setOnReceiveContentListener(myInput, MyReceiver.MIME_TYPES, MyReceiver()) } }
public class MyActivity extends Activity { @Override public void onCreate(Bundle savedInstanceState) { // ... AppCompatEditText myInput = findViewById(R.id.my_input); ViewCompat.setOnReceiveContentListener(myInput, MyReceiver.MIME_TYPES, new MyReceiver()); } }
הרשאות URI
המערכת מעניקה ומבטלת באופן אוטומטי הרשאות קריאה לכל מזהי URI של תוכן בתוכן הייעודי (payload) שמוענק ל-OnReceiveContentListener
.
בדרך כלל, האפליקציה מעבדת מזהי URI של תוכן בשירות או בפעילות. עבור
לעיבוד ממושך, צריך להשתמש
WorkManager. כאשר מטמיעים
זאת, להרחיב את ההרשאות לשירות או לפעילות היעד על ידי העברת
תוכן באמצעות
Intent.setClipData
ולהגדיר את הדגל
FLAG_GRANT_READ_URI_PERMISSION
.
לחלופין, אפשר להשתמש בשרשור ברקע במסגרת ההקשר הנוכחי כדי
לעבד את התוכן. במקרה כזה, צריך לשמור על הפניה לאובייקט payload
שהאזין קיבל כדי לוודא שהפלטפורמה לא תבטל את ההרשאות לפני הזמן.
תצוגות מותאמות אישית
אם באפליקציה שלך נעשה שימוש במחלקה משנית מותאמת אישית של View
, צריך לוודא
לא ניתן לעקוף את OnReceiveContentListener
.
אם הכיתה View
מבטלת את
onCreateInputConnection
צריך להשתמש ב-Jetpack API
InputConnectionCompat.createWrapper
כדי להגדיר את InputConnection
.
אם בכיתה View
מתבצעת החלפה של השיטה onTextContextMenuItem
, מעבירים את הטיפול ל-super כשפריט התפריט הוא R.id.paste
או R.id.pasteAsPlainText
.
השוואה ל-Keyboard Image API
אפשר להתייחס ל-API OnReceiveContentListener
כגרסה הבאה של ממשק ה-API הקיים לתמונות של מקלדת. הגרסה המאוחדת
ה-API תומך בפונקציונליות של ממשק ה-API של תמונת המקלדת
תכונות נוספות. התאימות של מכשירים ותכונות משתנה בהתאם
בין אם אתם משתמשים בספריית Jetpack או בממשקי ה-API המקוריים מ-Android SDK.
פעולה או תכונה | נתמך על ידי ממשק ה-API של תמונת המקלדת | תמיכה באמצעות API מאוחד |
---|---|---|
הוספה מהמקלדת | כן (רמת API 13 ואילך) | כן (רמת API 13 ומעלה) |
הוספה באמצעות הדבקה מהתפריט של הלחיצה הארוכה | לא | כן |
הוספה באמצעות גרירה ושחרור | לא | כן (רמת API 24 ואילך) |
פעולה או תכונה | נתמך על ידי ממשק ה-API של תמונת המקלדת | תמיכה באמצעות API מאוחד |
---|---|---|
הוספה מהמקלדת | כן (רמת API 25 ומעלה) | כן (Android מגרסה 12 ואילך) |
הוספה באמצעות הדבקה מהתפריט של הלחיצה הארוכה | לא | |
הוספה באמצעות גרירה ושחרור | לא |