管理焦点

手动焦点管理

Ionic 在组件（如 输入、搜索栏 和 文本区域）上提供了一个 setFocus API，允许开发人员手动将焦点设置到元素。 此 API 应代替 autofocus 属性使用，并应在以下情况中调用：

• ionViewDidEnter 生命周期事件，用于在路由应用程序中进入页面时。
• didPresent 生命周期事件，用于在呈现叠加层时。
• appload 事件，用于在原生 JavaScript 应用程序加载时。
• 用户手势或交互的结果。

为什么不使用 autofocus？

autofocus 属性是一个标准的 HTML 属性，允许开发人员在页面加载时将焦点设置到元素。 此属性通常用于将焦点设置到页面上的第一个输入元素。 但是，autofocus 属性在路由应用程序中在页面之间导航时会导致问题。 这是因为 autofocus 属性将在页面加载时将焦点设置到元素，但在重新访问页面时不会将焦点设置到该元素。 详细了解 MDN Web 文档 中的 autofocus 属性。

平台限制

使用 setFocus API 时，您应该注意一些平台限制，包括：

1. Android 要求在将焦点设置到元素之前进行用户交互。 这可以像用户点击屏幕一样简单。
2. 在 Mobile Safari（iOS）上，交互式元素只能通过用户手势（例如，作为按钮点击的结果调用 setFocus）获得焦点。

基本用法

以下示例演示了如何使用 setFocus API 在用户点击按钮时请求输入焦点。

路由

开发人员可以使用 ionViewDidEnter 生命周期事件在进入页面时将焦点设置到元素。

Angular

/* example.component.ts */
import { Component, ViewChild } from '@angular/core';
import { IonInput } from '@ionic/angular';

@Component({
  selector: 'app-example',
  templateUrl: './example.component.html',
})
export class ExampleComponent {
  @ViewChild('input') input!: IonInput;

  ionViewDidEnter() {
    this.input.setFocus();
  }
}

React

import React, { useRef } from 'react';
import { IonInput, IonPage, useIonViewDidEnter } from '@ionic/react';

const Home = () => {
  const input = useRef<HTMLIonInputElement>(null);

  useIonViewDidEnter(() => {
    input.current?.setFocus();
  });

  return (
    <IonPage>
      <IonInput ref={input} label="setFocus" labelPlacement="floating"></IonInput>
    </IonPage>
  );
};

export default Home;

Vue

<template>
  <ion-page>
    <ion-input ref="input" label="setFocus" label-placement="floating"></ion-input>
  </ion-page>
</template>

<script setup lang="ts">
  import { IonInput, IonPage, onIonViewDidEnter } from '@ionic/vue';
  import { ref } from 'vue';

  const input = ref();
  onIonViewDidEnter(() => {
    requestAnimationFrame(() => {
      // requestAnimationFrame is currently required due to:
      // https://github.com/ionic-team/ionic-framework/issues/24434
      input.value.$el.setFocus();
    });
  });
</script>

叠加层

开发人员可以使用 didPresent 生命周期事件在呈现叠加层时将焦点设置到元素。

Javascript

<ion-modal>
  <ion-input></ion-input>
</ion-modal>

<script>
  const modal = document.querySelector('ion-modal');
  modal.addEventListener('didPresent', () => {
    const input = modal.querySelector('ion-input');
    input.setFocus();
  });
</script>

Angular

/* example.component.ts */
import { Component, ViewChild } from '@angular/core';
import { IonInput } from '@ionic/angular';

@Component({
  selector: 'app-example',
  templateUrl: './example.component.html',
})
export class ExampleComponent {
  @ViewChild('input') input!: IonInput;

  onDidPresent() {
    this.input.setFocus();
  }
}

<!-- example.component.html -->
<ion-modal (didPresent)="onDidPresent()">
  <ion-input #input></ion-input>
</ion-modal>

React

import React, { useRef } from 'react';
import { IonInput, IonModal } from '@ionic/react';

const Home = () => {
  const input = useRef<HTMLIonInputElement>(null);

  const onDidPresent = () => {
    input.current?.setFocus();
  };

  return (
    <IonModal onDidPresent={onDidPresent}>
      <IonInput ref={input}></IonInput>
    </IonModal>
  );
};

export default Home;

Vue

<template>
  <ion-modal @didPresent="onDidPresent">
    <ion-input ref="input"></ion-input>
  </ion-modal>
</template>

<script setup lang="ts">
  import { IonInput, IonModal } from '@ionic/vue';
  import { ref } from 'vue';

  const input = ref();

  function onDidPresent() {
    input.value.$el.setFocus();
  }
</script>

辅助技术焦点管理

默认情况下，单页应用程序在浏览器或 webview 中没有内置方式通知屏幕阅读器活动视图已更改。 这意味着依赖辅助技术的用户并不总是知道导航事件是否发生。

启用 focusManagerPriority 配置 的开发人员可以在页面转换期间将焦点管理委托给 Ionic。 启用后，Ionic 会根据配置选项将焦点移动到正确的元素。 这将通知屏幕阅读器导航事件已发生。

类型

type FocusManagerPriority = 'content' | 'heading' | 'banner';

内容类型

下表说明了每个内容类型代表的内容。

类型	描述	Ionic 组件	语义 HTML 等效项	地标等效项
内容	视图的主要部分。	内容	main	role="main"
标题	视图的标题。	标题	h1	role="heading" 和 aria-level="1"
横幅	视图的页眉。	页眉	header	role="banner"

重要

开发人员应为每个视图上的主要 标题 指定 role="heading" 和 aria-level="1"。 由于可以在单个视图中使用多个 标题 组件，因此 Ionic 不会自动分配这些属性。

指定优先级

配置应按优先级递减的顺序指定。 在以下示例中，Ionic 将始终首先将焦点设置到标题。 如果视图没有标题，Ionic 才会继续执行下一个焦点优先级，即横幅。

focusManagerPriority: ['heading', 'banner'];

实现说明

• 在指定焦点优先级时，浏览器可能仍然会在该焦点优先级内移动焦点。 例如，在指定 'content' 焦点优先级时，Ionic 会将焦点移动到内容。 但是，浏览器随后可能会在该内容内将焦点移动到第一个可聚焦元素（例如按钮）。
• 如果在视图中找不到任何焦点优先级，Ionic 将改为将焦点设置到视图本身，以确保焦点通常会移动到正确的位置。 然后，浏览器可能会调整视图内的焦点。
• 在从当前视图导航到上一个视图时，Ionic 会将焦点移回呈现当前视图的元素。
• 焦点管理器可以在每个视图的基础上被覆盖，如 使用路由进行手动焦点管理 中所示。