logo

iMAG移动应用开发指南

List

列表布局控件

标签

标签名 描述 说明 子标签
list 列表标签 以列表的形式来展示内容 item

属性

属性名 取值 描述
id String id编码
type String 列表类型,取值:
plain:扁平类型,默认值
group:分组类型
transparent:透明类型,用于自定义背景
toolbar:工具栏类型,用于定制工具栏
说明:type属性在List初始化时设置,不可更改。
reuse Boolean 是否是复用列表,取值:
true:是复用列表
false:不是复用列表,默认值
sort:索引排序列表,用于排序
说明:reuse属性在List初始化时设置,不可更改。
style String
list样式,包括:
more URL 更多item数据的获取地址,用于分页显示数据
items Array 获取list中所有item的数组,只读

方法

方法名 参数 返回值 描述
css(name:String) name:样式名称 String 根据样式名称得到样式的值
css(name:String, value:String)
name:样式名称
value:样式值
None 设置单个样式
css(style:String) style:样式文本,多个样式用分号分隔 None 设置多个样式
css(style:Object) style:样式对象,键值对形式 None 设置多个样式
add(item:Object) item:ListItem对象 None 在list底部添加一个item
remove(item:Object) item:ListItem对象 None 移除list的一个item
clear() None None 移除list中所有的item
update(xml:String) xml:XML格式的item列表 None 更新list里的item,该方法会清空原有item添加新的item,数据格式为XML
addMore(xml:String) xml:XML格式的item列表 None 在list底部添加更多的item,数据格式为XML
addTop(item:Object) item:ListItem对象 None 在list顶部添加一个item
addTopMore(item:String) item:ListItem对象 None 在list顶部添加更多的item,数据格式为XML
hashMore() None Boolean 判断是否有下一页,主要是判读more属性是否为空
scrollToBottom() None None 将滚动条定位到底部

ListItem

列表项

标签名 描述 说明 子标签
item 列表项子标签 list的子标签,用来展示列表的一项内容 col

属性

属性名 取值 描述
id String id编码
style String
list-item样式,包括:
icon String 列表左侧图标
accessory String 列表右侧控件类型,取值
indicator:指示箭头
button:按钮
checkmark:多选按钮
radiomark:单选按钮
checked Boolean 标识列表是否选中,取值
true:已选中
false:未选中
说明:仅当accessory为checkmark或radiomark时checked属性有效
value String 列表项对应的值
href URL 下个页面的链接地址
target String 页面打开方式,取值:
_self:当前窗口打开
_blank:新窗口打开,默认值
confirm String 确认提示框信息,页面跳转或执行onclick脚本前提示是否要执行操作。
用"|"分割时"|"前面是标题,后面是内容。
selectable Boolean item是否是可选中的,取值:
true:可选中的,默认值
false:不可选中的,此时不会显示选中后的背景
collapsed Boolean 是否出于收缩状态,仅当item嵌套使用时有效,取值:
true:收缩状态,默认值
false:展开状态
indent Integer 子item距父item左边的边距,仅当item嵌套使用时有效。
sortlabel String 索引排序文本,用来对item进行排序,仅当list的reuse属性为true时有效。
onclick Javascript 点击时触发的脚本
onlongclick Javascript 长按时触发的脚本
onscrollbottom Javascript 当滚动条滚到底部时触发的脚本

方法

方法名 参数 返回值 描述
css(name:String) name:样式名称 String 根据样式名称得到样式的值
css(name:String, value:String)
name:样式名称
value:样式值
None 设置单个样式
css(style:String) style:样式文本,多个样式用分号分隔 None 设置多个样式
css(style:Object) style:样式对象,键值对形式 None 设置多个样式
add(widget:Object) widget:Widget对象 None 为item添加一个widget控件
remove(widget:Object) widget:Widget对象 None 移除item的一个widget控件
clear() None None 移除item中所有的widget控件
contains(widget:Object) widget:Widget对象 Boolean 判断item中是否包含某一widget控件

ListItemCol

列表项的一列

标签名 描述 说明
col 列表项列标签 item的子标签,用来展示列表项一列的内容

属性

属性名 取值 描述
id 文本 id编码
style 样式
list-item-col样式,包括:
onclick Javascript脚本 点击时触发的脚本

方法

方法名 参数 返回值 描述
css(name:String) name:样式名称 String 根据样式名称得到样式的值
css(name:String, value:String)
name:样式名称
value:样式值
None 设置单个样式
css(style:String) style:样式文本,多个样式用分号分隔 None 设置多个样式
css(style:Object) style:样式对象,键值对形式 None 设置多个样式
add(widget:Object) widget:Widget对象 None 为col添加一个widget控件
remove(widget:Object) widget:Widget对象 None 移除col的一个widget控件
clear() None None 移除col中所有的widget控件
contains(widget:Object) widget:Widget对象 Boolean 判断col中是否包含某一widget控件

控件详解

● 列表类型

list有plain, group, transparent, toolbar四种类型。
其中plain是默认的扁平风格的列表,group是分组列表。
transparent是透明风格的列表,plain和group类型的列表都有默认的边线和背景,而transparent则是把这些边线和背景去掉了的,这样可以在transparent类型的列表上设置新的背景。
toolbar类型的列表主要用于定制工具栏,toolbar类型的列表也是透明的,toolbar和transparent的区别是transparent列表内部有默认的边距,而toobar列表则把item里默认的margin和padding也去掉了。

● 扁平列表

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>扁平列表</label>
            </center>
        </title>
        <content draggable="true">
            <list>
                <item>
                    <label>新的好友</label>
                </item>
                <item>
                    <label>我的微博</label>
                </item>
                <item>
                    <label>我的相册</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

list默认为扁平风格的,即:type="plain"

● 分组列表

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>分组列表</label>
            </center>
        </title>
        <content draggable="true">
            <list type="group">
                <item>
                    <label>新的好友</label>
                </item>
            </list>
            <list type="group">
                <item>
                    <label>我的微博</label>
                </item>
                <item>
                    <label>我的相册</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

可以通过设置type="group"来设置分组列表。

● 列表布局

<list type="group" accessory="indicator">
    <item accessory="indicator">
        <label>标题</label>
        <label style="color:gray">副标题</label>
    </item>
    <item accessory="indicator">
        <row>
            <label>标题</label>
            <label style="color:gray">副标题</label>
        </row>
    </item>
    <item accessory="indicator">
        <col>
            <row>
                <label>标题</label>
                <label style="color:gray">副标题</label>
            </row>
        </col>
    </item>
    <item accessory="indicator">
        <col>
            <label>标题</label>
            <label style="color:gray">副标题</label>
        </col>
    </item>
    <item accessory="indicator">
        <col>
            <row>
                <label>标题</label>
                <label style="color:gray">副标题</label>
            </row>
        </col>
        <col>
            <label style="color:blue;font-size:14">2012-05-01</label>
        </col>
    </item>
    <item accessory="indicator">
        <col>
            <row>
                <label>标题</label>
            </row>
            <row>
                <label style="color:gray">副标题</label>
            </row>
        </col>
        <col>
            <label style="color:blue;font-size:14">2012-05-01</label>
        </col>
    </item>
    <item accessory="indicator" style="col-width:*,100;">
        <col>
            <row>
                <label>标题</label>
            </row>
            <row>
                <label style="color:gray">副标题</label>
            </row>
        </col>
        <col>
            <row>
                <label style="color:blue;align:right;font-size:14">2012-05-01</label>
           </row>
        </col>
    </item>
    <item accessory="indicator" style="col-width:*,100; col-valign:top,top">
        <col>
            <row>
                <label>标题</label>
            </row>
            <row>
                <label style="color:gray;">副标题</label>
            </row>
        </col>
        <col>
            <row>
                <label style="color:blue;align:right;font-size:14">2012-05-01</label>
           </row>
        </col>
    </item>
</list>

效果:

list的item中可以直接放置label,如:

<list type="group">
    <item accessory="indicator">
        <label>标题</label>
        <label style="color:gray">副标题</label>
    </item>
</list>

还可以通过rowcol来进行布局,col表示一列,row表示一行。如:

<list type="group">
    <item accessory="indicator">
        <row>
            <label>标题</label>
            <label style="color:gray">副标题</label>
        </row>
    </item>
    <item accessory="indicator">
        <col>
            <label>标题</label>
            <label style="color:gray">副标题</label>
        </col>
    </item>
    <item accessory="indicator">
        <col>
            <row>
                <label>标题</label>
                <label style="color:gray">副标题</label>
            </row>
        </col>
    </item>
</list>

注意这里是先有col(列)再有row(行),当只有一个col时col可以省略,只有一个row时row可以省略。

可以通过item的col-width样式来控制col的宽度,如:

  
<list type="group">
    <item accessory="indicator" style="col-width:*,100;">
        <col>
            <row>
                <label>标题</label>
            </row>
            <row>
                <label style="color:gray">副标题</label>
            </row>
        </col>
        <col>
            <row>
                <label style="color:blue;align:right;font-size:14">2012-05-01</label>
           </row>
        </col>
    </item>
</list>

col-width可以设置多列的宽度,中间用逗号(,)分割,星号(*)表示宽度自适应。

控件的左右对齐方式通过控件自身的align样式来设置,align取值为left, center, right

控件的上下对齐方式通过item的col-valign样式来控制,如:

  
<list type="group">
    <item accessory="indicator" style="col-width:*,100; col-valign:top,top">
        <col>
            <row>
                <label>标题</label>
            </row>
            <row>
                <label style="color:gray;">副标题</label>
            </row>
        </col>
        <col>
            <row>
                <label style="color:blue;align:right;font-size:14">2012-05-01</label>
           </row>
        </col>
    </item>
</list>

col-valign可以设置多列的上下对齐方式,中间用逗号(,)分割,取值为top, middle, bottom

● 带图标的列表

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>带图标的列表</label>
            </center>
        </title>
        <content draggable="true">
            <list>
                <item icon="weibo_at.png">
                    <label>提到我的</label>
                </item>
                <item icon="weibo_comments.png">
                    <label>评论</label>
                </item>
                <item icon="weibo_good.png">
                    <label>赞</label>
                </item>
                <item icon="weibo_messagebox.png">
                    <label>未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

设置item的icon属性,在前面加上图标。

● 带链接的列表

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>带链接的列表</label>
            </center>
        </title>
        <content draggable="true">
            <list>
                <item icon="weibo_at.png" accessory="indicator" href="list_script_search.xml">
                    <label>提到我的</label>
                </item>
                <item icon="weibo_comments.png" accessory="indicator" href="list_script_search.xml">
                    <label>评论</label>
                </item>
                <item icon="weibo_good.png" accessory="indicator" href="list_script_search.xml">
                    <label>赞</label>
                </item>
                <item icon="weibo_messagebox.png" accessory="indicator" href="list_script_search.xml">
                    <label>未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

通过item的href属性设置跳转地址,此时最好是同时设置accessory="indicator"用来表明这个item是带链接的。

● 定制右侧的指示图标

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>定制右侧的指示图标</label>
            </center>
        </title>
        <content draggable="true">
            <list>
                <item icon="weibo_at.png" accessory="indicator" href="list_script_search.xml">
                    <icon role="accessory" src="list_indicator.png"/>
                    <label>提到我的</label>
                </item>
                <item icon="weibo_comments.png" accessory="indicator" href="list_script_search.xml">
                    <icon role="accessory" src="list_indicator.png"/>
                    <label>评论</label>
                </item>
                <item icon="weibo_good.png" accessory="indicator" href="list_script_search.xml">
                    <icon role="accessory" src="list_indicator.png"/>
                    <label>赞</label>
                </item>
                <item icon="weibo_messagebox.png" accessory="indicator" href="list_script_search.xml">
                    <icon role="accessory" src="list_indicator.png"/>
                    <label>未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

在item里添加一个icon,设置属性role="accessory",用来定制列表右侧的指示图标。

● 带确认提示的列表

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>带确认提示的列表</label>
            </center>
        </title>
        <content draggable="true">
            <list>
                <item icon="weibo_at.png" accessory="indicator" href="list_script_search.xml" confirm="提示|确定进入页面?">
                    <label>提到我的</label>
                </item>
                <item icon="weibo_comments.png" accessory="indicator" href="list_script_search.xml" confirm="提示|确定进入页面?">
                    <label>评论</label>
                </item>
                <item icon="weibo_good.png" accessory="indicator" href="list_script_search.xml" confirm="提示|确定进入页面?">
                    <label>赞</label>
                </item>
                <item icon="weibo_messagebox.png" accessory="indicator" href="list_script_search.xml" confirm="提示|确定进入页面?">
                    <label>未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

页面跳转前先进行提示确认。

● 带事件的列表

   
<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>带事件的列表</label>
            </center>
        </title>
        <content draggable="true">
            <list>
                <item icon="weibo_at.png" accessory="indicator" onclick="$page.open('list_script_search.xml');" onlongclick="alert('提到我的')">
                    <label>提到我的</label>
                </item>
                <item icon="weibo_comments.png" accessory="indicator" onclick="$page.open('list_script_search.xml')" onlongclick="alert('评论')">
                    <label>评论</label>
                </item>
                <item icon="weibo_good.png" accessory="indicator" onclick="$page.open('list_script_search.xml')" onlongclick="alert('赞')">
                    <label>赞</label>
                </item>
                <item icon="weibo_messagebox.png" accessory="indicator" onclick="$page.open('list_script_search.xml')" onlongclick="alert('未关注人私信')">
                    <label>未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

可以在item上设置onclickonlongclick事件。

● 右侧带按钮的列表

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>右侧带按钮的列表</label>
            </center>
        </title>
        <content draggable="true">
            <list>
                <item icon="weibo_at.png" accessory="button" href="list_script_search.xml">
                    <button role="accessory" onclick="hint('提到我的')"/>
                    <label>提到我的</label>
                </item>
                <item icon="weibo_comments.png" accessory="button" href="list_script_search.xml">
                    <button role="accessory" onclick="hint('评论')"/>
                    <label>评论</label>
                </item>
                <item icon="weibo_good.png" accessory="button" href="list_script_search.xml">
                    <button role="accessory" onclick="hint('赞')"/>
                    <label>赞</label>
                </item>
                <item icon="weibo_messagebox.png" accessory="button" href="list_script_search.xml">
                    <button role="accessory" onclick="hint('未关注人私信')"/>
                    <label>未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

在item上设置accessory="button",此时在右边会显示一个按钮。
接着定制这个按钮:在item中添加一个button标签,在这个button上设置role="accessory",表明这是显示在右边的按钮,最后给这个button加上onclick事件。

还可以定制这个按钮的背景:

<button role="accessory" style="background:item_delete.png,item_delete_pressed.png" onclick="hint('提到我的')"/>

效果:

● 带多选按钮的列表

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>带多选按钮的列表</label>
            </center>
        </title>
        <content >="true">
            <list>
                <item icon="weibo_at.png" accessory="checkmark">
                    <label>提到我的</label>
                </item>
                <item icon="weibo_comments.png" accessory="checkmark" checked="true">
                    <label>评论</label>
                </item>
                <item icon="weibo_good.png" accessory="checkmark" checked="true">
                    <label>赞</label>
                </item>
                <item icon="weibo_messagebox.png" accessory="checkmark">
                    <label>未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

在item上设置accessory="checkmark"列表右侧会显示多选按钮,其中checked="true"的是当前选中的item。
item有个value属性用来存值,通常在Javascript里将checkedvalue合起来使用,用来存取选择的数据。

● 带单选按钮的列表

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>带单选按钮的列表</label>
            </center>
        </title>
        <content >="true">
            <list>
                <item icon="weibo_at.png" accessory="radiomark">
                    <label>提到我的</label>
                </item>
                <item icon="weibo_comments.png" accessory="radiomark">
                    <label>评论</label>
                </item>
                <item icon="weibo_good.png" accessory="radiomark" checked="true">
                    <label>赞</label>
                </item>
                <item icon="weibo_messagebox.png" accessory="radiomark">
                    <label>未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

radiomarkcheckmark用法类似,不同的是单选按钮只有一个能被选中。

● 设置列表背景

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>设置列表背景</label>
            </center>
        </title>
        <content draggable="true">
            <list>
                <item icon="weibo_at.png" style="background:#666666">
                    <label style="color:white">提到我的</label>
                </item>
                <item icon="weibo_comments.png" style="background:#666666">
                    <label style="color:white">评论</label>
                </item>
                <item icon="weibo_good.png" style="background:#666666">
                    <label style="color:white">赞</label>
                </item>
                <item icon="weibo_messagebox.png" style="background:#666666">
                    <label style="color:white">未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

● 设置列表选中背景

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>设置列表选中背景</label>
            </center>
        </title>
        <content draggable="true">
            <list>
                <item icon="weibo_at.png" style="background:#666666,gradient(gray)">
                    <label style="color:white">提到我的</label>
                </item>
                <item icon="weibo_comments.png" style="background:#666666,gradient(gray)">
                    <label style="color:white">评论</label>
                </item>
                <item icon="weibo_good.png" style="background:#666666,gradient(gray)">
                    <label style="color:white">赞</label>
                </item>
                <item icon="weibo_messagebox.png" style="background:#666666,gradient(gray)">
                    <label style="color:white">未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

● 设置列表不带选中背景

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>设置列表不带选中背景</label>
            </center>
        </title>
        <content draggable="true">
            <list>
                <item icon="weibo_at.png" selectable="false">
                    <label>提到我的</label>
                </item>
                <item icon="weibo_comments.png" selectable="false">
                    <label>评论</label>
                </item>
                <item icon="weibo_good.png" selectable="false">
                    <label>赞</label>
                </item>
                <item icon="weibo_messagebox.png" selectable="false">
                    <label>未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

list的item默认有一个蓝色的选中背景,可以通过selectable="false"将item设为不可选的。

● 设置分割线

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>设置列表分割线</label>
            </center>
        </title>
        <content draggable="true">
            <list>
                <item icon="weibo_at.png" style="divider-border:1 #333333">
                    <label>提到我的</label>
                </item>
                <item icon="weibo_comments.png" style="divider-border:1 #333333">
                    <label>评论</label>
                </item>
                <item icon="weibo_good.png" style="divider-border:1 #333333">
                    <label>赞</label>
                </item>
                <item icon="weibo_messagebox.png" style="divider-border:1 #333333">
                    <label>未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

通过item的divider-border样式来设置分割线的高度和颜色。

● 透明列表

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>透明列表</label>
            </center>
        </title>
        <content draggable="true">
           <list type="transparent" style="margin:30">
               <item style="col-width:60,*">
                   <col>
                      <row><label>用户名</label></row>
                   </col>
                   <col>
                      <row>
                          <input type="text" name="username" remember="true" placeholder="请输入用户名"/>
                      </row>
                   </col>
               </item>
               <item style="col-width:60,*">
                   <col>
                      <row><label>密码</label></row>
                   </col>
                   <col>
                      <row>
                          <input type="password" name="password" remember="remCheck" placeholder="请输入密码"/>
                      </row>
                   </col>
               </item>
               <item>
                  <row>
                     <checkbox name="remCheck" value="true" remember="true" style="align:center">记住密码</checkbox>
                  </row>
                  <row>
                     <input type="submit" name="submit" value="登录" style="width:120;align:center"/>
                  </row>
               </item>
           </list>
        </content>
    </page>
</imag>

效果:

设置type="transparent"让列表以透明效果显示,默认的背景和分割线都不会显示,适用于仅用list来布局的情况。

● 设置图片背景

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>设置图片背景</label>
            </center>
        </title>
        <content draggable="true">
            <list type="transparent">
                <item icon="weibo_at.png" style="background:list_bg_image.png 3 30">
                    <label>提到我的</label>
                </item>
                <item icon="weibo_comments.png" style="background:list_bg_image.png 3 30">
                    <label>评论</label>
                </item>
                <item icon="weibo_good.png" style="background:list_bg_image.png 3 30">
                    <label>赞</label>
                </item>
                <item icon="weibo_messagebox.png" style="background:list_bg_image.png 3 30">
                    <label>未关注人私信</label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

这个例子的列表item背景的原始图片为:

这是一个细窄长条形状的图片,大小为6x61,将背景设置为切割后拉伸:background:list_bg_image.png 3 30,能很好地适应列表内容的大小。 因为分割线是在图片背景上的,所以在list上设置type="transparent",将默认的分割线用图片背景来替代。

● 列表工具栏

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>列表工具栏</label>
            </center>
        </title>
       <content draggable="true">
       </content>
       <footer>
           <list type="toolbar">
               <item style="padding:2">
                    <col style="background:toolbar_bg_left_nor.png 10 0,toolbar_bg_left_sel.png 10 0;" onclick="hint('刷新');">
                        <row><icon src="toolbar_refresh_icon.png" style="align:center"/></row>
                        <row><label style="align:center;color:white;font-size:12">刷新</label></row>
                    </col>
                    <col style="background:toolbar_bg_middle_nor.png 10 0,toolbar_bg_middle_sel.png 10 0" onclick="hint('评论');">
                        <row><icon src="toolbar_comment_icon.png" style="align:center"/></row>
                        <row><label style="align:center;color:white;font-size:12">评论</label></row>
                    </col>
                    <col style="background:toolbar_bg_middle_nor.png 10 0,toolbar_bg_middle_sel.png 10 0" onclick="hint('转发');">
                        <row><icon src="toolbar_forward_icon.png" style="align:center"/></row>
                        <row><label style="align:center;color:white;font-size:12">转发</label></row>
                    </col>
                    <col style="background:toolbar_bg_middle_nor.png 10 0,toolbar_bg_middle_sel.png 10 0" onclick="hint('收藏');">
                        <row><icon src="toolbar_fav_icon.png" style="align:center"/></row>
                        <row><label style="align:center;color:white;font-size:12">收藏</label></row>
                    </col>
                    <col style="background:toolbar_bg_right_nor.png 10 0,toolbar_bg_right_sel.png 10 0" onclick="hint('更多');">
                        <row><icon src="toolbar_more_icon.png" style="align:center"/></row>
                        <row><label style="align:center;color:white;font-size:12">更多</label></row>
                    </col>
               </item>
           </list>
       </footer>
   </page>
</imag>

效果:

在list上设置type="toolbar",可以用list来定制工具栏。

● 列表工具栏2

    <?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
    <![CDATA[
        function showHotContent() {
            $('hotthread_label').css('color', '#2873C2');
            $('newthread_label').css('color', '#636363');
            $('hotforum_label').css('color', '#636363');
            $('hotthread_row').css('display', 'block');
            $('newthread_row').css('display', 'hidden');
            $('hotforum_row').css('display', 'hidden');
        }
        
        function showNewContent() {
            $('hotthread_label').css('color', '#636363');
            $('newthread_label').css('color', '#2873C2');
            $('hotforum_label').css('color', '#636363');
            $('hotthread_row').css('display', 'hidden');
            $('newthread_row').css('display', 'block');
            $('hotforum_row').css('display', 'hidden');
        }
        
        function showForumContent() {
            $('hotthread_label').css('color', '#636363');
            $('newthread_label').css('color', '#636363');
            $('hotforum_label').css('color', '#2873C2');
            $('hotthread_row').css('display', 'hidden');
            $('newthread_row').css('display', 'hidden');
            $('hotforum_row').css('display', 'block');
        }
     ]]>
    </script>
    <page>
       <title>
            <center>
                <label>列表工具栏2</label>
            </center>
        </title>
        <header>
            <list type="toolbar">
                <item style="background:#EFEFF4,#EFEFF4">
                    <col>
                        <row style="padding:8" onclick="showHotContent()">
                            <label id="hotthread_label" style="align:center;color:#2873C2;font-size:16;">论坛热帖</label>
                        </row>
                        <row id="hotthread_row" style="height:2;background:#2873C2">
                        </row>
                    </col>
                    <col>
                        <row style="padding:8" onclick="showNewContent()">
                            <label id="newthread_label" style="align:center;color:#636363;font-size:16;">最新帖子</label>
                        </row>
                        <row id="newthread_row" style="display:hidden;height:2;background:#2873C2">
                        </row>
                    </col>
                    <col>
                        <row style="padding:8" onclick="showForumContent()">
                            <label id="hotforum_label" style="align:center;color:#636363;font-size:16;">热门版块</label>
                        </row>
                        <row id="hotforum_row" style="display:hidden;height:2;background:#2873C2">
                        </row>
                    </col>
                </item>
            </list>
        </header>
    </page>
</imag>

● 可折叠的列表

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <page>
       <title>
            <center>
                <label>可折叠的列表</label>
            </center>
        </title>
        <content draggable="true">
            <list>
                <item collapsed="true" indent="30" style="background:#333333,#333333">
                    <label style="color:white">北京市</label>
                    <item>
                        <label>东城区</label>
                    </item>
                    <item>
                        <label>西城区</label>
                    </item>
                    <item>
                        <label>朝阳区</label>
                    </item>
                    <item>
                        <label>海淀区</label>
                    </item>
                </item>
                <item collapsed="false" indent="30" style="background:#333333,#333333">
                    <label style="color:white">上海市</label>
                    <item>
                        <label>徐汇区</label>
                    </item>
                    <item>
                        <label>黄浦区</label>
                    </item>
                    <item>
                        <label>静安区</label>
                    </item>
                    <item>
                        <label>闵行区</label>
                    </item>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

list的item可以嵌套,嵌套后的item是可以折叠收缩的,呈现出树状的效果。
collapsed="true"表示当前item出于收缩状态,点击后才显示子item的内容,indent属性表示子item距左边的边距。

上面的例子是两层item嵌套,还可以嵌套三层、四层...更多的层次。

● 列表查询

通过$http.get()$http.post()获取服务器数据,然后用update()方法渲染UI界面。

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
    <![CDATA[
        function doSearch() {
            $('prompt').css('display', '');
            $http.post('http://www.imagapp.com/download/data/list_search_ret.jsp', 
                {name: $('search').value}, function(data) {
                $('list').update(data);
            });
        
        }
    ]]>
    </script> 
    <page>
       <title>
            <center>
                <label>列表查询</label>
            </center>
        </title>
        <header>
            <row style="background:gradient(#E5EAEE #BAC8D2);padding:3">
                <input id="search" type="search" name="search" value="terry" onclick="doSearch();"/>
            </row>
        </header>
        <content>
            <list id="list">
                <item id="prompt" style="display:none">
                    <row><progress id="progress" style="display:none"/><label>正在查询...</label></row>
                </item>
            </list>
        </content>
    </page>
</imag>

● 列表更新

通过$http.get()$http.post()获取服务器数据,然后用update()方法渲染UI界面。

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
        <![CDATA[
            function doUpdate(content) {
                $http.get("http://www.imagapp.com/download/data/list_update_ret.jsp", function(data) {
                    $('list').update(data);
                    $('content').hideTop();
                });
            }
        ]]>
    </script>
    <page>
        <title>
            <center>
                <label>列表更新</label>
            </center>
        </title>
        <header>
        </header>
        <content id="content" draggable="true" ondragdown="doUpdate(this)">
            <list id="list">
                <item>
                    <label>向下拖动更新</label>
                </item>
            </list>
        </content>
    </page>
</imag>

上面的例子中服务器返回的数据格式为:

<imag>
    <list>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
    </list>
</imag>

update()方法会清空整个list然后显示XML中定义的新的item。

● 分页显示

通过more属性和addMore()方法来显示分页数据。

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
    <![CDATA[
        function doPaginate() {
            var list = $('list');
            if (list.hasMore()) {
                $('progress').css('display', '');
                $http.get(list.more, function(data) {
                     $('progress').css('display', 'none');
                     list.addMore(data);
                     if (!list.hasMore()) {
                         $('content').hideBottom();
                     }
                });
            }
        }
    ]]>
    </script> 
    <page>
       <title>
            <center>
                <label>列表分页</label>
            </center>
        </title>
        <content id="content" draggable="true" ondragup="doPaginate()">
            <row style="background:#666666;padding:5">
                <label style="align:center;color:white;">拖动列表和点击"更多"均可翻页</label>
            </row>
            <list id="list" more="http://www.imagapp.com/download/data/list_more_ret.jsp">
                <item icon="tab_address_normal.png">
                    <label>Terry</label>
                </item>
                <item icon="tab_address_normal.png">
                    <label>Terry</label>
                </item>
                <item icon="tab_address_normal.png">
                    <label>Terry</label>
                </item>
                <item icon="tab_address_normal.png">
                    <label>Terry</label>
                </item>
                <item icon="tab_address_normal.png">
                    <label>Terry</label>
                </item>
             </list>
             <bottom>
                <list>
                    <item onclick="doPaginate()">
                        <row>
                            <label style="align:center;">更多...</label>
                            <progress id="progress" style="display:hidden;align:center"/>
                        </row>
                    </item>
                </list>
             </bottom>
        </content>
    </page>
</imag>

more属性定义的是获取更多数据的URL地址,上面的例子通过$http.get()获取的数据格式如下:

<imag>
    <list more="http://www.imagapp.com/download/data/list_more_ret.jsp">
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
        <item icon="tab_address_normal.png">
            <label>Terry</label>
        </item>
    </list>
</imag>      

这个XML中同样有设置more属性,如果没有更多数据了,后台控制不设置more属性即可。addMore()会把item数据添加到list的末尾,如果要在list顶部显示则使用addTopMore()方法。

● 向上分页

先用list的scrollToBottom()方法将滚动条定位到底部,然后用addTopMore()方法向列表顶部添加数据,addTopMore()的用法和addMore()的用法一致。

● 新增单个列表项

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
    <![CDATA[
          function addListItem() {
              var item = $C('<list-item><item><label>新增的item</label></item></list-item>');
              $('list').add(item);
          }
    ]]>
    </script>             
    <page>
       <title>
            <center>
                <label>新增列表项</label>
            </center>
        </title>
        <content draggable="true">
            <list id="list" type="group">
                <item onclick="addListItem();">
                    <label>新增列表项</label>
                </item>
            </list>
        </content>
    </page>
</imag>

说明:add()方法用来添加单个item,新增多个列表项用addMore()方法,如果新增多个在for循环里用add()方法则性能较低。这里$C()里的XML根节点是list-item

● 列表选项

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
    <![CDATA[
          function setInputValue(value) {
              $('username').value = value;
          }
    ]]>
    </script>             
    <page>
       <title>
            <center>
                <label>列表选项</label>
            </center>
        </title>
        <content draggable="true">
            <list type="group">
                <item style="col-width:60,*">
                    <col>
                       <row><label>用户名</label></row>
                    </col>
                    <col>
                       <row>
                           <input id="username" type="text" name="username" remember="true" placeholder="请选择用户"/>
                           <button onclick="$page.open('http://www.imagapp.com/download/data/list_select_ret.jsp?username=' + $('username').value);">选择</button>
                       </row>
                    </col>
                </item>
            </list>
        </content>
    </page>
</imag>

通过列表选择数据后返回,并将选择的数据显示在前一页的输入框。

list_select_ret.jsp的代码如下:

<%@ page language="java" contentType="text/html; charset=UTF-8" pageEncoding="UTF-8"%>
<?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
    <![CDATA[
        $page.onload = function() {
            var username = '<%=request.getParameter("username")%>';
            if (username != '' && username != 'null') {
                var values = username.split(",");
                var list = $('list');
                for (var i = 0; i < list.items.length; i++) {
                    var item = list.items[i];
                    for (var j = 0; j < values.length; j++) {
                        if (item.value == values[j]) {
                            item.checked = true;
                        }
                    }
                }
            }
        };

        function doSelect() {
            var result = [];
            var list = $('list');
            for (var i = 0; i < list.items.length; i++) {
                var item = list.items[i];
                if (item.checked) {
                    result.push(item.value);
                }
            }
            $page.close('setInputValue("' + result.join() + '")');
        }
    ]]>
    </script>
    <page>
       <title>
            <center>
                <label>请选择用户</label>
            </center>
        </title>
        <content draggable="true">
            <list id="list">
                <item accessory="checkmark" value="Terry">
                    <label>Terry</label>
                </item>
                <item accessory="checkmark" value="Vic">
                    <label>Vic</label>
                </item>
                <item accessory="checkmark" value="Allen">
                    <label>Allen</label>
                </item>
                <item accessory="checkmark" value="Jack">
                    <label>Jack</label>
                </item>
                <item accessory="checkmark" value="John">
                    <label>John</label>
                </item>
            </list>
        </content>
        <footer style="background:nav(#0066CC);border-top:1 black">
            <row>
                <button style="width:100;height:40;align:center" onclick="doSelect();">确定</button>
            </row>
        </footer>
    </page>
</imag>

● 复用列表

说明:复用列表使用略复杂,请先熟练掌握普通列表再看这部分内容。

● 基本用法

复用列表(resue list)是不同于普通列表的另外一种列表,使用复用列表是为了优化性能,在大数据的情况下(上千个item)避免因内存占用过多而导致系统崩溃。这是因为在移动应用中view(视图)是很耗费系统资源的一个对象,过多的view(几千个,view所占内存大小取决于view的面积)可能会引起内存不足而崩溃,同时一次性加载这么多view也会花费很长的时间。

对此相应的解决方案是使用reuse list,reuse list的原理是只创建一屏幕显示的view对象,当view被滚动超出屏幕之后就会被用来复用,因此始终只会占用一屏幕view的内存, 有效地解决了内存不足而引起崩溃的问题, 同时因为实际创建的view个数较少,具有很快的加载速度。

使用复用列表需要设置reuse="true",同时content里只能有一个list,不能有多个list或其他控件,如:

  
<content>
	<list id="resuelist" reuse="true">
	    <item accessory="indicator">
	        <label></label>
	        <label style="color:gray"></label>
	    </item>
	</list>
</content>

这里content里有且仅有一个list。

reuse list中的item和普通list中的item有很大不同,因为reuse list的item并不是实际内容,而是UI模版,reuse list的item内容都通过Javascript脚本动态创建。关于reuse list完整的示例如下:

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
    <![CDATA[
        function initList() {
            var listJson = {items:[]};
            for (var i = 0; i < 1000; i++) {
                var itemJson = {
                    template:0,
                    onclick:'alert("item' + i + '")',
                    widgets:{
                        title:{text:'标题' + i},
                        subtitle:{text: '副标题' + i}
                    }
                }
                listJson.items.push(itemJson);
            }
            $('resuelist').update(listJson);
        }
        
        $page.onload = function() {
            initList();
        }
    ]]>    
    </script>
    <page>
        <title>
            <center>
                <label>reuse list</label>
            </center>
        </title>
        <content>
            <list id="resuelist" reuse="true">
                <item accessory="indicator">
                    <label reusekey="title"></label>
                    <label style="color:gray" reusekey="subtitle"></label>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

上面的例子通过JS动态创建了1000个item,使用的是list中先定义好的item模版,然后通过update()方法将JSON数据渲染成item。完整的JSON数据格式为:

{items:[{
    template:0,
    onclick:'alert("item0")',
    widgets:{
        title:{text:'标题0'},
        subtitle:{text: '副标题0'}
    }
},{
    template:0,
    onclick:'alert("item1")',
    widgets:{
        title:{text:'标题1'},
        subtitle:{text: '副标题1'}
    }
},{
    template:0,
    onclick:'alert("item2")',
    widgets:{
        title:{text:'标题2'},
        subtitle:{text: '副标题2'}
    }
},
....
]}

其中template是指定item模版的索引,因为这个例子中list中只定义了一个item模版,所以template都为0。onclick是item的属性,类似的还可以动态设置href, icon等属性。
widgets用来动态设置item中控件的属性,并通过reusekey所指定的关键字来和相应控件匹配,上面的例子中"title"和"subtitle"都是reusekey关键字,用来动态设置label的text属性。
上面的例子只设置了text属性,同样地也可动态设置style等label的其他属性。

如果是普通list渲染1000个item会花费较长时间,使用reuse list后1000个item一瞬间就显示出来了。

● 多套模版

reuse list还可以定义多个item模版,如:

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
    <![CDATA[
        function loadReuseList() {
            var listJson = {items:[]};
            for (var i = 0; i < 1000; i++) {
                var itemJson;
                if (i % 2 == 0) {
                    itemJson = {
                        template:0,
                        onclick:'alert("item' + i + '")',
                        widgets:{
                            title:{text: '标题' + i},
                            subtitle:{text: '副标题' + i}
                        }
                    }
                } else {
                    itemJson = {
                        template:1,
                        onclick:'alert("item' + i + '")',
                        widgets:{
                            title:{text: '标题' + i},
                            subtitle:{text: '副标题' + i},
                            date:{text: '2012-05-01'}
                        }
                    }
                }
                listJson.items.push(itemJson);
            }
            $('resuelist').update(listJson);
        }
        
        $page.onload = function() {
            loadReuseList();
        }
    ]]>    
    </script>
    <page>
        <title>
            <center>
                <label>reuse list(多套模版)</label>
            </center>
        </title>
        <content>
            <list id="resuelist" reuse="true">
                <item accessory="indicator">
                    <label reusekey="title"></label>
                    <label style="color:gray" reusekey="subtitle"></label>
                </item>
                <item accessory="indicator" style="background:#dddddd;col-width:*,100; col-valign:top,top">
                    <col>
                        <row>
                            <label reusekey="title"></label>
                        </row>
                        <row>
                            <label style="color:gray;" reusekey="subtitle"></label>
                        </row>
                    </col>
                    <col>
                        <row>
                            <label style="color:blue;align:right;font-size:14" reusekey="date"></label>
                       </row>
                    </col>
                </item>
            </list>
        </content>
    </page>
</imag>

效果:

上面的例子定义了两套item模版,分别用来显示不同数据结构。

● 分页显示

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
    <![CDATA[
        function loadMore() {
            var list = $('resuelist');
            if (list.hasMore()) {
                $('progress').css('display', '');
                $http.get(list.more, function(data) {
                     $('progress').css('display', 'none');
                     var obj = JSON.parse(data);
                     list.addMore(obj);
                     if (!list.hasMore()) {
                         $('content').hideBottom();
                     }
                });
            }
        }
        
        function initList() {
            $('resuelist').update({items:[{template:0}]});
            $http.get('http://www.imagapp.com/download/data/list_reuse_more.json', function(data) {
                var obj = JSON.parse(data);
                $('resuelist').update(obj);
                $('content').showBottom();
            });
        }
        
        $page.onload = function() {
            initList();
        }
    ]]>    
    </script>
    <page>
        <title>
            <center>
                <label>reuse list more</label>
            </center>
        </title>
        <content id="content" draggable="true" ondragup="loadMore();">
            <list id="resuelist" reuse="true">
                <item>
                    <row><label style="align:center">正在加载..</label><progress style="align:center"/></row>
                </item>
                <item accessory="indicator">
                    <label reusekey="title"></label>
                    <label style="color:gray" reusekey="subtitle"></label>
                </item>
            </list>
            <bottom style="display:none">
                <list>
                    <item onclick="loadMore()">
                        <row>
                            <label style="align:center;">更多...</label>
                            <progress id="progress" style="display:hidden;align:center"/>
                        </row>
                    </item>
                </list>
            </bottom>
        </content>
    </page>
</imag>

这个例子中从服务器返回的JSON数据格式为:

{
"more":"http://www.imagapp.com/download/data/list_reuse_more.json",
"items":[{
    "template":1,
    "onclick":"alert('item0')",
    "widgets":{
        "title":{"text":"标题0"},
        "subtitle":{"text":"副标题0"}
    }
},{
    "template":1,
    "onclick":"alert('item1')",
    "widgets":{
        "title":{"text":"标题1"},
        "subtitle":{"text":"副标题1"}
    }
},
...
]}

其中more属性是下一页数据的URL地址,上面这个例子中list下有两个item,第一个item用来初始时显示“正在加载...”等待内容。$http.get()方法从服务器端获取数据后再通过addMore()方法渲染UI界面,这个异步加载的过程和普通列表类似。

● 修改数据

因为实现的机制不一样,修改reuse list内容的方式跟普通list也不样,reuse list里的控件内容不能通过$(id)找到后直接修改,而是要通过item的update()方法修改,如:

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
    <![CDATA[
        function updateItem(index) {
            $('item' + index).update('title', {text:'新的标题'});
        }
        
        function initList() {
            var listJson = {items:[]};
            for (var i = 0; i < 1000; i++) {
                var itemJson = {
                    template:0,
                    id: 'item' + i,
                    onclick:'alert("item' + i + '")',
                    widgets:{
                        title:{text:'标题' + i},
                        subtitle:{text: '副标题' + i}
                    }
                }
                listJson.items.push(itemJson);
            }
            $('resuelist').update(listJson);
        }
        
        $page.onload = function() {
            initList();
        }
    ]]>    
    </script>
    <page>
        <title>
            <center>
                <label>reuse list update</label>
            </center>
            <right>
                <button onclick="updateItem(5);">修改数据</button>
            </right>
        </title>
        <content>
            <list id="resuelist" reuse="true">
                <item accessory="indicator">
                    <label reusekey="title"></label>
                    <label style="color:gray" reusekey="subtitle"></label>
                </item>
            </list>
        </content>
    </page>
</imag>

上面的例子先通过$('item' + index)找到对应的item,然后通过item的update(reusekey, options)方法动态修改label控件内容。 update(reusekey, options)方法有两个参数,第一个参数是控件的reusekey,第二个参数是要修改属性的键值对对象。

● 获取数据

获取数据使用item的getWidgetAttribute()方法修改,如:

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
    <![CDATA[
        function getItemValue(index) {
            var value = $('item' + index).getWidgetAttribute('title', 'text'});
            alert(value);
        }
        
        function initList() {
            var listJson = {items:[]};
            for (var i = 0; i < 1000; i++) {
                var itemJson = {
                    template:0,
                    id: 'item' + i,
                    onclick:'alert("item' + i + '")',
                    widgets:{
                        title:{text:'标题' + i},
                        subtitle:{text: '副标题' + i}
                    }
                }
                listJson.items.push(itemJson);
            }
            $('resuelist').update(listJson);
        }
        
        $page.onload = function() {
            initList();
        }
    ]]>    
    </script>
    <page>
        <title>
            <center>
                <label>reuse list update</label>
            </center>
            <right>
                <button onclick="getItemValue(5);">获取数据</button>
            </right>
        </title>
        <content>
            <list id="resuelist" reuse="true">
                <item accessory="indicator">
                    <label reusekey="title"></label>
                    <label style="color:gray" reusekey="subtitle"></label>
                </item>
            </list>
        </content>
    </page>
</imag>

上面的例子先通过$('item' + index)找到对应的item,然后通过item的getWidgetAttribute(reusekey, attribute)方法动态修改label控件内容。 getWidgetAttribute(reusekey, attribute)方法有两个参数,第一个参数是控件的reusekey,第二个参数attribute是要获取的属性名。

● 使用限制

只有拥有reusekey属性的控件才能在reuse list里动态创建,不是所有控件都有reusekey属性,拥有reusekey属性的控件有:
Label, Button, Icon, Image, Row, Input, Radio, Checkbox, Select, Radios,除此之外其他控件都不支持在reuse list里使用。

另外,通过item嵌套方式定义的可折叠的列表也不支持reuse list。

● 索引排序列表

在list设置reuse="sort"可以用来对item进行排序,同时要设置item的sortlabel属性,sortlabel是用来排序的文本内容。

<?xml version="1.0" encoding="utf-8"?>
<imag>
    <script>
    <![CDATA[
        var namelist = [
            '白玉芬',
            '仓春莲',
            '仓红',
            '陈超云',
            '陈高',
            '陈国祥',
            '陈宏柳',
            ....
        ];
        
        function initList() {
            var listJson = {items:[]};
            for (var i = 0; i < namelist.length; i++) {
                var itemJson = {
                    template:0,
                    sortlabel: namelist[i],
                    onclick:'alert("item' + i + '")',
                    widgets:{
                        title:{text:namelist[i]}
                    }
                }
                listJson.items.push(itemJson);
            }
            $('sortlist').update(listJson);
        }
        
        $page.onload = function() {
            initList();
        }
    ]]>    
    </script>
    <page>
        <title>
            <center>
                <label>索引排序列表</label>
            </center>
        </title>
        <content>
            <list id="sortlist" reuse="sort">
                <item style="divider-border:1 #cccccc">
                    <label reusekey="title"></label>
                </item>
            </list>
        </content>
    </page>
</imag>

示例下载

点此下载list相关的示例代码:imag-list.zip