diff --git a/mpd.tree b/mpd.tree index 800d5711..ee33ec98 100644 --- a/mpd.tree +++ b/mpd.tree @@ -45,7 +45,10 @@ - + + + + diff --git a/topics/compose/compose-ios-accessibility.md b/topics/compose/compose-ios-accessibility.md new file mode 100644 index 00000000..2216cd53 --- /dev/null +++ b/topics/compose/compose-ios-accessibility.md @@ -0,0 +1,101 @@ +[//]: # (title: Support for iOS accessibility features) + +Compose Multiplatform accessibility support allows people with disabilities to interact with the Compose Multiplatform UI +as comfortably as with the native iOS UI: +* Screen readers and VoiceOver can access the content of the Compose Multiplatform UI. +* The Compose Multiplatform UI supports the same gestures as the native iOS UI for navigation and interaction. + +This is possible because semantics data produced by Compose APIs is now mapped to native objects and properties +that are consumed by iOS Accessibility Services. For most interfaces built with Material widgets, this should happen +automatically. + +You can also use this semantic data in testing and other automation: properties such as `testTag` will correctly map +to native accessibility properties such as `accessibilityIdentifier`. This makes semantic data from Compose Multiplatform available +to Accessibility Services and XCTest framework. + +The Compose accessibility API doesn't currently support: +* Live regions (announcements about content changes in a specific area). +* [UIKit elements inside Compose Multiplatform UI](compose-ios-ui-integration.md#use-uikit-inside-compose-multiplatform). + +iOS accessibility support is in the early stages of development. If you have trouble with this feature, +we would appreciate your feedback in the [#compose-ios](https://kotlinlang.slack.com/archives/C0346LWVBJ4/p1678888063176359) +Slack channel or as an issue in the [Compose Multiplatform GitHub repo](https://github.com/JetBrains/compose-multiplatform/issues). + +## Customize synchronization of the accessibility tree + +With default settings: +* The iOS accessibility tree is synchronized with the UI only when Accessibility Services are running. +* Synchronization events are not logged. + +You can customize these settings with the new Compose Multiplatform API. + +### Choose the tree synchronization option + +To debug and test events and interactions, you can change the synchronization mode to: +* Never synchronize the tree with UI, for example, to temporarily disable accessibility mapping. +* Always synchronize the tree so that it is rewritten every time the UI updates to test the accessibility integration thoroughly. + +> Remember that synchronizing the tree after each UI event can be quite useful for debugging and testing but can degrade +> the performance of your app. +> +{type="note"} + +An example of enabling the option to always synchronize the accessibility tree: + +```kotlin +ComposeUIViewController(configure = { + accessibilitySyncOptions = AccessibilitySyncOptions.Always(debugLogger = null) +}) { + // your @Composable content +} +``` + +The `AccessibilitySyncOptions` class contains all available options: + +```kotlin +// package androidx.compose.ui.platform + +@ExperimentalComposeApi +sealed class AccessibilitySyncOptions { + + // Option to never synchronize the accessibility tree + object Never: AccessibilitySyncOptions + + // Option to synchronize the tree only when Accessibility Services are running + // + // You can include an AccessibilityDebugLogger to log interactions and tree syncing events + class WhenRequiredByAccessibilityServices(debugLogger: AccessibilityDebugLogger?) + + // Option to always synchronize the accessibility tree + // + // You can include an AccessibilityDebugLogger to log interactions and tree syncing events + class Always(debugLogger: AccessibilityDebugLogger?) +} +``` + +### Implement the logging interface + +You can implement the `AccessibilityDebugLogger` interface to write custom messages to an output of your choosing: + +```kotlin +ComposeUIViewController(configure = { + accessibilitySyncOptions = AccessibilitySyncOptions.WhenRequiredByAccessibilityServices(object: AccessibilityDebugLogger { + override fun log(message: Any?) { + if (message == null) { + println() + } else { + println("[a11y]: $message") + } + } + }) +}) { + // your @Composable content +} +``` + +## What's next? + +Now that you're up to speed with iOS accessibility support in Compose Multiplatform: +* Try out the project generated by [the Kotlin Multiplatform wizard](https://kmp.jetbrains.com/) in your usual iOS accessibility workflow. +* Learn about [resource qualifiers](compose-images-resources.md) that will be helpful when adapting +a Compose Multiplatform UI to a particular situation. \ No newline at end of file