HarmonyOS PC焦点系统建模与键盘事件分发实践

1. HarmonyOS PC 焦点系统建模的核心挑战

在开发HarmonyOS PC应用时，焦点管理往往成为最令人头疼的问题之一。我见过太多项目因为焦点处理不当而陷入困境：Tab键乱跳、键盘输入无响应、多窗口切换后焦点丢失...这些问题看似是简单的交互bug，实则暴露了系统架构层面的深层缺陷。

焦点问题的本质在于，大多数开发者错误地将它视为UI状态的一部分。我们习惯性地在组件内部维护isFocused这样的状态变量，然后基于这个状态来决定键盘事件的处理。这种看似直观的做法，在PC场景下却会引发一系列连锁反应：

typescript复制// 典型的错误实现
@State isFocused: boolean = false;

onFocus() {
  this.isFocused = true;
}

onBlur() {
  this.isFocused = false;
}

问题在于，PC端的焦点不仅关乎视觉反馈，更关键的是它决定了：

1. 键盘事件的接收者
2. 快捷键的生效范围
3. 输入法的激活状态
   当这些关键功能分散在各个组件中自行判断时，系统就失去了对输入控制的统一管理权。

2. 焦点系统的本质：输入路由权

2.1 从UI状态到输入所有权

PC环境下的焦点本质上是一种"输入路由权"的分配机制。它需要明确回答一个核心问题："当前用户的输入应该由哪个组件接收？"这与移动端简单的触摸反馈有着本质区别。

在真实项目中，我见过最典型的反模式是组件各自为政地管理焦点：

typescript复制TextInput {
  onFocus() { /* 自行处理 */ }
}

List {
  onFocus() { /* 自行处理 */ }
}

这种架构下，没有任何一个地方能够全局掌握当前的焦点归属，导致：

• 多个组件可能同时声明拥有焦点
• 窗口切换时焦点状态混乱
• 键盘事件分发不可预测

2.2 集中式焦点模型的优势

正确的做法是将焦点建模为系统的核心基础设施。通过建立明确的FocusModel，我们可以：

1. 提供单一的真相来源（Single Source of Truth）
2. 统一管理焦点切换逻辑
3. 集中处理输入事件分发

这种集中式管理带来了几个关键优势：

• 焦点状态可预测
• 行为一致性保障
• 多窗口协同支持
• 无障碍功能扩展性

3. 焦点系统的核心建模方案

3.1 FocusModel基础实现

让我们从最核心的FocusModel开始构建：

typescript复制// pc/focus/FocusModel.ts
export class FocusModel {
  private focusedId?: string;

  focus(id: string) {
    this.focusedId = id;
  }

  blur(id: string) {
    if (this.focusedId === id) {
      this.focusedId = undefined;
    }
  }

  isFocused(id: string): boolean {
    return this.focusedId === id;
  }

  current(): string | undefined {
    return this.focusedId;
  }
}

这个基础模型有几个关键设计点：

1. 使用字符串ID而非组件引用，避免内存泄漏
2. 提供原子化的focus/blur操作
3. 查询接口保持幂等性

3.2 可聚焦对象协议

为了规范组件行为，我们需要定义明确的接口：

typescript复制// pc/focus/Focusable.ts
export interface Focusable {
  readonly id: string;
  canFocus(): boolean;
  onFocus?(): void;
  onBlur?(): void;
}

组件实现这个接口时需要注意：

1. ID必须全局唯一且稳定
2. canFocus()应反映组件当前的可聚焦状态
3. 生命周期回调应避免副作用

3.3 焦点控制器实现

焦点切换逻辑应该集中管理：

typescript复制// pc/focus/FocusController.ts
export class FocusController {
  constructor(
    private focusModel: FocusModel,
    private registry: Map<string, Focusable>
  ) {}

  requestFocus(target: Focusable) {
    if (!target.canFocus()) return;
    
    // 先模糊当前焦点
    const current = this.focusModel.current();
    if (current) {
      this.registry.get(current)?.onBlur?.();
    }
    
    // 设置新焦点
    this.focusModel.focus(target.id);
    target.onFocus?.();
  }
}

控制器的关键职责包括：

1. 验证焦点请求的合法性
2. 管理焦点切换的生命周期
3. 维护焦点对象注册表

4. 键盘事件分发机制

4.1 集中式事件处理

键盘事件分发是焦点系统的核心应用场景。错误的实现方式：

typescript复制// 反模式：组件自行处理
onKeyDown(e) {
  if (this.isFocused) {
    handleKey(e);
  }
}

正确的架构应该基于FocusModel：

typescript复制// pc/input/KeyboardManager.ts
export class KeyboardManager {
  constructor(
    private focusModel: FocusModel,
    private handlers: Map<string, KeyHandler>
  ) {}

  handleKeyDown(e: KeyboardEvent) {
    const focusedId = this.focusModel.current();
    if (!focusedId) return;
    
    const handler = this.handlers.get(focusedId);
    handler?.(e);
  }
}

这种设计实现了：

1. 单一事件监听点
2. 基于当前焦点的动态分发
3. 明确的处理责任链

4.2 快捷键处理策略

对于全局快捷键，建议采用分层处理：

typescript复制interface ShortcutHandler {
  match(e: KeyboardEvent): boolean;
  handle(e: KeyboardEvent): void;
}

class ShortcutManager {
  private globals: ShortcutHandler[] = [];
  private locals: Map<string, ShortcutHandler[]> = new Map();

  registerGlobal(handler: ShortcutHandler) {
    this.globals.push(handler);
  }

  registerLocal(scope: string, handler: ShortcutHandler) {
    if (!this.locals.has(scope)) {
      this.locals.set(scope, []);
    }
    this.locals.get(scope)!.push(handler);
  }

  handleKey(e: KeyboardEvent) {
    // 先处理全局快捷键
    for (const handler of this.globals) {
      if (handler.match(e)) {
        handler.handle(e);
        return;
      }
    }

    // 再处理当前焦点的本地快捷键
    const focusedId = focusModel.current();
    if (focusedId) {
      const handlers = this.locals.get(focusedId) || [];
      for (const handler of handlers) {
        if (handler.match(e)) {
          handler.handle(e);
          return;
        }
      }
    }

    // 最后交给常规键盘处理
    keyboardManager.handleKeyDown(e);
  }
}

5. 高级焦点导航策略

5.1 焦点顺序建模

Tab键导航需要明确的顺序定义：

typescript复制// pc/focus/FocusOrder.ts
export class FocusOrder {
  private order: string[] = [];
  private relations: Map<string, {next?: string, prev?: string}> = new Map();

  setOrder(ids: string[]) {
    this.order = [...ids];
    this.buildRelations();
  }

  private buildRelations() {
    this.relations.clear();
    for (let i = 0; i < this.order.length; i++) {
      const id = this.order[i];
      this.relations.set(id, {
        next: this.order[i + 1],
        prev: this.order[i - 1]
      });
    }
  }

  next(current: string): string | undefined {
    return this.relations.get(current)?.next;
  }

  previous(current: string): string | undefined {
    return this.relations.get(current)?.prev;
  }
}

这个模型支持：

1. 显式的焦点顺序定义
2. 双向导航支持
3. 动态顺序更新

5.2 方向键导航

对于复杂布局，需要更智能的导航策略：

typescript复制// pc/focus/SpatialNavigation.ts
export class SpatialNavigation {
  private positions: Map<string, DOMRect> = new Map();

  updatePosition(id: string, rect: DOMRect) {
    this.positions.set(id, rect);
  }

  findInDirection(from: string, direction: 'up'|'down'|'left'|'right'): string|undefined {
    const sourceRect = this.positions.get(from);
    if (!sourceRect) return undefined;

    let bestMatch: {id: string, distance: number} | undefined;
    
    for (const [id, rect] of this.positions) {
      if (id === from) continue;

      if (direction === 'right' && rect.left >= sourceRect.right) {
        const distance = rect.left - sourceRect.right;
        if (!bestMatch || distance < bestMatch.distance) {
          bestMatch = {id, distance};
        }
      }
      // 其他方向类似处理...
    }

    return bestMatch?.id;
  }
}

6. 多窗口焦点管理

6.1 Workspace焦点隔离

PC环境需要支持多窗口的独立焦点：

typescript复制// pc/focus/WorkspaceFocus.ts
export class WorkspaceFocus {
  private workspaces: Map<string, FocusModel> = new Map();
  private activeWorkspace?: string;

  activate(workspaceId: string) {
    if (this.activeWorkspace) {
      // 冻结当前工作区焦点
      const model = this.workspaces.get(this.activeWorkspace);
      model?.blurAll();
    }
    
    this.activeWorkspace = workspaceId;
    // 恢复新工作区焦点
    const model = this.ensureModel(workspaceId);
    model.restore();
  }

  private ensureModel(workspaceId: string): FocusModel {
    if (!this.workspaces.has(workspaceId)) {
      this.workspaces.set(workspaceId, new FocusModel());
    }
    return this.workspaces.get(workspaceId)!;
  }

  getActiveModel(): FocusModel | undefined {
    if (!this.activeWorkspace) return undefined;
    return this.workspaces.get(this.activeWorkspace);
  }
}

6.2 窗口间焦点传递

有时需要在窗口间智能转移焦点：

typescript复制// pc/focus/InteropFocus.ts
export class InteropFocus {
  constructor(
    private workspaces: WorkspaceFocus,
    private focusOrder: FocusOrder
  ) {}

  transferToWindow(targetWindow: string) {
    const sourceModel = this.workspaces.getActiveModel();
    if (!sourceModel) return;

    const lastFocused = sourceModel.current();
    if (!lastFocused) return;

    this.workspaces.activate(targetWindow);
    const targetModel = this.workspaces.getActiveModel();
    if (!targetModel) return;

    // 尝试找到对应组件
    const counterpart = findCounterpart(lastFocused);
    if (counterpart) {
      targetModel.focus(counterpart);
    }
  }
}

7. 实战中的经验与陷阱

7.1 常见问题排查

在真实项目中，我们总结出这些典型问题：

7.2 性能优化技巧

1. 懒注册：只在组件挂载时注册焦点对象
2. 事件节流：对高频焦点变化进行批处理
3. 空间索引：使用R-tree优化空间导航计算
4. 内存管理：及时清理卸载组件的焦点状态

7.3 无障碍支持

良好的焦点模型天然支持无障碍：

typescript复制// pc/a11y/FocusTracker.ts
export class FocusTracker {
  private observer: MutationObserver;

  constructor(private root: HTMLElement) {
    this.observer = new MutationObserver(this.handleMutations);
  }

  start() {
    this.observer.observe(this.root, {
      subtree: true,
      attributeFilter: ['tabindex'],
      childList: true
    });
  }

  private handleMutations = (mutations: MutationRecord[]) => {
    // 检测可聚焦元素变化
    // 更新FocusOrder模型
  };
}

8. 架构演进建议

随着项目复杂度提升，可以考虑：

1. 焦点历史栈：支持"返回上一个焦点"功能
2. 焦点作用域：实现模态对话框的焦点约束
3. 远程焦点同步：用于分布式UI场景
4. 焦点策略插件：支持可扩展的导航规则

在HarmonyOS生态中，一个健壮的焦点系统应该被视为应用基础设施的核心部分。它不仅仅是交互细节的实现，更是确保整个输入系统可靠性的关键架构设计。