HTMLElement:focus() 方法

HTMLElement.focus() 方法用于将焦点设置到指定的元素上(如果该元素可以获得焦点)。获得焦点的元素是默认情况下将接收键盘和其他类似事件的元素。

默认情况下,浏览器会在将焦点设置到元素后将其滚动到视图中,并且它也可能会提供获得焦点的元素的可视指示(通常是在元素周围显示一个“焦点环”)。参数选项用于禁用默认滚动并强制在元素上显示可视指示。

语法

js
focus()
focus(options)

参数

options 可选

一个用于控制聚焦过程各个方面的可选对象。此对象可能包含以下属性

preventScroll 可选

一个布尔值,指示浏览器是否应该滚动文档以将新获得焦点的元素滚动到视图中。preventScrollfalse(默认值)表示浏览器将在聚焦元素后将其滚动到视图中。如果将 preventScroll 设置为 true,则不会发生滚动。

focusVisible 可选 实验性

一个布尔值,应将其设置为 true 以强制显示元素获得焦点的可视指示,或设置为 false 以阻止显示可视指示。如果未指定此属性,则浏览器将在确定这可以改善用户可访问性时提供可视指示。

返回值

无(undefined)。

示例

聚焦文本字段

此示例使用按钮将焦点设置到文本字段上。

HTML

html
<input id="myTextField" value="Text field." />
<button id="focusButton">Click to set focus on the text field</button>

JavaScript

以下代码添加了一个事件处理程序,以便在按下按钮时将焦点设置到文本字段上。请注意,大多数浏览器都会自动为获得焦点的文本字段添加可视指示(“焦点环”),因此代码未将 focusVisible 设置为 true

js
document.getElementById("focusButton").addEventListener("click", () => {
  document.getElementById("myTextField").focus();
});

结果

选择按钮以将焦点设置到文本字段上。

聚焦按钮

此示例演示如何将焦点设置到按钮元素上。

HTML

首先,我们定义了三个按钮。中间和右侧按钮都将焦点设置到最左侧的按钮上。最右侧的按钮还将指定 focusVisible

html
<button id="myButton">Button</button>
<button id="focusButton">Click to set focus on "Button"</button>
<button id="focusButtonVisibleIndication">
  Click to set focus and focusVisible on "Button"
</button>

JavaScript

以下代码为中间和右侧按钮的点击事件设置了处理程序。

js
document.getElementById("focusButton").addEventListener("click", () => {
  document.getElementById("myButton").focus();
});

document
  .getElementById("focusButtonVisibleIndication")
  .addEventListener("click", () => {
    document.getElementById("myButton").focus({ focusVisible: true });
  });

结果

选择中间按钮或最右侧按钮以将焦点设置到最左侧的按钮上。

浏览器通常不会在以编程方式设置焦点时在按钮元素上显示可视焦点指示,因此选择中间按钮的效果可能不明确。但是,如果您的浏览器支持 focusVisible 选项,则在选择最右侧按钮时,您应该会看到最左侧按钮上的焦点发生变化。

带滚动和不带滚动地聚焦

此示例显示了在将 preventScroll 设置为 truefalse(默认值)的情况下设置焦点的效果。

HTML

HTML 定义了两个按钮,用于设置屏幕外第三个按钮的焦点。

html
<button id="focus_scroll">Click to set focus on off-screen button</button>
<button id="focus_no_scroll">
  Click to set focus on offscreen button without scrolling
</button>

<div id="container">
  <button id="myButton" style="margin-top: 500px;">Button</button>
</div>

JavaScript

此代码在第一个和第二个按钮上设置了点击事件处理程序,以将焦点设置到最后一个按钮上。请注意,第一个处理程序没有指定 preventScroll 选项,因此将启用滚动到获得焦点的元素。

js
document.getElementById("focus_scroll").addEventListener("click", () => {
  document.getElementById("myButton").focus(); // default: {preventScroll:false}
});

document.getElementById("focus_no_scroll").addEventListener("click", () => {
  document.getElementById("myButton").focus({ preventScroll: true });
});

结果

选择第一个按钮以设置焦点并滚动到屏幕外的按钮。选择第二个按钮会设置焦点,但禁用滚动。

规范

规范
HTML 标准
# dom-focus-dev

注释

  • 如果从 mousedown 事件处理程序调用 HTMLElement.focus(),则必须调用 event.preventDefault() 以防止焦点离开 HTMLElement
  • 焦点相对于不同的 HTML 功能(如 tabindex阴影 DOM)的行为,以前未明确规定,已于 2019 年 10 月更新。有关更多信息,请参阅 WHATWG 博客

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅