Compose のユーザー補助

Compose で作成するアプリは、さまざまなニーズを持つ利用者に対するユーザー補助をサポートする必要があります。ユーザー補助サービスは、画面に表示される内容を、特定のニーズを持つ利用者に適した形式に変換するために使用されます。ユーザー補助サービスをサポートするため、アプリは UI 要素に関するセマンティック情報を公開する Android フレームワークの API を使用します。Android フレームワークは、このセマンティック情報をユーザー補助サービスに伝えます。個々のユーザー補助サービスは、ユーザーに対してアプリを説明するのに最も適した方法を選択できます。Android には、TalkBackスイッチ アクセスなど、いくつかのユーザー補助サービスが用意されています。

セマンティクス

Compose は、セマンティクス プロパティを使用してユーザー補助サービスに情報を渡します。セマンティクス プロパティは、ユーザーに表示される UI 要素に関する情報を提供します。TextButton のような組み込みコンポーザブルのほとんどは、コンポーザブルとその子から推測される情報をセマンティクス プロパティに入力します。toggleableclickable のようないくつかの修飾子も、特定のセマンティクス プロパティを設定します。しかし、フレームワークは、ユーザーに対して UI 要素を説明する方法を把握するために、より多くの情報を必要とする場合があります。

このドキュメントでは、Android フレームワークに対して情報を正しく説明するために、コンポーザブルに明示的に情報を追加する必要があるさまざまな状況について説明します。また、特定のコンポーザブルのためにセマンティクス情報を完全に置き換える方法についても説明します。このドキュメントは、Android のユーザー補助の基本を理解していることを前提としています。

一般的なユースケース

ユーザー補助を必要とする人がアプリを正しく使用できるようにするには、このページに記載されているベスト プラクティスに沿ってアプリを作成する必要があります。

視覚要素を説明する

Image または Icon コンポーザブルを定義する際に、何が表示されているかを Android フレームワークが自動的に認識する方法はありません。視覚要素のテキスト説明を渡す必要があります。

ユーザーが現在のページを友だちと共有できる画面があるとします。この画面には、クリック可能な共有アイコンがあります。

クリック可能なアイコンのバーと、ハイライト表示された共有アイコン

Android フレームワークは、アイコンだけでは、視覚障がいのあるユーザーへの説明方法を認識できません。Android フレームワークは、アイコンに関する追加のテキスト説明を必要とします。

視覚要素を説明するには、contentDescription パラメータを使用します。説明はユーザーに伝えられるものなので、ローカライズした文字列を使用する必要があります。

@Composable
fun ShareButton(onClick: () -> Unit) {
  IconButton(onClick = onClick) {
    Icon(
      imageVector = Icons.Filled.Share,
      contentDescription = stringResource(R.string.label_share)
    )
  }
}

一部の視覚要素は純粋に装飾的なものであるため、ユーザーに説明したくない場合があります。contentDescription パラメータを null に設定すると、この要素にはアクションまたは状態が関連付けられていないことを Android フレームワークに通知できます。

@Composable
fun PostImage(post: Post, modifier: Modifier = Modifier) {
  val image = post.imageThumb ?: imageResource(R.drawable.placeholder_1_1)

  Image(
    bitmap = image,
    // Specify that this image has no semantic meaning
    contentDescription = null,
    modifier = modifier
      .size(40.dp, 40.dp)
      .clip(MaterialTheme.shapes.small)
  )
}

特定の視覚要素に contentDescription が必要かどうかは自由に決定できます。ユーザーがタスクを実行するために必要な情報が視覚要素に含まれているかどうかを検討してください。含まれていない場合は、説明を省略する方が適切です。

カスタム コンテンツ説明を設定する

コンテンツ説明を明示的に設定したい場合があります。そのような場合は、semantics 修飾子を使用して、コンポーザブルにコンテンツ説明を直接割り当てることができます。たとえば、カスタム アイコンを描画したい場合、それは Icon コンポーザブルを直接使用できないことを意味します。

@Composable
fun CustomShareIcon(modifier: Modifier = Modifier) {
  val cd = stringResource(R.string.custom_share_icon_content_description)
  Canvas(modifier.semantics { contentDescription = cd }) {
    /* Draw custom icon here */
  }
}

要素を結合する

TalkBack やスイッチ アクセスなどのユーザー補助サービスでは、ユーザーは画面上の要素間でフォーカスを移動できます。適切な粒度で要素がフォーカスされることが重要です。画面上で低レベルの単一コンポーザブルが個別にフォーカスされている場合、ユーザーは画面上を移動するために多くの操作を行う必要があります。要素を過剰に結合すると、ユーザーはどの要素が結合されているかを把握できなくなります。

clickable 修飾子をコンポーザブルに適用すると、それに含まれるすべての要素が Compose によって自動的に結合されます。これは ListItem にも当てはまります。リストアイテム内の要素が結合され、ユーザー補助サービスからは 1 つの要素として認識されます。

論理グループを形成するコンポーザブルのセットを持つことはできますが、そのグループはクリック可能ではなく、リストアイテムの一部でもありません。それでもユーザー補助サービスがそれらを 1 つの要素として認識するようにしたい場合があります。たとえば、ユーザーのアバター、名前、追加情報を表示するコンポーザブルを想像してください。

ユーザー名を含む UI 要素のグループ。名前が選択されています。

semantics 修飾子の mergeDescendants パラメータを使用して、これらの要素を結合するように Compose に指示できます。そうすると、ユーザー補助サービスは結合された要素のみを選択し、子孫のすべてのセマンティクス プロパティが結合されます。

@Composable
private fun PostMetadata(metadata: Metadata) {
  // Merge elements below for accessibility purposes
  Row(modifier = Modifier.semantics(mergeDescendants = true) {}) {
    Image(
      imageVector = Icons.Filled.AccountCircle,
      contentDescription = null // decorative
    )
    Column {
      Text(metadata.author.name)
      Text("${metadata.date} • ${metadata.readTimeMinutes} min read")
    }
  }
}

ユーザー補助サービスは、コンテナ全体を一度にフォーカスして、それらのコンテンツを結合します。

ユーザー名を含む UI 要素のグループ。すべての要素がまとめて選択されています。

カスタム アクションを追加する

以下のリストアイテムをご覧ください。

記事タイトル、著者、ブックマーク アイコンを含む一般的なリストアイテム。

TalkBack のようなスクリーン リーダーを使用して画面の表示内容の読み上げを聴くときは、まずアイテム全体を選択し、次にブックマーク アイコンを選択します。

すべての要素がまとめて選択されたリストアイテム。

ブックマーク アイコンのみが選択されたリストアイテム。

長いリストは、繰り返しが多い場合があります。そのような場合は、ユーザーがアイテムをブックマークするためのカスタム アクションを定義する方が適切です。ブックマーク アイコン自体の動作を明示的に削除して、ユーザー補助サービスによって選択されないようにすることも忘れないでください。そのためには、clearAndSetSemantics 修飾子を使用します。

@Composable
fun PostCardSimple(
  /* ... */
  isFavorite: Boolean,
  onToggleFavorite: () -> Boolean
) {
  val actionLabel = stringResource(
    if (isFavorite) R.string.unfavorite else R.string.favorite
  )
  Row(modifier = Modifier
    .clickable(onClick = { /* ... */ })
    .semantics {
      // Set any explicit semantic properties
      customActions = listOf(
        CustomAccessibilityAction(actionLabel, onToggleFavorite)
      )
    }
  ) {
    /* ... */
    BookmarkButton(
      isBookmarked = isFavorite,
      onClick = onToggleFavorite,
      // Clear any semantics properties set on this node
      modifier = Modifier.clearAndSetSemantics { }
    )
  }
}

要素の状態を説明する

コンポーザブルでは、Android フレームワークによって使用されるセマンティクスの stateDescription を定義して、コンポーザブルの状態を読み上げることができます。たとえば、切り替え可能なコンポーザブルの状態は、「オン」または「オフ」のいずれかです。Compose が使用するデフォルトの状態説明ラベルをオーバーライドしたい場合もあります。これを行うには、コンポーザブルを切り替え可能として定義する前に、状態説明ラベルを明示的に指定します。

@Composable
private fun TopicItem(itemTitle: String, selected: Boolean, onToggle: () -> Unit) {
  val stateSubscribed = stringResource(R.string.subscribed)
  val stateNotSubscribed = stringResource(R.string.not_subscribed)
  Row(
    modifier = Modifier
      .semantics {
        // Set any explicit semantic properties
        stateDescription = if(selected) stateSubscribed else stateNotSubscribed
      }
      .toggleable(
        value = selected,
        onValueChange = { onToggle() }
      )
  ) {
    /* ... */
  }
}

見出しを定義する

アプリは、スクロール可能なコンテナで 1 つの画面に多数のコンテンツを表示することがあります。たとえば、1 つの画面にユーザーが読んでいる記事のすべての内容を表示する場合などです。

スクロール可能なコンテナで記事テキストを表示したブログ投稿のスクリーンショット。

ユーザー補助を必要とするユーザーにとって、そのような画面をナビゲートするのは困難です。ナビゲーションを補助するため、どの要素が見出しなのかを示すことができます。上記の例では、各サブセクションのタイトルをユーザー補助用の見出しとして定義できます。TalkBack のような一部のユーザー補助サービスでは、ユーザーは見出しから見出しに直接移動できます。

Compose で、あるコンポーザブルが見出しであることを示すには、セマンティクス プロパティを定義します。

@Composable
private fun Subsection(text: String) {
  Text(
    text = text,
    style = MaterialTheme.typography.h5,
    modifier = Modifier.semantics { heading() }
  )
}

低レベルのカスタム コンポーザブルを作成する

より高度なユースケースとして、アプリ内の特定のマテリアル コンポーネントをカスタム バージョンに置き換える場合があります。このシナリオでは、ユーザー補助の考慮事項を念頭に置くことが重要です。たとえば、マテリアル Checkbox を独自の実装で置き換える場合があります。その場合、このコンポーネントのユーザー補助プロパティを処理する triStateToggleable 修飾子を追加することを忘れがちです。

経験則上、マテリアル ライブラリのコンポーネントの実装を確認して、思いつく限りのユーザー補助動作を模倣する必要があります。さらに、UI レベルの修飾子ではなく、基盤修飾子を多用します。基盤修飾子は、すぐに使用できるユーザー補助の考慮事項に対応しているからです。カスタム コンポーネントの実装は、必ず複数のユーザー補助サービスでテストして、動作を検証してください。