# krpano-learn

**Repository Path**: h7374521/krpano-learn

## Basic Information

- **Project Name**: krpano-learn
- **Description**: 学习krpano而创建的仓库
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-03-04
- **Last Updated**: 2025-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

跟着[krpano中文网](http://www.krpano360.com/)的入门教程一步步尝试, 然后零零散散地记一些笔记:
> krpano version: 1.20.9

# 起步
使用下载的krpano文件夹中的工具可直接生成本demo

# [循序渐进（6）- 为何本地预览时在浏览器中显示错误](http://www.krpano360.com/xunxujianjin6-weihehtmlwenjianzailiulanqizhongxianshiheipingcuowu/)

## 编辑漫游
文中使用编辑工具加载`tour.xml`设置了启动视角, 并添加了一个热点, 发现这个加载的xml文件中就有了相应的修改变动:
启动视角:
```
<view hlookat="-51.240" vlookat="-4.454" fovtype="MFOV" fov="120.000" maxpixelzoom="2.0" fovmin="70" fovmax="140" limitview="auto" />
```
热点:
```
<hotspot name="spot1" style="skin_hotspotstyle" ath="-97.505" atv="5.397" linkedscene="scene_sb0criu-360-panorama-shore" />
```
文中提供了一个看示例的方法运行`krpano`文件夹里面的`krpano Testing Server.exe`, 然后修改本地文件夹为:
`D:/{krpano目录}/viewer/`, 接着点击这个测试服务器下方的`Sever Address`即可, 然后能看到`/viewer`目录下的文件, 点击相应的`example`即可, 选择完毕之后地址会变为: `http://192.168.3.38:8090/krpano.html?xml=examples/animated-hotspots/anihotspots.xml`, 后面发现是因为`/example/index.html`里面有个一个`meta`标签的内容是:
```
<meta http-equiv="refresh" content="0; url=../../krpano.html?xml=examples/demotour-corfu/tour.xml" />
```
这导致页面渲染到浏览器的时候直接浏览器做了刷新操作, `url`被替换成了这个`meta`标签的`content`中的`url`, 我自己也写了一个`html`文件试了试, 发现浏览器解析到`html`文件的`meta`标签的时候时`url`就被变更了, 后面的内容都不会被解析, `body`中的`js`也不会被执行
查看`w3c`文档之后发现这个操作相当于是给`响应头`里添加了一个键值对:
```
refresh: 0; url=../../krpano.html?xml=examples/demotour-corfu/tour.xml
```

## 参数问题
工具制作成的漫游项目的启动代码如下:
```
embedpano({
  swf:"tour.swf",
  xml:"krpano.xml",
  target:"pano",
  html5:"auto",
  mobilescale:1.0,
  passQueryParameters:true
});
```
`passQueryParameters`设置为`true`, 此时表示能从`url`中接收`查询字符串参数`, 比如启动之后`url`为这样:

```
http://192.168.3.101:8090/tour.html?xml=/tour.xml
```
那么此时, `krpano`将只会加载`tour.xml`而不会加载配置中的`xml`的值`krpano.xml`, 相反, 如果此时`url`上没有参数, 则只会加载`krpano.xml`

## 启动问题
通过xhr加载xml的问题, 这是由于浏览器的CORS策略导致的, 解决方法有两个:
1. https://krpano.com/docu/localusage/#changebrowsersettings, 修改浏览器的策略
2. 使用服务器环境, 比如直接用自带的`krpano testing server`
这里需要注意的是, 为了让服务器环境能正常启动生效, 路径里面不要带中文, 同时, 在学习过程中, 可能会遇到需要频繁查看`krpano`官方示例的情况, 那么此时可以使用`/vtour/tour_testingserver.exe`来启动我们自己的`demo`, 用`krpano`包里的`krpano testing server`来启动官方示例(`Local Folder`选到`viewer`文件夹即可), 这样就能一边写`demo`一边看官方示例了

# [循序渐进（11）- 1.19版本的默认tour.xml解析与换肤](http://www.krpano360.com/xunxujianjin11-tour-xmldejingtaidaimadouyoushenmezuoyong/)

## skin_settings标签
- `littleplanetintro`: 是否使用小行星开场
(其他标签可查看文章)

### 覆盖已经定义的xml配置(小行星开场)
给`embedpano`做如下设置能覆盖原本的配置, 从而打开小行星入场:
```
vars: {
  "skin_settings.littleplanetintro": "true"
}
```
`embedpano`方法接收的参数具体可以查看[Embedding into HTML](https://krpano.com/docu/html/)

### 设置小行星视角的第三种方式
```
initvars: {
  "view": "planet"
}
```
这个方法会在加载`xml`之前执行, 以及这个视角设置之后视角会一直保持小行星视角, 而且距离会很远, 不像`vars`设置的那样

## include标签
这个用于嵌入另一个`xml`标签, 由于`xml`的执行顺序也是从上到下的, 因此如果`a.xml`嵌入`b.xml`:
```
<!-- a.xml -->
<krpano>
  <include url="./b.xml" />
  <settings maps="false" />
</krpano>
```
```
<!-- b.xml -->
<krpano>
  <settings maps="true" />
</krpano>
```
这样的写法, `b.xml`中的配置会被`a.xml`给覆盖了, 反之如果`include`写在后面, 则是`a.xml`中的配置会被`b.xml`中的给覆盖

# [循序渐进（12）- krpano的内置元素](http://www.krpano360.com/krpanode26geneizhiyuansu/)
## 自定义右键菜单
通过`xml`中的`contextmenu`标签来自定义右键菜单, 比如自带的视角切换是英文的, 可以修改成中文的:
```
<contextmenu>
  //...
  <item name="lp" caption="Little Planet View" onclick="skin_view_littleplanet();"  showif="view.vlookatrange == 180" devices="flash|webgl" />
  //...
</contextmenu>
```
```
<contextmenu>
  //...
  <item name="lp" caption="小行星视角" onclick="skin_view_littleplanet();"  showif="view.vlookatrange == 180" devices="flash|webgl" />
  //...
</contextmenu>
```
但更自由的, 比如右键菜单中新增一个里面没有的项目, 然后做其他的功能, 比如点击之后打开一个弹窗这个暂时不了解, 目前唯一确定的就是其他的功能不比如小行星视角, 调用了一个叫`skin_view_littleplanet`的方法(`action`):
```
<action name="skin_view_littleplanet">
  tween(view.architectural, 0.0, distance(1.0,0.5));
  tween(view.pannini,       0.0, distance(1.0,0.5));
  tween(view.distortion,    1.0, distance(1.0,0.8));
  tween(view.fov,           150, distance(150,0.8));
  tween(view.vlookat,        90, distance(100,0.8));
  tween(view.hlookat, calc(view.hlookat + 100.0 + 45.0*random), distance(100,0.8));
  skin_deeplinking_update_url(1.0);
</action>
```
那么解法就在于在`action`标签中写代码了, 我推测这也是`krpano`的一个难点, 也就是它里面代码的语法规则是怎样的, 是如何被解析的

## 路径占位符
[url](https://krpano.com/docu/xml/#url)
`krpano`使用一些约定的占位符来解决路径层级过深的问题, 相当于目前前端工程化项目中的`@`指代`src`那样

## krpano和js之间的交互
[krpano js interface](https://krpano.com/docu/js/#top)
[External / Javascript Interface](https://krpano.com/docu/actions/#js)

### krpano调用js
法一:

这会是一个核心的内容, 探索了一下, `krpano`中调用`js`确实需要用到`action`:
```
<action name="myAction" type="Javascript">
  console.log(123);
</action>
```
比如使用的时候, 右键点击项被点击之后调这个方法:
```
<item name="aaa" caption="调js方法" onclick="myAction();" />
```
那么这个`js`方法就会被执行

法二:

更常见的情形是我们的`js`代码没写在`krpano`的`action[type="Javascript"]`中, 就在我们的项目里, 此时如果遇到`krpano`调用的话, `krpano`也提供了调用的接口或者说调用的处理方式:
`js`:
```
function foo(param) {
  console.log('foo invoked', param);
}
```
`krpano action`:
```
<action name="skin_view_littleplanet">
  tween(view.architectural, 0.0, distance(1.0,0.5));
  tween(view.pannini,       0.0, distance(1.0,0.5));
  tween(view.distortion,    1.0, distance(1.0,0.8));
  tween(view.fov,           150, distance(150,0.8));
  tween(view.vlookat,        90, distance(100,0.8));
  tween(view.hlookat, calc(view.hlookat + 100.0 + 45.0*random), distance(100,0.8));
  skin_deeplinking_update_url(1.0);
  js(foo(abc));
</action>
```
这里还是以`小行星视角`的`action`为例, 在里面加上一行:
```
js(foo(abc));
```
那么切换`小行星视角`的时候我们就能通过`krpano`调用`js`方法`foo`, 最终输出:
```
foo invoked abc
```
同时需要注意的是, `js`中定义的方法要写在`全局`, 也就是要写到`window`上, 否则`krpano`无法调到

### js调用krpano
方法一:

右键菜单中加一项, 点击之后执行`js`并调用`小行星`视角方法
```
<item name="aaa" caption="调js方法" onclick="myAction();" />
```
```
<action name="myAction" type="Javascript">
  console.log(123);
  krpano.call("skin_view_littleplanet();");
</action>
```
方法二:

这是官方文档中推荐的一个方法, 但这是`onready`这生命周期执行之后调用, 实际情况要看是否需要在该生命周期中执行
```
embedpano({
  //...
  onready: krpano => {
    krpano.call("skin_view_littleplanet();");
  }
  //...
});
```
往后看的过程中发现, 有一个场景可能比较常见: 直接在`js`代码中的任意位置随意调用`krpano`的方法; 而`krpano`这个实例只能在`action[type="Javascript"]`中访问到, 而这个里面能写`js`, 那么我可以在项目一开始加载的时候将`krpano`实例设置到`window`对象上即可, 此时的`window`对象可以理解为`JSBridge`, 一个桥梁, 一个连接`js`和`krpano`的桥梁, 具体写法如下:
```
<action name="init" type="Javascript" autorun="preinit">
  <![CDATA[
    window.krpano = krpano;
  ]]>
</action>
```
这里的`autorun="preinit"`表示:
```
preinit - 'Pre-Initialize' - run this action at initialization before any other event or action (also before the onstart event). Will be called only ONCE.
> 在初始化时, 任何其他事件和动作(也在onstart事件)之前执行, 它只会被执行一次
```
看了官网文档的解释, 给这个`action`设置`autorun="preinit"`再合适不过
此时如果我们需要在`js`代码里切换`小行星视角`, 那么此时就可以这么写:
```
window.krpano.call('skin_view_littleplanet');
```
这样的写法也可以:
```
window.krpano.call('skin_view_littleplanet()');
```
但私以为第一种写法要更合适, 毕竟我们要调用`skin_view_littleplanet`这个方法, 那么给它传方法名即可, 而不是方法的调用, 除非这个方法调用之后返回另一个方法, 但观察`krpano`的例子发现, 在标签中调用`action`的方式是这样的:
```
//...
onclick="skin_view_stereographic();"
//...
```
就是还是加了`()`, 尝试后发现这样不加`()`也是可以的:
```
<hotspot
  name="spot1"
  style="up-arrow-style"
  ath="-97.544"
  atv="3.675"
  linkedscene="scene_sb0criu-360-panorama-shore"
  ondown="_1st_hotspot_down"
/>

<action name="_1st_hotspot_down" type="Javascript">
  <![CDATA[
    console.log(123)
  ]]>
</action>
```
以及我们的切换`小行星视角`:
```
onclick="skin_view_littleplanet"
```
这里需要注意的是这个标签:
```
<![CDATA[

]]>
```
论坛中`krpano`的作者`Klaus Reinfeld`回复说这是为了防止某些字符在解析`xml`时导致`xml解析错误`而设置的, 他推荐的处理方式是: 无论如何都加上; 原贴如下:

[Question about 'CDATA' inside JavaScript type action in xml](https://krpano.com/forum/wbb/index.php?page=Thread&threadID=16034)

这里不特指写`js`的时候需要加, 作者只是以`js`来举例, 同时在后面的学习中发现`krpano`自己的`action`中也出现了这个标签, 但写`js`的时候推荐加上, 理由就是防止出现解析报错的问题出现

# [修改默认皮肤缩略图文字大小](http://www.krpano360.com/%e4%bf%ae%e6%94%b9%e9%bb%98%e8%ae%a4%e7%9a%ae%e8%82%a4%e7%bc%a9%e7%95%a5%e5%9b%be%e6%96%87%e5%ad%97%e5%a4%a7%e5%b0%8f/)
加载一些`xml`配置是通过`action`标签里写的方法实现的, 比如修改一个默认皮肤的样式, 这个样式是被`action`标签加载进来的, 比如`缩略图文字样式`的`style`: `<style nmae="skin_thumbtext_style" ...>...</style>`, 首先显示缩略图文字的设置在这:
`tour.xml`:
```
<skin_settings
  //...
  thumbs_text="false"
  //...
</skin_settings>
```
`thumbs_text`改为`true`即可, 然后具体样式在样式标签中修改, 比如改个字号:
```
<style
  name="skin_thumbtext_style"
  //...
  css="calc:skin_settings.design_text_css + ' text-align:center; font-size:10px;'"
  //...
</style>
```
`font-size:10px;`修改为`font-size:20px;`

# [如何控制默认热点跳转到指定场景的指定视角](http://www.krpano360.com/ruhekongzhimorenrediantiaozhuandaozhidingchangjingdezhidingshijiao/)
当前版本的`场景跳转视角`修改是通过给`热点`标签设置属性来完成的:
```
<hotspot
  name="spot1"
  style="skin_hotspotstyle"
  ath="-171.038"
  atv="2.727"
  linkedscene="scene_09r1n16-a-small-boat-in-a-body-of-water"
  linkedscene_lookat="36.0, 0.0, 120.0"
/>
```
设置一下这个: `linkedscene_lookat="36.0, 0.0, 120.0"`即可, 这个`linkedscene_lookat`由三个值组成, 分别是`hlookat`, `vlookat`和`fov`, `krpano`中的`fov`应该指的是`水平方向的fov`

# [让官方皮肤在手机展示时也默认弹出缩略图（1.18）](http://www.krpano360.com/rangguanfangpifuzaishoujizhanshishiyemorendanchusuoluetu/)
`tour.xml`中修改皮肤设置:
```
<skin_settings
  //...
  thumbs_opened="true"
  //...
/>
```
将`skin_settings`的`thumbs_opened`改为`true`即可, 同时需要注意的是, 这个文章是`1.18`的, 里面提到设置不生效的情况, 然后解决方法是去这个`action`里面修改它的`action`的逻辑:
`vtourskin.xml`中:
```
<action name="skin_startup" scope="local">
//...
</action>
```
这个`action`相当于是一个生命周期, 皮肤刚加载的生命周期, 看到现在, 我发现`action`里的代码代表一个一个的动作或者说是指令, 类似于`react`中的那个`action`, 而`krpano`中的`action`里的代码并不是`js`, 乍一看挺像, 但语法完全不一样, 只是有些相似, 它有着自己的语法规则

# krpano action探究
> 参考文档: [krpano XML Reference: action](https://krpano.com/docu/xml/#action)
> 这部分就是上方的js和krpano通信的一个详细的内容

## Normal krpano actions
`demo`里的`action`就是这个样子的, 这些`action`在`krpano`中进行使用, 比如之前的右键菜单点击事件这些

## Javascript krpano actions
比如还是右键`小行星`:
```
<contextmenu>
  //...
  <item name="lp" caption="Little Planet View" onclick="myJsAction(cba);"  showif="view.vlookatrange == 180" devices="flash|webgl" />
  //...
</contextmenu>
```
```
<action name="myJsAction" type="Javascript"><![CDATA[
  krpano.call("skin_view_littleplanet();");
  //在这个作用域中预定义了一些对象 方法:
  console.log(krpano); //krpano实例
  console.log(args); //该action被调用时传过来的参数, args[0]是方法名, args[1]是第一个参数, 以此类推
  console.log(caller); //调用这个action的<layer>, <plugin>或<hotspot>
  console.log(resolve); //用于解析/获取krpano变量/路径的值的函数, 当给定的变量/路径存在时，将返回该值，而当变量/路径不存在时，将按原样返回传递的值
  console.log(actions); //内置的原生krpano action
]]></action>
```
或者:
```
<action name="myJsAction" type="Javascript">
  //...
></action>
```
这两种是一样的, 只是`action[type="Javascript"]`在官方文档中写法是:
```
<action name="..." type="Javascript"><![CDATA[
    ...
    Javascript code
    ...
]]></action>
```
也就是在`action`标签和`js`代码之间有个`<![CDATA[...]]>`, 按照官网的来即可, 这里只列举了部分内容, 详细内容可参考官方文档
同时这里提到一个`api`: `debugjsactions`, 当我们在`action`标签中写`js`的时候, 默认情况下, `js`的报错信息会被捕获, 没法在`浏览器控制台`里输出, 当设置了`debugjsactions`为`true`时错误信息就不会被捕获了, 而这个设置我试了在`skin_settings`标签中设置, 结果不对, 后来灵机一动: 这是某个标签的属性, 那我去看标签文档即可, 于是在`krpano xml`文档处搜索, 可一无所获, 最后是这句话给了我灵感:
```
The advanced elements and attributes are hidden by default and can be shown (or hidden) by pressing the [show/hide advanced settings]  button withhin each part of the documentation.
> 默认情况下, 高级元素和属性是被隐藏了的, 你可以通过点击文档每个部分中的[显示/隐藏高级设置]按钮来显示/隐藏它们
```
然后结合我的经验, `debug`功能一般是顶层或者说是全局开启, 因此我点了`krpano`标签那的`[show/hide advanced settings]`之后就看到了`debugjsactions`的设置:
```
<krpano
  //...
  debugjsactions="true"
  //...
>
//...
</krpano>
```
此时在`action[type="Javascript"]`中就能正常显示`js`异常了

# 隐藏默认皮肤
法一:
```
set(layer[skin_layer].visible, false);
```

法二:
```
<action autorun="onstart">
  delayedcall(0.5, skin_hideskin(instant);set(layer[skin_layer].visible,false););
</action>
```
这个`action`的意思是当`onstart`的时候自动执行, 执行的内容就是`action`里面的代码, `delayedcall`为其内置的方法, 内置方法可查看`krpano`的文档: [krpano Actions / Scripting Reference](https://krpano.com/docu/actions/), 其中`delayedcall`的函数签名为: `delayedcall(delay, actions)`, 延迟`0.5`秒后做了两件事: `skin_hideskin(instant);`和`set(layer[skin_layer].visible,false);`, `skin_hideskin`是一个`name`为`skin_hideskin`的`action`, 另一个操作是内置的`set`方法, 目的是隐藏`skin_layer`, 以及这里这个`action`的`name`可加可不加, 不加的话只是别的地方就没法调用了

# plugin标签
插件的应用在看[Dragable Hotspots](https://krpano.com/releases/1.20.9/examples/#dragable-hotspots)的时候尝试过, 只是结合自己的`demo`的时候发现了一个坑: 这个`plugin`要写到`scene`标签内, 而不能像其他标签一样是`krpano`标签的直接子标签, 不然无法生效, 同时需要留意的是这个`action`:
```
<action name="print_hotspot_pos"><![CDATA[
  copy(print_ath, ath);
  copy(print_atv, atv);
  roundval(print_ath, 3);
  roundval(print_atv, 3);
  calc(plugin[hotspot_pos_info].html, '&lt;hotspot name="' + name + '"[br]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...[br]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ath="' + print_ath + '"[br]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;atv="' + print_atv + '"[br]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;...[br]&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;/&gt;');
]]></action>
```
没有`js`代码但是却使用了`CDATA`标签, 目的是为了解析特殊字符, 不然就会报错, 这也从侧面印证了作者的回帖中关于`CDATA`标签作用的解释

# 动画热点
有动画效果的热点的设置, 官方`demo`: [Animated Hotspots](https://krpano.com/releases/1.20.9/examples/#animated-hotspots)中提供了一个动画`action`:
```
<action name="do_crop_animation" scope="local" args="framewidth, frameheight, framerate">
  <!-- define local variables -->
  calc(local.xframes, (caller.imagewidth /framewidth) BOR 0);
  calc(local.frames, xframes * ((caller.imageheight / frameheight) BOR 0));
  def(local.frame, integer, 0);

  <!-- set the first frame -->
  calc(caller.crop, '0|0|' + framewidth + '|' + frameheight);

  <!-- do the animation -->
  setinterval(calc('crop_anim_' + caller.name), calc(1.0 / framerate),
    if(caller.loaded,
      inc(frame);
      if(frame GE frames, if(caller.onlastframe !== null, callwith(caller, onlastframe() ) ); set(frame,0); );
      mod(xpos, frame, xframes);
      div(ypos, frame, xframes);
      Math.floor(ypos);
      mul(xpos, framewidth);
      mul(ypos, frameheight);
      calc(caller.crop, xpos + '|' + ypos + '|' + framewidth + '|' + frameheight);
      ,
      <!-- stop the interval when the hotspot gets removed -->
      clearinterval(calc('crop_anim_' + caller.name));
    );
  );
</action>
```
调用的时候传递`宽`, `高`, `帧率`即可, 只是不同的图片, 传递的`宽`, `高`会有不同

# 文字热点
```
<hotspot
  name="mytext"
  type="text"
  ath="-108.043"
  atv="21.781"
  edge="center"
  distorted="true"
  renderer="webgl"
  html="一个文字热点"
  css="font-family:Arial; font-size:16px; color:#fff;"
  vcenter="false"
  padding="2"
  wordwrap="true"
  bg="true"
  bgcolor="0x52c41a"
  bgalpha="1.0"
  bgborder="0"
  bgroundedge="0"
  bgshadow=""
  txtshadow=""
  mergedalpha="true"
  oversampling="1.0"
  mipmapping="false"
  onautosized=""
  onclick="text_hotspot_click"
/>
```
这是`1.19`之后的`文字热点`的使用方法, 详情可查看官方文档: [Textfield Plugin](https://krpano.com/plugins/textfield/), 同时, 这里的`onclick`事件`text_hotspot_click`是一个自定义的`action`

# 其他自定义操作
沙盘可以看这个示例: `demotour-winecellar`

自定义皮肤可以看这几个示例: `demotour-corfu-skinselect`, `dragable-layers`

弹窗相关可以看这个: `postprocessing`

## 自定义皮肤
自定义皮肤的操作可以使用`layer[type="image"]`来设置图片作为自定义皮肤, 但如果图片没法满足的场景, 比如半透明的效果而且有和默认皮肤不同的矩形或者其他形状的时候则需要使用`html`, `css`来写皮肤, 再通过和`krpano`的交互来完成(比如场景切换)

同时需要注意的是使用`layer[type="container"]`的时候如果要使用`bgcolor`那么`bgalpha`也要一起设置上, 不然`bgcolor`无法生效, 只用`bgborder`的时候是不需要的