krpano 1.19-pr14 (生成 2017-12-01)

嵌入到 HTML 中

为了将 krpano 播放器嵌入到 HTML 页面中, 需要包含核心 "krpano" 脚本文件 (文件名可以不同), 并调用 embedpano ()函数。 embedpano 函数检测浏览器支持, 并决定使用哪个 krpano 播放器 (krpano HTML5 或 krpano Flash 播放器)。 使用 krpano Flash 播放器时, 嵌入脚本还会应用多个 Flashplayer 和浏览器修复程序和变通方法 (例如, 在不支持此项的系统中启用鼠标滚轮的使用)。 这使得 krpano 播放器的嵌入简单简单--只有一个脚本包含和一行嵌入代码。
文档主题:

脚本引用

krpano 脚本文件需要在 html 页中的任何位置 (但在 embedpano () 使用之前) 包含一次: 
<script src="krpano.js"></script>

一些细节和注意事项:
  • "krpano" 文件可以命名为不同的-例如, 当使用制作全景或使 VTOUR 的水滴, 它通常命名为 "全景. js" 或 "游览. js"。
  • 文件本身包含两个部分-krpano 嵌入脚本和 krpano HTML5 播放器。 krpano Flash播放器是一个单独的外部文件 (如 "krpano" 文件)。
  • 该文件总是相同的, 它不包含任何全景或旅游特定的信息, 这意味着它可以在多个帕诺斯/旅游或项目共享。
    例如, 要使以后的更新更容易, 只需只使用一个全局文件夹 krpano 播放器和插件文件, 并从所有其他项目链接到它们。 然后, 只有更新全局 krpano 文件, 才能更新所有项目。

播放器嵌入

在 html 页的任意位置创建播放器应嵌入的 < div >元素, 为该 div 元素指定唯一的 "id"名称, 并通过 css 样式定义其大小: 
<div id="pano" style="width:100%;height:100%;"></div>

定义 < div >元素后, 使用嵌入脚本代码创建 < 脚本 >元素。
对于嵌入本身, 存在全局 embedpano ()函数: 

embedpano({...embedding parameters...});
  • embedpano () 函数需要具有 嵌入参数的对象.

  • 完整示例: 
    <script src="krpano.js"></script>
<div id="pano" style="width:600px; height:400px;"></div>
<script>
embedpano({swf:"krpano.swf", xml:"pano.xml", target:"pano"});
</script>

嵌入参数

embedpano () 函数需要 Javascript 对象作为参数。 此对象用于通过使用 parametername: value对传递所有参数 (以随机顺序)。 几乎所有参数 ( target参数除外) 都是可选的-在未定义它们时, 将使用它们的默认值。
参数对象提供以下设置: 

xml:"krpano.xml"
  • 启动 xml 文件 (相对于 html 文件) 的名称和路径。
  • 如果未设置, 将使用. swf 文件的文件名 (如 "krpano. swf" 的 "krpano")。
  • 当启动时不应加载 xml 文件时, 可以使用值 null 。

target:"...pano-div-id..."
  • 要嵌入播放器的 html 元素的 #id。
  • 如果没有目标设置, 将出现 "警报 ()" 错误。

swf:"krpano.swf"
  • 播放器 ". swf" 文件 (相对于 html 文件) 的名称和路径。
  • 默认值为 "krpano. swf" .
  • 此文件仅用于 Flashplayer, 仅在使用 HTML5 时不需要此文件。

id:"krpanoSWFObject"
  • 内部播放器对象的 id。
  • 这将是通过 Javascript 接口将播放器接口的对象。.
  • 默认 id 为 "krpanoSWFObject" .
  • 重要的是, 每个播放器将有一个唯一的 id!
  • 当已存在具有给定 id 的对象时, 嵌入脚本将自动在 id 的末尾添加数字, 直到它唯一。

bgcolor:"#000000"
  • 播放器的背景色 (以 html 颜色格式)。
  • 默认值为 "#000000" (= 黑色)。

html5:"auto"
  • 设置 krpano HTML5 播放器用法。
  • 可能的设置:
    • 自动-默认设置-自动使用 krpano HTML5 播放器。
      使用该设置, krpano HTML5 播放器将在默认情况下使用 (因为版本 1.19, 在旧版本中 Flash 被用作默认值)! 当 HTML5 将无法使用时, Flash 播放器将用作备用。
    • 首选-如果可能, 更喜欢使用 krpano HTML5 播放器, 否则使用 Flash (自版本1.19 以来与 auto相同)。
    • 回退-更喜欢在可能的情况下使用 krpano Flash 播放器。 仅当 Flash 不可用时, 使用 krpano HTML5 播放器作为回退。
    • 仅-仅使用 krpano HTML5 播放器-从不使用 krpano Flash 播放器。
      使用该设置, krpano HTML5 播放器将在可能时使用。 当系统/浏览器未 HTML5-compatible 时, 将显示 错误消息。
    • 始终-始终使用 krpano HTML5 播放器, 无论系统和浏览器是否支持必要的功能!
      注意-此设置应仅用于内部测试, 决不用于发布!
    • 从不-从不使用 krpano HTML5 播放器, 强制使用 krpano Flash 播放器。
  • 其他扩展设置 (用于控制呈现方法):
    • + webgl -仅当 webgl 可用时, 才使用 krpano HTML5 播放器。
      注意-有些功能只有在 WebGL 可用时才可用-例如全景视频支持、WebVR 支持、立体声渲染、球面和圆柱形图像、视图失真 (鱼眼、littleplanet).....。
    • + css3d -更喜欢 css3d 呈现的用法, 而不是 WebGL 呈现 (默认情况下 WebGL 将首选)。 css3d 设置应仅用于内部测试, 而不应用于发布!
    使用示例:
    • 首选 + webgl -仅当 webgl 可用时使用 krpano HTML5 播放器, 否则使用 Flash。
    • 仅 + webgl -仅当 webgl 可用时使用 krpano HTML5 播放器, 否则显示 错误消息 . 

flash:""
  • 设置 krpano Flash播放器的使用情况。
  • 这与 html5设置基本相同, 只是反向。 它可以用于更好的 url, 例如使用 flash = 首选而不是 html5=fallback .
  • 当设置 flash设置时, 将将其映射到 html5设置并改写它。
  • 可能的设置:
    • 自动或不设置-使用 html5设置。
    • 首选-希望尽可能使用 krpano Flash 播放器。
      仅当没有 Flashplayer 且系统/浏览器为 HTML5-compatible 时, 才使用 krpano HTML5 播放器。
      此设置将映射到 html5=fallback .
    • 回退-更喜欢在可能的情况下使用 krpano HTML5 播放器。 当 HTML5 不可用时, 请使用 krpano Flash播放器作为回退。
      此设置将映射到 html5=prefer .
    • 仅-仅使用 krpano Flash 播放器-从不使用 krpano HTML5 播放器。
      使用该设置, krpano Flash 播放器将在可能时使用。 如果没有 Flashplayer, 则会显示一条错误消息。
      此设置将映射到 html5=never .
    • 从不-从不使用 krpano flash 播放器, 只使用 krpano flash 播放器。
      此设置将映射到 html5=only . 

wmode:"..."
  • 设置 Flashplayer wmode
    设置.
  • 可能的设置:
    • window -Flashplayer 默认值, 即系统支持和性能之间的折衷。 注意-在某些系统和浏览器中, html 元素不能在这种模式下重叠 Flashplayer! 有关详细信息, 请参见此 wmode链接。
    • 不 透明-允许其他 html 元素与 Flashplayer 重叠 (视系统和浏览器而定)。
    • 不 透明-flash -与不 透明相同, 但仅对于 Flashplayer (将被 HTML5 播放器忽略-请参见下面的 HTML5 注释)。
    • 透明-使 Flashplayer 背景透明, 允许在 Flashplayer 后面看到 html 元素, 另外还允许其他 html 元素重叠 Flashplayer (取决于系统和浏览器, 这可能会导致速度减慢和 生涩渲染)。
    • 透明-Flash-与 透明相同, 但仅用于 Flashplayer (HTML5 播放器将忽略这些), 请参见下面的 HTML5 说明)。
    • 直接-最佳性能、硬件加速演示、在许多系统和浏览器上没有 html 重叠 (这通常是最快的模式, 但在不兼容或较旧的系统和浏览器中, 这可能会导致减速)。
  • 默认情况下, krpano 将使用 wmode = 直接, 除 Chrome 之外, 默认情况下将使用 wmode = 窗口(在调整大小期间, 性能更好, 没有黑窗口)。
  • HTML5 注意: wmode 设置通常是 Flashplayer 设置, 但 wmode = 不 透明和 wmode = 透明也将由 krpano HTML5 播放器评估, 并使播放器背景也透明。 在使用 HTML5 播放器时, 重叠的 html 元素本身始终是可能的。 

localfallback:"http://localhost:8090"
  • 在本地使用 file:// url 运行 HTML5 内容时, 几个浏览器 (特别是 Chrome 和 Safari) 限制了数据文件的动态加载! 在 krpano HTML5 播放器中, 这会影响 xml 和插件加载。
  • 有关此案例的详细信息, 请参阅此处- 本地用法 .
  • 为了避免在这种情况下得到 xml 加载错误, 嵌入脚本在这种情况下检查, 如果加载是可能的, 如果没有, 它提供了一些替代解决方案。
  • 可能的设置:
    • krpano 测试服务器的 url (默认情况下 http://localhost:8090 )
      • 如果将 localfallback 设置设置为 krpano 测试服务器(默认情况下) 的 url, 并且服务器当前已在运行, 则当前页将自动重定向到测试服务器, 以允许具有完整功能的本地 使用.
      • 当服务器未运行时, 将使用 error回退情况。
    • flash -使用 krpano flash 播放器代替。 Flashplayer 不受本地浏览器限制的影响。
    • 错误-显示有关本地使用情况的错误和信息消息。
      可以使用 onerror回调自定义错误消息。
    • 无-忽略它们是本地限制, 无论如何启动 HTML5 播放器.。 

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 中使用的变量 ( 如果检查 < 包括 > ) 元素.
  • 例如: 
    embedpano({..., initvars:{mypath:"./panos1/"} });
    xml: 
    url="%$mypath%image.jpg"
  • 若要能够直接在 html 文件的 url 上通过 http 查询传递 initvars变量, 则需要使用此语法: 
    tour.html?initvars.variable=value

basepath:...
  • 为解析相对于 krpano swf 文件的路径设置自定义基路径。
  • 可用于 Flash 和 HTML5 中, 用于调整 xml 中的相对路径。

consolelog:false
  • 定义 krpano 日志/跟踪消息的布尔设置是否也应发送到浏览器 Javascript 控制台。

mwheel:true
  • 用于控制鼠标滚轮使用的布尔设置。
  • 如果设置为 true (默认值), 则会捕获鼠标滚轮事件, 并可在播放器中使用 (例如缩放)。
  • 如果设置为 false, 则任何鼠标滚轮的使用都将被忽略, 浏览器将执行其默认的鼠标轮处理 (通常是滚动网页)。

capturetouch:true
  • 用于控制触摸事件 captureing 的布尔设置。
  • 如果设置为 true (默认值), 则将捕获触摸事件, 并可在播放器中使用 (例如, 用于平移和缩放)。
  • 如果设置为 false, 则播放器仍将使用触摸事件本身, 但它们的默认事件处理不会停止。 这意味着在这种情况下, 浏览器可能会平移或缩放网页。 

focus:true
  • 一个布尔设置, 使播放器在启动时输入/键盘焦点。
  • 如果未设置, 将根据播放器大小自动设置设置, 当播放器将覆盖整个网页时, 焦点将设置为 true, 否则为 false。
  • 这仅适用于 HTML5 (所有浏览器) 和 Chrome Flashplayer。 在其他浏览器中, Flash 元素需要用户初始单击才能获得焦点。 

webglsettings:{preserveDrawingBuffer:false, depth:false, stencil:false}
  • 为 WebGL 上下文创建传递具有特殊设置的对象。
  • WebGL 上下文将在启动时创建, 在运行时无法更改, 因此需要在嵌入过程中指定这些设置。
  • 可用设置:
    • preserveDrawingBuffer -保留绘图缓冲区内容。 当试图通过 toDataURL 或 readPixels 对 WebGL 画布进行截图时, 默认情况下为 false, 则需要启用该功能。
    • 深度-创建深度缓冲区, 默认情况下为 false。 需要为正确的 ThreeJS插件用法启用。
    • 模具-创建模具缓冲区, 默认情况下为 false。
    • failIfMajorPerformanceCaveat -当呈现性能显著低于本机应用程序的 OpenGL 呈现性能时, 不使用 WebGL, 默认情况下为 false。
  • 默认情况下, 所有这些设置都被禁用, 因为性能和内存原因 (特别是在移动设备上)。

mobilescale:0.5
  • 默认情况下, 移动设备上的所有 krpano 内容将被缩放0.5。
  • 要禁用该缩放, 请将 mobilescale设置设置为1.0。
  • 这对于实现响应 webdesigns 非常有用。
  • 另请参见 xml stagescale设置。

fakedevice:""
  • 假冒 krpano 设备检测设置。
  • 可用设置: "移动"、"平板"、"桌面"。
  • 注意-此设置应仅用于内部测试, 决不用于发布! 

onready:...Javascript-Function...
  • onready设置可用于设置调用回函数, 以便在完成嵌入操作时得到通知, 并且 krpano 播放器可以使用。
  • 将使用 krpano Javascript 接口对象调用给定函数.
  • 例如: 
    embedpano({target:"krpanoDIV", onready:krpanoReady});
function krpanoReady(krpano)
{
krpano.call("trace(krpano is ready...)");
}
  • Flashplayer 注意: 这个函数需要 Flashplayer 的外部接口! 这意味着只有在调整了 Flashplayer 的安全设置后, 回拨才能脱机/本地工作。 请参阅此处了解更多 detatils 本地/离线用法 . 

onerror:...Javascript-Function...
  • onerror设置可用于设置自定义嵌入错误处理功能。
  • 将使用错误消息字符串作为参数调用给定函数。

passQueryParameters:false
  • 布尔设置。 如果设置为 true, 则 html url 中的所有查询参数都将作为变量传递给播放器。
  • 如果启用, 则还可以直接在 html url 上传递 html5、 flash、 wmode、 mobilescale、 fakedevice和 initvars设置。
  • 使用示例: 
    tour.html?html5=only&startscene=scene2&initvars.design=flat

删除播放器

要从 html 页中删除全景播放器, 需要使用 removepano ()函数! removepano () 函数将删除所有内部连接的鼠标修复 (Flash) 和所有 DOM 元素和事件 (HTML5)。 


removepano(id);
  • 需要使用播放器对象的唯一 id调用 removepano () 函数。
  • 例如: 
    embedpano({target:"panoDIV", id:"pano1"});
...
removepano("pano1");