管理焦点

手动对焦管理

🌐 Manual Focus Management

Ionic 在诸如 Input、Searchbar 和 Textarea 等组件上提供了一个 setFocus API，允许开发者手动将焦点设置到某个元素上。这个 API 应该替代 autofocus 属性使用，并在以下情况下调用:

🌐 Ionic provides a setFocus API on components such as Input, Searchbar, and Textarea that allows developers to manually set focus to an element. This API should be used in place of the autofocus attribute and called within:

• ionViewDidEnter 生命周期事件用于路由应用在进入页面时触发。
• 当覆盖显示时，覆盖的 didPresent 生命周期事件。
• appload 事件适用于当应用加载时的原生 JavaScript 应用。
• 用户手势或交互的结果。

为什么不自动对焦？

🌐 Why not autofocus?

autofocus 属性是一个标准的 HTML 属性，它允许开发者在页面加载时将焦点设置到某个元素上。该属性通常用于将焦点设置到页面上的第一个输入元素上。然而，autofocus 属性在路由应用中在页面间导航时可能会引发问题。这是因为 autofocus 属性会在页面加载时将焦点设置到该元素，但在页面再次访问时不会将焦点设置到该元素。可以在 MDN Web Docs 中了解更多关于 autofocus 属性的信息。

🌐 The autofocus attribute is a standard HTML attribute that allows developers to set focus to an element when a page loads. This attribute is commonly used to set focus to the first input element on a page. However, the autofocus attribute can cause issues in routing applications when navigating between pages. This is because the autofocus attribute will set focus to the element when the page loads, but will not set focus to the element when the page is revisited. Learn more about the autofocus attribute in the MDN Web Docs.

平台限制

🌐 Platform Restrictions

在使用 setFocus API 时，你应注意以下平台限制，包括：

🌐 There are platform restrictions you should be aware of when using the setFocus API, including:

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

基本用法

🌐 Basic Usage

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

🌐 The example below demonstrates how to use the setFocus API to request focus on an input when the user clicks a button.

路由

🌐 Routing

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

🌐 Developers can use the ionViewDidEnter lifecycle event to set focus to an element when a page is entered.

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>

叠加层

🌐 Overlays

开发者可以使用 didPresent 生命周期事件在弹出层显示时将焦点设置到某个元素上。

🌐 Developers can use the didPresent lifecycle event to set focus to an element when an overlay is presented.

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();
  }
}

<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>

辅助技术焦点管理

🌐 Assistive Technology Focus Management

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

🌐 By default, Single Page Applications have no built-in way of informing screen readers that the active view has changed in a browser or webview. This means that users who rely on assistive technology do not always know if a navigation event occurred.

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

🌐 Developers who enable the focusManagerPriority config can delegate focus management to Ionic during page transitions. When enabled, Ionic will move focus to the correct element as specified in the config option. This will inform screen readers that a navigation event occurred.

类型

🌐 Types

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

内容类型

🌐 Content Types

下表解释了每种内容类型代表的含义：

🌐 The following table explains what each content type represents:

类型	描述	Ionic 组件	语义化 HTML 对应	地标对应
content	视图的主要部分。	Content	main	role="main"
heading	视图的标题。	Title	h1	role="heading" 与 aria-level="1"
banner	视图的页眉。	Header	header	role="banner"

important

开发者应将 role="heading" 和 aria-level="1" 分配给每个视图中的主 Title。由于单个视图中可以使用多个 Title 组件，Ionic 不会自动分配这些属性。

指定优先级

🌐 Specifying Priority

配置应按优先级递减的顺序指定。在下面的示例中，Ionic 将始终首先聚焦标题。只有当视图没有标题时，Ionic 才会继续下一个聚焦优先级，即横幅：

🌐 The config should be specified in order of decreasing priority. In the following example, Ionic will always focus headings to start. Ionic only proceeds to the next focus priority, banner, if a view does not have a heading:

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

实现说明

🌐 Implementation Notes

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