input.focus()

请求把键盘和指针输入焦点交给本应用的指定绘图面。宿主可以因后台状态、可信 UI 覆盖或系统策略拒绝。

Syntax

await host.input.focus(canvasId);

Parameters

canvasId: string：本应用仍然存活且可聚焦的绘图面。

Return value

{ focused: true }。成功返回前宿主已经获得焦点；若应用声明了 input.focusChange，对应事件必须在方法成功返回前入队。不能聚焦时以 HostError 失败，不返回“已接受但结果未知”。

目标已经聚焦时幂等成功，不产生重复事件。从本应用另一绘图面切换时，旧面的 pointer cancel/失焦先入队，新面的得焦随后入队；两面的 reason 都是 requested。

Examples

async function activateEditor() {
  await host.input.focus('editor');
  drawFocusRing();
}

Errors

特有错误：denied、not-found、not-visible、limit-exceeded。不能用它从后台抢占系统焦点。

Requirements

• 能力：host:input.focus
• 用户激活：不需要；应用必须可见且没有可信宿主 UI 覆盖
• 信任档位：green

See also

input.focusChange、input.key、ime.openSession()