krpano使用简化的xml文本文件存储krpano viewer的数据。这些文件可以使用任意文本编辑器进行编写和编辑，但在编写xml代码时，需注意符合xml语法规则。本文档的官网英文说明

xml语法规则简单、符合逻辑、易学易用。

下面是规则说明：

• xml文件由若干xml元素组成，也叫做xml节点或xml标签。
• xml元素的名字由一对单括号<>包围。
  
  <元素名>

  1

  <元素名>

• 每个xml元素都需要闭合。
  有两种形式 – 一个是包含开始与结束元素：
  
  <元素名> ... </元素名>

  1	<元素名> ... </元素名>

  一个是如下简单的闭合：
  
  <元素名/>

  1

  <元素名/>

• 一个xml元素可以包含额外的xml子元素。
  在这种情况下，xml元素必须写成以下形式：
  
  <父元素名字> <子元素名字/> </父元素名字>

  1 2 3

  <父元素名字>    <子元素名字/> </父元素名字>

• 一个xml元素可以拥有一个或多个属性。每个属性由一个属性名与属性值组成。属性值必须写在单引号或双引号里。
  
  <父元素名 属性名="数值"> <子元素名 test1="value1" test2="value2" /> </父元素名>

  1 2 3

  <父元素名 属性名="数值">    <子元素名 test1="value1" test2="value2" /> </父元素名>

  注意 – 一个元素的重复属性是不允许的，会引起语法错误！
• 在xml文件里始终有一个根元素。它的级别高于其它元素。所有其它的xml元素必须包含在其中。
  对于krpano viewer而言，这个元素就是<krpano> 元素，例如：
  
  <krpano onstart="..."> ... <preview url="..." /> <image> <cube url="..." /> </image> ... </krpano>

  1 2 3 4 5 6 7 8

  <krpano onstart="...">    ...    <preview url="..." />    <image>      <cube url="..." />    </image>    ... </krpano>

• 注释 – 注释是xml的一部分，在读取或解析xml文件时会被忽略。xml的注释始于：
  
  <!--

  1

  <!--

  结束于：
  
  -->

  1

  -->

  在注释中不允许包含字符串‘–’。也就是说注释符号是成对出现的。

  例子：

  <krpano ...> <!-- this is a krpano example --> ... </krpano>

  1 2 3 4

  <krpano ...>    <!-- this is a krpano example -->    ... </krpano>

• xml元素与xml属性是区分大小写的。也就是说元素起始的名字必须是相同的大小写。
  注意 – 对于xml语法规则来说，大小写非常重要，但对于krpano viewer本身，krpano的xml元素的大小写没有区分 – krpano viewer会自动将所有元素和属性的名字转换成小写，使得它们的krpano使用是区分大小写的。
• 为了避免字符编码问题，所有的xml文件应该保存为UTF-8或UTF-16文件。在这种情况下，文本编辑器会自动在xml文件的开头添加一个小的隐藏头部，称之为UTF-BOM。
• 在xml元素和xml属性之间的空白诸如空格、制表符、换行会被忽略。但属性数值内部的空白将会保留。这可以允许以多种方式自由编写和结构xml。但为了更好的可读性，通常使用缩进方式使得xml结构更加清晰。
• 部分字符在xml语法中是保留字符，因此不能直接使用。
  你需要用指定的字符串进行替换：

  禁止字符	替换方式	字符描述
  <	&lt;	小于
  >	&gt;	大于
  &	&amp;	和
  ‘	&apos;	单引号
  “	&quot;	双引号

• 你只需要在浏览器直接打开xml文件，就能检查xml的语法错误。如今大多数浏览器可以直接显示错误的类型和位置。
• 下面是xml错误的快速检错表。
  1. 是否包含根元素
     <krpano>
     …
     </krpano>
  2. 是否所有元素正确闭合？
     

     错误	正确
     <element> … <element>	<element> … </element>
     <element … >	<element … />

  3. 是否所有的xml注释都是正确的？（以<!–开始，以 –>结束，中间不包含 –）
     <!– <!– nested comment –> –>
     <!–——–>
  4. 是否有保留字符？（例如&、< 和 >）
     

     错误	正确
     text=”krpano & xml”	text=”krpano & xml”
     text=”<xml>“	text=”&lt;xml&gt;“
     if(x < 10, …)	if(x LT 10, …)

  5. 是否所有的属性值都有引号？
     

     错误	正确
     <element x=123 … />	<element x=“123” … />
     <element x=123 … />	<element x=‘123’ … />

  6. 是否在一个元素里有重复属性？
     <element x=“123” x=“456” … />
  7. 两个属性之间是否有空格？
     

     错误	正确
     <element x=”123″y=”456″	<element x=”123″ y=”456″

• 有时候在Flashplayer正常运作，但在HTML5版本中会显示错误信息。
• 原因是在Flashplayer中对于xml的解析，在对待xml语法错误时要比HTML5浏览器更为宽松。
• 简单的办法很简单 – 确保没有任何语法错误，使其在Flash和HTML5都正常运作。