Android API 中文 —— ListView
前言
关键字：Android API 中文 , Android 中文 API , android.widget.ListView
本章内容是 android.widget.ListView，译为"列表视图"，版本为Android 2.2 r1，翻译来自"Tina"，这是翻译组至今独立完成翻译最长的一篇 ，再次感谢"Tina"为大家带来优质的翻译稿 ！期待你一起参与Android API 的中文翻译，联系我[email protected]。
声明
欢迎转载，但请保留文章原始出处:)
博客园：http://www.cnblogs.com/
Android中文翻译组：http://www.cnblogs.com/over140/
正文
一、结构
public class RatingBar extends AbsSeekBar
java.lang.Object
android.view.View
android.view.ViewGroup
android.widget.AdapterView<T extends android.widget.Adapter>
android.widget.AbsListView
android.widget.ListView
直接子类
ExpandableListView （使用竖滚动条查看的两级列表视图）
二、概述
通过竖滚动条查看的列表视图。ListAdapter里包含的内容和此视图相关联。参见List View tutorial。
三、内部类
class ListView.FixedViewInfo
表示一个列表中的固定视图，如放在最顶部的页眉和最底部的页脚
四、XML属性
| 属性名称 |
描述 |
| android:choiceMode |
规定此ListView所使用的选择模式。缺省状态下，list没有选择模式。 属性值必须设置为下列常量之一： none，值为0，表示无选择模式； singleChoice，值为1，表示最多可以有一项被选中； multipleChoice，值为2，表示可以多项被选中。 可参看全局属性资源符号choiceMode。 |
| android:divider |
规定List项目之间用某个图形或颜色来分隔。可以用"@[+][package:]type:name"或者"?[package:][type:]name"（主题属性）的形式来指向某个已有资源；也可以用"#rgb"，"#argb"，"#rrggbb"或者"#aarrggbb"的格式来表示某个颜色。 可参看全局属性资源符号divider。 |
| android:dividerHeight |
分隔符的高度。若没有指明高度，则用此分隔符固有的高度。必须为带单位的浮点数，如"14.5sp"。可用的单位如px（pixel像素），dp（density-independent pixels 与密集度无关的像素）, sp（scaled pixels based on preferred font size 基于字体大小的固定比例的像素）， in (inches英寸), mm (millimeters毫米)。 可以用"@[package:]type:name "或者"?[package:][type:]name"（主题属性）的格式来指向某个包含此类型值的资源。 可参看全局属性资源符号dividerHeight。 |
| android:entries |
引用一个将使用在此ListView里的数组。若数组是固定的，使用此属性将比在程序中写入更为简单。 必须以"@[+][package:]type:name"或者 "?[package:][type:]name"的形式来指向某个资源。 可参看全局属性资源符号entries。 |
| android:footerDividersEnabled |
设成flase时，此ListView将不会在页脚视图前画分隔符。此属性缺省值为true。 属性值必须设置为true或false。 可以用"@[package:]type:name "或者"?[package:][type:]name"（主题属性）的格式来指向某个包含此类型值的资源。 可参看全局属性资源符号footerDividersEnabled。 |
| android:headerDividersEnabled |
设成flase时，此ListView将不会在页眉视图后画分隔符。此属性缺省值为true。 属性值必须设置为true或false。 可以用"@[package:]type:name "或者"?[package:][type:]name"（主题属性）的格式来指向某个包含此类型值的资源。 可参看全局属性资源符号headerDividersEnabled。 |
五、常量
Int CHOICE_MODE_MULTIPLE
（常量值为2）列表允许同时选取多项
Int CHOICE_MODE_NONE
（常量值为0）普通列表，不指明选取模式
Int CHOICE_MODE_SINGLE
（常量值为1）列表只允许选取最多一项
六、公共方法
public void addFooterView (View v)
加一个固定显示于list底部的视图。如果此方法被调用超过一次，所加的几个视图将按照它们加入的顺序排列。加入的视图可取得焦点。
注意：在调用setAdapter之前调用此方法。这样的话，可以利用点击光标来收起有header view和footer view的ListView。
参数
v 要加的视图
public void addFooterView (View v, Object data, boolean isSelectable)
加一个固定显示于list底部的视图。如果此方法被调用超过一次，所加的几个视图将按照它们加入的顺序排列。加入的视图可取得焦点。
注意：在调用setAdapter之前调用此方法。这样的话，可以利用点击光标来收起有header view和footer view的ListView。
参数
v 要加的视图
data 和此视图关联的数据
isSelectable 设为true则表示footer view可以被选中
public void addHeaderView (View v)
加一个固定显示于list顶部的视图。如果此方法被调用超过一次，所加的几个视图将按照它们加入的顺序排列。加入的视图可取得焦点。
注意：在调用setAdapter之前调用此方法。这样的话，可以利用点击光标来收起有header view和footer view的ListView。
参数
v 要加的视图
public void addHeaderView (View v, Object data, boolean isSelectable)
加一个固定显示于list顶部的视图。如果此方法被调用超过一次，所加的几个视图将按照它们加入的顺序排列。加入的视图可取得焦点。
注意：在调用setAdapter之前调用此方法。这样的话，可以利用点击光标来收起有header view和footer view的ListView。
参数
v 要加的视图
data 和此视图关联的数据
isSelectable 表示此header view可选与否
public void clearChoices ()
取消之前设置的任何选择
public boolean dispatchKeyEvent (KeyEvent event)
按照可以获得焦点的顺序（从视图树的顶端到当前获得焦点的视图），分派一个按键事件给下一个视图。若此视图有焦点，事件将会分派给它自己。否则它将按照顺序，分派给下一个节点。此方法同时触动所有按键监听器。
参数
event 被分派的事件
返回
若事件被处理，则返回true；否则为false
public boolean dispatchPopulateAccessibilityEvent (AccessibilityEvent event)
在视图的子项目被构建时，分派一个辅助事件。
参数
event 事件
返回
若事件全部完成，则返回true
public ListAdapter getAdapter ()
返回ListView当前用的适配器。返回的适配器不可以和传给setAdapter(ListAdapter)的参数一样，但是可以是WrapperListAdapter。
返回
当前用来显示ListView中数据的适配器
参见
setAdapter(ListAdapter)
public long[] getCheckItemIds ()
此方法已经过时了。使用getCheckedItemIds()代替。
返回被选中项目的索引集合。只有当选择模式没有被设置为CHOICE_MODE_NONE时才有效。
public long[] getCheckedItemIds ()
返回被选中项目的索引集合。只有当选择模式没有被设置为CHOICE_MODE_NONE，并且适配器有稳定的 ID（hasStableIds()==true） 时，结果才有效。
返回
一个新的数组，包含列表中每个被选中的索引（id）
public int getCheckedItemPosition ()
返回当前被选中的项目。只有当选择模式已被设置为CHOICE_MODE_SINGLE时 ，结果才有效。
返回
返回当前被选中的项目的索引；若没有项目被选中，则返回INVALID_POSITION
参见
setChoiceMode(int)
public SparseBooleanArray getCheckedItemPositions ()
返回当前被选中的项目集合。只有当选择模式没有被设置为CHOICE_MODE_NONE时 ，结果才有效。
返回
类型为SparseBooleanArray的值，其中，对每一个索引所代表的项目，若被选中，则返回true；当选择模式被设置为CHOICE_MODE_NONE时 ，返回null。
public int getChoiceMode ()
返回
返回当前的选择模式
参见
setChoiceMode(int)
public Drawable getDivider ()
返回
返回当前画在列表元素之间，作为分隔符的图形
public int getDividerHeight ()
返回
返回分隔符的高度
public int getFooterViewsCount ()
返回
列表中的页脚视图数量；缺省实现时，数量为0
public int getHeaderViewsCount ()
返回
列表中的页眉视图数量；缺省实现时，数量为0
public boolean getItemsCanFocus ()
返回
ListAdapter所生成的视图是否可以包含能取得焦点的项目
public int getMaxScrollAmount ()
返回
The maximum amount a list view will scroll in response to an arrow event.
响应箭头事件时，列表视图可以滚动的最大值。（译者注：此处翻译待改进，恐怕需要仔细查看源代码才能明白其含义，也可以用Google Code搜索相关的代码）
public boolean isItemChecked (int position)
对于由position指定的项目，返回其是否被选中。只有当选择模式已被设置为CHOICE_MODE_SINGLE或CHOICE_MODE_MULTIPLE时 ，结果才有效。
参数
position 要返回选中状态的项目
返回
返回项目的选中状态；若选择模式无效，则返回false
public boolean onKeyDown (int keyCode, KeyEvent event)
KeyEvent.Callback.onKeyMultiple()的缺省实现：若视图被激活并且可以被点击，当出现KEYCODE_DPAD_CENTER和KEYCODE_ENTER代表的行为时，做点击该视图的动作。
参数
keyCode 表示按某个按键的按键代号，参见KeyEvent
event 定义按键动作的按键事件对象
返回
若事件被成功处理，则返回true；若想要下一个接收器处理该事件，则返回false
public boolean onKeyMultiple (int keyCode, int repeatCount, KeyEvent event)
KeyEvent.Callback.onKeyMultiple()的缺省实现：总是返回false（不处理该事件）。
参数
keyCode 表示按某个按键的按键代号，参见KeyEvent
repeatedCount 实现动作的次数
event 定义按键动作的按键事件对象
返回
若事件被成功处理，则返回true；若想要下一个接收器处理该事件，则返回false
public boolean onKeyUp (int keyCode, KeyEvent event)
KeyEvent.Callback.onKeyMultiple()的缺省实现：当出现KEYCODE_DPAD_CENTER和KEYCODE_ENTER代表的行为时，做点击该视图的动作。
参数
keyCode 表示按某个按键的按键代号，参见KeyEvent
event 定义按键动作的按键事件对象
返回
若事件被成功处理，则返回true；若想要下一个接收器处理该事件，则返回false
public void onRestoreInstanceState (Parcelable state)
重新创建并显示一个视图，此视图拥有之前onSaveInstanceState()保存的内部状态。当state为null时，此方法不会被调用。
参数
state 之前onSaveInstanceState()保存的状态
public Parcelable onSaveInstanceState ()
保存视图的内部状态，用于以后创建新的拥有同样状态的实例。可保存的状态只包含非持久性的，或者可重新组建的信息。比如，永远不可能保存你当前在屏幕上的位置，因为当新的实例被放置于视图层次体系中时，位置会被重新计算。
一些可以被保存的状态：文本视图（但是通常不是指文本本身，因为文本是被保存在内容提供商或其他持久性的储存体中）中当前的光标位置；列表视图中当前的选中项。
返回
返回一个包含视图当前动态状态的接口方法对象；若没有东西被保存，则返回null。缺省情况下返回null。
public boolean onTouchEvent (MotionEvent ev)
此方法用于处理触摸屏的动作事件。
参数
ev 动作事件
返回
若事件被成功处理，则返回true；否则返回false
public boolean performItemClick (View view, int position, long id)
调用定义好的OnItemClickListener。
参数
view AdapterView中被点击到的视图
position 视图在适配器中的索引
id 被点击到的项目的行id
返回
若有定义好的OnItemClickListener被成功调用，则返回true；否则返回false
public boolean removeFooterView (View v)
删除之前加入的某个页脚视图。
参数
v 要删除的视图
返回
若视图被成功删除，则返回true；若此视图不是页脚视图，则返回false
public boolean removeHeaderView (View v)
删除之前加入的某个页眉视图。
参数
v 要删除的视图
返回
若视图被成功删除，则返回true；若此视图不是页眉视图，则返回false
public boolean requestChildRectangleOnScreen (View child, Rect rect, boolean immediate)
当组里的某个子项需要被定位在屏幕的某个矩形范围时，调用此方法。
重载此方法的ViewGroup可确认以下几点：
· 子项目将是组里的直系子项
· 矩形将在子项目的坐标体系中
重载此方法的ViewGroup必须保证以下几点：
· 若矩形已经是可见的，则没有东西会改变
· 为使矩形区域全部可见，视图将可以被滚动显示
参数
child 发出请求的子项目
rect 子项目坐标系内的矩形，即此子项目希望在屏幕上的定位
immediate 设为true，则禁止动画和缓释移动滚动条
返回
这个可滚动显示的组，是否接受请求
public void setAdapter (ListAdapter adapter)
设置ListView背后的数据。根据ListView目前使用的特性，adapter可能被WrapperListAdapter收起。例如：加页眉和/或页脚会使adapter被收起。
参数
adapter 负责维护列表背后的数据，以及生成视图来显示数据里的项目
参见
getAdapter()
public void setCacheColorHint (int color)
当color的值不为0时，此值表示的颜色将提示使用者，列表正在一片单色不透明的背景上被画出。
参数
color 背景色
public void setChoiceMode (int choiceMode)
设置List的选择模式。缺省情况下，列表没有选择模式（即值为CHOICE_MODE_NONE）。
参数
choiceMode 值可为CHOICE_MODE_NONE，CHOICE_MODE_NONE和CHOICE_MODE_NONE中的一种
public void setDivider (Drawable divider)
设置将画在列表中每个项目之间的图形。如果图形没有已设定好的高度，则必须同时调用setDividerHeight(int)。
参数
divider 将用作分隔符的图形
public void setDividerHeight (int height)
设置分隔符（画在列表中每个项目之间）的高度。调用此方法将覆盖由setDivider(Drawable)设置的高度。
参数
height 分隔符的新高度，单位为像素
public void setFooterDividersEnabled (boolean footerDividersEnabled)
设置可以或者不可以为页脚视图画上分隔符。
参数
headerDividersEnabled 设为true，表明可以画；设为false则不可以
参见
setHeaderDividerEnabled(boolean)
addFooterView(android.view.View)
public void setHeaderDividersEnabled (boolean headerDividersEnabled)
设置可以或者不可以为页眉视图画上分隔符。
参数
headerDividersEnabled 设为true，表明可以画；设为false则不可以
参见
setFooterDividerEnabled(boolean)
addHeaderView(android.view.View)
public void setItemChecked (int position, boolean value)
设置position所指定项目的选择状态。只有选择模式为CHOICE_MODE_SINGLE或者CHOICE_MODE_MULTIPLE时，此设置才有效。
参数
position 需要改变选择状态的项目的索引
value 新的选择状态
public void setItemsCanFocus (boolean itemsCanFocus)
表明在由ListAdapter创建的视图中，可包含能获得焦点的项目。
参数
itemsCanFocus 若项目能获得焦点，则设为true；否则为false
public void setSelection (int position)
选中position指定的项目。若为触摸模式，则指定项目不会被选中，但位置变化一样。若position的值小于0，则position为0的项目将被选中。
参数
position 需要选中的项目的索引（从0开始）
public void setSelectionAfterHeaderView ()
选中页眉视图下的第一个列表项目。
public void setSelectionFromTop (int position, int y)
选中position指定的项目，并将所选项置于距离ListView顶端y像素的位置（若为触摸模式，则指定项目不会被选中，但位置变化一样）。
参数
position 需要选中的项目的索引（从0开始）
y 距离 ListView （包括间隙）顶端的位置
七、受保护方法
protected boolean canAnimate ()
表示此视图组是否可以在第一次被布局后，仍可以动态调整其子项。
返回
若可以则为true，否则为false
protected void dispatchDraw (Canvas canvas)
调用此方法来绘出子视图。可被衍生类重写，以便在其子项被画出之前取得控制权。
参数
canvas 绘出View所用的canvas（画布？）
protected View findViewTraversal (int id)
参数
id 要找的View的id
返回值
有此id的View，若没有找到则为null
protected View findViewWithTagTraversal (Object tag)
参数
tag 要找的View的标签
返回值
有此标签的View，若没有找到则为null
protected void layoutChildren ()
子类必须重写此方法来布局其子项。
protected void onFinishInflate ()
当View以及所有子项从XML中导入时被调用，是导入的最后一步。即使子类重写onFinishInflate，也必须保证有调用超方法，这样，方法才会被调用。
protected void onFocusChanged (boolean gainFocus, int direction, Rect previouslyFocusedRect)
当View的焦点改变时被调用。重写时，要确保超类的直接调用，这样取得焦点的方式才是标准的。
参数
gainFocus 若View有焦点，则为True；否则为False。
direction 当requestFocus()被调用时，方向焦点被移动。其值可为FOCUS_UP，FOCUS_DOWN，FOCUS_LEFT或FOCUS_RIGHT。在使用缺省条件的情况下，direction并不总是可用。
previouslyFocusedRect 之前得到焦点的View的坐标系统所构成的矩形。如果可用，这个将被当成精确信息（表明焦点从何而来以及从何方向而来）来传递；否则将传递null。
protected void onMeasure (int widthMeasureSpec, int heightMeasureSpec)
View调用此方法来确定本身和所包含内容的大小。此方法被measure(int,int)唤起，而且必须被子类重写以得到所包含内容的确切大小。
注意：当重写此方法时，必须调用setMeasureDimension(int,int)来保存View的大小。如果没有做到，将会引发一个measure(int,int)抛出的IllegalStateException（非法状态错误）。超类onMeasure(int,int)可以被调用。
编写基类的确认大小的方法，缺省情况下是根据其背景大小来确认，除非MeasureSepc允许有更大的高度或宽度。子类必须重写onMeasure(int,int)以得到对其内容大小的更准确的测量。
若此方法被重写，它的子类需要确保其高度和宽度至少达到View所规定的最小值（可通过getSuggestedMinimumHeight()和getSuggestedMinimumWidth()得到）。
参数
widthMeaureSpec 受上一层大小影响下的对水平空间的要求。可参看View.MeasureSpec。
heightMeasureSpec 受上一层大小影响下的对垂直空间的要求。可参看View.MeasureSpec。
protected void onSizeChanged (int w, int h, int oldw, int oldh)
当VIew的大小改变时此方法被调用。如果VIew是刚刚被加入，则视之前的值为0。
参数
w View的当前宽度
h View的当前高度
oldw View大小改变之前的宽度
oldh View 大小改变之前的高度
八、补充
参考链接
Android入门第六篇之ListView (一)
android ListView详解
android异步加载ListView中的图片
Google I/O 2010 - The world of ListView
Android: 显示SD卡文件列表
Android: 带图标的ListView实现