焦點事件

基本概念

• 焦點

  指向當前應(yīng)用界面上唯一的一個可交互元素，當用戶使用鍵盤、電視遙控器、車機搖桿/旋鈕等非指向性輸入設(shè)備與應(yīng)用程序進行間接交互時，基于焦點的導航和交互是重要的輸入手段。

• 默認焦點

  應(yīng)用打開或切換頁面后，若當前頁上存在可獲焦的組件，則樹形結(jié)構(gòu)的組件樹中第一個可獲焦的組件默認獲得焦點?？梢允褂?a rel="external nofollow" target="_blank" rel="external nofollow" target="_blank" >自定義默認焦點進行自定義指定。

• 獲焦

  指組件獲得了焦點，同一時刻，應(yīng)用中最多只有1個末端組件是獲焦的，且此時它的所有祖宗組件（整個組件鏈）均是獲焦的。當期望某個組件獲焦，須確保該組件及其所有的祖宗節(jié)點均是可獲焦的（focusable屬性為true）。

• 失焦

  指組件從獲焦狀態(tài)變成了非獲焦狀態(tài)，失去了焦點。組件失焦時，它的所有祖宗組件（失焦組件鏈）與新的獲焦組件鏈不相同的節(jié)點都會失焦。

• 走焦

  表示焦點在當前應(yīng)用中轉(zhuǎn)移的過程，走焦會帶來原焦點組件的失焦和新焦點組件的獲焦。應(yīng)用中焦點發(fā)生變化的方式按行為可分為兩類：

  • 主動走焦：指開發(fā)者/用戶主觀的行為導致焦點移動，包含：外接鍵盤上按下TAB/方向鍵、使用requestFocus主動給指定組件申請焦點、組件focusOnTouch屬性為true后點擊組件。
  • 被動走焦：指組件焦點因其他操作被動的轉(zhuǎn)移焦點，此特性為焦點系統(tǒng)默認行為，無法由開發(fā)者自由設(shè)定，例如當使用if-else語句將處于獲焦的組件刪除/將處于獲焦的組件（或其父組件）置成不可獲焦時、當頁面切換時。
• 焦點態(tài)

  獲焦組件的樣式，不同組件的焦點態(tài)樣式大同小異，默認情況下焦點態(tài)不顯示，僅使用外接鍵盤按下TAB鍵/方向鍵時才會觸發(fā)焦點態(tài)樣式出現(xiàn)。首次觸發(fā)焦點態(tài)顯示的TAB鍵/方向鍵不會觸發(fā)走焦。當應(yīng)用接收到點擊事件時（包括手指觸屏的按下事件和鼠標左鍵的按下事件），自動隱藏焦點態(tài)樣式。焦點態(tài)樣式由后端組件定義，開發(fā)者無法修改。

走焦規(guī)則

走焦規(guī)則是指用戶使用“TAB鍵/SHIFT+TAB鍵/方向鍵”主動進行走焦，或焦點系統(tǒng)在執(zhí)行被動走焦時的順序規(guī)則。組件的走焦規(guī)則默認由走焦系統(tǒng)定義，由焦點所在的容器決定。

• 線性走焦：常見的容器有Flex、Row、Column、List，這些都是典型的單方向容器，組件在這些容器內(nèi)的排列都是線性的，那么走焦規(guī)則也是線性的。走焦的方向和方向鍵的方向一致。
  圖1 線性走焦示意圖
  

  例如Row容器，使用方向鍵左右（←/→）即可將焦點在相鄰的2個可獲焦組件之間來回切換。

• 十字走焦：使用方向鍵上(↑)下(↓)左(←)右(→)可以使焦點在相鄰的組件上切換。典型的是Grid容器，如下圖：
  圖2 Grid組件十字走焦示意圖
  
  說明

  • TAB/SHIFT+TAB鍵在以上兩種走焦規(guī)則上的功能和方向鍵一致。TAB鍵等同于“先執(zhí)行方向鍵右，若無法走焦，再執(zhí)行方向鍵下”，SHIFT+TAB鍵等同于“先執(zhí)行方向鍵左，若無法走焦，再執(zhí)行方向鍵上”。
  • 觸發(fā)走焦的按鍵是按下的事件（DOWN事件）。
  • 刪除組件、設(shè)置組件無法獲焦后，會使用線性走焦規(guī)則，自動先往被刪除/Unfocusable組件的前置兄弟組件上走焦，無法走焦的話，再往后置兄弟組件上走焦。
• tabIndex走焦：給組件設(shè)置tabIndex通用屬性，自定義組件的TAB鍵/SHIFT+TAB鍵的走焦順序。
• 區(qū)域走焦：給容器組件設(shè)置tabIndex通用屬性，再結(jié)合groupDefaultFocus通用屬性，自定義容器區(qū)域的TAB鍵/SHIFT+TAB鍵的走焦順序和默認獲焦組件。
• 走焦至容器組件規(guī)則：當焦點走焦到容器（該容器沒有配置groupDefaultFocus）上時，若該容器組件為首次獲焦，則會先計算目標容器組件的子組件的區(qū)域位置，得到距離目標容器中心點最近的子組件，焦點會走到目標容器上的該子組件上。若該容器非首次獲焦，焦點會自動走焦到上一次目標容器中獲焦的子組件。
• 焦點交互：當某組件獲焦時，該組件的固有點擊任務(wù)或開發(fā)者綁定的onClick回調(diào)任務(wù)，會自動掛載到空格/回車按鍵上，當按下按鍵時，任務(wù)就和手指/鼠標點擊一樣被執(zhí)行。

監(jiān)聽組件的焦點變化

onFocus(event: () => void)

設(shè)置組件是否獲焦

通過focusable接口設(shè)置組件是否可獲焦：

focusable(value: boolean)

按照組件的獲焦能力可大致分為三類：

• 默認可獲焦的組件，通常是有交互行為的組件，例如Button、Checkbox，TextInput組件，此類組件無需設(shè)置任何屬性，默認即可獲焦。
• 有獲焦能力，但默認不可獲焦的組件，典型的是Text、Image組件，此類組件缺省情況下無法獲焦，若需要使其獲焦，可使用通用屬性focusable(true)使能。
• 無獲焦能力的組件，通常是無任何交互行為的展示類組件，例如Blank、Circle組件，此類組件即使使用focusable屬性也無法使其可獲焦。

自定義默認焦點

defaultFocus(value: boolean)

焦點系統(tǒng)在頁面初次構(gòu)建完成時，會搜索當前頁下的所有組件，找到第一個綁定了defaultFocus(true)的組件，然后將該組件置為默認焦點，若無任何組件綁定defaultFocus(true)，則將第一個找到的可獲焦的組件置為默認焦點。

以如下應(yīng)用為例，應(yīng)用布局如下：

以下是實現(xiàn)該應(yīng)用的示例代碼，且示例代碼中沒有設(shè)置defaultFocus：

// xxx.ets
import promptAction from '@ohos.promptAction';

class MyDataSource implements IDataSource {
  private list: number[] = [];
  private listener: DataChangeListener;

  constructor(list: number[]) {
    this.list = list;
  }

  totalCount(): number {
    return this.list.length;
  }

  getData(index: number): any {
    return this.list[index];
  }

  registerDataChangeListener(listener: DataChangeListener): void {
    this.listener = listener;
  }

  unregisterDataChangeListener() {
  }
}

@Entry
@Component
struct SwiperExample {
  private swiperController: SwiperController = new SwiperController()
  private data: MyDataSource = new MyDataSource([])

  aboutToAppear(): void {
    let list = []
    for (let i = 1; i <= 4; i++) {
      list.push(i.toString());
    }
    this.data = new MyDataSource(list);
  }

  build() {
    Column({ space: 5 }) {
      Swiper(this.swiperController) {
        LazyForEach(this.data, (item: string) => {
          Row({ space: 20 }) {
            Column() {
              Button('1').width(200).height(200)
                .fontSize(40)
                .backgroundColor('#dadbd9')
            }

            Column({ space: 20 }) {
              Row({ space: 20 }) {
                Button('2')
                  .width(100)
                  .height(100)
                  .fontSize(40)
                  .type(ButtonType.Normal)
                  .borderRadius(20)
                  .backgroundColor('#dadbd9')
                Button('3')
                  .width(100)
                  .height(100)
                  .fontSize(40)
                  .type(ButtonType.Normal)
                  .borderRadius(20)
                  .backgroundColor('#dadbd9')
              }

              Row({ space: 20 }) {
                Button('4')
                  .width(100)
                  .height(100)
                  .fontSize(40)
                  .type(ButtonType.Normal)
                  .borderRadius(20)
                  .backgroundColor('#dadbd9')
                Button('5')
                  .width(100)
                  .height(100)
                  .fontSize(40)
                  .type(ButtonType.Normal)
                  .borderRadius(20)
                  .backgroundColor('#dadbd9')
              }

              Row({ space: 20 }) {
                Button('6')
                  .width(100)
                  .height(100)
                  .fontSize(40)
                  .type(ButtonType.Normal)
                  .borderRadius(20)
                  .backgroundColor('#dadbd9')
                Button('7')
                  .width(100)
                  .height(100)
                  .fontSize(40)
                  .type(ButtonType.Normal)
                  .borderRadius(20)
                  .backgroundColor('#dadbd9')
              }
            }
          }
          .width(480)
          .height(380)
          .justifyContent(FlexAlign.Center)
          .borderWidth(2)
          .borderColor(Color.Gray)
          .backgroundColor(Color.White)
        }, item => item)
      }
      .cachedCount(2)
      .index(0)
      .interval(4000)
      .indicator(true)
      .loop(true)
      .duration(1000)
      .itemSpace(0)
      .curve(Curve.Linear)
      .onChange((index: number) => {
        console.info(index.toString());
      })
      .margin({ left: 20, top: 20, right: 20 })

      Row({ space: 40 }) {
        Button('←')
          .fontSize(40)
          .fontWeight(FontWeight.Bold)
          .fontColor(Color.Black)
          .backgroundColor(Color.Transparent)
          .onClick(() => {
            this.swiperController.showPrevious();
          })
        Button('→')
          .fontSize(40)
          .fontWeight(FontWeight.Bold)
          .fontColor(Color.Black)
          .backgroundColor(Color.Transparent)
          .onClick(() => {
            this.swiperController.showNext();
          })
      }
      .width(480)
      .height(50)
      .justifyContent(FlexAlign.Center)
      .borderWidth(2)
      .borderColor(Color.Gray)
      .backgroundColor('#f7f6dc')

      Row({ space: 40 }) {
        Button('Cancel')
          .fontSize(30)
          .fontColor('#787878')
          .type(ButtonType.Normal)
          .width(140)
          .height(50)
          .backgroundColor('#dadbd9')
        
        Button('OK')
          .fontSize(30)
          .fontColor('#787878')
          .type(ButtonType.Normal)
          .width(140)
          .height(50)
          .backgroundColor('#dadbd9')
          .onClick(() => {
            promptAction.showToast({ message: 'Button OK on clicked' });
          })
      }
      .width(480)
      .height(80)
      .justifyContent(FlexAlign.Center)
      .borderWidth(2)
      .borderColor(Color.Gray)
      .backgroundColor('#dff2e4')
      .margin({ left: 20, bottom: 20, right: 20 })
    }.backgroundColor('#f2f2f2')
    .margin({ left: 50, top: 50, right: 20 })
  }
}

自定義TAB鍵走焦順序

tabIndex(index: number)

tabIndex用于設(shè)置自定義TAB鍵走焦順序，默認值為0。使用“TAB/Shift+TAB鍵”走焦時（方向鍵不影響），系統(tǒng)會自動獲取到所有配置了tabIndex大于0的組件，然后按照遞增/遞減排序進行走焦。

groupDefaultFocus

groupDefaultFocus(value: boolean)

自定義TAB鍵走焦順序中所展示的使用tabIndex完成快速走焦的能力有如下問題：

每個區(qū)域（白色/黃色/綠色三個區(qū)域）都設(shè)置了某個組件為tabIndex節(jié)點（白色-Button1、黃色-左箭頭、綠色-ButtonOK），但這樣設(shè)置之后，只能在這3個組件上按TAB/ShiftTab鍵走焦時會有快速走焦的效果。

解決方案是給每個區(qū)域的容器設(shè)置tabIndex，但是這樣設(shè)置的問題是：第一次走焦到容器上時，獲焦的子組件是默認的第一個可獲焦組件，并不是自己想要的組件（Button1、左箭頭、ButtonOK）。

這樣便引入了groupDefaultFocus通用屬性，參數(shù)：boolean，默認值：false。

用法需和tabIndex組合使用，使用tabIndex給區(qū)域（容器）綁定走焦順序，然后給Button1、左箭頭、ButtonOK綁定groupDefaultFocus(true)，這樣在首次走焦到目標區(qū)域（容器）上時，它的綁定了groupDefaultFocus(true)的子組件同時獲得焦點。

// xxx.ets
import promptAction from '@ohos.promptAction';

class MyDataSource implements IDataSource {
  private list: number[] = [];
  private listener: DataChangeListener;

  constructor(list: number[]) {
    this.list = list;
  }

  totalCount(): number {
    return this.list.length;
  }

  getData(index: number): any {
    return this.list[index];
  }

  registerDataChangeListener(listener: DataChangeListener): void {
    this.listener = listener;
  }

  unregisterDataChangeListener() {
  }
}

@Entry
@Component
struct SwiperExample {
  private swiperController: SwiperController = new SwiperController()
  private data: MyDataSource = new MyDataSource([])

  aboutToAppear(): void {
    let list = []
    for (let i = 1; i <= 4; i++) {
      list.push(i.toString());
    }
    this.data = new MyDataSource(list);
  }

  build() {
    Column({ space: 5 }) {
      Swiper(this.swiperController) {
        LazyForEach(this.data, (item: string) => {
          Row({ space: 20 }) {    // 設(shè)置該Row組件為tabIndex的第一個節(jié)點
            Column() {
              Button('1').width(200).height(200)
                .fontSize(40)
                .backgroundColor('#dadbd9')
                .groupDefaultFocus(true)    // 設(shè)置Button-1為第一個tabIndex的默認焦點
            }

            Column({ space: 20 }) {
              Row({ space: 20 }) {
                Button('2')
                  .width(100)
                  .height(100)
                  .fontSize(40)
                  .type(ButtonType.Normal)
                  .borderRadius(20)
                  .backgroundColor('#dadbd9')
                Button('3')
                  .width(100)
                  .height(100)
                  .fontSize(40)
                  .type(ButtonType.Normal)
                  .borderRadius(20)
                  .backgroundColor('#dadbd9')
              }

              Row({ space: 20 }) {
                Button('4')
                  .width(100)
                  .height(100)
                  .fontSize(40)
                  .type(ButtonType.Normal)
                  .borderRadius(20)
                  .backgroundColor('#dadbd9')
                Button('5')
                  .width(100)
                  .height(100)
                  .fontSize(40)
                  .type(ButtonType.Normal)
                  .borderRadius(20)
                  .backgroundColor('#dadbd9')
              }

              Row({ space: 20 }) {
                Button('6')
                  .width(100)
                  .height(100)
                  .fontSize(40)
                  .type(ButtonType.Normal)
                  .borderRadius(20)
                  .backgroundColor('#dadbd9')
                Button('7')
                  .width(100)
                  .height(100)
                  .fontSize(40)
                  .type(ButtonType.Normal)
                  .borderRadius(20)
                  .backgroundColor('#dadbd9')
              }
            }
          }
          .width(480)
          .height(380)
          .justifyContent(FlexAlign.Center)
          .borderWidth(2)
          .borderColor(Color.Gray)
          .backgroundColor(Color.White)
          .tabIndex(1)
        }, item => item)
      }
      .cachedCount(2)
      .index(0)
      .interval(4000)
      .indicator(true)
      .loop(true)
      .duration(1000)
      .itemSpace(0)
      .curve(Curve.Linear)
      .onChange((index: number) => {
        console.info(index.toString());
      })
      .margin({ left: 20, top: 20, right: 20 })

      Row({ space: 40 }) {    // 設(shè)置該Row組件為第二個tabIndex節(jié)點
        Button('←')
          .fontSize(40)
          .fontWeight(FontWeight.Bold)
          .fontColor(Color.Black)
          .backgroundColor(Color.Transparent)
          .onClick(() => {
            this.swiperController.showPrevious();
          })
          .groupDefaultFocus(true)    // 設(shè)置Button-左箭頭為第二個tabIndex節(jié)點的默認焦點
        Button('→')
          .fontSize(40)
          .fontWeight(FontWeight.Bold)
          .fontColor(Color.Black)
          .backgroundColor(Color.Transparent)
          .onClick(() => {
            this.swiperController.showNext();
          })
      }
      .width(480)
      .height(50)
      .justifyContent(FlexAlign.Center)
      .borderWidth(2)
      .borderColor(Color.Gray)
      .backgroundColor('#f7f6dc')
      .tabIndex(2)

      Row({ space: 40 }) {    // 設(shè)置該Row組件為第三個tabIndex節(jié)點
        Button('Cancel')
          .fontSize(30)
          .fontColor('#787878')
          .type(ButtonType.Normal)
          .width(140)
          .height(50)
          .backgroundColor('#dadbd9')

        Button('OK')
          .fontSize(30)
          .fontColor('#787878')
          .type(ButtonType.Normal)
          .width(140)
          .height(50)
          .backgroundColor('#dadbd9')
          .defaultFocus(true)
          .onClick(() => {
            promptAction.showToast({ message: 'Button OK on clicked' });
          })
          .groupDefaultFocus(true)    // 設(shè)置Button-OK為第三個tabIndex節(jié)點的默認焦點
      }
      .width(480)
      .height(80)
      .justifyContent(FlexAlign.Center)
      .borderWidth(2)
      .borderColor(Color.Gray)
      .backgroundColor('#dff2e4')
      .margin({ left: 20, bottom: 20, right: 20 })
      .tabIndex(3)
    }.backgroundColor('#f2f2f2')
    .margin({ left: 50, top: 50, right: 20 })
  }
}

focusOnTouch

focusOnTouch(value: boolean)

點擊獲焦能力，參數(shù)：boolean，默認值：false（輸入類組件：TextInput、TextArea、Search、Web默認值是true）。

點擊是指使用觸屏或鼠標左鍵進行單擊，默認為false的組件，例如Button，不綁定該API時，點擊Button不會使其獲焦，當給Button綁定focusOnTouch(true)時，點擊Button會使Button立即獲得焦點。

給容器綁定focusOnTouch(true)時，點擊容器區(qū)域，會立即使容器的第一個可獲焦組件獲得焦點。

示例代碼：

// requestFocus.ets
import promptAction from '@ohos.promptAction';

@Entry
@Component
struct RequestFocusExample {
  @State idList: string[] = ['A', 'B', 'C', 'D', 'E', 'F', 'N']

  build() {
    Column({ space:20 }){
      Button("id: " + this.idList[0] + " focusOnTouch(true) + focusable(false)")
        .width(400).height(70).fontColor(Color.White).focusOnTouch(true)
        .focusable(false)
      Button("id: " + this.idList[1] + " default")
        .width(400).height(70).fontColor(Color.White)
      Button("id: " + this.idList[2] + " focusOnTouch(false)")
        .width(400).height(70).fontColor(Color.White).focusOnTouch(false)
      Button("id: " + this.idList[3] + " focusOnTouch(true)")
        .width(400).height(70).fontColor(Color.White).focusOnTouch(true)
    }.width('100%').margin({ top:20 })
  }
}

focusControl.requestFocus

focusControl.requestFocus(id: string)

主動申請焦點能力的全局方法，參數(shù)：string，參數(shù)表示被申請組件的id（通用屬性id設(shè)置的字符串）。