Bildschirme für KI-Agenten verständlich machen: Praktische Anleitung zur Jetpack Compose Semantics-Gestaltung

Bildschirme für KI-Agenten verständlich machen: Praktische Anleitung zur Jetpack Compose Semantics-Gestaltung

Einführung

Damit KI-Agenten und automatisierte Test-Tools in Jetpack Compose "was macht dieser Button" genau verstehen können, ist die richtige Gestaltung von Semantics (Semantik) der Schlüssel.

Compose verfügt intern über einen "Semantics Tree", der als Bedeutungsstruktur für Barrierefreiheit, UI-Tests und automatisierte Bedienung (Appium/UIAutomator/MCP usw.) fungiert. Es ist sozusagen das Äquivalent zu ARIA und DOM im Web.

Hauptattribute von Semantics

contentDescription

Das grundlegendste Attribut zur Zuweisung einer Bedeutung zu reinen Icon-Buttons.

IconButton(
    onClick = onDelete,
    modifier = Modifier.semantics {
        contentDescription = "削除"
    }
) {
    Icon(Icons.Default.Delete, contentDescription = null)
}

KI und Barrierefreiheitstools erkennen dies als "Delete-Button · anklickbar · Button-Rolle" an.

role

Macht den UI-Typ für benutzerdefinierte UIs explizit. Ein einfaches Box(clickable) wird als "anklickbare Etwas" erkannt, aber durch die Angabe einer Rolle wird deutlich, dass es sich um Button, Switch, Checkbox, Tab usw. handelt.

Modifier.semantics {
    role = Role.Button
}

stateDescription

Vermittelt der KI den aktuellen Zustand der UI.

Modifier.semantics {
    stateDescription =
        if (subscribed) "購読中"
        else "未購読"
}

testTag

Der wichtigste Identifikator für die Zusammenarbeit mit MCP, Appium und automatisierten UI-Agenten. Er ermöglicht eine stabile Identifizierung unabhängig von Koordinaten, OCR oder Textänderungen.

Modifier.testTag("login_button")

Konfiguration für UIAutomator-Integration

Da Compose keine View-Hierarchie direkt erstellt, ist testTag von UIAutomator manchmal nicht sichtbar. Dies kann durch das Folgende am Root gelöst werden.

Scaffold(
    modifier = Modifier.semantics {
        testTagsAsResourceId = true
    }
)

testTag wird als resource-id erkannt und kann direkt von UIAutomator abgerufen werden.

Implementierungsmuster, die KI am leichtesten versteht

Die beste Praktik ist die Kombination mehrerer Attribute.

Button(
    onClick = login,
    modifier = Modifier
        .testTag("login_button")
        .semantics {
            contentDescription = "ログイン"
            role = Role.Button
        }
) {
    Text("ログイン")
}

Komplexe UIs zu einer einzigen Bedeutung zusammenfassen

Wenn komplexe Zusammensetzungen wie Icon, Text und Badge der KI als ein einziger Button gezeigt werden sollen, verwenden Sie clearAndSetSemantics.

Modifier.clearAndSetSemantics {
    contentDescription = "商品をカートに追加"
    role = Role.Button
}

Die interne Verschachtelungsstruktur und Icon-Gruppen werden ignoriert und nur die Bedeutung an die KI übermittelt.

Was Semantics-Gestaltung ermöglicht

Stabilisierung der automatisierten Bedienung

Mit testTag ist eine stabile Bedienung ohne Koordinaten oder OCR möglich. Selbst nach einem UI-Redesign funktioniert die Automatisierung, solange der testTag gleich bleibt. Auch bei mehrsprachigen Versionen wird die Automatisierung robuster.

Reduktion der Token-Menge

Nur mit Screenshots ist eine große Menge an Tokens für Bildanalyse erforderlich, aber mit dem Semantics Tree können Sie strukturierte Daten leicht handhaben.

[
  {"type": "Button", "label": "ログイン"},
  {"type": "TextField", "label": "メール"},
  {"type": "TextField", "label": "パスワード"}
]

Dies ist besonders wirksam bei langer Automatisierung und großflächiger Bildschirmanalyse und trägt auch zur Vermeidung von Context-Überfluss bei.

Zustandsverständnis durch KI

Mit stateDescription kann die KI den aktuellen Zustand des Bildschirms abschätzen und Entscheidungen treffen wie "es ist paused, also sollte ich den Play-Button drücken". Es wird möglich, den Bildschirm als Zustandsmaschine verstehen zu lassen.

Strukturierte Analyse durch MCP-Integration

Der Semantics Tree kann von einem MCP Server abgerufen und an den LLM-Agenten übermittelt werden, was Bedeutungsverständnis des gesamten Bildschirms, Schätzung der nächsten Bedienungsoptionen und Zustandsübergangsanalyse ermöglicht.

Compose UI → Semantics Tree → MCP Server → LLM Agent

Zusammenfassung zur Verwendung von Semantics-Attributen

Fazit

Compose ermöglicht die Trennung von "Erscheinungsbild" und "Bedeutung". Das Wesen von Semantics-Gestaltung liegt darin, dass Sie Benutzeroberfläche für Menschen und Bedeutungsstruktur für KI unabhängig voneinander gestalten können.

Wenn Sie KI-Agenten, MCP, UIAutomator und automatisierte E2E-Tests nutzen, erzielen Sie durch die folgende Standardisierung für jede Komponente ein hohes Kosten-Nutzen-Verhältnis.

Modifier
    .testTag(...)
    .semantics {
        contentDescription = ...
        role = ...
    }

Statt Farbe, Position und Größe die Information "was ist dieser Button, was passiert beim Drücken, wie ist der aktuelle Zustand" über Semantics zu übermitteln — das ist der Kern von KI-freundlichem UI-Design.