页面布局（AXML)

AXML 实现了一套标签语言的子集，用于描述页面模板的节点结构.

基础语法

AXML 有以下几个组成要素

• 实体标签，比如 <view>
• 控制标签，比如 <block>
• 属性，比如
  • 样式属性 class="hello" style="color:red;"
  • 节点属性 hover-class="view-hover"
  • 节点 dataset data-x="{{x}}"
  • 节点事件绑定 onTap="onHandleTap"
• 控制属性，如 a:if
• 文本，比如 <text>hello world</text>

标签

对于 实体标签 ，支持以下标签：

• <label>
• <progress>
• <view>
• <scroll-view>
• <image>
• <text>
• <button>
• <navigator>
• <swiper>
• <rich-text>
• <input>
• <textarea>

非控制属性

class

需要注意的是，对于 class 属性，由于目前底层限制，其工作模式为 有序带空格字符串，对于如下代码，其最终表现和标准支付宝小程序不一致

.a { color: #F00; }
.b { color: #0F0; }

<view id="v1" class="a b"></view>
<view id="v2" class="b a"></view>

上述示例中

• 对于支付宝小程序，样式覆盖规则始终以 css 为准(即b覆盖a)
• 对于精灵屏显模板，样式覆盖完全按照 class 中的顺序(即 #v1 为 b 覆盖 a，#v2 为 a 覆盖 b)

style

需要注意的是，对于 style 属性，遵守了 style 优先级比 class 高这一特点，但是只保证 对于同一个样式属性，style优先级比class高，这里的同一个样式属性对于 样式缩写 有局限性，对于如下代码，其最终表现不一致

.a { margin: 10rpx 5rpx; }

<view id="v1" class="a" style="margin: 5rpx 10rpx"></view>
<view id="v2" class="a" style="margin-top: 5rpx"></view>

上述示例中

• 对于支付宝小程序，margin-top 值最终都是 5rpx
• 对于精灵屏显模板，只有 #v2 节点的 margin-top 为 5rpx
  • 而 #v1 节点中，对于 class 中的 margin: 10rpx 5rpx 实际上在编译时被展开为了 margin-top: 10rpx 而 style 传入的 margin: 5rpx 10rpx 并没有覆盖 margin-top 值

事件

每个元素所额外支持的事件，以及事件回调中的事件对象，目前是支付宝小程序的子集，正在不断补充完善中，目前的支持程度可以查阅 自定义模板-标签

样式能力（ACSS)

精灵设备采用了一种更高性能的模式来渲染屏显模板，因此样式布局能力只支持Web标准的一个有限子集。

选择器

选择器种类

支持如下单选择器:

• 单类选择器 .className
• ID选择器 #id
• 类型选择器 view

选择器匹配

目前仅支持 , 逗号分隔匹配，如下

.aaa, .bbb {
}

对于如下规则均不支持

• 后代选择器 .a .b
• 类共存选择器 .a.b
• 通用选择器 *
• 伪类 .a::before
• 属性选择器 view[role]

style属性值

规则扫描

针对开发者写的样式代码，在进行真机预览或者发布模板操作时，会进行规则扫描

扫描等级

• 对于目前不支持的样式属性，默认等级均为 警告
• 针对部分写的不合理会造成严重布局问题的，会标记为 异常 ，并直接退出编译，请开发者按照以下完整样式属性支持情况修改代码再进行提交

单位

色彩单位

目前支持如下 4 种 写法:

color-unit {
   color: #AAA;
   color: #AAAAAA;
   color: rgb(255, 255, 255);
   color: rgba(255, 255, 255 1);
}

长度单位

支持 px , rpx ，不支持 100% 百分比的属性

长度单位+百分比

支持 px , rpx ，50.1%的属性

时间单位

支持 ms 毫秒，不支持 s 秒

缓动函数

• 枚举值
  • ease
  • ease-in
  • ease-out
  • linear
  • ease-in-out
• 贝塞尔曲线
  • cubic-bezier(x1,y1,x2,y2)
    • 其中 x1 ,y1 ,x2 ,y2 必须满足 >= 0 and <=1
    • 对于不符合数值区间的会自动降级为 ease-in

布局

只支持 Flex 布局，具体支持属性如下

盒模型

内外边距

支持 margin , padding ，但是具体细节有些不同

边框

能力支持，但是在语法解析上稍有不足 :::warning ⚠️ 不支持 border 简写，需要手动拆分成 border-width , border-style , border-color

• 上述简写问题，在 ACSS 文件编译时会被自动解析掉，但是直接写在 AXML 的 style 中不被支持 ::: | 属性名 | 默认值 | 支持程度 | 差异 | 异常等级 | | —- | —- | —- | —- | —- | | border | 0 solid black | ⚠️ 仅在 ACSS 中支持 | | | | border-width | 0 | 支持 长度单位 | | | | border-{pos}-width | 0 | 支持 长度单位, pos: 支持 top ,left ,right ,bottom | | | | border-style | solid | 支持 none, dashed, dotted, solid | | | | border-{pos}-style | solid | 支持 none, dashed, dotted, solid | | | | border-color | black | 支持 色彩单位 | | | | border-{pos}-color | black | 支持 色彩单位 | | | | border-radius | 0 | 支持 长度单位, 仅支持 单值 , 不支持 1px 1px 1px 1px | | 严重 | | border-top-left-radius | 0 | 支持 长度单位 |
  | | | border-top-right-radius | 0 | 支持 长度单位 | | | | border-bottom-left-radius | 0 | 支持 长度单位 | | | | border-bottom-right-radius | 0 | 支持 长度单位 | | |

宽高

装饰样式

- url(“data:”) base64 编码
- linear-gradient(s1, s2, …, slast)
- 第一段
- 必须是 deg 单位
- 第二段
- 色彩单位
- 如果有百分比值，必须为 **0%**
- 中间段
- 色彩单位
- 必须写百分比值
- 最后一段
- 色彩单位
- 如果有百分比值，必须为 **100%**
| 严重 | | background-color | transparent | 支持 色彩单位 | 严重 | | background-size | | 可枚举值支持 cover, contain, auto, unset
- ${x}px ${y}px 双值 长度单位
- ${x}px 单值 长度单位
| 严重 | | background-position | | 支持 top, right, bottom, left, center | 严重 | | background-repeat | no-repeat | 支持 repeat-x, repeat-y, no-repeat, repeat; | 严重 | | box-shadow | | 支持格式 ${x} ${y} ${size} ${color}
- x, y, size 满足 长度单位
- color 满足 色彩单位
| 严重 | | opacity | 1 | 0 到 1之间的浮点数值 | 严重 |

文本样式

:::warning 注意 标签内不能应用 display: flex 布局 ::: | 属性名 | 默认值 | 支持程度 | 异常等级 | | —- | —- | —- | —- | | color | | 支持 色彩单位 | 严重 | | font-family |
- iOS: “PingFang SC”, “Helvetica Neue”
- Android: 系统字体
| | | | font-size | | 支持 长度单位 | 严重 | | font-style | |
- italic
| | | line-height | | 支持 长度单位, 支持倍数 | 严重 | | font-weight | normal | normal ,bold | 严重 | | text-overflow | clip | clip ,ellipsis | | | lines | | 用以表示文本行数，设置为 1 时并且 text-overflow 为 ellipsis 即为 ... 省略效果 | | | text-decoration | none | none , underline , line-through , underline line-through | |

动画

transform

- 放缩: scale / scaleX / scaleY 支持 数值
- 旋转: rotate 仅支持 deg
- 偏移: translate / translateX / translateY ，支持 长度单位+百分比
- 多个函数同时支持程度
- translate 必须在 scale 的左边( scale 不会影响 translate 的倍率 )
- translate 必须在 rotate 的左边( rotate 不会影响 translate 的方向)
- 同一个函数名只能出现一次
| 严重 | | transform-origin | center | 只支持 center，请使用position/margin偏移来替代实现 | 严重 |

transition

animation

- @keyframes 的 step 支持
- from, to
- 百分比值
| 严重 | | animation-timing-function | | 支持 缓动函数 | 严重 | | animation-iteration-count | |
- 支持数值
- 支持 infinite (等价于 9999)
| 严重 | | animation-direction | normal | 支持 normal ,alternate | 严重 | | animation-delay | 0ms | 支持 时间单位 | 严重 | | animation-duration | 0ms | 支持 时间单位 | 严重 | | animation-fill-mode | forwards | 支持 forwards ,backwards ,both | 严重 |

**

@keyframes

• 选择器
  • 支持 to ,from ,50% 百分比值
  • 必须写 0% 和 100% 这两个边界值
• 属性值

支持 transform ,opacity ,background-color 。其他一概不支持

• 示例

  @keyframes Test {
  from {
    opacity: 0;
  }
  50% {
    opacity: 0.6;
  }
  100% {
    opacity: 1;
  }
  }

逻辑能力（JS)

模板的执行逻辑需要按照 commonjs 的模块规范进行封装，写在 logic.js 中，比如

// logic.js
module.exports = {
    onTemplateLoad: function(dataSource) {
    // 模板首次加载时，默认会将云端下发的 dataSource 解构赋值到 this.data 中，
    // 比如 dataSource = { text: 'hell world'}，
    // 那么在模板加载后，this.data.text = 'hello world'
    // 如果需要对云端下发的数据进行二次处理，可以再次执行 this.setData
    var newText = 'genie ' + dataSource.text;
    this.setData({
      text: newText,
    });
  },
  onTemplateUpdate: function(dataSource) {
      // 同样，在模板更新数据时，云端下发的 dataSource 也会解构赋值到 this.data 中
    // 比如二次下发的 dataSource = { text: 'hell world again' }，
    // 那么在模板数据更新后，this.data.text = 'hello world again'
    // 如果需要对云端下发的数据进行二次处理，可以再次执行 this.setData
    var newText = 'genie ' + dataSource.text;
    this.setData({
      text: newText,
    });
  },
  // layout.axml 中节点绑定的事件函数可以封装在这个模块中
  customTapHandler: function(e) {},
};

通用

模板生命周期回调

模板在第一次加载和二次更新时会触发相应生命周期的回调函数，开发者可以在这两个回调函数中进行一些数据处理、初始化等逻辑

• onTemplateLoad: 模板首次加载时触发

• onTemplateUpdate: 模板在前台展示过程中，如果设备接收到同一个模板的 Render 指令时触发

  示例

  // logic.js
  module.exports = {
  // 模板首次加载时，默认会将云端下发的 dataSource 解构赋值到 this.data 中，
  // 也可以增加一些页面启动逻辑，比如动画的初始化等
  onTemplateLoad: function() {
    var originTextFromCloud = this.data.text;
    var transformedText = originTextFromCloud + '$$';
        this.setData({ text: transformedText });
  },
  // 模板在前台展示过程中，如果设备接收到同一个模板的 Render 指令时触发
  onTemplateUpdate: function() {
  },
  };

  UI交互事件绑定

  在页面布局中可以给标签声明交互事件的处理函数方法，处理函数可以声明在 logic.js 中

  示例

  <view id="demo" onTap="onViewTap" data-text="hello world">Say Hi</view>

  // logic.js
  module.exports = {
  onTemplateLoad: function() {
  },
  onTemplateUpdate: function() {
  },
  onViewTap: function(e) {
    console.log(e.target.dataset.text);
  }
  };