יצירה של תכונות שינוי בהתאמה אישית

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

ב-Compose יש הרבה משתני אופן פעולה להתנהגויות נפוצות, אבל אפשר גם ליצור משתני אופן פעולה מותאמים אישית.

לשינויים יש כמה חלקים:

• מפעל לשינוי תנאי
  • זוהי פונקציית תוסף ב-Modifier, שמספקת ממשק API שמותאם לשינוי, ומאפשרת לשרשר יחד קלילות שינויים. מפעל ה-modifier מייצר את רכיבי הצירוף שמשמשים את Compose כדי לשנות את ממשק המשתמש.
• רכיב שינוי
  • כאן אפשר להטמיע את ההתנהגות של הצירוף.

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

קישור של מגבילים קיימים

לעיתים קרובות אפשר ליצור מגבילים בהתאמה אישית רק באמצעות המשנים הקיימים. לדוגמה, Modifier.clip() מוטמע באמצעות המשתנה graphicsLayer. בשיטה הזו נעשה שימוש ברכיבי מודификатор קיימים, ואתם צריכים לספק מפעל מודификаторים מותאם אישית משלכם.

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

fun Modifier.clip(shape: Shape) = graphicsLayer(shape = shape, clip = true)
CustomModifierSnippets.kt

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

fun Modifier.myBackground(color: Color) = padding(16.dp)
    .clip(RoundedCornerShape(8.dp))
    .background(color)
CustomModifierSnippets.kt

יצירת ערך לשינוי מותאם אישית באמצעות יצרן קומפוזבילי

אפשר גם ליצור משתנה מותאם אישית באמצעות פונקציה שניתנת ליצירה כדי להעביר ערכים למשתנה קיים. המבנה הזה נקרא 'מפעל מודификаторים שניתנים ליצירה'.

שימוש במפעל של מודификаторים שניתנים ליצירה כדי ליצור מודификатор מאפשר גם להשתמש בממשקי API ברמה גבוהה יותר, כמו animate*AsState וממשקי API אחרים של אנימציה שמבוססים על מצב של Compose. לדוגמה, קטע הקוד הבא מציג אנימציה שממחישה שינוי בגרסת אלפא כשהיא מופעלת/מושבתת:

@Composable
fun Modifier.fade(enable: Boolean): Modifier {
    val alpha by animateFloatAsState(if (enable) 0.5f else 1.0f)
    return this then Modifier.graphicsLayer { this.alpha = alpha }
}
CustomModifierSnippets.kt

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

@Composable
fun Modifier.fadedBackground(): Modifier {
    val color = LocalContentColor.current
    return this then Modifier.background(color.copy(alpha = 0.5f))
}
CustomModifierSnippets.kt

לגישה הזו יש כמה מגבלות שמפורטות בהמשך.

ערכי CompositionLocal נפתרים באתר הקריאה של מפעל המשתנה

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

@Composable
fun Modifier.myBackground(): Modifier {
    val color = LocalContentColor.current
    return this then Modifier.background(color.copy(alpha = 0.5f))
}

@Composable
fun MyScreen() {
    CompositionLocalProvider(LocalContentColor provides Color.Green) {
        // Background modifier created with green background
        val backgroundModifier = Modifier.myBackground()

        // LocalContentColor updated to red
        CompositionLocalProvider(LocalContentColor provides Color.Red) {

            // Box will have green background, not red as expected.
            Box(modifier = backgroundModifier)
        }
    }
}
CustomModifierSnippets.kt

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

אף פעם לא מדלגים על משתני פונקציה הניתנת להגדרה

מודификаторים של יצירת רכיבים לא דילוגים אף פעם, כי אי אפשר לדלג על פונקציות ניתנות ליצירה שיש להן ערכי החזרה. כלומר, פונקציית המשנה תופעל בכל פעם שמתבצעת יצירת קומפוזיציה מחדש, ויכול להיות שהפעולה הזו תהיה יקרה אם היצירה מחדש מתבצעת לעיתים קרובות.

צריך להפעיל את המשתנים של פונקציות הניתנות להגדרה בתוך פונקציה הניתנת להגדרה

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

val extractedModifier = Modifier.background(Color.Red) // Hoisted to save allocations

@Composable
fun Modifier.composableModifier(): Modifier {
    val color = LocalContentColor.current.copy(alpha = 0.5f)
    return this then Modifier.background(color)
}

@Composable
fun MyComposable() {
    val composedModifier = Modifier.composableModifier() // Cannot be extracted any higher
}
CustomModifierSnippets.kt

הטמעת התנהגות של שינוי מותאם אישית באמצעות Modifier.Node

Modifier.Node הוא ממשק API ברמה נמוכה יותר ליצירת מודификаторים ב-Compose. זהו אותו ממשק API שבו Compose מטמיע את המשתנים שלו, והוא הדרך הכי יעילה ליצור משתנים מותאמים אישית.

הטמעת משתנה מותאם אישית באמצעות Modifier.Node

יש שלושה חלקים להטמעת פונקציית שינוי מותאמת אישית באמצעות Modifier.Node:

• הטמעה של Modifier.Node שמכילה את הלוגיקה והמצב של המשנה.
• ModifierNodeElement שיוצר ומעדכן את המופעים של הצומת של המגביל.
• מפעל אופציונלי של מודификаторים, כפי שמתואר למעלה.

כיתות ModifierNodeElement הן ללא מצב (stateless), ומוקצים להן מופעים חדשים בכל יצירת קומפוזיציה מחדש. לעומת זאת, כיתות Modifier.Node יכולות להיות עם מצב (stateful), והן ישרדו כמה פעולות של יצירת קומפוזיציה מחדש, ואפילו אפשר יהיה לעשות בהן שימוש חוזר.

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

Modifier.Node

ההטמעה של Modifier.Node (בדוגמה הזו, CircleNode) מטמיעה את הפונקציונליות של המשתנה המותאם אישית.

// Modifier.Node
private class CircleNode(var color: Color) : DrawModifierNode, Modifier.Node() {
    override fun ContentDrawScope.draw() {
        drawCircle(color)
    }
}
CustomModifierSnippets.kt

בדוגמה הזו, הוא מצייר את העיגול בצבע שהוענק לפונקציית המשנה.

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

אלה סוגי הקבצים הזמינים:

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

ModifierNodeElement

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

// ModifierNodeElement
private data class CircleElement(val color: Color) : ModifierNodeElement<CircleNode>() {
    override fun create() = CircleNode(color)

    override fun update(node: CircleNode) {
        node.color = color
    }
}
CustomModifierSnippets.kt

הטמעות של ModifierNodeElement צריכות לבטל את השיטות הבאות:

1. create: זוהי הפונקציה שיוצרת מופע של צומת המשתנה. הפעולה הזו נקראת יצירת הצומת כשמחילים את הצירוף בפעם הראשונה. בדרך כלל, הפעולה הזו כוללת יצירה של הצומת והגדרה שלו באמצעות הפרמטרים שהועברו למפעל המשתנים.
2. update: הפונקציה הזו נקראת בכל פעם שמספקים את המשתנה הזה באותו מקום שבו הצומת כבר קיים, אבל נכס השתנה. הוא נקבע לפי השיטה equals של הכיתה. צומת המשתנה שנוצר קודם נשלח כפרמטר לקריאה ל-update. בשלב הזה, צריך לעדכן את המאפיינים של הצמתים כך שיתואמים לפרמטרים המעודכנים. היכולת לעשות שימוש חוזר בצורה הזו בצמתים היא המפתח לשיפור הביצועים שמתקבל באמצעות Modifier.Node. לכן, צריך לעדכן את הצומת הקיים במקום ליצור צומת חדש בשיטה update. בדוגמה של המעגל, הצבע של הצומת מתעדכן.

בנוסף, הטמעות של ModifierNodeElement צריכות לכלול גם הטמעה של equals ושל hashCode. update תופעל רק אם ההשוואה ל-equals עם הרכיב הקודם תחזיר false.

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

מפעל של מקשי צירוף

זוהי פני השטח הציבוריים של ה-API של המשתנה. ברוב הטמעות ה-CSS, פשוט יוצרים את רכיב המשתנה ומוסיפים אותו לרשת המשתנים:

// Modifier factory
fun Modifier.circle(color: Color) = this then CircleElement(color)
CustomModifierSnippets.kt

דוגמה מלאה

שלושת החלקים האלו מתחברים כדי ליצור את המגביל המותאם אישית כדי לשרטט מעגל באמצעות ממשקי ה-API של Modifier.Node:

// Modifier factory
fun Modifier.circle(color: Color) = this then CircleElement(color)

// ModifierNodeElement
private data class CircleElement(val color: Color) : ModifierNodeElement<CircleNode>() {
    override fun create() = CircleNode(color)

    override fun update(node: CircleNode) {
        node.color = color
    }
}

// Modifier.Node
private class CircleNode(var color: Color) : DrawModifierNode, Modifier.Node() {
    override fun ContentDrawScope.draw() {
        drawCircle(color)
    }
}
CustomModifierSnippets.kt

מצבים נפוצים שבהם נעשה שימוש ב-Modifier.Node

כשיוצרים משתני התאמה אישית באמצעות Modifier.Node, אלה כמה מצבים נפוצים שעשויים להתרחש.

אפס פרמטרים

אם למגביל אין פרמטרים, הוא אף פעם לא צריך להתעדכן, ובנוסף הוא לא צריך להיות סיווג נתונים. דוגמה להטמעה של מודификатор שמחיל כמות קבועה של ריפוד על רכיב מורכב:

fun Modifier.fixedPadding() = this then FixedPaddingElement

data object FixedPaddingElement : ModifierNodeElement<FixedPaddingNode>() {
    override fun create() = FixedPaddingNode()
    override fun update(node: FixedPaddingNode) {}
}

class FixedPaddingNode : LayoutModifierNode, Modifier.Node() {
    private val PADDING = 16.dp

    override fun MeasureScope.measure(
        measurable: Measurable,
        constraints: Constraints
    ): MeasureResult {
        val paddingPx = PADDING.roundToPx()
        val horizontal = paddingPx * 2
        val vertical = paddingPx * 2

        val placeable = measurable.measure(constraints.offset(-horizontal, -vertical))

        val width = constraints.constrainWidth(placeable.width + horizontal)
        val height = constraints.constrainHeight(placeable.height + vertical)
        return layout(width, height) {
            placeable.place(paddingPx, paddingPx)
        }
    }
}
CustomModifierSnippets.kt

הפניה למשתני מקומיים של קומפוזיציה

המשתנים המשתנים של Modifier.Node לא מזהים באופן אוטומטי שינויים באובייקטים של מצב Compose, כמו CompositionLocal. היתרון של מגבילי הצירוף Modifier.Node יש על פני המגבילים שנוצרו לאחרונה באמצעות מפעל קומפוזבילי, הוא שהם יכולים לקרוא את הערך המקומי של הקומפוזביליות מהמקום שבו משתמשים בעץ בממשק המשתמש, ולא במקום שבו הוקצה הצירוף, באמצעות currentValueOf.

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

• DrawModifierNode: ContentDrawScope
• LayoutModifierNode: MeasureScope ו-IntrinsicMeasureScope
• SemanticsModifierNode: SemanticsPropertyReceiver

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

class BackgroundColorConsumerNode :
    Modifier.Node(),
    DrawModifierNode,
    CompositionLocalConsumerModifierNode {
    override fun ContentDrawScope.draw() {
        val currentColor = currentValueOf(LocalContentColor)
        drawRect(color = currentColor)
        drawContent()
    }
}
CustomModifierSnippets.kt

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

לדוגמה, Modifier.scrollable משתמש בשיטה הזו כדי לעקוב אחרי שינויים ב-LocalDensity. דוגמה פשוטה מופיעה בהמשך:

class ScrollableNode :
    Modifier.Node(),
    ObserverModifierNode,
    CompositionLocalConsumerModifierNode {

    // Place holder fling behavior, we'll initialize it when the density is available.
    val defaultFlingBehavior = DefaultFlingBehavior(splineBasedDecay(UnityDensity))

    override fun onAttach() {
        updateDefaultFlingBehavior()
        observeReads { currentValueOf(LocalDensity) } // monitor change in Density
    }

    override fun onObservedReadsChanged() {
        // if density changes, update the default fling behavior.
        updateDefaultFlingBehavior()
    }

    private fun updateDefaultFlingBehavior() {
        val density = currentValueOf(LocalDensity)
        defaultFlingBehavior.flingDecay = splineBasedDecay(density)
    }
}
CustomModifierSnippets.kt

ערך משנה עם אנימציה

להטמעות של Modifier.Node יש גישה אל coroutineScope. כך ניתן להשתמש בממשקי API של Compose Animatable API. לדוגמה, קטע הקוד הזה משנה את הערך של CircleNode שלמעלה כדי להציג אותו בהדרגה שוב ושוב:

class CircleNode(var color: Color) : Modifier.Node(), DrawModifierNode {
    private val alpha = Animatable(1f)

    override fun ContentDrawScope.draw() {
        drawCircle(color = color, alpha = alpha.value)
        drawContent()
    }

    override fun onAttach() {
        coroutineScope.launch {
            alpha.animateTo(
                0f,
                infiniteRepeatable(tween(1000), RepeatMode.Reverse)
            ) {
            }
        }
    }
}
CustomModifierSnippets.kt

שיתוף מצב בין משתני פונקציה באמצעות הענקת גישה

משתני Modifier.Node יכולים להקצות לעצמם צמתים אחרים. יש הרבה תרחישים לדוגמה, כמו חילוץ הטמעות נפוצות במגוון מודификаторים, אבל אפשר גם להשתמש בזה כדי לשתף מצב משותף בין מודификаторים.

לדוגמה, הטמעה בסיסית של צומת של משתנה משתנה שניתן ללחוץ עליו, שמשתף נתוני אינטראקציה:

class ClickableNode : DelegatingNode() {
    val interactionData = InteractionData()
    val focusableNode = delegate(
        FocusableNode(interactionData)
    )
    val indicationNode = delegate(
        IndicationNode(interactionData)
    )
}
CustomModifierSnippets.kt

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

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

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

דוגמה היפותטית לכך מוצגת בהמשך, עם שינוי שיש לו פונקציית lambda של color, ‏ size ו-onClick כמאפיינים. המשתנה הזה מבטל רק את מה שנדרש, ומדלג על ביטול של פריטים שלא נדרשים:

class SampleInvalidatingNode(
    var color: Color,
    var size: IntSize,
    var onClick: () -> Unit
) : DelegatingNode(), LayoutModifierNode, DrawModifierNode {
    override val shouldAutoInvalidate: Boolean
        get() = false

    private val clickableNode = delegate(
        ClickablePointerInputNode(onClick)
    )

    fun update(color: Color, size: IntSize, onClick: () -> Unit) {
        if (this.color != color) {
            this.color = color
            // Only invalidate draw when color changes
            invalidateDraw()
        }

        if (this.size != size) {
            this.size = size
            // Only invalidate layout when size changes
            invalidateMeasurement()
        }

        // If only onClick changes, we don't need to invalidate anything
        clickableNode.update(onClick)
    }

    override fun ContentDrawScope.draw() {
        drawRect(color)
    }

    override fun MeasureScope.measure(
        measurable: Measurable,
        constraints: Constraints
    ): MeasureResult {
        val size = constraints.constrain(size)
        val placeable = measurable.measure(constraints)
        return layout(size.width, size.height) {
            placeable.place(0, 0)
        }
    }
}
CustomModifierSnippets.kt