模板和组件

频道

在 APP 中,频道是展示和存储消息流的载体,普通用户通过订阅频道之后,开发者可以主动推消息给指定订阅者或频道全体订阅者,订阅者也可以主动通过频道菜单互动产生消息。订阅者在频道中可以通过消息与开发者服务进行互动。

频道菜单

菜单作为功能入口,提供用户主动与频道进行互动的能力,用户通过点击菜单,可以生成新消息、打开新页面(加载模板)和打开链接。菜单管理请前往开发者后台-频道-菜单管理进行操作。


模板与数据

  • 模板

    不同于于以往普通的文本或图文信息,为了让消息具备丰富的展示和互动能力,为此而专门设计开发的一套模板语言。模板类似XML 语法,支持变量、事件,仅需短短几行代码即可定义一个具备丰富展示和互动能力的模板。因此,超级消息 APP 中的消息更像是一个微型网页或者表单,允许用户在消息上面进行互动操作,以便更高效的处理事务。每一条消息可以使用一个模板,只 要消息没删除,就可以通过动态地更换模板,让同一条消息可以使用不同的展示方式。

    模板同样可以在(本地)页面中渲染。

  • 数据

    消息数据是一串 JSON 格式的字符串,每次随着消息一起推送或者在 API 请求中返回,配合模板用于渲染。

    消息数据是可选的。


模板版本号

通常情况下,一条消息会包括一个模板消息变量(即填充模板的数据),在消息发送到用户手中设备时数据会被存储,一段时间之后,用户仍然可以通过查看历史数据找回这条消息。因为业务变更,需要对模板进行升级,如果强行将用户设备中的旧模板进行更新,那么新模板旧消息变量之间可能会引起冲突。

因此,对于已经发布的模板将不允许修改,取而代之的操作是,在旧模板的基础上,新建一个新版本的模板,内容与旧模板一样,在此内容上进行更新,然后发布出去。这样同一个模板,就存在不同的版本,而不同的版本可能对应着不同的消息变量,只要每次推送的消息模板和消息变量是匹配的,历史消息和新消息都不会出现冲突。

对于大部分的业务,如果能区分开来,请尽量使用不同的模板去管理,而不是全部在一个模板上面依赖版本号来管理。


服务地址

服务地址就是您提供接口的地址,当模板需要使用诸如 api:get/api:post特殊属性的时候,就需要提供此地址,每个模板限制使用一个服务地址。

对于公开频道,只能使用域名访问,未来可能会限制只能使用 https 服务地址; 对于私有频道,暂时不作限制,只要能访问即可;


组件命名

模板由标签组成,不同的标签对应相应的组件。

一个组件包含打开标签关闭标签属性标签内容(打开标签和关闭标签之间的非组件内容),打开标签里面可以声明属性,例如:

<Tag attrName="value">标签内容</Tag>

有几条规则稍微记一下,将会使你明白模板语法规则:

  1. 标签名采用驼峰式,首字母大写

  2. 属性名采用驼峰式,首字母小写,属性值必须由英文双引号括起来

  3. 普通属性名称只有英文或数字,特殊属性由 :(冒号)相隔,比如 link:openv:hide,有着特殊的作用,除非特别声明,通常所有组件都能使用这些特殊属性

  4. 模板支持变量,变量由 {{}} 括起来,比如

<Text>家里当前室温 {{celsius}} 度</Text>
<Input label="目标温度" name="targetCelsius">{{default}}</Input>
<Button api:post="/airconditioning?action=on">开启暖气</Button>
{
    "celsius": 9,
    "default": 20
}
查看渲染结果

变量

  • 格式

    变量使用格式形如 {{var_name}},使用大括号包围变量名。

  • 有效变量名称

    变量名支持字母、数字和下划线(_)、短横线(-)混合,顺序无要求。

  • 使用 . 号访问深层数据

    {
        "a": {
            "b": {
                "c": "world"
            }
        }
    }
    

    上面的数据可以使用 a.b.c 访问;如果任何一层的 key 不存在,当成 null 处理。

    <Text>Hello {{a.b.c}}!</Text>
    
  • 默认值:

    {{name|礼物}},名称后面紧随一竖线,__第一道__竖线后面至变量名结束所有内容均为默认值;当模板接收到的 JSON 数据没有 name 字段或 name 字段为 null 时,将使用默认值。其它情况不使用默认值。

并不是每个属性都支持变量,具体情况请参考具体组件的文档说明


模板布局

通常移动设备上面,大部分的布局都是纵向,没有太多横向的复杂布局需要考虑。

模板通过 ColumnRow 两个组件来实现纵向和横向的布局。

  • Column 会把其下的子组件(不包括孙组件)纵向排列渲染,每个子组件占一行,高度又子组件内容决定
  • Row 会把其下的子组件(不包括孙组件)横向排列渲染,每个子组件占一列,默认占用相同的宽度
<Column>
    <Button>按钮一</Button>
    <Button>按钮一</Button>
    <Row>
        <Button>按钮三</Button>
        <Button>按钮四</Button>
    </Row>
</Column>
查看渲染结果

在模板的最外层,默认是 Column 组件,也就是说,当你在编写模板时,最外层不需要加上 Column 组件