krpano官网文档翻译-------嵌入【Embedding】

 鸿蒙专栏：想学鸿蒙的，冲

C语言专栏：想学C语言的，冲

 VUE专栏：想学VUE的，冲这里

 CSS专栏：想学CSS的，冲这里

Krpano专栏：想学VUE的，冲这里

上述专栏，都在不定期持续更新中！！！！！！！！！！！！！

目录

✨ 前言

脚本包括

查看器嵌入

embedpano({...embedding parameters...});

嵌入参数

xml:"krpano.xml"

target:...

背景:“# 000000”

vars:{...}

initvars:{...}

basepath:...

consolelog:false

mwheel:true

capturetouch:true

focus:true

webgl:true

webglsettings:{preserveDrawingBuffer:false, depth:true, stencil:true, ...}

webxr:"auto"

mobilescale:1.0 

safearea:"auto" 

touchdevicemousesupport:true 

fakedevice:""

onready:...Javascript-Callback-Function...

onerror:...Javascript-Callback-Function...

passQueryParameters:false

查看器删除

removepano(id);

krpano.unload();

✨ 结语

---

 

✨ 前言

        为了将krpano查看器嵌入到HTML页面中，需要包含 krpano.js 脚本文件(文件名可以不同)，并调用 embedpano() 函数。

文档的主题::

• 脚本包括
• 查看器嵌入
• 嵌入参数
• 查看器删除

 

脚本包括

krpano脚本文件需要在html页面的任何地方包含一次(但在embedpano()使用之前): 

一些细节和注意事项:

• “krpano.js”文件可以命名不同-例如，当使用MAKE PANO或MAKE VTOUR液滴时，它通常被命名为“pano.js”或“tour.js”。
• 该文件本身包含krpano查看器，并且在注册时还包含许可信息。
• 通常，所有panos和tours的文件都是相同的(除非应用了自定义保护设置)。这意味着同一个文件可以用于多个panos和tour。
  当托管多个pano和tour时，这甚至是一种推荐的方式——为krpano查看器和插件文件使用一个全局位置，并从所有其他项目引用到它们。这样更新版本就容易多了。

查看器嵌入

在html页面的任何地方创建一个

元素，在查看器应该嵌入的地方，给这个div元素一个唯一的'id'名称，并通过css样式定义它的大小:

在定义了

元素之后，用嵌入的脚本代码创建一个

嵌入参数

        embedpano()函数需要一个Javascript对象作为参数。该对象用于通过parametername:value对传递所有参数(以随机顺序)。几乎所有的参数(除了目标参数)都是可选的——当没有定义它们时，将使用它们的默认值。
parameters对象提供以下设置: 

xml:"krpano.xml"

• 启动xml文件的名称和路径(相对于html文件)。
• 当启动时不加载xml文件时，不要设置该值或使用null。
• 向后兼容性:如果没有设置，并且设置了swf文件的路径，则将使用swf文件的文件名(例如:'krpano.xml'(用于'krpano.swf')。

target:...

• 设置目标html元素，pano查看器应该嵌入其中。
• 可以是html-element的id，也可以直接是html-element本身。
• 如果没有设置目标，或者找不到具有给定id的html元素，就会出现Javascript alert()错误。 

背景:“# 000000”

• 查看器的背景颜色(html颜色格式)。
• 默认值是#000000 (=Black)。
• 可选的值transparent可用于查看pano后面的内容(网站，blglayer图层)。

注意-当使用透明背景时，只支持正常的交叉渐变全景混合(自动)。

vars:{...}

• 传递一个带有krpano变量的Javascript对象:值对。
• 这些变量将在xml文件加载和解析之后设置。
• 因此，可以使用这些变量来添加新设置或覆盖已经在xml中定义的设置。
• 例子: 

  var settings = {};
  settings["onstart"] = "trace('on start...')";
  settings["view.hlookat"] = 30;
  embedpano({xml:"pano.xml", target:"pano", vars:settings});

initvars:{...}

• 传递一个带有krpano变量的Javascript对象:值对。
• 这与vars设置基本相同，但是这些变量将在加载和解析xml文件之前设置。
• 这个设置的主要用途是设置自定义路径变量，这些变量可以用作xml文件中url路径中的占位符，或者设置可以在元素的xml-if检查中使用的变量。
• 例子: 

  embedpano({..., initvars:{mypath:"./panos1/"} });

  XML:

  url="%$mypath%image.jpg"

  为了能够通过http查询直接在html文件的url上传递initvars变量，需要使用以下语法:
   

  tour.html?initvars.variable=value

basepath:...

• 设置相对于krpano查看器url路径进行解析的自定义路径。
• 注意:改变这个会影响%VIEWER% url占位符。 

consolelog:false

• 一个布尔值设置，用于定义krpano日志/跟踪消息是否也应发送到浏览器Javascript控制台。 

mwheel:true

• 控制鼠标滚轮支持的布尔值设置。
• 当设置为true(默认值)时，鼠标滚轮事件将被捕获并可以在查看器中使用(例如用于缩放)。
• 当设置为false时，任何鼠标滚轮的使用都将被忽略，浏览器将执行默认的鼠标滚轮处理(通常是滚动网页)。
• 鼠标滚轮支持也可以在运行时通过使用控件进行更改。disablewheel设置。 

capturetouch:true

• 一个布尔设置来控制触摸事件的捕获。
• 当设置为true(默认值)时，触摸事件将被捕获并可以在查看器中使用(例如，用于平移和缩放)。
• 当设置为false时，查看器仍将使用触摸事件本身，但它们的默认事件处理不会停止。这意味着在这种情况下，浏览器可能会平移或缩放网页。
• 也可以在运行时通过使用控件更改设置。capturetouch设置。 

focus:true

• 布尔设置，使查看器在启动时关注输入/键盘。
• 当未设置时，该设置将根据查看器的大小自动设置-当查看器覆盖整个网页时，焦点将设置为true，否则为false。 

webgl:true

• 使用WebGL进行渲染(推荐)。
• 代替WebGL, CSS 3d变换可以用于显示全景，但与使用WebGL相比，这是非常有限的。
• 设置: 

1. true -只使用WebGL(默认)。
2. false -不要使用WebGL，总是使用CSS 3d转换。
3. “auto”-在可用时使用WebGL，否则使用CSS 3d转换。

• 当WebGL或CSS 3d转换不可用时，将显示错误。
• 注意-没有WebGL这些特性是不可用的:

1. 球形，圆柱形和鱼眼Panos(仅限立方体和平面Panos)
2. Video-Panos
3. 观看投影(小行星视图)
4. 深度图/ 3d模型Panos
5. Pano-blending模式
6. 产生
7. 后处理
8. Chromakey和alpha通道热点
9. 热点blendmodes
10. VR和立体声支持

• 注:根据浏览器和设备的不同，一个网页上WebGL元素的数量是有限的(例如，只有8个WebGL元素)。当请求更多的WebGL元素时，最近最少使用的元素将被释放。当在一个网页上放置多个panos时需要考虑到这一点。对于简单的panos/tours，禁用WebGL也是一种选择。

webglsettings:{preserveDrawingBuffer:false, depth:true, stencil:true, ...}

• 传递一个具有WebGL上下文创建特殊设置的对象。
• WebGL上下文将在启动时创建，不能在运行时更改，因此这些设置需要在嵌入时指定。
• 可用的设置:
• webgl2 -尝试使用可用的WebGL 2.0 API。目前默认设置为false，因为仍然是实验性的，没有在所有系统上进行全面测试。
• 目前WebGL2在krpano中的优势:
• 非2次幂纹理也可以使用mipmapping。
• 非2次幂纹理可以使用可重复的纹理坐标(需要一些.obj 3d模型)，而不需要着色器。
• 保留绘图缓冲区的内容。在某些浏览器中，当试图通过toDataURL或readPixels对WebGL画布进行截图时，需要启用。默认设置为false以获得更好的性能。
• depth -创建一个深度缓冲区。需要深度图支持和3d对象渲染。默认设置为true，但在不需要时可以禁用。
• 创建一个模板缓冲区。当使用透明线边颜色时，需要对多边形热点进行正确的线渲染。默认设置为true，但在不需要时可以禁用。
• failIfMajorPerformanceCaveat -当WebGL的渲染性能明显低于原生应用的OpenGL渲染性能时，不要使用WebGL。默认为false。
• antialias -设置是否应该使用抗锯齿- true或false。
• 当不设置时，krpano自行决定最佳性能，因为某些设备/浏览器/gpu组合在启用抗锯齿时表现非常糟糕(例如半帧率)。此设置应仅用于内部测试或非常特殊的情况。 

webxr:"auto"

• 控制WebXR API支持。
• 要使用WebXR API，必须在启动时进行几个初始设置步骤，因此在嵌入查看器时需要定义WebXR API的使用。
• 可用的设置: 

        1、auto (the default)

• - 仅在桌面浏览器和专用VR系统/浏览器上使用WebXR API。在Android移动系统上，替代krpano MobileVR支持目前具有更好和更广泛的设备支持。
• - 当WebVR API和WebXR API同时可用时，则首选WebVR API。今天，WebVR API仍然是更好的选择。它允许使用过采样来获得更高的图像质量和设备特定的性能优化。目前WebXR API无法实现这两种功能，未来的API版本和浏览器可能会变得更好。

        2、preferwebvr

• - 当WebVR和WebXR都可用时，首选WebVR API。

        3、prefer / true

• - 当WebVR和WebXR都可用时，首选WebXR API。

        4、no / false

• - 不要使用WebXR API，始终使用WebVR API或krpano MobileVR支持VR显示。

mobilescale:1.0 

• 可选地为移动设备使用不同的全局刻度的设置。
• 另请参见xml stagescale设置。

safearea:"auto" 

• 启用或禁用一般安全区域支持(对于带有缺口的iOS设备)。
• 可用的设置:

1. auto(默认值)-当查看器嵌入到“整页”html元素时，自动启用安全区域支持。
2. true -始终启用安全区域支持。在嵌入期间，当embedding-target-html-元素不是整页大小时可以使用。
3. false -不启用安全区域支持。

• 注意-在html文件中，需要在html 元素中也有这个设置，以便能够使用安全区:

• 更多信息: krpano论坛帖子

touchdevicemousesupport:true 

• 可选地禁用触摸设备上的鼠标支持的设置。

fakedevice:""

• 伪造krpano设备检测设置。
• 可设置:“移动”、“平板”、“桌面”。
• 注意-这个设置应该只用于内部测试，不要用于发布! 

onready:...Javascript-Callback-Function...

• onready设置可用于设置回调函数，以便在嵌入完成并且krpano查看器准备使用时获得通知。
• 将使用krpano接口对象作为参数调用给定的函数。
• 例子: 

  embedpano({target:"id-of-your-div", onready:function(krpano)
  {
    console.log("krpano is ready - version="+krpano.version);
    krpano.actions.loadpano("pano.xml",null,null,null,function()
    {
      var hs = krpano.addhotspot();
      hs.type = "text";
      hs.html = "Test Hotspot";
      hs.ath = 20;
      hs.atv = 10;
      hs.onclick = function()
      {
        alert("Test");
      }
    });
  }});

onerror:...Javascript-Callback-Function...

• onerror设置可用于设置自定义嵌入错误处理函数。
• 将以错误消息字符串作为参数调用给定的函数。 

passQueryParameters:false

• 有了这个设置，就可以将http查询参数作为变量从url传递/重定向到krpano查看器。
• 可能的值:

1. True -将所有参数传递给查看器。
2. False -不传递任何参数(默认值)。
3. “param1 param2 param3,……”-定义允许传递的逗号分隔参数的自定义列表。

• 使用的例子:

  tour.html?startscene=scene2&initvars.design=flat

• 安全警告:
  当允许传递所有参数(设置为true)或可以包含可执行代码的参数时，这可以为跨站点脚本打开可能性。如果这可能是一个问题取决于个人用例和周围/包含的网站。 

查看器删除

        有两种方法可以正确地从页面中删除krpano查看器并卸载/释放其分配的所有资源:

removepano(id);

• removepano()函数既可以用html目标元素的id调用，也可以用嵌入期间定义的唯一id调用
• 例子:

  embedpano({target:"panoDIV"});
  ...
  removepano("panoDIV");

  or:

  embedpano({target:"panoDIV", id:"pano1"});
  ...
  removepano("pano1");

krpano.unload();

• 当有一个krpano接口对象时(例如从onready回调)，也可以调用它的unload()函数来删除krpano查看器。
• 例子: 

  embedpano({target:"id-of-your-div", onready:function(krpano)
  {
    ...
    krpano.unload();
  }});

✨ 结语

我们改日再会，下一篇：krpano XML Reference