XRSession

安全上下文:此功能仅在安全上下文(HTTPS)中可用,在一些或所有支持的浏览器中。

实验性:这是一个实验性技术
在生产环境中使用此功能之前,请仔细查看浏览器兼容性表

XRSessionWebXR 设备 API 的接口,它表示正在进行的 XR 会话,提供用于与会话交互和控制会话的方法和属性。要打开 WebXR 会话,请使用 XRSystem 接口的 requestSession() 方法。

使用 XRSession 方法,您可以轮询查看器的 位置 和 方向(XRViewerPose),收集有关用户环境的信息,并将图像呈现给用户。XRSession 支持内联和沉浸式虚拟现实和增强现实模式。

EventTarget XRSession

实例属性

除了下面列出的属性外,XRSession 还从其父接口 EventTarget 继承了属性。

depthDataFormat 实验性 只读

返回配置会话的深度感应数据格式。

depthUsage 实验性 只读

返回配置会话的深度感应使用情况。

domOverlayState 实验性 只读

提供有关 DOM 叠加层的信息(如果启用了此功能)。

environmentBlendMode 实验性 只读

返回此会话的混合模式,该模式表示通过 XR 设备可以看到多少真实世界环境,以及设备如何将设备图像与之混合。

inputSources Experimental 只读

返回此会话的 XRInputSource 列表,每个列表都表示用于控制相机和/或场景的输入设备。

interactionMode Experimental 只读

返回此会话的交互模式,它描述了应用程序为当前会话绘制交互式 UI 的最佳空间(根据用户代理)。

preferredReflectionFormat Experimental 只读

返回此会话的用于照明估计纹理数据的首选反射格式。

renderState Experimental 只读

一个 XRRenderState 对象,其中包含影响图像渲染方式的选项。这包括诸如近平面和远平面(定义对象可以渲染的最近和最远距离)以及视野信息之类的东西。

visibilityState Experimental 只读

一个字符串,指示会话的图像是否对用户可见,如果是,则指示它是否可见但当前不是用户事件的目标。

实例方法

XRSession 除了从其父接口 EventTarget 继承的那些方法之外,还提供以下方法。

cancelAnimationFrame() Experimental

XRSession 的动画帧渲染回调集中删除来自动画帧绘制回调的回调,方法是提供先前对 requestAnimationFrame() 的调用返回的标识句柄。

end() Experimental

结束 WebXR 会话。返回一个 promise,该 promise 在会话关闭后解析。

requestAnimationFrame() Experimental

安排在下次 用户代理 正在为 WebXR 设备渲染动画帧时调用指定方法。返回一个整数值,该值可用于识别请求,以便使用 cancelAnimationFrame() 取消回调。此方法类似于 Window.requestAnimationFrame() 方法。

requestHitTestSource() Experimental

请求一个 XRHitTestSource 对象,该对象处理命中测试订阅。

requestHitTestSourceForTransientInput() Experimental

请求一个 XRTransientInputHitTestSource 对象,该对象处理瞬态输入源的命中测试订阅。

requestLightProbe() Experimental

请求一个 XRLightProbe,它估计用户环境中给定点的照明信息。

requestReferenceSpace() Experimental

请求创建指定类型的新的 XRReferenceSpace。返回一个 promise,该 promise 解析为请求的 XRReferenceSpaceXRBoundedReferenceSpace,或者如果设备不支持请求的空间类型,则抛出 NotSupportedError DOMException

updateRenderState() Experimental

更新会话渲染状态的属性。

事件

以下事件将传递给 XRSession 对象。

end Experimental

在 WebXR 会话结束且所有硬件相关功能都完成之后发送到 XRSession 对象。该事件由类型为 XRSessionEvent 的对象表示。也可以通过 onend 事件处理程序属性获得。

inputsourceschange Experimental

当活动 XR 输入源列表发生更改时,发送到 XRSession 的类型为 XRInputSourcesChangeEvent 的事件。也可以通过 oninputsourceschange 事件处理程序属性获得。

select Experimental

一个类型为 XRInputSourceEvent 的事件,当会话的某个输入源成功完成 主要操作 时,该事件将发送到会话。这通常对应于用户按下触发器、触摸板或按钮、说出命令或执行可识别的姿势。select 事件在发送 selectstart 事件后立即发送,并在发送 selectend 事件之前立即发送。如果没有发送 select,则选择操作在完成之前就被中止了。也可以通过 onselect 事件处理程序属性获得。

selectend Experimental

一个类型为 XRInputSourceEvent 的事件,当会话的某个输入设备完成其主要操作或在处理主要操作的过程中断开连接时,该事件将发送到会话对象。例如:对于按钮或触发器操作,这意味着按钮已被释放;对于语音命令,这意味着用户已完成说话。这是发送的三个 select* 事件中的最后一个。也可以通过 onselectend 事件处理程序属性获得。

selectstart Experimental

一个类型为 XRInputSourceEvent 的事件,当会话的某个输入设备首次被用户以启动主要操作的方式使用时,该事件将发送到会话对象。这是发送的 session* 事件中的第一个。也可以通过 onselectstart 事件处理程序属性获得。

squeeze Experimental

一个 XRInputSourceEvent,用于指示 主要挤压操作 已成功完成。这表示正在挤压的设备已释放,可能代表例如丢弃抓取的对象。它在发送 squeezeend 事件之前立即发送,以指示挤压操作已结束。也可以通过 onsqueeze 事件处理程序属性获得。

squeezeend Experimental

主要挤压操作 结束时,无论操作是否成功,都发送到 XRSession 的一个 XRInputSourceEvent。也可以使用 onsqueezeend 事件处理程序属性获得。

squeezestart Experimental

一个类型为 XRInputSourceEvent 的事件,当用户最初挤压可挤压的控制器时,该事件将发送到 XRSession。例如,这可能是一个用于代表抓取对象的触发器,或者可能代表戴着触觉手套时实际挤压。也可以通过 onsqueezestart 事件处理程序属性获得。

visibilitychange Experimental

一个 XRSessionEvent,当它的可见性状态(如 visibilityState 所示)发生变化时,该事件将发送到会话。也可以通过 onvisibilitychange 事件处理程序属性获得。

示例

此示例在 inline 模式下建立了一个新的 XRSession,以便它可以显示在 HTML 元素中,从而避免了对专用 AR 或 VR 查看设备(例如头戴式设备)的需要。

js
const XR = navigator.xr;

if (XR) {
  XR.requestSession("inline").then((xrSession) => {
    xrSession.requestReferenceSpace("local").then((xrReferenceSpace) => {
      xrSession.requestAnimationFrame((time, xrFrame) => {
        const viewer = xrFrame.getViewerPose(xrReferenceSpace);

        gl.bindFramebuffer(xrWebGLLayer.framebuffer);

        for (const xrView of viewer.views) {
          const xrViewport = xrWebGLLayer.getViewport(xrView);
          gl.viewport(
            xrViewport.x,
            xrViewport.y,
            xrViewport.width,
            xrViewport.height,
          );
        }
      });
    });
  });
} else {
  /* WebXR is not available */
}

规范

规范
WebXR 设备 API
# xrsession-interface

浏览器兼容性

BCD 表格仅在浏览器中加载