Element

Element 是最通用的基类,Document 中的所有元素对象(即表示元素的对象)都继承自它。它只具有各种元素共有的方法和属性。更具体的类则继承自 Element。

例如,HTMLElement 接口是所有 HTML 元素的基本接口。同样,SVGElement 接口是所有 SVG 元素的基本接口,而 MathMLElement 接口则是 MathML 元素的基础接口。大多数功能是在这个类的更深层级的接口中被进一步制定的。

在 Web 平台的领域以外的语言,比如 XUL,通过 XULElement 接口,同样也实现了 Element 接口。

实例属性

Element 从其父接口 Node 以及该接口的父接口 EventTarget 继承属性。

Element.assignedSlot 只读

返回一个表示节点所插入的 <slot> 的 HTMLSlotElement 值。

Element.attributes 只读

返回一个 NamedNodeMap 对象,其中包含相应 HTML 元素的指定属性。

Element.childElementCount 只读

返回此元素的子元素个数。

Element.children 只读

返回此元素的子元素。

Element.classList 只读

返回该元素包含的所有 class 属性,是一个 DOMTokenList。

Element.className

一个字符串,表示这个元素的类。

Element.clientHeight 只读

返回代表元素内部高度的数值。

Element.clientLeft 只读

返回代表元素左边界宽度的数值。

Element.clientTop 只读

返回代表元素顶部边框宽度的数值。

Element.clientWidth 只读

返回代表元素内部宽度的数值。

Element.currentCSSZoom 只读

表示元素有效缩放尺寸的数字,如果元素未渲染,则为 1.0。

Element.elementTiming 实验性

一个字符串,反映了 elementtiming 属性,该属性在 PerformanceElementTiming API 中标记了一个观察元素。

Element.firstElementChild 只读

返回此元素的第一个子元素。

Element.id

一个字符串,表示此元素的 id 值。

Element.innerHTML

一个字符串,表示元素内容标记。

Element.lastElementChild 只读

返回此元素的最后一个子元素。

Element.localName 只读

一个字符串,代表元素限定名称的本地部分。

Element.namespaceURI 只读

元素对应的命名空间 URI,如果没有则返回 null。

Element.nextElementSibling 只读

一个 Element,树中紧跟给定元素的元素,如果没有同级节点,则为 null。

Element.outerHTML

一个字符串,代表元素的标记(包括其内容)。作为 setter 使用时,将用从给定字符串解析出的节点替换元素。

Element.part

代表元素的部分标识符(即使用 part 属性设置的标识符),以 DOMTokenList 的形式返回。

Element.prefix 只读

代表元素命名空间前缀的字符串,如果没有指定前缀,则为 null。

Element.previousElementSibling 只读

一个 Element,树中紧靠给定元素的元素,如果没有同级元素,则为 null。

Element.scrollHeight 只读

元素滚动视图高度的数值。

Element.scrollLeft

元素左滚动偏移量的数值。

Element.scrollLeftMax 非标准 只读

元素可能的最大左滚动偏移值。

Element.scrollTop

元素顶部垂直滚动的像素数。

Element.scrollTopMax 非标准 只读

元素可能的最大顶部滚动偏移值。

Element.scrollWidth 只读

代表元素滚动视图宽度的数值。

Element.shadowRoot 只读

返回元素挂载的开放影子根;如果没有开放影子根,则返回 null。

Element.slot

返回元素插入的影子 DOM 插槽的名称。

Element.tagName 只读

返回一个字符串,包含给定元素的标签名称。

ARIA 中包含的实例属性

Element 接口也包括以下属性。

Element.ariaAtomic

反映 aria-atomic 属性的字符串,表示辅助技术是否将根据 aria-relevant 属性定义的变更通知,显示全部或仅部分变更区域。

Element.ariaAutoComplete

反映 aria-autocomplete 属性的字符串,表示输入文本是否会触发显示一个或多个用户对组合框、搜索框或文本框的预期值的预测,并指定如果进行了预测将如何显示。

Element.ariaBrailleLabel

反映 aria-braillelabel 属性的字符串,该属性定义了元素的盲文标签。

Element.ariaBrailleRoleDescription

反映 aria-brailleroledescription 属性的字符串,该属性定义了元素的 ARIA 盲文角色描述。

Element.ariaBusy

反映 aria-busy 属性的字符串,表示元素是否正在被修改,因为辅助技术可能希望等到修改完成后再向用户展示。

Element.ariaChecked

反映 aria-checked属性的字符串,表示复选框、单选按钮和其他具有选中状态的部件的当前"选中"状态。

Element.ariaColCount

反映 aria-colcount 属性的字符串,该属性定义了表格、网格或树状网格中的列数。

Element.ariaColIndex

反映 aria-colindex 属性的字符串,该属性定义了元素的列索引或相对于表格、网格或树状网格中列总数的位置。

Element.ariaColIndexText

反映 aria-colindextext 属性的字符串,该属性定义了 aria-colindex 的人类可读文本替代。

Element.ariaColSpan

反映 aria-colspan 属性的字符串,该属性定义了表格、网格或树型网格中单元格或网格单元格所跨列数。

Element.ariaCurrent

反映 aria-current 属性的字符串,表示在一个容器或一组相关元素中代表当前项目的元素。

Element.ariaDescription

反映 aria-description 属性的字符串,该属性定义了描述或注释当前元素的字符串值。

Element.ariaDisabled

反映 aria-disabled 属性的字符串,表示该元素可感知但已禁用,因此不可编辑或以其他方式操作。

Element.ariaExpanded

反映 aria-expanded 属性的字符串,表示该元素拥有或控制的分组元素是展开还是折叠状态。

Element.ariaHasPopup

反映 aria-haspopup 属性的字符串,表示可由元素触发的交互式弹出元素(如菜单或对话框)的可用性和类型。

Element.ariaHidden

反映 aria-hidden 属性的字符串,表示元素是否暴露于无障碍 API。

Element.ariaInvalid

反映 aria-invalid 属性的字符串,表示输入的值不符合应用程序预期的格式。

Element.ariaKeyShortcuts

反映 aria-keyshortcuts 属性的字符串,表示作者为激活元素或将焦点赋予元素而实施的键盘快捷方式。

Element.ariaLabel

反映 aria-label 属性的字符串,该属性定义了标示当前元素的字符串值。

Element.ariaLevel

反映 aria-level 属性的字符串,该属性定义了结构中元素的层次级别。

Element.ariaLive

反映 aria-live 属性的字符串,表示元素将被更新,并描述了用户代理、辅助技术和用户可期望从实时区域获得的更新类型。

Element.ariaModal

反映 aria-modal 属性的字符串,表示元素在显示时是否为模态元素。

Element.ariaMultiline

反映 aria-multiline 属性的字符串,表示文本框是接受多行输入还是只接受单行输入。

Element.ariaMultiSelectable

反映 aria-multiselectable 属性的字符串,表示用户可以从当前可选后代中选择多个项目。

Element.ariaOrientation

反映 aria-orientation 属性的字符串,表示元素的方向是水平、垂直还是未知/模糊。

Element.ariaPlaceholder

反映 aria-placeholder 属性的字符串,它定义了一个简短的提示,目的是在控件无值时帮助用户输入数据。

Element.ariaPosInSet

反映 aria-posinset 属性的字符串,它定义了元素在当前列表项或树状项集合中的编号或位置。

Element.ariaPressed

反映 aria-pressed 属性的字符串,表示切换按钮当前的"按下"状态。

Element.ariaReadOnly

反映 aria-readonly 属性的字符串,表示该元素不可编辑,但在其他方面是可操作的。

Element.ariaRelevant 非标准

反映 aria-relevant 属性的字符串,表示当实时区域内的无障碍树被修改时,用户代理将触发哪些通知。该属性用于描述 aria-live 区域中哪些变化是相关的,应予以公布。

Element.ariaRequired

aria-required 属性的字符串,表示在提交表单前需要用户输入。

Element.ariaRoleDescription

反映 aria-roledescription 属性的字符串,它定义了一个元素的角色的人类可读、作者本地化描述。

Element.ariaRowCount

反映 aria-rowcount 属性的字符串,该属性定义了表格、网格或树状网格中的总行数。

Element.ariaRowIndex

反映 aria-rowindex 属性的字符串,它定义了元素的行索引或相对于表格、网格或树状网格中总行数的位置。

Element.ariaRowIndexText 实验性

反映 aria-rowindextext 属性的字符串,它定义了 aria-rowindex 的人类可读文本替代。

Element.ariaRowSpan

反映 aria-rowspan 属性的字符串,该属性定义了表格、网格或树型网格中单元格或网格单元格所跨行数。

Element.ariaSelected

反映 aria-selected 属性的字符串,表示具有选定状态的元素的当前"选定"状态。

Element.ariaSetSize

反映 aria-setsize 属性的字符串,该属性定义了当前列表项或树状项集合中的项数。

Element.ariaSort

反映 aria-sort 属性的字符串,表示表格或网格中的项目是按升序还是降序排序。

Element.ariaValueMax

反映 aria-valueMax 属性的字符串,该属性定义了范围部件允许的最大值。

Element.ariaValueMin

反映 aria-valueMin 属性的字符串,该属性定义了范围部件的最小允许值。

Element.ariaValueNow

反映 aria-valueNow 属性的字符串,该属性定义了范围部件的当前值。

Element.ariaValueText

反映 aria-valuetext 属性的字符串,该属性为范围部件定义了 aria-valuenow 的人类可读文本替代值。

Element.role

反映了显式设置的 role 属性的字符串,该属性提供了元素的语义角色。

从 ARIA 元素引用中反映的实例属性

这些属性反映了相应属性中由 id 引用指定的元素,但有一些注意事项。更多信息请参阅反射属性指南中的反射元素参考。

Element.ariaActiveDescendantElement

当焦点位于 composite 微件、combobox、textbox、group 或 application 时,代表当前活动元素的元素。反射了 aria-activedescendant 属性。

Element.ariaControlsElements

一个元素数组,其内容或存在由所应用的元素控制。反射了 aria-controls 属性。

Element.ariaDescribedByElements

一个元素数组,包含所应用元素的无障碍描述。反射了 aria-describedby 属性。

Element.ariaDetailsElements

一个元素数组,提供所应用元素的无障碍详细信息。反射了 aria-details 属性。

Element.ariaErrorMessageElements

一个元素数组,为其应用的元素提供错误信息。反射了 aria-errormessage 属性。

Element.ariaFlowToElements

一个元素数组,用于在内容的另一种阅读顺序中标识下一个(或多个)元素,用户可自行决定覆盖一般默认阅读顺序。反射了 aria-flowto 属性。

Element.ariaLabelledByElements

一个元素数组,为所应用的元素提供无障碍名称。反射了 aria-labelledby 属性。

Element.ariaOwnsElements

该元素所拥有的元素数组。当 DOM 层次结构不能用来表示父元素和子元素之间的关系时,它就用来定义父元素和子元素之间的视觉、功能或上下文关系。反射了 aria-owns 属性。

实例方法

Element 继承 Node 及其父接口 EventTarget 的方法。

Element.after()

在 Element 父节点的子节点列表中插入一组 Node 对象或字符串,位于 Element 之后。

Element.animate()

在元素上创建并运行动画的快捷方法。返回创建的动画对象实例。

Element.append()

在元素的最后一个子元素后插入一组 Node 对象或字符串。

Element.attachShadow()

为指定元素附加影子 DOM 树,并返回指向其 ShadowRoot 的引用。

Element.before()

在 Element 父节点的子节点列表中插入一组 Node 对象或字符串,位于 Element 之前。

Element.checkVisibility()

根据可配置的检查,返回元素是否可见。

Element.closest()

返回 Element 当前元素(或当前元素本身)最接近的祖先,且与参数中给定的选择器匹配。

Element.computedStyleMap()

返回一个 StylePropertyMapReadOnly 接口,该接口提供 CSS 声明块的只读表示,可替代 CSSStyleDeclaration。

Element.getAnimations()

返回元素当前活动的动画对象数组。

Element.getAttribute()

从当前节点读取指定属性的值,并以字符串形式返回。

Element.getAttributeNames()

返回当前元素的属性名称数组。

Element.getAttributeNode()

从当前节点获取指定属性的节点表示,并以 Attr 的形式返回。

Element.getAttributeNodeNS()

从当前节点读取指定名称和命名空间的属性的节点表示,并以 Attr 的形式返回。

Element.getAttributeNS()

从当前节点读取指定名称空间和名称的属性值,并以字符串形式返回。

Element.getBoundingClientRect()

返回元素的大小及其相对于视口的位置。

Element.getBoxQuads() 实验性

返回代表节点 CSS 片段的 DOMQuad 对象列表。

Element.getClientRects()

返回表示客户端中每行文本边界矩形的矩形集合。

Element.getElementsByClassName()

返回一个实时的 HTMLCollection,其中包含当前元素的所有后代,这些后代拥有参数中给定的类列表。

Element.getElementsByTagName()

返回一个实时的 HTMLCollection,其中包含当前元素的特定标签名的所有后代元素。

Element.getElementsByTagNameNS()

返回一个实时的 HTMLCollection,其中包含当前元素的特定标签名和命名空间的所有后代元素。

Element.getHTML()

以 HTML 字符串形式返回元素的 DOM 内容,可选择包含任何影子 DOM。

Element.hasAttribute()

返回一个布尔值,表示元素是否具有指定属性。

Element.hasAttributeNS()

返回一个布尔值,表示元素是否在指定名称空间中具有指定属性。

Element.hasAttributes()

返回一个布尔值,表示元素是否具有一个或多个 HTML 属性。

Element.hasPointerCapture()

指示调用该函数的元素是否具有指针捕获功能,用于捕获由给定指针 ID 标识的指针。

Element.insertAdjacentElement()

将指定元素节点插入调用该函数的元素的指定位置。

Element.insertAdjacentHTML()

解析 HTML 或 XML 文本,并将生成的节点插入树中指定的位置。

Element.insertAdjacentText()

将给定的文本节点插入调用该函数的元素的指定位置。

Element.matches()

返回一个布尔值,表示该元素是否会被指定的选择器字符串选中。

Element.moveBefore() 实验性

将给定的 Node 作为直接子节点移动到调用节点内部的给定引用节点之前,而无需先移除节点再插入。

Element.prepend()

在元素的第一个子元素之前插入一组 Node 对象或字符串。

Element.querySelector()

返回相对于元素符合指定选择器字符串的第一个 Node。

Element.querySelectorAll()

返回 NodeList 中相对于元素符合指定选择器字符串的节点。

Element.releasePointerCapture()

释放(停止)之前为特定指针事件设置的指针捕捉。

Element.remove()

从父元素的子元素列表中删除该元素。

Element.removeAttribute()

从当前节点删除指定属性。

Element.removeAttributeNode()

从当前节点删除指定属性的节点表示。

Element.removeAttributeNS()

从当前节点删除指定名称和命名空间的属性。

Element.replaceChildren()

用一组指定的新子节点替换 Node 的现有子节点。

Element.replaceWith()

用一组 Node 对象或字符串替换父元素子元素列表中的元素。

Element.requestFullscreen()

异步要求浏览器全屏显示元素。

Element.requestPointerLock()

允许异步请求锁定给定元素上的指针。

Element.scroll()

滚动到指定元素内部的特定坐标。

Element.scrollBy()

以给定数值滚动元素。

Element.scrollIntoView()

滚动页面,直到元素进入视图。

Element.scrollIntoViewIfNeeded() 非标准

如果当前元素尚未进入浏览器窗口的可见区域,则将其滚动到浏览器窗口的可见区域。请使用标准的 Element.scrollIntoView()。

Element.scrollTo()

滚动到指定元素内部的特定坐标。

Element.setAttribute()

设置当前节点的指定属性值。

Element.setAttributeNode()

设置当前节点指定属性的节点表示形式。

Element.setAttributeNodeNS()

设置当前节点具有指定名称和命名空间的属性的节点表示形式。

Element.setAttributeNS()

设置当前节点指定名称和命名空间的属性值。

Element.setCapture() 非标准 已弃用

设置鼠标事件捕获,将所有鼠标事件重定向到此元素。

Element.setHTML() 安全上下文 实验性

将 HTML 字符串解析并净化为文档片段,然后在 DOM 中替换元素的原始子树。

Element.setHTMLUnsafe()

将 HTML 字符串解析为文档片段,不进行净化处理,然后替换 DOM 中元素的原始子树。HTML 字符串可能包含声明式影子根,如果使用 Element.innerHTML 设置 HTML,这些影子根将被解析为模板元素。

Element.setPointerCapture()

指定一个特定的元素作为未来指针事件的捕获目标。

Element.toggleAttribute()

在指定的元素上切换布尔属性,如果存在则删除它,如果不存在则添加它。

事件

使用 addEventListener() 或将事件监听器分配给此接口的 oneventname 属性来监听这些事件。

afterscriptexecute 非标准 已弃用

脚本执行完毕后触发此事件。

beforeinput

当输入元素的值即将被修改时触发此事件。

beforematch

浏览器在(处于被找到前隐藏状态的)元素因用户已通过"在页面中查找"功能或片段导航找到了该内容而即将显示时触发此事件。

beforescriptexecute 非标准 已弃用

脚本即将执行时触发此事件。

beforexrselect 实验性

在派发 WebXR 选择事件(select、selectstart、selectend)前触发此事件。

contentvisibilityautostatechange 实验性

当元素开始或停止与用户相关和跳过其内容时,触发任何设置了 content-visibility: auto 的元素。

input

当用户操作直接导致元素值发生变化时触发此事件。

securitypolicyviolation

当违反内容安全策略时触发此事件。

wheel

当用户旋转指向设备(通常是鼠标)上的滚轮按钮时触发此事件。

动画事件

animationcancel

当动画意外终止时触发此事件。

animationend

当动画正常结束时触发此事件。

animationiteration

当动画迭代完成时触发此事件。

animationstart

当动画开始时触发此事件。

剪贴板事件

copy

当用户通过浏览器的用户界面初始化复制操作时触发此事件。

cut

当用户通过浏览器的用户界面初始化剪切操作时触发此事件。

paste

当用户通过浏览器的用户界面初始化粘贴操作时触发此事件。

合成事件

compositionend

当文本合成系统(如输入法编辑器)完成或取消当前合成会话时触发此事件。

compositionstart

当文本合成系统(如输入法编辑器)开始新的合成会话时触发此事件。

compositionupdate

在文本合成系统(如输入法编辑器)控制的文本合成会话中收到新字符时触发此事件。

聚焦事件

blur

当元素失去焦点时触发此事件。

focus

当元素获得焦点时触发此事件。

focusin

当元素获得焦点时触发此事件,位于 focus 事件之后。

focusout

当元素失去焦点时触发此事件,位于 blur 事件之后。

全屏事件

fullscreenchange

当前 Element 进入或退出全屏模式时,向该 Element 发送此事件。

fullscreenerror

如果在尝试将当前 Element 切换到或切换出全屏模式时发生错误,则向该 Element 发送此事件。

键盘事件

keydown

当按键按下时触发此事件。

keypress 已弃用

当按下可产生字符值的按键时触发此事件。

keyup

当按键释放时触发此事件。

鼠标事件

auxclick

当元素上的非主要指针设备按钮(例如除左键以外的任何鼠标按钮)被按下并释放时触发此事件。

click

指针设备按钮(如鼠标的主按钮)在单个元素上按下并释放时触发此事件。

contextmenu

当用户尝试打开上下文菜单时触发此事件。

dblclick

当指针设备按钮(如鼠标的主按钮)在单个元素上被点击两次时触发此事件。

DOMActivate 已弃用

元素被激活,例如通过鼠标点击或按键时触发此事件。

DOMMouseScroll 已弃用 非标准

操作鼠标滚轮或类似设备,且自上次事件以来累计滚动量超过 1 行或 1 页时触发此事件。

mousedown

当元素上的指针设备按钮被按下时触发此事件。

mouseenter

当指针设备(通常是鼠标)移动到附加了监听器的元素上时触发此事件。

mouseleave

当指针设备(通常是鼠标)的指针移出附有监听器的元素时触发此事件。

mousemove

当指针设备(通常是鼠标)在元素上移动时触发此事件。

mouseout

当指针设备(通常是鼠标)离开监听器所连接的元素或其子元素时触发此事件。

mouseover

当指针设备移动到监听器所连接的元素上或其子元素上时触发此事件。

mouseup

当元素上的指针设备按钮被释放时触发此事件。

mousewheel 已弃用 非标准

操作鼠标滚轮或类似设备时触发此事件。

MozMousePixelScroll 已弃用 非标准

操作鼠标滚轮或类似设备时触发此事件。

webkitmouseforcechanged 非标准

每次触控板触摸屏上的压力发生变化时触发此事件。

webkitmouseforcedown 非标准

在鼠标按下事件后,一旦施加了足够的压力,就会触发"强制点击"。

webkitmouseforcewillbegin 非标准

在 mousedown 事件之前触发。

webkitmouseforceup 非标准

在 webkitmouseforcedown 事件之后,当压力充分减小以结束"强制点击"时触发。

指针事件

gotpointercapture

当元素使用 setPointerCapture() 捕捉指针时触发。

lostpointercapture

当捕获指针被释放时触发。

pointercancel

指针事件取消时触发。

pointerdown

指针变为活动状态时触发。

pointerenter

指针移动到元素或其子代的命中测试边界时触发。

pointerleave

当指针移出元素的命中测试边界时触发。

pointermove

指针改变坐标时触发。

pointerout

当指针移出元素的命中测试边界(以及其他原因)时触发。

pointerover

当指针移动到元素的命中测试边界时触发。

pointerrawupdate

指针改变任何属性时触发,这些属性不会触发 pointerdown 或 pointerup 事件。

pointerup

指针不再处于活动状态时触发。

滚动事件

scroll

当文档视图或元素滚动时触发此事件。

scrollend

当文档视图完成滚动时触发此事件。

scrollsnapchange 实验性

当选择了新的滚动捕捉目标时,在滚动操作结束时在滚动容器上触发此事件。

scrollsnapchanging 实验性

当浏览器确定有新的滚动捕捉目标(即当前滚动手势结束时将选择该目标)时,在滚动容器上触发此事件。

触摸事件

gesturechange 非标准

触控手势期间数字移动时触发。

gestureend 非标准

当不再有多个手指接触触摸表面时触发,从而结束手势。

gesturestart 非标准

当多个手指接触触摸表面时触发,从而开始一个新手势。

touchcancel

当一个或多个触摸点以特定的实现方式受到破坏(例如,创建的触摸点过多)时触发。

touchend

当一个或多个触摸点从触摸表面移除时触发。

touchmove

当一个或多个触摸点沿触摸表面移动时触发。

touchstart

当一个或多个触摸点放置在触摸表面时触发。

过渡事件

transitioncancel

CSS 过渡被取消时触发的 Event。

transitionend

CSS 过渡结束播放时触发的 Event。

transitionrun

当创建 CSS 过渡(即当它被添加到一组正在运行的过渡中时)时,一个 Event 会被触发,但不一定会被启动。

transitionstart

CSS 过渡开始过渡时触发的 Event。

规范

浏览器兼容性