元素
Element
是所有元素对象(即表示元素的对象)在 Document
中继承的最通用的基类。它只包含所有元素共有的方法和属性。更具体的类从 Element
继承。
例如,HTMLElement
接口是 HTML 元素的基接口。类似地,SVGElement
接口是所有 SVG 元素的基础,而MathMLElement
接口是 MathML 元素的基接口。大多数功能在类层次结构中进一步指定。
Web 平台范围之外的语言,如通过 XULElement
接口的 XUL,也实现了 Element
。
实例属性
Element
从其父接口 Node
继承属性,并通过扩展继承该接口的父接口 EventTarget
。
Element.assignedSlot
只读-
返回一个
HTMLSlotElement
,它表示节点插入的<slot>
。 Element.attributes
只读-
返回一个
NamedNodeMap
对象,其中包含相应 HTML 元素的已分配属性。 Element.childElementCount
只读-
返回此元素的子元素数量。
Element.children
只读-
返回此元素的子元素。
Element.classList
只读-
返回一个
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
。注意: 在 Firefox 3.5 及更早版本中,HTML 元素没有命名空间。在更高版本中,HTML 元素在 HTML 和 XML 树中都位于
http://www.w3.org/1999/xhtml
命名空间中。 Element.nextElementSibling
只读-
一个
Element
,树中紧随给定元素的元素,如果不存在同级节点,则为null
。 Element.outerHTML
-
表示元素标记的字符串,包括其内容。当用作设置器时,将使用从给定字符串解析的节点替换元素。
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
属性,该属性指示可由元素触发的交互式弹出元素(如菜单或对话框)的可用性和类型。 -
一个字符串,反映了
aria-hidden
属性,该属性指示元素是否暴露给辅助功能 API。 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
属性的字符串,该属性定义元素在当前 listitems 或 treeitems 集中的编号或位置。 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
属性的字符串,该属性定义当前 listitems 或 treeitems 集中的项目数。 Element.ariaSort
-
一个反映
aria-sort
属性的字符串,该属性指示表格或网格中的项目是按升序还是降序排序。 Element.ariaValueMax
-
一个反映
aria-valueMax
属性的字符串,该属性定义范围小部件允许的最大值。 Element.ariaValueMin
-
一个反映
aria-valueMin
属性的字符串,该属性定义范围小部件允许的最小值。 Element.ariaValueNow
-
一个反映
aria-valueNow
属性的字符串,该属性定义范围小部件的当前值。 Element.ariaValueText
-
一个反映
aria-valuetext
属性的字符串,该属性定义范围小部件的 aria-valuenow 的人类可读文本替代项。
实例方法
Element
继承了其父级 Node
的方法,以及其自身的父级 EventTarget
的方法。
Element.after()
-
在
Element
的父级元素的子级列表中,将一组Node
对象或字符串插入到Element
之后。 Element.animate()
-
一个快捷方法,用于在元素上创建和运行动画。返回创建的 Animation 对象实例。
Element.append()
-
在元素的最后一个子级之后插入一组
Node
对象或字符串。 Element.attachShadow()
-
将阴影 DOM 树附加到指定的元素,并返回对其
ShadowRoot
的引用。 Element.before()
-
在
Element
的父级元素的子级列表中,将一组Node
对象或字符串插入到Element
之前。 Element.checkVisibility()
-
根据可配置的检查,返回元素是否预计可见。
Element.closest()
-
返回与参数中给定的选择器匹配的当前元素的最近祖先元素(或当前元素本身)。
Element.computedStyleMap()
-
返回一个
StylePropertyMapReadOnly
接口,该接口提供 CSS 声明块的只读表示,它是CSSStyleDeclaration
的替代方案。 Element.getAnimations()
-
返回当前在元素上活动的 Animation 对象数组。
Element.getAttribute()
-
从当前节点检索命名属性的值,并将其作为字符串返回。
Element.getAttributeNames()
-
从当前元素返回属性名称数组。
Element.getAttributeNode()
-
从当前节点检索命名属性的节点表示,并将其作为
Attr
返回。 Element.getAttributeNodeNS()
-
从当前节点检索具有指定名称和命名空间的属性的节点表示,并将其作为
Attr
返回。 Element.getAttributeNS()
-
从当前节点检索具有指定命名空间和名称的属性的值,并将其作为字符串返回。
Element.getBoundingClientRect()
-
返回元素的大小及其相对于视窗的位置。
Element.getBoxQuads()
实验性的-
返回一个
DOMQuad
对象列表,这些对象表示节点的 CSS 片段。 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.prepend()
-
在元素的第一个子级之前插入一组
Node
对象或字符串。 Element.querySelector()
-
返回相对于元素的第一个与指定的選擇器字符串匹配的
Node
。 Element.querySelectorAll()
-
返回相对于元素的与指定的選擇器字符串匹配的
NodeList
节点。 Element.releasePointerCapture()
-
释放(停止)先前针对特定
PointerEvent
设置的指针捕获。 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.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
设置为 与用户相关 并且 跳过其内容 时,它会对任何元素触发。 scroll
-
当文档视图或元素滚动时触发。
scrollend
-
当文档视图滚动完成时触发。
securitypolicyviolation
-
当违反 内容安全策略 时触发。
wheel
-
当用户在指点设备(通常是鼠标)上旋转滚轮按钮时触发。
动画事件
animationcancel
-
当动画意外中止时触发。
animationend
-
当动画正常完成时触发。
animationiteration
-
当动画迭代完成时触发。
animationstart
-
当动画开始时触发。
剪贴板事件
组合事件
compositionend
-
当文本组合系统(如 输入法编辑器)完成或取消当前组合会话时触发。
compositionstart
-
当文本组合系统(如 输入法编辑器)启动新的组合会话时触发。
compositionupdate
-
当在文本组合系统(如 输入法编辑器)控制的文本组合会话的上下文中收到新字符时触发。
焦点事件
全屏事件
fullscreenchange
-
当元素过渡到 全屏 模式或退出全屏模式时发送给
Element
。 fullscreenerror
-
如果在尝试将元素切换到 全屏 模式或退出全屏模式时发生错误,则发送给
Element
。
键盘事件
鼠标事件
auxclick
-
当非主要指点设备按钮(例如,除左键以外的任何鼠标按钮)在一个元素上被按下和释放时触发。
click
-
当指点设备按钮(例如,鼠标的主按钮)在一个元素上被按下和释放时触发。
-
当用户尝试打开上下文菜单时触发。
dblclick
-
当指点设备按钮(例如,鼠标的主按钮)在一个元素上被双击时触发。
DOMActivate
已弃用-
当元素被激活时发生,例如,通过鼠标点击或按键。
DOMMouseScroll
已弃用 非标准-
当鼠标滚轮或类似设备操作,并且自上次事件以来累计滚动量超过 1 行或 1 页时发生。
mousedown
-
当指点设备按钮在一个元素上被按下时触发。
mouseenter
-
当指点设备(通常是鼠标)移动到附加了监听器的元素上时触发。
mouseleave
-
当指点设备(通常是鼠标)从附加了监听器的元素或其子元素移出时触发。
mousemove
-
当指点设备(通常是鼠标)在附加了监听器的元素上移动时触发。
mouseout
-
当指点设备(通常是鼠标)从附加了监听器的元素或其子元素之一移出时触发。
mouseover
-
当指点设备移动到附加了监听器的元素或其子元素之一上时触发。
mouseup
-
当指点设备按钮在一个元素上被释放时触发。
mousewheel
已弃用 非标准-
当鼠标滚轮或类似设备操作时触发。
MozMousePixelScroll
已弃用 非标准-
当鼠标滚轮或类似设备操作时触发。
webkitmouseforcechanged
非标准-
每次触控板/触摸屏的压力变化时触发。
webkitmouseforcedown
非标准-
在 mousedown 事件之后触发,只要施加的压力足以算作“强制点击”。
webkitmouseforcewillbegin
非标准-
在
mousedown
事件之前触发。 webkitmouseforceup
非标准-
在
webkitmouseforcedown
事件之后触发,只要压力降低到足以结束“强制点击”。
指针事件
gotpointercapture
-
当元素使用
setPointerCapture()
捕获指针时触发。 lostpointercapture
-
当 捕获的指针 被释放时触发。
pointercancel
-
当指针事件被取消时触发。
pointerdown
-
当指针变为活动状态时触发。
pointerenter
-
当指针移动到元素或其后代的命中测试边界内时触发。
pointerleave
-
当指针从元素的命中测试边界移出时触发。
pointermove
-
当指针改变坐标时触发。
pointerout
-
当指针从元素的命中测试边界移出(除其他原因)时触发。
pointerover
-
当指针移动到元素的命中测试边界内时触发。
pointerrawupdate
实验性-
当指针更改任何不触发
pointerdown
或pointerup
事件的属性时触发。 pointerup
-
当指针不再活动时触发。
触摸事件
gesturechange
非标准-
当手指在触摸手势过程中移动时触发。
gestureend
非标准-
当不再有多个手指接触触摸表面时触发,从而结束手势。
gesturestart
非标准-
当多个手指接触触摸表面时触发,从而开始一个新的手势。
touchcancel
-
当一个或多个触点以特定于实现的方式中断时触发(例如,创建了太多触点)。
touchend
-
当一个或多个触点从触摸表面移除时触发。
touchmove
-
当一个或多个触点沿触摸表面移动时触发。
touchstart
-
当一个或多个触点放置在触摸表面上时触发。
过渡事件
规范
规范 |
---|
DOM 标准 # interface-element |
指针事件 # extensions-to-the-element-interface |
全屏 API 标准 # api |
DOM 解析和序列化 # extensions-to-the-element-interface |
CSSOM 视图模块 # extension-to-the-element-interface |
浏览器兼容性
BCD 表格仅在浏览器中加载