管理焦點

手動焦點管理

Ionic 在諸如 Input、Searchbar 和 Textarea 等元件上提供 setFocus API，允許開發人員手動將焦點設定到元素。此 API 應取代 autofocus 屬性，並在以下情況下呼叫：

• 路由應用程式在進入頁面時的 ionViewDidEnter 生命週期事件。
• 覆蓋層在呈現時的 didPresent 生命週期事件。
• 在應用程式載入時，香草 JavaScript 應用程式的 appload 事件。
• 使用者手勢或互動的結果。

為什麼不使用 autofocus？

autofocus 屬性是一個標準的 HTML 屬性，允許開發人員在頁面載入時將焦點設定到元素。此屬性通常用於將焦點設定到頁面上的第一個輸入元素。但是，當在頁面之間導航時，autofocus 屬性可能會在路由應用程式中引起問題。這是因為 autofocus 屬性會在頁面載入時將焦點設定到元素，但不會在重新訪問頁面時將焦點設定到元素。在 MDN Web Docs 中了解更多關於 autofocus 屬性的資訊。

平台限制

使用 setFocus API 時，您應該注意一些平台限制，包括：

1. Android 需要使用者互動才能將焦點設定到元素。這可以簡單到使用者點擊螢幕。
2. 互動元素只能作為行動 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 等效項	地標等效項
content	視圖的主要部分。	Content	main	role="main"
heading	視圖的標題。	Title	h1	role="heading" 搭配 aria-level="1"
banner	視圖的標頭。	Header	header	role="banner"

重要

開發人員應該將 role="heading" 和 aria-level="1" 指派給每個視圖上的主要 Title。由於可以在單個視圖中使用多個 Title 元件，因此 Ionic 不會自動指派這些屬性。

指定優先順序

配置應該依照優先順序遞減的順序指定。在以下範例中，Ionic 將始終優先聚焦標題。如果視圖沒有標題，Ionic 只會繼續下一個焦點優先順序，即橫幅。

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

實作注意事項

• 指定焦點優先順序時，瀏覽器可能仍然會在該焦點優先順序內移動焦點。例如，當指定 'content' 焦點優先順序時，Ionic 會將焦點移動到內容。但是，瀏覽器可能會將焦點移動到該內容中的第一個可聚焦元素，例如按鈕。
• 如果在視圖中找不到任何焦點優先順序，Ionic 會將焦點移動到視圖本身，以確保焦點通常會移動到正確的位置。然後，瀏覽器可能會在視圖中調整焦點。
• 從目前視圖導覽到上一個視圖時，Ionic 會將焦點移回呈現目前視圖的元素。
• 可以按照使用路由進行手動焦點管理中所示，在每個視圖的基礎上覆寫焦點管理器。