安卓资源的使用 二

目录

22：安卓资源 二

动画资源

一个动画资源可以定义以下两种动画类型之一：

  • 属性动画

    通过使用 Animator 在设定的时间段内修改对象的属性值来创建动画。

  • 视图动画

    使用视图动画框架可以创建两种类型的动画：补间动画：通过使用 Animation 对单张图片执行一系列转换来创建动画帧动画：通过使用 AnimationDrawable 按顺序显示一系列图片来创建动画。

属性动画

在 XML 中定义的动画，用于在设定的一段时间内修改目标对象的属性，例如背景颜色或 Alpha 值。

  • 文件位置：

    res/animator/*filename*.xml 该文件名将用作资源 ID。

  • 编译后的资源数据类型：

    指向 ValueAnimator、ObjectAnimator 或 AnimatorSet 的资源指针。

  • 资源引用：

    在 Java 或 Kotlin 代码中：R.animator.*filename* 在 XML 中：@[*package*:]animator/*filename*

  • 语法：

        <set
      android:ordering=["together" | "sequentially"]>

        <objectAnimator
            android:propertyName="string"
            android:duration="int"
            android:valueFrom="float | int | color"
            android:valueTo="float | int | color"
            android:startOffset="int"
            android:repeatCount="int"
            android:repeatMode=["repeat" | "reverse"]
            android:valueType=["intType" | "floatType"]/>

        <animator
            android:duration="int"
            android:valueFrom="float | int | color"
            android:valueTo="float | int | color"
            android:startOffset="int"
            android:repeatCount="int"
            android:repeatMode=["repeat" | "reverse"]
            android:valueType=["intType" | "floatType"]/>

        <set>
            ...
        </set>
    </set>

  • 元素：

    <set>容纳其他动画元素（<objectAnimator>、<valueAnimator> 或其他 <set> 元素）的容器。代表 AnimatorSet。您可以指定嵌套的 <set> 标记来将动画进一步组合在一起。每个 <set> 都可以定义自己的 ordering 属性。属性：android:ordering关键字。指定此集合中动画的播放顺序。值说明sequentially依序播放此集合中的动画together（默认）同时播放此集合中的动画。

  • <objectAnimator>

    在特定的一段时间内为对象的特定属性创建动画。代表 ObjectAnimator。属性：

  • android:propertyName

    字符串。必需。要添加动画的对象属性，通过其名称引用。例如，您可以为 View 对象指定 "alpha" 或 "backgroundColor"。 但是，objectAnimator 元素不包含 target 属性，因此您无法在 XML 声明中设置要添加动画的对象。您必须通过调用 loadAnimator() 来扩充您的动画 XML 资源，然后调用 setTarget() 来设置包含此属性的目标对象。

  • android:valueTo

    浮点数、整数或颜色。必需。动画属性的结束值。颜色以六位十六进制数字表示（例如，#333333）。

  • android:valueFrom

    浮点数、整数或颜色。动画属性的开始值。如果未指定，则动画将从属性的 get 方法获得的值开始。颜色以六位十六进制数字表示（例如，#333333）。

  • android:duration

    整数。动画的时间，以毫秒为单位。默认为 300 毫秒。

  • android:startOffset

    整数。调用 start() 后动画延迟的毫秒数。

  • android:repeatCount

    整数。动画的重复次数。设为 "-1" 表示无限次重复，也可设为正整数。例如，值 "1" 表示动画在初次播放后重复播放一次，因此动画总共播放两次。默认值为 "0"，表示不重复。

  • android:repeatMode

    整数。动画播放到结尾处的行为。android:repeatCount 必须设置为正整数或 "-1"，该属性才有效。设置为 "reverse" 可让动画在每次迭代时反向播放，设置为 "repeat" 则可让动画每次从头开始循环播放。

  • android:valueType

    关键字。如果值为颜色，则不要指定此属性。动画框架会自动处理颜色值值说明intType指定动画值为整数floatType（默认）指定动画值为浮点数

<animator>

在指定的时间段内执行动画。代表 ValueAnimator。

属性：

android:valueTo

浮点数、整数或颜色。必需。动画的结束值。颜色以六位十六进制数字表示（例如，#333333）。

android:valueFrom

浮点数、整数或颜色。必需。动画的开始值。颜色以六位十六进制数字表示（例如，#333333）。

android:duration

整数。动画的时间，以毫秒为单位。默认为 300ms。

android:startOffset

整数。调用 start() 后动画延迟的毫秒数。。

android:repeatCount

整数。动画的重复次数。设为 "-1" 表示无限次重复，也可设为正整数。例如，值 "1" 表示动画在初次播放后重复播放一次，因此动画总共播放两次。默认值为 "0"，表示不重复。

android:repeatMode

整数。动画播放到结尾处的行为。android:repeatCount 必须设置为正整数或 "-1"，该属性才有效。设置为 "reverse" 可让动画在每次迭代时反向播放，设置为 "repeat" 则可让动画每次从头开始循环播放。

android:valueType

关键字。如果值为颜色，则不要指定此属性。动画框架会自动处理颜色值。

值 说明
intType 指定动画值为整数
floatType（默认） 指定动画值为浮点数

示例：

保存在 res/animator/property_animator.xml 的 XML 文件：

    <set android:ordering="sequentially">
        <set>
            <objectAnimator
                android:propertyName="x"
                android:duration="500"
                android:valueTo="400"
                android:valueType="intType"/>
            <objectAnimator
                android:propertyName="y"
                android:duration="500"
                android:valueTo="300"
                android:valueType="intType"/>
        </set>
        <objectAnimator
            android:propertyName="alpha"
            android:duration="500"
            android:valueTo="1f"/>
    </set>

为了运行此动画，您必须将代码中的 XML 资源扩充为 AnimatorSet 对象，然后在开始运行动画集之前为所有动画设置目标对象。为方便起见，调用 setTarget() 即可设置一个用于 AnimatorSet 的所有子项的目标对象。以下代码展示了如何执行此操作：

KOTLINJAVA

    val set: AnimatorSet = AnimatorInflater.loadAnimator(myContext, R.animator.property_animator)
        .apply {
            setTarget(myObject)
            start()
        }

另请参阅：

视图动画

视图动画框架可支持补间动画和逐帧动画，两者都可以在 XML 中声明。以下几个部分介绍如何使用这两种方法。

补间动画

在 XML 中定义的动画，用于对图形执行旋转、淡出、移动和拉伸等转换。

  • 文件位置：

    res/anim/*filename*.xml 该文件名将用作资源 ID。

  • 编译后的资源数据类型：

    指向 Animation 的资源指针。

  • 资源引用：

    在 Java 中：R.anim.*filename* 在 XML 中：@[*package*:]anim/*filename*

  • 语法：

        <?xml version="1.0" encoding="utf-8"?>
    <set xmlns:android="http://schemas.android.com/apk/res/android"
        android:interpolator="@[package:]anim/interpolator_resource"
        android:shareInterpolator=["true" | "false"] >
        <alpha
            android:fromAlpha="float"
            android:toAlpha="float" />
        <scale
            android:fromXScale="float"
            android:toXScale="float"
            android:fromYScale="float"
            android:toYScale="float"
            android:pivotX="float"
            android:pivotY="float" />
        <translate
            android:fromXDelta="float"
            android:toXDelta="float"
            android:fromYDelta="float"
            android:toYDelta="float" />
        <rotate
            android:fromDegrees="float"
            android:toDegrees="float"
            android:pivotX="float"
            android:pivotY="float" />
        <set>
            ...
        </set>
    </set>

  • 元素：

    元素：

    • <set>

      容纳其他动画元素（<alpha>、<scale>、<translate>、<rotate>）或其他 <set> 元素的容器。代表 AnimationSet。属性：android:interpolator插值器资源。 要应用于动画的 Interpolator。 该值必须是对指定插值器的资源的引用（而不是插值器类名称）。您可以使用平台提供的默认插值器资源，也可以创建自己的插值器资源。有关插值器的详细信息，请参阅以下说明。android:shareInterpolator布尔值。如果要在所有子元素中共用同一插值器，则为“true”。

    • <alpha>

      淡入或淡出动画。代表 AlphaAnimation。属性：android:fromAlpha浮点数。起始不透明度偏移，0.0 表示透明，1.0 表示不透明。android:toAlpha浮点数。结束不透明度偏移，0.0 表示透明，1.0 表示不透明。要了解 <alpha> 支持的更多属性，请参阅 Animation 类引用（其中所有 XML 属性均由此元素继承）。

    • <scale>

      大小调整动画。您可以通过指定 pivotX 和 pivotY，来指定图片向外（或向内）扩展的中心点。例如，如果这两个值为 0、0（左上角），则所有扩展均向右下方向进行。代表 ScaleAnimation。属性：android:fromXScale浮点数。起始 X 尺寸偏移，其中 1.0 表示不变。android:toXScale浮点数。结束 X 尺寸偏移，其中 1.0 表示不变。android:fromYScale浮点数。起始 Y 尺寸偏移，其中 1.0 表示不变。android:toYScale浮点数。结束 Y 尺寸偏移，其中 1.0 表示不变。android:pivotX浮点数。在对象缩放时要保持不变的 X 坐标。android:pivotY浮点数。在对象缩放时要保持不变的 Y 坐标。要了解 <scale> 支持的更多属性，请参阅 Animation 类引用（其中所有 XML 属性均由此元素继承）。

    • <translate>

      垂直和/或水平移动。支持采用以下三种格式之一的以下属性：从 -100 到 100 的以“％”结尾的值，表示相对于自身的百分比；从 -100 到 100 的以“％p”结尾的值，表示相对于其父项的百分比；不带后缀的浮点值，表示绝对值。代表 TranslateAnimation。属性：android:fromXDelta浮动数或百分比。起始 X 偏移。表示方式：相对于正常位置的像素数（例如 "5"），相对于元素宽度的百分比（例如 "5%"），或相对于父项宽度的百分比（例如 "5%p"）。android:toXDelta浮动数或百分比。结束 X 偏移。表示方式：相对于正常位置的像素数（例如 "5"），相对于元素宽度的百分比（例如 "5%"），或相对于父项宽度的百分比（例如 "5%p"）。android:fromYDelta浮动数或百分比。起始 Y 偏移。表示方式：相对于正常位置的像素数（例如 "5"），相对于元素高度的百分比（例如 "5%"），或相对于父项高度的百分比（例如 "5%p"）。android:toYDelta浮动数或百分比。结束 Y 偏移。表示方式：相对于正常位置的像素数（例如 "5"），相对于元素高度的百分比（例如 "5%"），或相对于父项高度的百分比（例如 "5%p"）。要了解 <translate> 支持的更多属性，请参阅 Animation 类引用（其中所有 XML 属性均由此元素继承）。

    • <rotate>

      旋转动画。代表 RotateAnimation。属性：android:fromDegrees浮点数。起始角度位置，以度为单位。android:toDegrees浮点数。结束角度位置，以度为单位。android:pivotX浮动数或百分比。旋转中心的 X 坐标。表示方式：相对于对象左边缘的像素数（例如 "5"），相对于对象左边缘的百分比（例如 "5%"），或相对于父级容器左边缘的百分比（例如 "5%p"）。android:pivotY浮点数或百分比。旋转中心的 Y 坐标。表示方式：相对于对象上边缘的像素数（例如 "5"），相对于对象上边缘的百分比（例如 "5%"），或相对于父级容器上边缘的百分比（例如 "5%p"）。要了解 <rotate> 支持的更多属性，请参阅 Animation 类引用（其中所有 XML 属性均由此元素继承）。

  • 示例：

    保存在 res/anim/hyperspace_jump.xml 的 XML 文件：` <set

        <set xmlns:android="http://schemas.android.com/apk/res/android"
        android:shareInterpolator="false">
        <scale
            android:interpolator="@android:anim/accelerate_decelerate_interpolator"
            android:fromXScale="1.0"
            android:toXScale="1.4"
            android:fromYScale="1.0"
            android:toYScale="0.6"
            android:pivotX="50%"
            android:pivotY="50%"
            android:fillAfter="false"
            android:duration="700" />
        <set
            android:interpolator="@android:anim/accelerate_interpolator"
            android:startOffset="700">
            <scale
                android:fromXScale="1.4"
                android:toXScale="0.0"
                android:fromYScale="0.6"
                android:toYScale="0.0"
                android:pivotX="50%"
                android:pivotY="50%"
                android:duration="400" />
            <rotate
                android:fromDegrees="0"
                android:toDegrees="-45"
                android:toYScale="0.0"
                android:pivotX="50%"
                android:pivotY="50%"
                android:duration="400" />
        </set>
    </set>

  • 另请参阅：

    2D 图形：补间动画

插值器

插值器是在 XML 中定义的动画修改器，它会影响动画的变化率。插值器可对现有的动画效果执行加速、减速、重复、退回等。

插值器通过 android:interpolator 属性应用于动画元素，该属性的值是对插值器资源的引用。

Android 中提供的所有插值器都是 Interpolator 类的子类。为便于您使用 android:interpolator 属性将插值器应用于动画，Android 针对每个插值器类包含了一个可供您引用的公共资源。下表指定了每个插值器要使用的资源：

插值器类 资源 ID
AccelerateDecelerateInterpolator @android:anim/accelerate_decelerate_interpolator
AccelerateInterpolator @android:anim/accelerate_interpolator
AnticipateInterpolator @android:anim/anticipate_interpolator
AnticipateOvershootInterpolator @android:anim/anticipate_overshoot_interpolator
BounceInterpolator @android:anim/bounce_interpolator
CycleInterpolator @android:anim/cycle_interpolator
DecelerateInterpolator @android:anim/decelerate_interpolator
LinearInterpolator @android:anim/linear_interpolator
OvershootInterpolator @android:anim/overshoot_interpolator

您可以通过以下方式使用 android:interpolator 属性应用上述某个插值器：

    <set android:interpolator="@android:anim/accelerate_interpolator">
        ...
    </set>

自定义插值器

如果您对平台提供的插值器（在上表中列出）不满意，则可以使用修改过的属性创建自定义插值器资源。例如，您可以调整 AnticipateInterpolator 的加速率或调整 CycleInterpolator 的循环次数。为此，您需要在 XML 文件中创建自己的插值器资源。

  • 文件位置：

    res/anim/*filename*.xml 该文件名将用作资源 ID。

  • 编译后的资源数据类型：

    指向相应插值器对象的资源指针。

  • 资源引用：

    在 XML 中：@[*package*:]anim/*filename*

  • 语法：

    <?xml version="1.0" encoding="utf-8"?> <*InterpolatorName* xmlns:android="http://schemas.android.com/apk/res/android" android:*attribute_name*="*value*" /> 如果您不应用任何属性，则您的插值器的运作方式将与平台提供的插值器（在上表中列出）完全相同。

  • 元素：

    请注意，在 XML 中定义的每个 Interpolator 实现的名称都以小写字母开头。<accelerateDecelerateInterpolator>变化率在开始和结束时缓慢，但在中间会加快。没有属性。<accelerateInterpolator>变化率在开始时较为缓慢，然后会加快。属性：android:factor浮点数。加速率（默认为 1）。<anticipateInterpolator>先反向变化，然后再急速正向变化。属性：android:tension浮点数。要应用的张力（默认为 2）。<anticipateOvershootInterpolator>先反向变化，再急速正向变化并超过目标值，然后以最终值结束。属性：android:tension浮点数。要应用的张力（默认为 2）。android:extraTension浮点数。张力要乘以的倍数（默认值为 1.5）。<bounceInterpolator>变化会在结束时退回。没有属性。<cycleInterpolator>按指定的循环次数重复动画。变化率符合正弦曲线图。属性：android:cycles整数。循环次数（默认值为 1）。

  • <decelerateInterpolator>

    变化率开始时很快，然后减慢。属性：android:factor浮点数。减速率（默认值为 1）。

  • <linearInterpolator>

    变化率恒定不变。没有属性。

  • <overshootInterpolator>

    先急速正向变化，再超过最终值，然后回到最终值。属性：android:tension浮点数。要应用的张力（默认为 2）。

示例：

保存在 res/anim/my_overshoot_interpolator.xml 的 XML 文件：

    <?xml version="1.0" encoding="utf-8"?>
    <overshootInterpolator xmlns:android="http://schemas.android.com/apk/res/android"
        android:tension="7.0"
        />

此动画 XML 将应用插值器：

    <scale xmlns:android="http://schemas.android.com/apk/res/android"
        android:interpolator="@anim/my_overshoot_interpolator"
        android:fromXScale="1.0"
        android:toXScale="3.0"
        android:fromYScale="1.0"
        android:toYScale="3.0"
        android:pivotX="50%"
        android:pivotY="50%"
        android:duration="700" />

帧动画

在 XML 中定义的按顺序显示一系列图片的动画（如电影）。

  • 文件位置：

    res/drawable/*filename*.xml 该文件名将用作资源 ID。

  • 编译后的资源数据类型：

    指向 AnimationDrawable 的资源指针。

  • 资源引用：

    在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable.*filename*

  • 语法：

    <?xml version="1.0" encoding="utf-8"?> <animation-list xmlns:android="http://schemas.android.com/apk/res/android" android:oneshot=["true" | "false"] > <item android:drawable="@[package:]drawable/*drawable_resource_name*" android:duration="*integer*" /> </animation-list>

  • 元素：

    <animation-list>必需。此元素必须是根元素。包含一个或多个 <item> 元素。属性：android:oneshot布尔值。如果您想要执行一次动画，则为“true”；如果要循环播放动画，则为“false”。<item>单帧动画。必须是 <animation-list> 元素的子元素。属性：android:drawable可绘制资源。要用于此帧的可绘制对象。android:duration整数。显示此帧的持续时间，以毫秒为单位。

  • 示例：

    保存在 res/drawable/rocket.xml 的 XML 文件： <?xml version="1.0" encoding="utf-8"?> <animation-list xmlns:android="http://schemas.android.com/apk/res/android" android:oneshot="false"> <item android:drawable="@drawable/rocket_thrust1" android:duration="200" /> <item android:drawable="@drawable/rocket_thrust2" android:duration="200" /> <item android:drawable="@drawable/rocket_thrust3" android:duration="200" /> </animation-list> 以下应用代码会将该动画设置为 View 的背景，然后播放动画：KOTLINJAVA val rocketImage: ImageView = findViewById(R.id.rocket_image) rocketImage.setBackgroundResource(R.drawable.rocket_thrust) val rocketAnimation = rocketImage.background if (rocketAnimation is Animatable) { rocketAnimation.start() }

  • 另请参阅：

    2D 图形：帧动画

颜色状态列表资源

ColorStateList 是一个您可以在 XML 中定义的对象，您可以将其作为颜色来应用，但它实际上会更改颜色，具体取决于其应用到的 View 对象的状态。例如，Button 微件可以处于多种不同状态中的一种（按下、聚焦或既不按下也不聚焦），而使用颜色状态列表，您可以为每种状态提供不同的颜色。

您可以在 XML 文件中描述状态列表。每种颜色都在单个 <selector> 元素内的 <item> 元素中定义。每个 <item> 使用不同的属性描述其应在什么状态下使用。

在每次状态更改期间，系统将从上到下遍历状态列表，并且将使用与当前状态匹配的第一项。系统的选择并非基于“最佳匹配”，而仅仅是基于符合状态的最低标准的第一项。

注意：如果要提供静态颜色资源，请使用简单的颜色值。

  • 文件位置：

    res/color/*filename*.xml 该文件名将用作资源 ID。

  • 编译后的资源数据类型：

    指向 ColorStateList 的资源指针。

  • 资源引用：

    在 Java 中：R.color.*filename* 在 XML 中：@[*package*:]color/*filename*

  • 语法：

        <?xml version="1.0" encoding="utf-8"?>
    <selector xmlns:android="http://schemas.android.com/apk/res/android" >
        <item
            android:color="hex_color"
            android:state_pressed=["true" | "false"]
            android:state_focused=["true" | "false"]
            android:state_selected=["true" | "false"]
            android:state_checkable=["true" | "false"]
            android:state_checked=["true" | "false"]
            android:state_enabled=["true" | "false"]
            android:state_window_focused=["true" | "false"] />
    </selector>

  • 元素：

    必需。该元素必须是根元素。包含一个或多个 <item> 元素。

    属性：

    • xmlns:android

      字符串。必需。定义 XML 命名空间，该命名空间必须为 "http://schemas.android.com/apk/res/android"。

    定义在某些状态下使用的颜色，状态通过其属性来描述。必须是 <selector> 元素的子元素。

    属性：

    • android:color

      十六进制颜色。必需。颜色通过 RGB 值和可选的 Alpha 通道指定。该值始终以井号 (#) 字符开头，后跟以下某种格式的“透明度、红、绿、蓝”(Alpha-Red-Green-Blue) 信息：#RGB#ARGB#RRGGBB#AARRGGBB

    • android:state_pressed

      布尔值。如果此项应在按下对象时（例如轻触/点按了按钮时）使用，则为“true”；如果此项应在默认的非按下状态下使用，则为“false”。

    • android:state_focused

      布尔值。如果此项应在聚焦对象时（例如使用轨迹球/方向键突出显示按钮时）使用，则为“true”；如果此项应在默认的非聚焦状态下使用，则为“false”。

    • android:state_selected

      布尔值。如果此项应在选择对象时（例如打开标签页时）使用，则为“true”；如果此项应在未选择对象时使用，则为“false”。

    • android:state_checkable

      布尔值。如果此项应在对象可勾选时使用，则为“true”；如果此项应在对象不可勾选时使用，则为“false”。（仅适用于对象可在可勾选和不可勾选的微件之间转换的情况。）

    • android:state_checked

      布尔值。如果此项应在勾选对象时使用，则为“true”；如果应在取消勾选对象时使用，则为“false”。

    • android:state_enabled

      布尔值。如果此项应在启用对象（能够接收轻触/点按事件）时使用，则为“true”；如果应在停用对象时使用，则为“false”。

    • android:state_window_focused

      布尔值。如果此项应在应用窗口具有焦点（应用位于前台）时使用，则为“true”；如果此项应在应用窗口没有焦点时（例如通知栏下拉或出现一个对话框时）使用，则为“false”。

    注意：请注意，系统将应用状态列表中与对象的当前状态匹配的第一项。因此，如果列表中的第一项不包含上述任何状态属性，则每次都会应用该项，因此默认值应始终为最后一项，如以下示例所示。

  • 示例：

    保存于 res/color/button_text.xml 的 XML 文件：

        <?xml version="1.0" encoding="utf-8"?>
    <selector xmlns:android="http://schemas.android.com/apk/res/android">
        <item android:state_pressed="true"
              android:color="#ffff0000"/> <!-- pressed -->
        <item android:state_focused="true"
              android:color="#ff0000ff"/> <!-- focused -->
        <item android:color="#ff000000"/> <!-- default -->
    </selector>

    此布局 XML 会将颜色列表应用到 View：

        <Button
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:text="@string/button_text"
        android:textColor="@color/button_text" />

    另请参阅：

  • 另请参阅：

可绘制对象资源

目录位图位图文件XML 位图九宫格

可绘制对象资源是图形的一般概念，是指可在屏幕上绘制的图形，以及可使用 getDrawable(int) 等 API 检索，或应用到拥有 android:drawable 和 android:icon 等属性的其他 XML 资源的图形。可绘制对象包含以下多种类型：

位图图形文件（`.png`、`.jpg` 或 `.gif`）。创建 `BitmapDrawable`。

  • 九宫格文件

    具有可伸缩区域的 PNG 文件，支持根据内容调整图像大小 (.9.png)。创建 NinePatchDrawable。

  • 图层列表

    管理其他可绘制对象阵列的可绘制对象。这些可绘制对象按阵列顺序绘制，因此索引最大的元素绘制于顶部。创建 LayerDrawable。

  • 状态列表

    此 XML 文件用于为不同状态引用不同位图图形（例如，按下按钮时使用不同图像）。创建 StateListDrawable。

  • 级别列表

    此 XML 文件用于定义管理大量备选可绘制对象的可绘制对象，每个可绘制对象都配有最大备选数量。创建 LevelListDrawable。

  • 转换可绘制对象

    此 XML 文件用于定义可在两种可绘制对象资源之间交错淡出的可绘制对象。创建 TransitionDrawable。

  • 插入可绘制对象

    此 XML 文件用于定义以指定距离插入其他可绘制对象的可绘制对象。当视图需要小于视图实际边界的背景可绘制对象时，此类可绘制对象非常有用。

  • 裁剪可绘制对象

    此 XML 文件用于定义对其他可绘制对象进行裁剪（根据其当前级别值）的可绘制对象。创建 ClipDrawable。

  • 缩放可绘制对象

    此 XML 文件用于定义更改其他可绘制对象大小（根据其当前级别值）的可绘制对象。创建 ScaleDrawable

  • 形状可绘制对象

    此 XML 文件用于定义几何形状（包括颜色和渐变）。创建 GradientDrawable。

另请参阅动画资源文档，了解如何创建 AnimationDrawable。

请注意：颜色资源也可用作 XML 中的可绘制对象。例如，在创建状态列表可绘制对象时，可以引用 android:drawable 属性的颜色资源 (android:drawable="@color/green")。

位图

位图图像。Android 支持以下三种格式的位图文件：.png（首选）、.jpg（可接受）、.gif（不建议）。

您可以使用文件名作为资源 ID 直接引用位图文件，也可以在 XML 中创建别名资源 ID。

注：在构建过程中，可通过 aapt 工具自动优化位图文件，对图像进行无损压缩。例如，不需要超过 256 色的真彩色 PNG 可通过调色板转换为 8 位 PNG。这样产生的图像质量相同，但所需内存更少。因此请注意，此目录中的图像二进制文件在构建时可能会发生变化。如果您打算以比特流的形式读取图像，进而将其转换为位图，请改为将图像放在 res/raw/ 文件夹中，避免系统对其进行优化。

位图文件

位图文件是 .png、.jpg 或 .gif 文件。当您将任一位图文件保存到 res/drawable/ 目录中时，Android 会为其创建 Drawable 资源。

  • 文件位置：

    res/drawable/*filename*.png（.png、.jpg 或 .gif） 文件名用作资源 ID。

  • 编译资源的数据类型：

    指向 BitmapDrawable 的资源指针。

  • 资源引用：

    在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable/*filename*

  • 示例：

    当图像保存为 res/drawable/myimage.png 后，此布局 XML 会将该图像应用至视图：<ImageView android:layout_height="wrap_content" android:layout_width="wrap_content" android:src="@drawable/myimage" />以下应用代码将图像作为 Drawable 进行检索：KOTLINJAVAval drawable: Drawable? = ResourcesCompat.getDrawable(resources, R.drawable.myimage, null)

  • 另请参阅：

    2D 图形BitmapDrawable

XML 位图

XML 位图是在 XML 文件中定义的资源，指向位图文件。实际上是原始位图文件的别名。XML 可以指定位图的其他属性，例如抖动和层叠。

注：您可以将 <bitmap> 元素用作 <item> 元素的子项。例如，在创建状态列表或图层列表时，可以将 android:drawable 属性从 <item> 元素中排除，并在其中嵌套用于定义可绘制项的 <bitmap>。

  • 文件位置：

    res/drawable/*filename*.xml 文件名用作资源 ID。

  • 编译资源的数据类型：

    指向 BitmapDrawable 的资源指针。

  • 资源引用：

    在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable/*filename*

  • 语法：

  • <?xml version="1.0" encoding="utf-8"?>
<bitmap
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:src="@[package:]drawable/drawable_resource"
    android:antialias=["true" | "false"]
    android:dither=["true" | "false"]
    android:filter=["true" | "false"]
    android:gravity=["top" | "bottom" | "left" | "right" | "center_vertical" |
                      "fill_vertical" | "center_horizontal" | "fill_horizontal" |
                      "center" | "fill" | "clip_vertical" | "clip_horizontal"]
    android:mipMap=["true" | "false"]
    android:tileMode=["disabled" | "clamp" | "repeat" | "mirror"] />

  • 元素：

    <bitmap>

    定义位图来源及其属性。

    属性：

    • xmlns:android

      字符串。定义 XML 命名空间，其必须是 "http://schemas.android.com/apk/res/android"。这仅当 <bitmap> 是根元素时才需要，当 <bitmap> 嵌套在 <item> 内时不需要。

    • android:src

      可绘制对象资源。必备。引用可绘制对象资源。

    • android:antialias

      布尔值。启用或停用抗锯齿。

    • android:dither

      布尔值。当位图的像素配置与屏幕不同时（例如：ARGB 8888 位图和 RGB 565 屏幕），启用或停用位图抖动。

    • android:filter

      布尔值。启用或停用位图过滤。当位图收缩或拉伸以使其外观平滑时使用过滤。

    • android:gravity

      关键字。定义位图的重力。重力指示当位图小于容器时，可绘制对象在其容器中放置的位置。必须是以下一个或多个（用 '|' 分隔）常量值：值说明top将对象放在其容器顶部，不改变其大小。bottom将对象放在其容器底部，不改变其大小。left将对象放在其容器左边缘，不改变其大小。right将对象放在其容器右边缘，不改变其大小。center_vertical将对象放在其容器的垂直中心，不改变其大小。fill_vertical按需要扩展对象的垂直大小，使其完全适应其容器。center_horizontal将对象放在其容器的水平中心，不改变其大小。fill_horizontal按需要扩展对象的水平大小，使其完全适应其容器。center将对象放在其容器的水平和垂直轴中心，不改变其大小。fill按需要扩展对象的垂直大小，使其完全适应其容器。这是默认值。clip_vertical可设置为让子元素的上边缘和/或下边缘裁剪至其容器边界的附加选项。裁剪基于垂直重力：顶部重力裁剪上边缘，底部重力裁剪下边缘，任一重力不会同时裁剪两边。clip_horizontal可设置为让子元素的左边和/或右边裁剪至其容器边界的附加选项。裁剪基于水平重力：左边重力裁剪右边缘，右边重力裁剪左边缘，任一重力不会同时裁剪两边。

    • android:mipMap

      布尔值。启用或停用 mipmap 提示。如需了解详情，请参阅 setHasMipMap()。默认值为 false。

    • android:tileMode

      关键字。定义平铺模式。当平铺模式启用时，位图会重复。重力在平铺模式启用时将被忽略。必须是以下常量值之一：值说明disabled不平铺位图。这是默认值。clamp当着色器绘制范围超出其原边界时复制边缘颜色repeat水平和垂直重复着色器的图像。mirror水平和垂直重复着色器的图像，交替镜像图像以使相邻图像始终相接。

  • 示例：

    <?xml version="1.0" encoding="utf-8"?><bitmap xmlns:android="http://schemas.android.com/apk/res/android"  android:src="@drawable/icon"  android:tileMode="repeat" />

  • 另请参阅：

    BitmapDrawable创建别名资源

九宫格

NinePatch 是一种 PNG 图像，您可在其中定义可伸缩区域，以便 Android 在视图中的内容超出正常图像边界时进行缩放。此类图像通常指定为至少有一个尺寸设置为 "wrap_content" 的视图背景，而且当视图通过扩展来适应内容时，九宫格图像也会通过扩展来匹配视图的大小。举例而言，Android 的标准 Button 微件所使用的背景便是典型的九宫格图像，其必须通过伸缩来适应按钮内的文本（或图像）。

与普通位图一样，您可直接引用九宫格文件，也可通过 XML 定义资源对其进行引用。

如需完整了解如何创建包含可伸缩区域的九宫格文件，请参阅 2D 图形文件。

九宫格文件

  • 文件位置：

    res/drawable/*filename*.9.png 文件名用作资源 ID。

  • 编译资源的数据类型：

    指向 NinePatchDrawable 的资源指针。

  • 资源引用：

    在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable/*filename*

  • 示例：

    当图像保存为 res/drawable/myninepatch.9.png 后，此布局 XML 会将九宫格应用到视图：<Button android:layout_height="wrap_content" android:layout_width="wrap_content" android:background="@drawable/myninepatch" />

  • 另请参阅：

    2D 图形NinePatchDrawable

XML 九宫格

XML 九宫格是在 XML 中定义的资源，指向九宫格文件。XML 可以为图像指定抖动。

  • 文件位置：

    res/drawable/*filename*.xml 文件名用作资源 ID。

  • 编译资源的数据类型：

    指向 NinePatchDrawable 的资源指针。

  • 资源引用：

    在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable/*filename*

  • 语法：

    <?xml version="1.0" encoding="utf-8"?>
<nine-patch xmlns:android="http://schemas.android.com/apk/res/android"
    android:src="@drawable/myninepatch"
    android:dither="false" />

  • 元素：

    <nine-patch>定义九宫格来源及其属性。属性：xmlns:android字符串。必备。定义 XML 命名空间，其必须是 "http://schemas.android.com/apk/res/android"。android:src可绘制对象资源。必备。引用九宫格文件。android:dither布尔值。当位图的像素配置与屏幕不同时（例如：ARGB 8888 位图和 RGB 565 屏幕），启用或停用位图抖动。

  • 示例：

    <?xml version="1.0" encoding="utf-8"?><nine-patch xmlns:android="http://schemas.android.com/apk/res/android" android:src="@drawable/myninepatch" android:dither="false" />

图层列表

LayerDrawable 是管理其他可绘制对象阵列的可绘制对象。列表中的每个可绘制对象均按照列表顺序绘制，列表中的最后一个可绘制对象绘于顶部。

每个可绘制对象由单一 <layer-list> 元素内的 <item> 元素表示。

  • 文件位置：

    res/drawable/*filename*.xml 文件名用作资源 ID。

  • 编译资源的数据类型：

    指向 LayerDrawable 的资源指针。

  • 资源引用：

    在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable/*filename*

  • 语法：

    <?xml version="1.0" encoding="utf-8"?>
<layer-list
    xmlns:android="http://schemas.android.com/apk/res/android" >
    <item
        android:drawable="@[package:]drawable/drawable_resource"
        android:id="@[+][package:]id/resource_name"
        android:top="dimension"
        android:right="dimension"
        android:bottom="dimension"
        android:left="dimension" />
</layer-list>

  • 元素：

    • <layer-list>

      必备。这必须是根元素。包含一个或多个 <item> 元素。属性：xmlns:android字符串。必备。定义 XML 命名空间，其必须是 "http://schemas.android.com/apk/res/android"。

    • <item>

      定义放于图层可绘制对象中由其属性所定义位置的可绘制对象。必须是 <layer-list> 元素的子项。接受子 <bitmap> 元素。属性：android:drawable可绘制对象资源。必备。引用可绘制对象资源。android:id资源 ID。此可绘制对象的唯一资源 ID。要为此项新建资源 ID，请使用以下形式："@+id/*name*"。加号表示应创建为新 ID。您可以使用此 ID 检索和修改拥有 View.findViewById() 或 Activity.findViewById() 的可绘制对象。android:top整型。顶部偏移（像素）。android:right整型。右边偏移（像素）。android:bottom整型。底部偏移（像素）。android:left整型。左边偏移（像素）。

  • 。默认情况下，所有可绘制项都会缩放以适应包含视图的大小。因此，将图像放在图层列表中的不同位置可能会增大视图的大小，并且有些图像会相应地缩放。为避免缩放列表中的项目，请在 <item> 元素内使用 <bitmap> 元素指定可绘制对象，并且对某些不缩放的项目（例如 "center"）定义重力。例如，以下 <item> 定义缩放以适应其容器视图的项目：

    <item android:drawable="@drawable/image" />

    为避免缩放，以下示例使用重力居中的 <bitmap> 元素：

    <item>
  <bitmap android:src="@drawable/image"
          android:gravity="center" />
</item>

  • 示例：

    XML 文件保存在 res/drawable/layers.xml 中：

    <?xml version="1.0" encoding="utf-8"?>
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
    <item>
      <bitmap android:src="@drawable/android_red"
        android:gravity="center" />
    </item>
    <item android:top="10dp" android:left="10dp">
      <bitmap android:src="@drawable/android_green"
        android:gravity="center" />
    </item>
    <item android:top="20dp" android:left="20dp">
      <bitmap android:src="@drawable/android_blue"
        android:gravity="center" />
    </item>
</layer-list>

    请注意，此示例使用嵌套的 <bitmap> 元素为每个具有“中心”重力的项目定义可绘制对象资源。这可确保没有图像会为了适应容器的大小而缩放，因为偏移图像会造成大小调整。此布局 XML 会将可绘制对象应用到视图：

    <ImageView
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:src="@drawable/layers" />

    结果是一堆不断偏移的图像：img

  • 另请参阅：

    LayerDrawable

状态列表

StateListDrawable 是在 XML 文件中定义的可绘制对象，它会根据对象状态，使用多个不同的图像来表示同一个图形。例如，Button 微件可以是多种不同状态（按下、聚焦或这两种状态都不是）中的其中一种，并且您可利用状态列表可绘制对象，为每种状态提供不同的背景图片。

您可以在 XML 文件中描述状态列表。每个图形由单一 <selector> 元素内的 <item> 元素表示。每个 <item> 均使用各种属性来描述应用作可绘制对象的图形的状态。

在每个状态变更期间，将从上到下遍历状态列表，并使用第一个与当前状态匹配的项目 —此选择并非基于“最佳匹配”，而是选择符合状态最低条件的第一个项目。

  • 文件位置：

    res/drawable/*filename*.xml 文件名用作资源 ID。

  • 编译资源的数据类型：

    指向 StateListDrawable 的资源指针。

  • 资源引用：

    在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable/*filename*

  • 语法：

    <?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android="http://schemas.android.com/apk/res/android"
    android:constantSize=["true" | "false"]
    android:dither=["true" | "false"]
    android:variablePadding=["true" | "false"] >
    <item
        android:drawable="@[package:]drawable/drawable_resource"
        android:state_pressed=["true" | "false"]
        android:state_focused=["true" | "false"]
        android:state_hovered=["true" | "false"]
        android:state_selected=["true" | "false"]
        android:state_checkable=["true" | "false"]
        android:state_checked=["true" | "false"]
        android:state_enabled=["true" | "false"]
        android:state_activated=["true" | "false"]
        android:state_window_focused=["true" | "false"] />
</selector>

    元素：

    • <selector>

      必备。这必须是根元素。包含一个或多个 <item> 元素。属性：xmlns:android字符串。必备。定义 XML 命名空间，其必须是 "http://schemas.android.com/apk/res/android"。android:constantSize布尔值。如果可绘制对象报告的内部大小在状态变更时保持不变，则值为“true”（大小是所有状态的最大值）；如果大小根据当前状态而变化，则值为“false”。默认值为 false。android:dither布尔值。值为“true”时，将在位图的像素配置与屏幕不同时（例如：ARGB 8888 位图和 RGB 565 屏幕）启用位图的抖动；值为“false”时则停用抖动。默认值为 true。android:variablePadding布尔值。如果可绘制对象的内边距应根据选择的当前状态而变化，则值为“true”；如果内边距应保持不变（基于所有状态的最大内边距），则值为“false”。启用此功能要求您在状态变更时处理执行布局，这通常不受支持。默认值为 false。

    • <item>

      定义要在某些状态期间使用的可绘制对象，如其属性所述。必须是 <selector> 元素的子项。属性：android:drawable可绘制对象资源。必备。引用可绘制对象资源。android:state_pressed布尔值。如果在按下对象（例如触摸/点按某按钮）时应使用此项目，则值为“true”；如果在默认的未按下状态时应使用此项目，则值为“false”。android:state_focused布尔值。如果在对象具有输入焦点（例如当用户选择文本输入时）时应使用此项目，则值为“true”；如果在默认的非焦点状态时应使用此项目，则值为“false”。android:state_hovered布尔值。如果当光标悬停在对象上时应使用此项目，则值为“true”；如果在默认的非悬停状态时应使用此项目，则值为“false”。通常，这个可绘制对象可能与用于“聚焦”状态的可绘制对象相同。此项为 API 级别 14 新引入的配置。android:state_selected布尔值。如果在使用定向控件浏览（例如使用方向键浏览列表）的情况下对象为当前用户选择时应使用此项目，则值为“true”；如果在未选择对象时应使用此项目，则值为“false”。当焦点 (android:state_focused) 不充分（例如，列表视图有焦点但使用方向键选择其中的项目）时，使用所选状态。android:state_checkable布尔值。如果当对象可选中时应使用此项目，则值为“true”；如果当对象不可选中时应使用此项目，则值为“false”。（仅当对象可在可选中与不可选中小部件之间转换时才有用。）android:state_checked布尔值。如果在对象已选中时应使用此项目，则值为“true”；如果在对象未选中时应使用此项目，则值为“false”。android:state_enabled布尔值。如果在对象启用（能够接收触摸/点击事件）时应使用此项目，则值为“true”；如果在对象停用时应使用此项目，则值为“false”。android:state_activated布尔值。如果在对象激活作为持续选择（例如，在持续导航视图中“突出显示”之前选中的列表项）时应使用此项目，则值为“true”；如果在对象未激活时应使用此项目，则值为“false”。此项为 API 级别 11 新引入的配置。android:state_window_focused布尔值。如果当应用窗口有焦点（应用在前台）时应使用此项目，则值为“true”；如果当应用窗口没有焦点（例如，通知栏下拉或对话框出现）时应使用此项目，则值为“false”。

  • 示例：

    XML 文件保存在 res/drawable/button.xml 中：

    <?xml version="1.0" encoding="utf-8"?>
<selector xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:state_pressed="true"
          android:drawable="@drawable/button_pressed" /> <!-- pressed -->
    <item android:state_focused="true"
          android:drawable="@drawable/button_focused" /> <!-- focused -->
    <item android:state_hovered="true"
          android:drawable="@drawable/button_focused" /> <!-- hovered -->
    <item android:drawable="@drawable/button_normal" /> <!-- default -->
</selector>

    此布局 XML 将状态列表可绘制对象应用到按钮：

    <Button
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:background="@drawable/button" />

  • 另请参阅：

    StateListDrawable

级别列表

管理大量备选可绘制对象的可绘制对象，每个可绘制对象都配有最大备选数量。若使用 setLevel() 设置可绘制对象的级别值，则会加载级别列表中 android:maxLevel 值大于或等于传递至方法的值的可绘制对象资源。

  • 文件位置：

    res/drawable/*filename*.xml 文件名用作资源 ID。

  • 编译资源的数据类型：

    指向 LevelListDrawable 的资源指针。

  • 资源引用：

    在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable/*filename*

  • 语法：

    <?xml version="1.0" encoding="utf-8"?>
<level-list
    xmlns:android="http://schemas.android.com/apk/res/android" >
    <item
        android:drawable="@drawable/drawable_resource"
        android:maxLevel="integer"
        android:minLevel="integer" />
</level-list>

  • 元素：

    这必须是根元素。包含一个或多个 <item> 元素。

    属性：

    • xmlns:android

      字符串。必备。定义 XML 命名空间，其必须是 "http://schemas.android.com/apk/res/android"。

    定义要在某特定级别使用的可绘制对象。

    属性：

    • android:drawable

      可绘制对象资源。必备。引用要插入的可绘制对象资源。

    • android:maxLevel

      整型。此项目允许的最高级别。

    • android:minLevel

      整型。此项目允许的最低级别。

  • 示例：

    <?xml version="1.0" encoding="utf-8"?>
<level-list xmlns:android="http://schemas.android.com/apk/res/android" >
    <item
        android:drawable="@drawable/status_off"
        android:maxLevel="0" />
    <item
        android:drawable="@drawable/status_on"
        android:maxLevel="1" />
</level-list>

    在将此项目应用到 View 后，您便可通过 setLevel() 或 setImageLevel() 更改级别。

  • 另请参阅：

    LevelListDrawable

转换可绘制对象

TransitionDrawable 是可在两种可绘制对象资源之间交错淡出的可绘制对象。

每个可绘制对象由单个 <transition> 元素内的 <item> 元素表示。不支持超过两个项目。如要向前转换，请调用 startTransition()。如要向后转换，则调用 reverseTransition()。

  • 文件位置：

    res/drawable/*filename*.xml 文件名用作资源 ID。

  • 编译资源的数据类型：

    指向 TransitionDrawable 的资源指针。

  • 资源引用：

    在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable/*filename*

  • 语法：

    <?xml version="1.0" encoding="utf-8"?>
<transition
xmlns:android="http://schemas.android.com/apk/res/android" >
    <item
        android:drawable="@[package:]drawable/drawable_resource"
        android:id="@[+][package:]id/resource_name"
        android:top="dimension"
        android:right="dimension"
        android:bottom="dimension"
        android:left="dimension" />
</transition>

  • 元素：

    元素：

    • <transition>

      必备。这必须是根元素。包含一个或多个 <item> 元素。属性：xmlns:android字符串。必备。定义 XML 命名空间，其必须是 "http://schemas.android.com/apk/res/android"。

    • <item>

      定义要用作可绘制对象转换一部分的可绘制对象。必须是 <transition> 元素的子项。接受子 <bitmap> 元素。属性：android:drawable可绘制对象资源。必备。引用可绘制对象资源。android:id资源 ID。此可绘制对象的唯一资源 ID。要为此项新建资源 ID，请使用以下形式："@+id/*name*"。加号表示应创建为新 ID。您可以使用此 ID 检索和修改拥有 View.findViewById() 或 Activity.findViewById() 的可绘制对象。android:top整型。顶部偏移（像素）。android:right整型。右边偏移（像素）。android:bottom整型。底部偏移（像素）。android:left整型。左边偏移（像素）。

  • 示例：

    XML 文件保存在 res/drawable/transition.xml 中：

    <?xml version="1.0" encoding="utf-8"?>
<transition xmlns:android="http://schemas.android.com/apk/res/android">
    <item android:drawable="@drawable/on" />
    <item android:drawable="@drawable/off" />
</transition>

    此布局 XML 会将可绘制对象应用到视图：

    <ImageButton
    android:id="@+id/button"
    android:layout_height="wrap_content"
    android:layout_width="wrap_content"
    android:src="@drawable/transition" />

    以下代码会执行从第一个项目到第二个项目的 500ms 转换：

    KOTLINJAVA

    val button: ImageButton = findViewById(R.id.button)val drawable: Drawable = button.drawableif (drawable is TransitionDrawable) {  drawable.startTransition(500)}

  • 另请参阅：

    TransitionDrawable

插入可绘制对象

在 XML 文件中定义，以指定距离插入其他可绘制对象的可绘制对象。当视图需要小于视图实际边界的背景时，此类可绘制对象很有用。

  • 文件位置：

    res/drawable/*filename*.xml 文件名用作资源 ID。

  • 编译资源的数据类型：

    指向 InsetDrawable 的资源指针。

  • 资源引用：

    在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable/*filename*

  • 语法：

    <?xml version="1.0" encoding="utf-8"?>
<inset
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:drawable="@drawable/drawable_resource"
    android:insetTop="dimension"
    android:insetRight="dimension"
    android:insetBottom="dimension"
    android:insetLeft="dimension" />

  • 元素：

    • <inset>

      定义插入可绘制对象。这必须是根元素。属性：xmlns:android字符串。必备。定义 XML 命名空间，其必须是 "http://schemas.android.com/apk/res/android"。android:drawable可绘制对象资源。必备。引用要插入的可绘制对象资源。android:insetTop尺寸。顶部插入，表示为尺寸值或尺寸资源android:insetRight尺寸。右边插入，表示为尺寸值或尺寸资源android:insetBottom尺寸。底部插入，表示为尺寸值或尺寸资源android:insetLeft尺寸。左边插入，表示为尺寸值或尺寸资源

    示例：

  • <?xml version="1.0" encoding="utf-8"?>
<inset xmlns:android="http://schemas.android.com/apk/res/android"
    android:drawable="@drawable/background"
    android:insetTop="10dp"
    android:insetLeft="10dp" />

  • 另请参阅：

    InsetDrawable

裁剪可绘制对象

在 XML 文件中定义，对其他可绘制对象进行裁剪（根据其当前级别）的可绘制对象。您可以根据级别以及用于控制其在整个容器中位置的重力，来控制子可绘制对象的裁剪宽度和高度。通常用于实现进度栏之类的项目。

  • 文件位置：

    res/drawable/*filename*.xml 文件名用作资源 ID。

  • 编译资源的数据类型：

    指向 ClipDrawable 的资源指针。

  • 资源引用：

    在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable/*filename*

  • 语法：

    <?xml version="1.0" encoding="utf-8"?>
<clip
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:drawable="@drawable/drawable_resource"
    android:clipOrientation=["horizontal" | "vertical"]
    android:gravity=["top" | "bottom" | "left" | "right" | "center_vertical" |
                     "fill_vertical" | "center_horizontal" | "fill_horizontal" |
                     "center" | "fill" | "clip_vertical" | "clip_horizontal"] />

  • 元素：

    • <clip>

      定义裁剪可绘制对象。这必须是根元素。属性：xmlns:android字符串。必备。定义 XML 命名空间，其必须是 "http://schemas.android.com/apk/res/android"。android:drawable可绘制对象资源。必备。引用要裁剪的可绘制对象资源。android:clipOrientation关键字。裁剪方向。必须是以下常量值之一：值说明horizontal水平裁剪可绘制对象。vertical垂直裁剪可绘制对象。android:gravity关键字。指定可绘制对象中要裁剪的位置。必须是以下一个或多个（用 '|' 分隔）常量值：值说明top将对象放在其容器顶部，不改变其大小。当 clipOrientation 是 "vertical" 时，在可绘制对象的底部裁剪。bottom将对象放在其容器底部，不改变其大小。当 clipOrientation 是 "vertical" 时，在可绘制对象的顶部裁剪。left将对象放在其容器左边缘，不改变其大小。这是默认值。当 clipOrientation 是 "horizontal" 时，在可绘制对象的右边裁剪。这是默认值。right将对象放在其容器右边缘，不改变其大小。当 clipOrientation 是 "horizontal" 时，在可绘制对象的左边裁剪。center_vertical将对象放在其容器的垂直中心，不改变其大小。裁剪行为与重力为 "center" 时相同。fill_vertical按需要扩展对象的垂直大小，使其完全适应其容器。当 clipOrientation 是 "vertical" 时，不会进行裁剪，因为可绘制对象会填充垂直空间（除非可绘制对象级别为 0，此时它不可见）。center_horizontal将对象放在其容器的水平中心，不改变其大小。裁剪行为与重力为 "center" 时相同。fill_horizontal按需要扩展对象的水平大小，使其完全适应其容器。当 clipOrientation 是 "horizontal" 时，不会进行裁剪，因为可绘制对象会填充水平空间（除非可绘制对象级别为 0，此时它不可见）。center将对象放在其容器的水平和垂直轴中心，不改变其大小。当 clipOrientation 是 "horizontal" 时，在左边和右边裁剪。当 clipOrientation 是 "vertical" 时，在顶部和底部裁剪。fill按需要扩展对象的垂直大小，使其完全适应其容器。不会进行裁剪，因为可绘制对象会填充水平和垂直空间（除非可绘制对象级别为 0，此时它不可见）。clip_vertical可设置为让子元素的上边缘和/或下边缘裁剪至其容器边界的附加选项。裁剪基于垂直重力：顶部重力裁剪上边缘，底部重力裁剪下边缘，任一重力不会同时裁剪两边。clip_horizontal可设置为让子元素的左边和/或右边裁剪至其容器边界的附加选项。裁剪基于水平重力：左边重力裁剪右边缘，右边重力裁剪左边缘，任一重力不会同时裁剪两边。

    示例：

    XML 文件保存在 res/drawable/clip.xml 中：

    <?xml version="1.0" encoding="utf-8"?>
<clip xmlns:android="http://schemas.android.com/apk/res/android"
    android:drawable="@drawable/android"
    android:clipOrientation="horizontal"
    android:gravity="left" />

    以下布局 XML 会将裁剪可绘制对象应用到视图：

    <ImageView
    android:id="@+id/image"
    android:background="@drawable/clip"
    android:layout_height="wrap_content"
    android:layout_width="wrap_content" />

    以下代码用于获取可绘制对象，并增加裁剪量，以便逐渐显示图像：

    KOTLINJAVA

    val imageview: ImageView = findViewById(R.id.image)
val drawable: Drawable = imageview.background
if (drawable is ClipDrawable) {
    drawable.level = drawable.level + 1000
}

    通过提高级别，即可减少裁剪量并慢慢显示图像。以下图像的级别为 7000：

    img

  • 另请参阅：

    ClipDrawable

  • 缩放可绘制对象

    在 XML 文件中定义的更改其他可绘制对象大小（根据其当前级别）的可绘制对象。

    • 文件位置：

      res/drawable/*filename*.xml 文件名用作资源 ID。

    • 编译资源的数据类型：

      指向 ScaleDrawable 的资源指针。

    • 资源引用：

      在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable/*filename*

    • 语法：

      <?xml version="1.0" encoding="utf-8"?><scale xmlns:android="http://schemas.android.com/apk/res/android" android:drawable="@drawable/*drawable_resource*" android:scaleGravity=["top" | "bottom" | "left" | "right" | "center_vertical" | "fill_vertical" | "center_horizontal" | "fill_horizontal" | "center" | "fill" | "clip_vertical" | "clip_horizontal"] android:scaleHeight="*percentage*" android:scaleWidth="*percentage*" />

    • 元素：

      <scale>定义缩放可绘制对象。这必须是根元素。属性：xmlns:android字符串。必备。定义 XML 命名空间，其必须是 "http://schemas.android.com/apk/res/android"。android:drawable可绘制对象资源。必备。引用可绘制对象资源。android:scaleGravity关键字。指定缩放后的重力位置。必须是以下一个或多个（用 '|' 分隔）常量值：值说明top将对象放在其容器顶部，不改变其大小。bottom将对象放在其容器底部，不改变其大小。left将对象放在其容器左边缘，不改变其大小。这是默认值。right将对象放在其容器右边缘，不改变其大小。center_vertical将对象放在其容器的垂直中心，不改变其大小。fill_vertical按需要扩展对象的垂直大小，使其完全适应其容器。center_horizontal将对象放在其容器的水平中心，不改变其大小。fill_horizontal按需要扩展对象的水平大小，使其完全适应其容器。center将对象放在其容器的水平和垂直轴中心，不改变其大小。fill按需要扩展对象的垂直大小，使其完全适应其容器。clip_vertical可设置为让子元素的上边缘和/或下边缘裁剪至其容器边界的附加选项。裁剪基于垂直重力：顶部重力裁剪上边缘，底部重力裁剪下边缘，任一重力不会同时裁剪两边。clip_horizontal可设置为让子元素的左边和/或右边裁剪至其容器边界的附加选项。裁剪基于水平重力：左边重力裁剪右边缘，右边重力裁剪左边缘，任一重力不会同时裁剪两边。android:scaleHeight百分比。缩放高度，表示为可绘制对象边界的百分比。值的格式为 XX%。例如：100%、12.5% 等。android:scaleWidth百分比。缩放宽度，表示为可绘制对象边界的百分比。值的格式为 XX%。例如：100%、12.5% 等。

    • 示例：

      <?xml version="1.0" encoding="utf-8"?><scale xmlns:android="http://schemas.android.com/apk/res/android" android:drawable="@drawable/logo" android:scaleGravity="center_vertical|center_horizontal" android:scaleHeight="80%" android:scaleWidth="80%" />

    • 另请参阅：

      ScaleDrawable

    形状可绘制对象

    这是一种在 XML 文件中定义的通用形状。

    • 文件位置：

      res/drawable/*filename*.xml 文件名用作资源 ID。

    • 编译资源的数据类型：

      指向 GradientDrawable 的资源指针。

    • 资源引用：

      在 Java 中：R.drawable.*filename* 在 XML 中：@[*package*:]drawable/*filename*

    • 语法：

      <?xml version="1.0" encoding="utf-8"?>
<shape
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape=["rectangle" | "oval" | "line" | "ring"] >
    <corners
        android:radius="integer"
        android:topLeftRadius="integer"
        android:topRightRadius="integer"
        android:bottomLeftRadius="integer"
        android:bottomRightRadius="integer" />
    <gradient
        android:angle="integer"
        android:centerX="float"
        android:centerY="float"
        android:centerColor="integer"
        android:endColor="color"
        android:gradientRadius="integer"
        android:startColor="color"
        android:type=["linear" | "radial" | "sweep"]
        android:useLevel=["true" | "false"] />
    <padding
        android:left="integer"
        android:top="integer"
        android:right="integer"
        android:bottom="integer" />
    <size
        android:width="integer"
        android:height="integer" />
    <solid
        android:color="color" />
    <stroke
        android:width="integer"
        android:color="color"
        android:dashWidth="integer"
        android:dashGap="integer" />
</shape>

  • 元素：

    • <shape>

      形状可绘制对象。这必须是根元素。属性：xmlns:android字符串。必备。定义 XML 命名空间，其必须是 "http://schemas.android.com/apk/res/android"。android:shape关键字。定义形状的类型。有效值为：值描述"rectangle"填充包含视图的矩形。这是默认形状。"oval"适应包含视图尺寸的椭圆形状。"line"跨越包含视图宽度的水平线。此形状需要 <stroke> 元素定义线宽。"ring"环形。仅当 android:shape="ring" 如下时才使用以下属性：android:innerRadius尺寸。环内部（中间的孔）的半径，以尺寸值或尺寸资源表示。android:innerRadiusRatio浮点型。环内部的半径，以环宽度的比率表示。例如，如果 android:innerRadiusRatio="5"，则内半径等于环宽度除以 5。此值被 android:innerRadius 覆盖。默认值为 9。android:thickness尺寸。环的厚度，以尺寸值或尺寸资源表示。android:thicknessRatio浮点型。环的厚度，表示为环宽度的比率。例如，如果 android:thicknessRatio="2"，则厚度等于环宽度除以 2。此值被 android:innerRadius 覆盖。默认值为 3。android:useLevel布尔值。如果此属性用作 LevelListDrawable，则值为“true”。此属性的值通常应为“false”，否则无法显示形状。

    • <corners>

      为形状产生圆角。仅当形状为矩形时适用。属性：android:radius尺寸。所有角的半径，以尺寸值或尺寸资源表示。对于每个角，这会被以下属性覆盖。android:topLeftRadius尺寸。左上角的半径，以尺寸值或尺寸资源表示。android:topRightRadius尺寸。右上角的半径，以尺寸值或尺寸资源表示。android:bottomLeftRadius尺寸。左下角的半径，以尺寸值或尺寸资源表示。android:bottomRightRadius尺寸。右下角的半径，以尺寸值或尺寸资源表示。注：（最初）必须为每个角提供大于 1 的角半径，否则无法产生圆角。如果希望特定角不要倒圆角，解决方法是使用 android:radius 设置大于 1 的默认角半径，然后使用实际所需的值替换每个角，为不希望倒圆角的角提供零（“0dp”）。

    • <gradient>

      指定形状的渐变颜色。属性：android:angle整型。渐变的角度（度）。0 为从左到右，90 为从上到上。必须是 45 的倍数。默认值为 0。android:centerX浮点型。渐变中心的相对 X 轴位置 (0 - 1.0)。android:centerY浮点型。渐变中心的相对 Y 轴位置 (0 - 1.0)。android:centerColor颜色。起始颜色与结束颜色之间的可选颜色，以十六进制值或颜色资源表示。android:endColor颜色。结束颜色，表示为十六进制值或颜色资源。android:gradientRadius浮点型。渐变的半径。仅在 android:type="radial" 时适用。android:startColor颜色。起始颜色，表示为十六进制值或颜色资源。android:type关键字。要应用的渐变图案的类型。有效值为：值说明"linear"线性渐变。这是默认值。"radial"径向渐变。起始颜色为中心颜色。"sweep"流线型渐变。android:useLevel布尔值。如果此属性用作 LevelListDrawable，则值为“true”。

    • <padding>

      要应用到包含视图元素的内边距（这会填充视图内容的位置，而非形状）。属性：android:left尺寸。左内边距，表示为尺寸值或尺寸资源android:top尺寸。上内边距，表示为尺寸值或尺寸资源android:right尺寸。右内边距，表示为尺寸值或尺寸资源android:bottom尺寸。下内边距，表示为尺寸值或尺寸资源

    • <size>

      形状的大小。属性：android:height尺寸。形状的高度，表示为尺寸值或尺寸资源android:width尺寸。形状的宽度，表示为尺寸值或尺寸资源注：默认情况下，形状根据此处定义的尺寸，按比例缩放至容器视图的大小。在 ImageView 中使用形状时，您可将 android:scaleType 设置为 "center"，从而限制缩放。

    • <solid>

      用于填充形状的纯色。属性：android:color颜色。应用于形状的颜色，以十六进制值或颜色资源表示。

    • <stroke>

      形状的笔划中线。属性：android:width尺寸。线宽，以尺寸值或尺寸资源表示。android:color颜色。线的颜色，表示为十六进制值或颜色资源。android:dashGap尺寸。短划线的间距，以尺寸值或尺寸资源表示。仅在设置了 android:dashWidth 时有效。android:dashWidth尺寸。每个短划线的大小，以尺寸值或尺寸资源表示。仅在设置了 android:dashGap 时有效。

    示例：

    XML 文件保存在 res/drawable/gradient_box.xml 中：

    <?xml version="1.0" encoding="utf-8"?>
<shape xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape="rectangle">
    <gradient
        android:startColor="#FFFF0000"
        android:endColor="#80FF00FF"
        android:angle="45"/>
    <padding android:left="7dp"
        android:top="7dp"
        android:right="7dp"
        android:bottom="7dp" />
    <corners android:radius="8dp" />
</shape>

    此布局 XML 会将形状可绘制对象应用到视图：

    <TextView
    android:background="@drawable/gradient_box"
    android:layout_height="wrap_content"
    android:layout_width="wrap_content" />

    此应用代码会获取形状可绘制对象，并将其应用至视图：

    KOTLINJAVA

    val shape: Drawable? = getDrawable(resources, R.drawable.gradient_box, getTheme())val tv: TextView = findViewById(R.id.textview)tv.background = shape

  • 另请参阅：

    ShapeDrawable

布局资源

  • 布局资源定义了 Activity 中的界面或界面中的组件的架构。

    • 文件位置：

      res/layout/*filename*.xml 该文件名将用作资源 ID。

    • 编译后的资源数据类型：

      指向 View（或子类）资源的资源指针。

    • 资源引用：

      在 Java 中：R.layout.*filename* 在 XML 中：@[*package*:]layout/*filename*

    • 语法：

      <?xml version="1.0" encoding="utf-8"?>  <***ViewGroup***    xmlns:android="http://schemas.android.com/apk/res/android"    android:id="@[+][*package*:]id/*resource_name*"    android:layout_height=["*dimension*" | "match_parent" | "wrap_content"]    android:layout_width=["*dimension*" | "match_parent" | "wrap_content"]    [*ViewGroup-specific attributes*] >    <***View***      android:id="@[+][*package*:]id/*resource_name*"      android:layout_height=["*dimension*" | "match_parent" | "wrap_content"]      android:layout_width=["*dimension*" | "match_parent" | "wrap_content"]      [*View-specific attributes*] >      <requestFocus/>    </*View*>    <***ViewGroup*** >      <***View*** />    </*ViewGroup*>    <include layout="@layout/*layout_resource*"/>

      </ViewGroup> **注意**：根元素可以是 ViewGroup、View或 [``](https://developer.android.com/guide/topics/resources/layout-resource#merge-element) 元素，但只能有一个根元素，并且它必须包含带有android命名空间的xmlns:android` 属性，如上所示。

    • 元素：

      • <ViewGroup>

        其他 View 元素的容器。ViewGroup 对象有许多种类型，每一种都支持您以不同的方式指定子元素的布局。不同类型的 ViewGroup 对象包括 LinearLayout、RelativeLayout 和 FrameLayout。您不应假设 ViewGroup 的任何派生对象都接受嵌套的 View。有些 ViewGroup 是 AdapterView 类的实现，该类仅从 Adapter 确定其子项。属性：android:id资源 ID。元素的唯一资源名称，可用于从应用中获取对 ViewGroup 的引用。要详细了解 android:id 的值，请参见下文。android:layout_height尺寸或关键字。必需。组的高度，采用尺寸值（或尺寸资源）或关键字（"match_parent" 或 "wrap_content"）的形式。请参阅下面的有效值。android:layout_width尺寸或关键字。必需。组的宽度，采用尺寸值（或尺寸资源）或关键字（"match_parent" 或 "wrap_content"）的形式。请参阅下面的有效值。ViewGroup 基类支持更多属性，而且 的每个实现又另外支持很多属性。有关所有可用属性的参考信息，请参阅 ViewGroup 类的对应参考文档（例如，LinearLayout XML 属性）。

      • <View>

        单个界面组件，通常称为“微件”。不同类型的 View 对象包括 TextView、Button 和 CheckBox。属性：android:id资源 ID。元素的唯一资源名称，可用于从应用中获取对 View 的引用。要详细了解 android:id 的值，请参见下文。android:layout_height尺寸或关键字。必需。元素的高度，采用尺寸值（或尺寸资源）或关键字（"match_parent" 或 "wrap_content"）的形式。请参阅下面的有效值。android:layout_width尺寸或关键字。必需。元素的宽度，采用尺寸值（或尺寸资源）或关键字（"match_parent" 或 "wrap_content"）的形式。请参阅下面的有效值。View 基类支持更多属性，而且 的每个实现又另外支持很多属性。如需了解详情，请参阅布局。有关所有可用属性的参考信息，请参阅对应的参考文档（例如，TextView XML 属性）。

      • <requestFocus>

        任何代表 View 对象的元素都可以包含这个空元素，它会在屏幕上为其父项提供初始焦点。每个文件只能包含一个这种元素。

      • <include>

        在此布局中包含一个布局文件。属性：layout布局资源。必需。对布局资源的引用。android:id资源 ID。替换提供给所含布局中的根视图的 ID。android:layout_height尺寸或关键字。替换提供给所含布局中的根视图的高度。仅在同时也声明了 android:layout_width 时才有效。android:layout_width尺寸或关键字。替换提供给所含布局中的根视图的宽度。仅在同时也声明了 android:layout_height 时才有效。您可以在 <include> 中添加所含布局中的根元素所支持的任何其他布局属性，它们将替换根元素中定义的相应属性。注意：如果要使用 <include> 标记来替换布局属性，您必须同时替换 android:layout_height 和 android:layout_width 才能让其他布局属性生效。添加布局的另一种方式是使用 ViewStub。这是一个轻型视图，在对其进行明确膨胀（此时它会添加由其 android:layout 属性定义的布局文件）之前，它不会占用任何布局空间。如需详细了解如何使用 ViewStub，请参阅按需加载视图。

      • <merge>

        未在布局层次结构中绘制的替代根元素。如果您知道此布局将被放置到一个已包含相应父视图的布局中，以包含 <merge> 元素的子项，则将此元素用作根元素会非常有用。当您打算使用 `` 将此布局添加到另一个布局文件中，并且此布局不需要不同的 ViewGroup 容器时，这样做尤其有用。如需详细了解如何合并布局，请参阅通过 重新使用布局。

      android:id 的值

      对于 ID 值，通常应该使用这种语法形式："@+id/*name*"。加号 + 表示这是一个新的资源 ID，如果不存在，aapt 工具会在 R.java 类中创建一个新的资源整数。例如：

          <TextView android:id="@+id/nameTextbox"/>

      nameTextbox 名称现在是附加到此元素的资源 ID。然后，您就可以在 Java 中引用与此 ID 关联的 TextView：

      KOTLINJAVA

          val textView: TextView? = findViewById(R.id.nameTextbox)

      此代码会返回 TextView 对象。

      但是，如果您已经定义了一个 ID 资源并且尚未使用它，则可以通过去掉 android:id 值中的加号，将该 ID 应用到 View 元素。

      android:layout_height 和 android:layout_width 的值：

      高度和宽度值可使用 Android 支持的任意尺寸单位（px、dp、sp、pt、in、mm）或以下关键字来表示：

      值 说明
      match_parent 将尺寸设为与父元素的尺寸一致。在 API 级别 8 中引入以替代 fill_parent。
      wrap_content 将尺寸设为适配此元素的内容所需的大小。

      自定义 View 元素

      您可以创建自己的自定义 View 和 ViewGroup 元素，并将它们应用到您的布局，就像应用标准布局元素一样。您还可以指定 XML 元素中支持的属性。要了解详情，请参阅自定义组件开发者指南。

  • 示例：

    保存在 res/layout/main_activity.xml 的 XML 文件：

        <?xml version="1.0" encoding="utf-8"?>
    <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
                  android:layout_width="match_parent"
                  android:layout_height="match_parent"
                  android:orientation="vertical" >
        <TextView android:id="@+id/text"
                  android:layout_width="wrap_content"
                  android:layout_height="wrap_content"
                  android:text="Hello, I am a TextView" />
        <Button android:id="@+id/button"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:text="Hello, I am a Button" />
    </LinearLayout>

    此应用代码会在 onCreate() 方法中加载 Activity 的布局：

    KOTLINJAVA public override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.main_activity) }

  • 另请参阅：

    布局

菜单资源

菜单资源定义可通过 MenuInflater 进行扩充的应用菜单，包括选项菜单、上下文菜单和子菜单。

有关使用菜单的指南，请参阅菜单开发者指南。

  • 文件位置：

    res/menu/*filename*.xml 该文件名将用作资源 ID。

  • 编译后的资源数据类型：

    指向 Menu（或其子类）资源的资源指针。

  • 资源引用：

    在 Java 中：R.menu.*filename* 在 XML 中：@[*package*:]menu.*filename*

  • 语法：

  •     <?xml version="1.0" encoding="utf-8"?>
    <menu xmlns:android="http://schemas.android.com/apk/res/android">
        <item android:id="@[+][package:]id/resource_name"
              android:title="string"
              android:titleCondensed="string"
              android:icon="@[package:]drawable/drawable_resource_name"
              android:onClick="method name"
              android:showAsAction=["ifRoom" | "never" | "withText" | "always" | "collapseActionView"]
              android:actionLayout="@[package:]layout/layout_resource_name"
              android:actionViewClass="class name"
              android:actionProviderClass="class name"
              android:alphabeticShortcut="string"
              android:alphabeticModifiers=["META" | "CTRL" | "ALT" | "SHIFT" | "SYM" | "FUNCTION"]
              android:numericShortcut="string"
              android:numericModifiers=["META" | "CTRL" | "ALT" | "SHIFT" | "SYM" | "FUNCTION"]
              android:checkable=["true" | "false"]
              android:visible=["true" | "false"]
              android:enabled=["true" | "false"]
              android:menuCategory=["container" | "system" | "secondary" | "alternative"]
              android:orderInCategory="integer" />
        <group android:id="@[+][package:]id/resource name"
               android:checkableBehavior=["none" | "all" | "single"]
               android:visible=["true" | "false"]
               android:enabled=["true" | "false"]
               android:menuCategory=["container" | "system" | "secondary" | "alternative"]
               android:orderInCategory="integer" >
            <item />
        </group>
        <item >
            <menu>
              <item />
            </menu>
        </item>
    </menu>

    元素：

    • <menu>

      必需。该元素必须是根节点。包含 <item> 和/或 <group> 元素。属性：xmlns:androidXML 命名空间。必需。定义 XML 命名空间，该命名空间必须为 "http://schemas.android.com/apk/res/android"。

    • <item>

      菜单项。可能包含 <menu> 元素（用于子菜单）。必须是 <menu> 或 <group> 元素的子元素。属性：android:id资源 ID。唯一资源 ID。要为此项创建新的资源 ID，请使用以下形式："@+id/*name*"。加号表示应将其创建为新 ID。android:title字符串资源。字符串资源或原始字符串形式的菜单标题。android:titleCondensed字符串资源。字符串资源或原始字符串形式的压缩标题。此标题在正常标题过长的情况下使用。android:icon可绘制资源。用作菜单项图标的图片。android:onClick方法名称。点击此菜单项时调用的方法。此方法必须在 Activity 中声明为公共方法，并接受 MenuItem 作为其唯一参数，该参数指示所点击的项。此方法优先于对 onOptionsItemSelected() 的标准回调。请参见页面结尾处的示例。警告：如果您使用 ProGuard（或类似工具）混淆代码，切记不要重命名在此属性中指定的方法，因为这样会破坏功能。在 API 级别 11 中引入。android:showAsAction关键字。指示此项应在应用栏中显示为操作项的时机和方式。菜单项只有在 Activity 包含应用栏时才能显示为操作项。有效值：值说明ifRoom只有在应用栏中有空间的情况下，才将此项放置其中。如果没有足够的空间来容纳标记为 "ifRoom" 的所有项，则 orderInCategory 值最低的项会显示为操作，其余项将显示在溢出菜单中。withText此外，还会随操作项添加标题文本（由 android:title 定义）。您可以将此值与某个其他值一起作为标记集添加，用竖线 | 分隔。never不得将此项放在应用栏中，而应将其列在应用栏的溢出菜单中。always始终将此项放在应用栏中。除非此项必须始终显示在操作栏中，否则请勿使用该值。将多个项设置为始终显示为操作项，会导致它们与应用栏中的其他界面重叠。collapseActionView与此操作项相关联的操作视图（由 android:actionLayout 或 android:actionViewClass 声明）是可收起的。 在 API 级别 14 中引入。如需了解详情，请参阅添加应用栏培训课程。在 API 级别 11 中引入。android:actionLayout布局资源。用作操作视图的布局。如需了解详情，请参阅操作视图和操作提供器。在 API 级别 11 中引入。android:actionViewClass类名称。要用作操作视图的 View 的完全限定类名称。例如，"android.widget.SearchView" 表示将使用 SearchView 作为操作视图。如需了解详情，请参阅操作视图和操作提供器。警告：如果您使用 ProGuard（或类似工具）混淆代码，切记不要重命名在此属性中指定的类，因为这样会破坏功能。在 API 级别 11 中引入。android:actionProviderClass类名称。要用于代替操作项的 ActionProvider 的完全限定类名称。例如，"android.widget.ShareActionProvider" 表示将使用 ShareActionProvider。如需了解详情，请参阅操作视图和操作提供器。警告：如果您使用 ProGuard（或类似工具）混淆代码，切记不要重命名在此属性中指定的类，因为这样会破坏功能。在 API 级别 14 中引入。android:alphabeticShortcut字符。字母快捷键的字符。android:numericShortcut整数。数字快捷键的数字。android:alphabeticModifiers关键字。菜单项的字母快捷键的辅助键。默认值对应于 Control 键。有效值：值说明META对应于 Meta 元键CTRL对应于 Control 元键ALT对应于 Alt 元键SHIFT对应于 Shift 元键SYM对应于 Sym 元键FUNCTION对应于 Function 元键注意：您可以在一个属性中指定多个关键字。例如，android:alphabeticModifiers="CTRL|SHIFT" 表示要触发相应的菜单项，用户需要同时按下 Control 和 Shift 元键以及快捷键。您可以使用 setAlphabeticShortcut() 方法以编程方式设置属性值。要详细了解 alphabeticModifier 属性，请转到 alphabeticModifiers。android:numericModifiers关键字。菜单项的数字快捷键的辅助键。 默认值对应于 Control 键。有效值：值说明META对应于 Meta 元键CTRL对应于 Control 元键ALT对应于 Alt 元键SHIFT对应于 Shift 元键SYM对应于 Sym 元键FUNCTION对应于 Function 元键注意：您可以在一个属性中指定多个关键字。例如，android:numericModifiers="CTRL|SHIFT" 表示要触发相应的菜单项，用户需要同时按下 Control 和 Shift 元键以及快捷键。您可以使用 setNumericShortcut() 方法以编程方式设置属性值。要详细了解 numericModifier 属性，请转到 numericModifiers。android:checkable布尔值。如果该项可勾选，则为“true”。android:checked布尔值。如果默认情况下该项为勾选状态，则为“true”。android:visible布尔值。如果默认情况下该项可见，则为“true”。android:enabled布尔值。如果默认情况下该项为启用状态，则为“true”。android:menuCategory关键字。对应于 Menu CATEGORY_* 常量的值，这些常量用于定义项的优先级。有效值：值说明container这类项归属于容器。system这类项由系统提供。secondary这类项是用户提供的次要（不常用）选项。alternative这类项是对当前显示的数据的替代操作。android:orderInCategory整数。项在组内的“重要性”顺序。

    • <group>

      一个菜单组，用于创建一组具有相同特征（例如是否可见、是否启用或是否可勾选）的项。包含一个或多个 <item> 元素。必须是 <menu> 元素的子元素。属性：android:id资源 ID。唯一资源 ID。要为此项创建新的资源 ID，请使用以下形式："@+id/*name*"。加号表示应将其创建为新 ID。android:checkableBehavior关键字。组的可勾选行为类型。有效值：值说明none不可勾选all可以勾选所有项（使用复选框）single只能勾选一项（使用单选按钮）android:visible布尔值。如果组可见，则为“true”。android:enabled布尔值。如果组为启用状态，则为“true”。android:menuCategory关键字。对应于 Menu CATEGORY_* 常量的值，这些常量用于定义组的优先级。有效值：值说明container这类组归属于容器。system这类组由系统提供。secondary这类组是用户提供的次要（不常用）选项。alternative这类组是对当前显示的数据的替代操作。android:orderInCategory整数。项在类别中的默认顺序。

示例：

保存在 res/menu/example_menu.xml 的 XML 文件：

    <menu xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:app="http://schemas.android.com/apk/res-auto">
        <item android:id="@+id/item1"
              android:title="@string/item1"
              android:icon="@drawable/group_item1_icon"
              app:showAsAction="ifRoom|withText"/>
        <group android:id="@+id/group">
            <item android:id="@+id/group_item1"
                  android:onClick="onGroupItemClick"
                  android:title="@string/group_item1"
                  android:icon="@drawable/group_item1_icon" />
            <item android:id="@+id/group_item2"
                  android:onClick="onGroupItemClick"
                  android:title="@string/group_item2"
                  android:icon="@drawable/group_item2_icon" />
        </group>
        <item android:id="@+id/submenu"
              android:title="@string/submenu_title"
              app:showAsAction="ifRoom|withText" >
            <menu>
                <item android:id="@+id/submenu_item1"
                      android:title="@string/submenu_item1" />
            </menu>
        </item>
    </menu>

以下应用代码会通过 onCreateOptionsMenu(Menu) 回调扩充菜单，还会声明其中两个项的点击回调：

KOTLINJAVA

    override fun onCreateOptionsMenu(menu: Menu): Boolean {
        menuInflater.inflate(R.menu.example_menu, menu)
        return true
    }

    fun onGroupItemClick(item: MenuItem) {
        // One of the group items (using the onClick attribute) was clicked
        // The item parameter passed here indicates which item it is
        // All other menu item clicks are handled by <code><a href="/reference/android/app/Activity.html#onOptionsItemSelected(android.view.MenuItem)">onOptionsItemSelected()</a></code>
    }

字符串资源

字符串资源为您的应用提供具有可选文本样式和格式设置的文本字符串。共有三种类型的资源可为您的应用提供字符串：

所有字符串都能应用某些样式设置标记和格式设置参数。如需了解有关样式和格式设置字符串的信息，请参阅格式和样式设置部分。

String

可从应用或其他资源文件（如 XML 布局）引用的单个字符串。

请注意：字符串是一种简单资源，您可以使用 name 属性（并非 XML 文件的名称）中提供的值对其进行引用。因此，您可以在一个 <resources> 元素下，将字符串资源与其他简单资源合并到一个 XML 文件中。

  • 文件位置：

    res/values/*filename*.xml filename 是任意值。<string> 元素的 name 用作资源 ID。

  • 编译资源的数据类型：

    指向 String 的资源指针。

  • 资源引用：

    在 Java 中：R.string.*string_name* 在 XML 中：@string/*string_name*

  • 语法：

    <?xml version="1.0" encoding="utf-8"?><resources> <string name="*string_name*" >*text_string*</string></resources>

  • 元素：

    <resources>必备。此元素必须是根节点。无属性。<string>字符串，可包含样式设置标记。请注意，您必须对撇号和引号进行转义。如需了解有关如何正确设置字符串样式和格式的详细信息，请参阅下文的格式和样式设置。属性：nameString。字符串的名称。此名称用作资源 ID。

  • 示例：

    保存在 res/values/strings.xml 的 XML 文件：<?xml version="1.0" encoding="utf-8"?><resources> <string name="hello">Hello!</string></resources>该布局 XML 会对视图应用一个字符串：<TextView android:layout_width="fill_parent" android:layout_height="wrap_content" **android:text="@string/hello"** />以下应用代码用于检索字符串：KOTLINJAVAval string: String = getString(R.string.hello)您可以使用 getString(int) 或 getText(int) 检索字符串。getText(int) 会保留所有应用于字符串的富文本样式。

String Array

可从应用引用的字符串数组。

请注意：字符串数组是一种简单资源，您可以使用 name 属性（并非 XML 文件的名称）中提供的值对其进行引用。因此，您可以在一个 <resources> 元素下，将字符串数组资源与其他简单资源合并到一个 XML 文件中。

  • 文件位置：

    res/values/*filename*.xml filename 是任意值。<string-array> 元素的 name 用作资源 ID。

  • 编译资源的数据类型：

    指向 String 数组的资源指针。

  • 资源引用：

    在 Java 中：R.array.*string_array_name*

  • 语法：

    <?xml version="1.0" encoding="utf-8"?><resources> <string-array name="*string_array_name*"> <item >*text_string*</item> </string-array></resources>

  • 元素：

    <resources>必备。此元素必须是根节点。无属性。<string-array>定义一个字符串数组。包含一个或多个 <item> 元素。属性：nameString。数组的名称。此名称用作引用数组的资源 ID。<item>字符串，可包含样式设置标记。其值可以是对另一字符串资源的引用。必须为 <string-array> 元素的子项。请注意，您必须对撇号和引号进行转义。如需了解有关如何正确设置字符串样式和格式的信息，请参阅下文的格式和样式设置。无属性。

  • 示例：

    保存在 res/values/strings.xml 的 XML 文件：<?xml version="1.0" encoding="utf-8"?><resources> <string-array name="planets_array"> <item>Mercury</item> <item>Venus</item> <item>Earth</item> <item>Mars</item> </string-array></resources>以下应用代码用于检索字符串数组：KOTLINJAVAval array: Array = resources.getStringArray(R.array.planets_array)

Quantity Strings (Plurals)

针对语法数量的一致性，不同语言有不同规则。例如，在英语中，数量 1 是一种特殊情况。我们会写成“1 book”，但如果是任何其他数量，则会写成“n books”。这种对单复数的区分很常见，但其他语言拥有更细致的区分。Android 支持以下完整集合：zero、one、two、few、many 和 other。

决定为给定语言和数量使用哪种情况的规则可能非常复杂，因此 Android 为您提供 getQuantityString() 等方法来选择合适资源。

虽然 Quantity Strings 过去称作“Quantity Strings”（并且 API 中仍采用此名称），但其只应用于表示复数。例如，类似使用 Quantity Strings 实现 Gmail 的“Inbox”这类情况便属于错误行为，正确的做法是用其实现“Inbox (12)”这种存在未读邮件的情况。使用 Quantity Strings 来替代 if 语句似乎很方便，但必须注意的是，某些语言（如中文）根本不做这些语法区分，因此您获取的始终是 other 字符串。

选择使用哪一个字符串完全取决于语法上的必要性。在英语中，即使数量为 0，表示 zero 的字符串也会被忽略，因为在语法上，0 与 2 或除 1 以外的任何其他数字并无区别（“zero books”、“one book”、“two books”等）。相反，韩语中仅使用过 other 字符串。

请勿被某些事实误导，例如 two 听起来仅适用于数量 2：某种语言可能规定，对 2、12、102（依此类推）等数量进行相同处理，但对其他数量进行特殊处理。您可以依靠翻译人员来了解其语言的实际区分要求。

通常，您可以利用“Books: 1”等无需考虑数量的表示，从而避免使用 Quantity Strings。如果您的应用可接受此样式，则您和翻译人员的工作都会更轻松。

请注意：Plurals 集合是一种简单资源，您可以使用 name 属性（并非 XML 文件的名称）中提供的值对其进行引用。因此，您可以在一个 <resources> 元素下，将 plurals 资源与其他简单资源合并到一个 XML 文件中。

  • 文件位置：

    res/values/*filename*.xml filename 是任意值。<plurals> 元素的 name 用作资源 ID。

  • 资源引用：

    在 Java 中：R.plurals.*plural_name*

  • 语法：

    <?xml version="1.0" encoding="utf-8"?>
<resources>
    <string
        name="string_name"
        >text_string</string>
</resources>

  • 元素：

    • <resources>

      必备。此元素必须是根节点。无属性。

    • <string>

      字符串，可包含样式设置标记。请注意，您必须对撇号和引号进行转义。如需了解有关如何正确设置字符串样式和格式的详细信息，请参阅下文的格式和样式设置。属性：nameString。字符串的名称。此名称用作资源 ID。

    示例：

    保存在 res/values/strings.xml 的 XML 文件：

    <?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="hello">Hello!</string>
</resources>

    该布局 XML 会对视图应用一个字符串：

    <TextView  android:layout_width="fill_parent"  android:layout_height="wrap_content"  **android:text="@string/hello"** />
val string: String = getString(R.string.hello)

您可以使用 getString(int) 或 getText(int) 检索字符串。getText(int) 会保留所有应用于字符串的富文本样式。

String Array

可从应用引用的字符串数组。

请注意：字符串数组是一种简单资源，您可以使用 name 属性（并非 XML 文件的名称）中提供的值对其进行引用。因此，您可以在一个 <resources> 元素下，将字符串数组资源与其他简单资源合并到一个 XML 文件中。

  • 文件位置：

    res/values/*filename*.xml filename 是任意值。<string-array> 元素的 name 用作资源 ID。

  • 编译资源的数据类型：

    指向 String 数组的资源指针。

  • 资源引用：

    在 Java 中：R.array.*string_array_name*

  • 语法：

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array
        name="string_array_name">
        <item
            >text_string</item>
    </string-array>
</resources>

元素：

  • <resources>

    必备。此元素必须是根节点。无属性。

  • <string-array>

    定义一个字符串数组。包含一个或多个 <item> 元素。属性：nameString。数组的名称。此名称用作引用数组的资源 ID。

  • <item>

    字符串，可包含样式设置标记。其值可以是对另一字符串资源的引用。必须为 <string-array> 元素的子项。请注意，您必须对撇号和引号进行转义。如需了解有关如何正确设置字符串样式和格式的信息，请参阅下文的格式和样式设置。无属性。

示例：

保存在 res/values/strings.xml 的 XML 文件：

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string-array name="planets_array">
        <item>Mercury</item>
        <item>Venus</item>
        <item>Earth</item>
        <item>Mars</item>
    </string-array>
</resources>

以下应用代码用于检索字符串数组：

val array: Array = resources.getStringArray(R.array.planets_array)

Quantity Strings (Plurals)

针对语法数量的一致性，不同语言有不同规则。例如，在英语中，数量 1 是一种特殊情况。我们会写成“1 book”，但如果是任何其他数量，则会写成“n books”。这种对单复数的区分很常见，但其他语言拥有更细致的区分。Android 支持以下完整集合：zero、one、two、few、many 和 other。

决定为给定语言和数量使用哪种情况的规则可能非常复杂，因此 Android 为您提供 getQuantityString() 等方法来选择合适资源。

虽然 Quantity Strings 过去称作“Quantity Strings”（并且 API 中仍采用此名称），但其只应用于表示复数。例如，类似使用 Quantity Strings 实现 Gmail 的“Inbox”这类情况便属于错误行为，正确的做法是用其实现“Inbox (12)”这种存在未读邮件的情况。使用 Quantity Strings 来替代 if 语句似乎很方便，但必须注意的是，某些语言（如中文）根本不做这些语法区分，因此您获取的始终是 other 字符串。

选择使用哪一个字符串完全取决于语法上的必要性。在英语中，即使数量为 0，表示 zero 的字符串也会被忽略，因为在语法上，0 与 2 或除 1 以外的任何其他数字并无区别（“zero books”、“one book”、“two books”等）。相反，韩语中仅使用过 other 字符串。

请勿被某些事实误导，例如 two 听起来仅适用于数量 2：某种语言可能规定，对 2、12、102（依此类推）等数量进行相同处理，但对其他数量进行特殊处理。您可以依靠翻译人员来了解其语言的实际区分要求。

通常，您可以利用“Books: 1”等无需考虑数量的表示，从而避免使用 Quantity Strings。如果您的应用可接受此样式，则您和翻译人员的工作都会更轻松。

请注意：Plurals 集合是一种简单资源，您可以使用 name 属性（并非 XML 文件的名称）中提供的值对其进行引用。因此，您可以在一个 <resources> 元素下，将 plurals 资源与其他简单资源合并到一个 XML 文件中。

  • 文件位置：

    res/values/*filename*.xml filename 是任意值。<plurals> 元素的 name 用作资源 ID。

  • 资源引用：

    在 Java 中：R.plurals.*plural_name*

  • 语法：

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <plurals
        name="plural_name">
        <item
            quantity=["zero" | "one" | "two" | "few" | "many" | "other"]
            >text_string</item>
    </plurals>
</resources>

元素：

  • <resources>

    必备。此元素必须是根节点。无属性。

  • <plurals>

    字符串集合，根据事物数量提供其中的一个字符串。包含一个或多个 <item> 元素。属性：nameString。字符串对的名称。此名称用作资源 ID。

  • <item>

    一个复数或单数字符串。其值可以是对另一字符串资源的引用。必须为 <plurals> 元素的子项。请注意，您必须对撇号和引号进行转义。如需了解有关如何正确设置字符串样式和格式的信息，请参阅下文的格式和样式设置。属性：quantity关键字。表示应在何时使用该字符串的值。以下是该关键字的有效值（括号内仅为部分示例）：Value描述zero当某种语言要求对数字 0（如阿拉伯语中的 0）进行特殊处理时。one当某种语言要求对 1 这类数字（如英语和大多数其他语言中的数字 1；在俄语中，任何末尾为 1 但非 11 的数字均属此类）进行特殊处理时。two当某种语言要求对 2 这类数字（如威尔士语中的 2，或斯洛文尼亚语中的 102）进行特殊处理时。few当某种语言要求对“小”数字（如捷克语中的 2、3 和 4；或波兰语中末尾为 2、3 或 4，但非 12、13 或 14 的数字）进行特殊处理时。many当某种语言要求对“大”数字（如马耳他语中末尾为 11 至 99 的数字）进行特殊处理时。other当某种语言未要求对给定数量（如中文中的所有数字，或英语中的 42）进行特殊处理时。

示例：

保存在 res/values/strings.xml 的 XML 文件：

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <plurals name="numberOfSongsAvailable">
        <!--
             As a developer, you should always supply "one" and "other"
             strings. Your translators will know which strings are actually
             needed for their language. Always include %d in "one" because
             translators will need to use %d for languages where "one"
             doesn't mean 1 (as explained above).
          -->
        <item quantity="one">%d song found.</item>
        <item quantity="other">%d songs found.</item>
    </plurals>
</resources>

保存在 res/values-pl/strings.xml 中的 XML 文件：

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <plurals name="numberOfSongsAvailable">
        <item quantity="one">Znaleziono %d piosenkę.</item>
        <item quantity="few">Znaleziono %d piosenki.</item>
        <item quantity="other">Znaleziono %d piosenek.</item>
    </plurals>
</resources>

用法：

KOTLINJAVA

val count = getNumberOfSongsAvailable()
val songsFound = resources.getQuantityString(R.plurals.numberOfSongsAvailable, count, count)

使用 getQuantityString() 方法时，如果您的字符串包含带有数字的字符串格式设置，则您需要传递两次 count。例如，对于字符串 %d songs found，第一个 count 参数会选择相应的复数字符串，第二个 count 参数会被插入 %d 占位符内。如果您的复数字符串没有字符串格式设置，则无需向 getQuantityString 传递第三个参数。

格式和样式

关于如何正确设置字符串资源的格式和样式，您应了解以下几个要点。

处理特殊字符

如果 XML 或 Android 中的字符串包含有特殊用法的字符，则必须转义这些字符。您可以使用前导反斜杠转义某些字符，但其他字符需使用 XML 转义。您也可以通过在双引号中包括整个字符串，处理撇号和单引号。以下为部分示例：

字符 转义形式
@ @
? ?
< <
& &
单引号 (') 以下任意字符：''在双引号中包括整个字符串（例如，"This'll work"）
双引号 (") 以下任意字符：""请注意，您必须转义双引号。在单引号中包括字符串没有任何作用。

设置字符串格式

如需设置字符串的格式，您可以在字符串资源中放入格式参数（如以下示例资源所示）。

<string name="welcome_messages">Hello, %1$s! You have %2$d new messages.</string>

在本例中，格式字符串有两个参数：%1$s 为字符串，而 %2$d 为十进制数字。然后，您可通过调用 getString(int, Object...) 来设置字符串格式。例如：

KOTLINJAVA

var text = getString(R.string.welcome_messages, username, mailCount)

使用 HTML 标记设置样式

您可以使用 HTML 标记为字符串添加样式设置。例如：

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="welcome">Welcome to <b>Android</b>!</string>
</resources>

支持以下 HTML 元素：

  • 粗体：、
  • 斜体：、、
  • 文本放大 25%：
  • 文本缩小 20%：
  • 设置字体属性：。可能的字体系列示例包括 monospace、serif 和 sans_serif。
  • 设置等宽字体系列：
  • 删除线：、、
  • 下划线：
  • 上标：
  • 下标：
  • 列表标记：
      、
    • 换行符：
    • 区隔标记：
    • CSS 样式：
    • 段落：<p dir=”rtl | ltr” style=”…”>

    如果您没有应用格式设置，则可通过调用 setText(java.lang.CharSequence) 直接设置 TextView 文本。但在某些情况下，您可能想创建带样式的文本资源，并将其用作格式字符串。您通常无法实现此目标，因为 format(String, Object...) 和 getString(int, Object...) 方法会删除字符串中的所有样式信息。解决方法是编写带转义实体的 HTML 标记，并在完成格式设置后通过 fromHtml(String) 恢复这些实体。例如：

    1. 将您带样式的文本资源存储为 HTML 转义字符串：

      <resources>
  <string name="welcome_messages">Hello, %1$s! You have &lt;b>%2$d new messages&lt;/b>.</string>
</resources>

      如上所示，带格式的字符串中添加了 <b> 元素。请注意，开括号使用 < 符号实现了 HTML 转义。

    2. 然后照常设置字符串格式，但还需调用

      fromHtml(String)

      ，以将 HTML 文本转换成带样式的文本：

      KOTLINJAVA

      val text: String = getString(R.string.welcome_messages, username, mailCount)
val styledText: Spanned = Html.fromHtml(text, FROM_HTML_MODE_LEGACY)

    由于 fromHtml(String) 方法会设置所有 HTML 实体的格式，因此请务必使用 htmlEncode(String) 转义带格式文本的字符串中任何可能存在的 HTML 字符。例如，如果您打算对包含“<”或“&”等字符的字符串进行格式设置，则在设置格式前必须先转义这类字符。如此一来，当通过 fromHtml(String) 传递带格式的字符串时，字符才会以最初的编写形式显示。例如：

    KOTLINJAVA

    val escapedUsername: String = TextUtils.htmlEncode(username)

val text: String = getString(R.string.welcome_messages, escapedUsername, mailCount)
val styledText: Spanned = Html.fromHtml(text, FROM_HTML_MODE_LEGACY)

    使用 Spannable 设置样式

    Spannable 是一种文本对象，您可使用颜色和字体粗细等字体属性对其进行样式设置。您可以使用 SpannableStringBuilder 生成文本，然后对文本应用 android.text.style 软件包中定义的样式。

    您可以使用以下辅助方法设置创建 spannable 文本的大量工作：

    KOTLINJAVA

    /**
 * Returns a CharSequence that concatenates the specified array of CharSequence
 * objects and then applies a list of zero or more tags to the entire range.
 *
 * @param content an array of character sequences to apply a style to
 * @param tags the styled span objects to apply to the content
 *        such as android.text.style.StyleSpan
 */
private fun apply(content: Array<out CharSequence>, vararg tags: Any): CharSequence {
    return SpannableStringBuilder().apply {
        openTags(tags)
        content.forEach { charSequence ->
            append(charSequence)
        }
        closeTags(tags)
    }
}

/**
 * Iterates over an array of tags and applies them to the beginning of the specified
 * Spannable object so that future text appended to the text will have the styling
 * applied to it. Do not call this method directly.
 */
private fun Spannable.openTags(tags: Array<out Any>) {
    tags.forEach { tag ->
        setSpan(tag, 0, 0, Spannable.SPAN_MARK_MARK)
    }
}

/**
 * "Closes" the specified tags on a Spannable by updating the spans to be
 * endpoint-exclusive so that future text appended to the end will not take
 * on the same styling. Do not call this method directly.
 */
private fun Spannable.closeTags(tags: Array<out Any>) {
    tags.forEach { tag ->
    if (length > 0) {
            setSpan(tag, 0, length, Spanned.SPAN_EXCLUSIVE_EXCLUSIVE)
        } else {
            removeSpan(tag)
        }
    }
}

    以下 bold、italic 和 color 方法包含上述辅助方法，并展示应用 android.text.style 软件包中所定义样式的具体示例。通过创建类似的方法，您也可对其他类型的文本进行样式设置。

    KOTLINJAVA

    /**
 * Returns a CharSequence that applies boldface to the concatenation
 * of the specified CharSequence objects.
 */
fun bold(vararg content: CharSequence): CharSequence = apply(content, StyleSpan(Typeface.BOLD))

/**
 * Returns a CharSequence that applies italics to the concatenation
 * of the specified CharSequence objects.
 */
fun italic(vararg content: CharSequence): CharSequence = apply(content, StyleSpan(Typeface.ITALIC))

/**
 * Returns a CharSequence that applies a foreground color to the
 * concatenation of the specified CharSequence objects.
 */
fun color(color: Int, vararg content: CharSequence): CharSequence =
        apply(content, ForegroundColorSpan(color))

    以下示例展示如何通过结合这些方法，向短语中的单个字词应用各种样式：

    KOTLINJAVA

    // Create an italic "hello, " a red "world",
// and bold the entire sequence.
val text: CharSequence = bold(italic(getString(R.string.hello)),
        color(Color.RED, getString(R.string.world)))

    core-ktx Kotlin 模块还包含扩展函数，便于您更轻松地使用 span。您可以前往 GitHub 查看 android.text 软件包文档，了解详情。

    如需了解有关使用 span 的更多信息，请访问以下链接：

    使用注解设置样式

    您可以通过使用 strings.xml 资源文件中的 Annotation 类和 <annotation> 标记，应用复杂样式或自定义样式。借助注解标记，您可以通过在 XML 文件中定义自定义键值对来标记自定义样式的部分字符串，框架随后会将该 XML 文件转换成 Annotation span。然后，您便可检索这些注解，并使用键和值来应用样式。

    创建注解时，请务必为 strings.xml 文件中的所有字符串翻译添加 <annotation> 标记。

    img
    在所有语言中向“text”一词应用自定义字体

    示例 - 添加自定义字体

    1. 添加 <annotation> 标记并定义键值对。在此情况下，键为 font，而值是我们要使用的字体类型：title_emphasis

      // values/strings.xml
<string name="title">Best practices for <annotation font="title_emphasis">text</annotation> on Android</string>

// values-es/strings.xml
<string name="title"><annotation font="title_emphasis">Texto</annotation> en Android: mejores prácticas</string>

    2. 加载字符串资源并找到包含 font 键的注解。然后，创建一个自定义 span，并用其替换现有 span。

      KOTLINJAVA

      // get the text as SpannedString so we can get the spans attached to the text
val titleText = getText(R.string.title) as SpannedString

// get all the annotation spans from the text
val annotations = titleText.getSpans(0, titleText.length, Annotation::class.java)

// create a copy of the title text as a SpannableString.
// the constructor copies both the text and the spans. so we can add and remove spans
val spannableString = SpannableString(titleText)

// iterate through all the annotation spans
for (annotation in annotations) {
   // look for the span with the key font
   if (annotation.key == "font") {
      val fontName = annotation.value
      // check the value associated to the annotation key
      if (fontName == "title_emphasis") {
         // create the typeface
         val typeface = getFontCompat(R.font.permanent_marker)
         // set the span at the same indices as the annotation
         spannableString.setSpan(CustomTypefaceSpan(typeface),
            titleText.getSpanStart(annotation),
            titleText.getSpanEnd(annotation),
            Spannable.SPAN_EXCLUSIVE_EXCLUSIVE)
      }
   }
}

// now, the spannableString contains both the annotation spans and the CustomTypefaceSpan
styledText.text = spannableString

    如果您多次使用相同文本，则应构建一次 SpannableString 对象并根据需要重复使用该对象，以避免出现潜在的性能和内存问题。

    如需了解注解用法的更多示例，请参阅在 Android 中设置国际化文本的样式

    注解 span 和文本打包

    Annotation span 也是 ParcelableSpans，因此需对键值对进行打包和拆包。只要包的接收方了解如何解释注解，您便可使用 Annotation span 向打包文本应用自定义样式。

    如要在向 Intent Bundle 传递文本时保留自定义样式，您首先需在文本中添加 Annotation span。您可以使用 标记在 XML 资源中执行此操作（如上例所示），或通过创建新的 Annotation 并将其设置为 span，在代码中执行此操作（如下所示）：

    KOTLINJAVA

    val spannableString = SpannableString("My spantastic text")
val annotation = Annotation("font", "title_emphasis")
spannableString.setSpan(annotation, 3, 7, Spannable.SPAN_EXCLUSIVE_EXCLUSIVE)

// start Activity with text with spans
val intent = Intent(this, MainActivity::class.java)
intent.putExtra(TEXT_EXTRA, spannableString)
startActivity(intent)

    以 SpannableString 的形式从 Bundle 中检索文本，然后解析附加的注解（如上例所示）。

    KOTLINJAVA

    // read text with Spans
val intentCharSequence = intent.getCharSequenceExtra(TEXT_EXTRA) as SpannableString

    如需了解有关文本样式设置的更多信息，请访问以下链接：

    样式

    样式资源定义界面的格式和外观。样式可应用于单个 View（从布局文件中）或应用于整个 Activity 或应用（从清单文件中）。

    如需详细了解如何创建和应用样式，请参阅样式和主题。

    注意：样式是使用 name 属性中提供的值（不是 XML 文件的名称）引用的简单资源。因此，您可以在一个 XML 文件中将样式资源与其他简单资源合并到一个 <resources> 元素下。

    • 文件位置：

      res/values/*filename*.xml 该文件名可以任意设置。元素的 name 将用作资源 ID。

    • 资源引用：

      在 XML 中：@[package:]style/*style_name*

    • 语法：

          <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <style
            name="style_name"
            parent="@[package:]style/style_to_inherit">
            <item
                name="[package:]style_property_name"
                >style_value</item>
        </style>
    </resources>

    • 元素：

      • <resources>

        必需。该元素必须是根节点。没有属性。

      • <style>

        定义单个样式。包含 <item> 元素。属性：name字符串。必需。样式的名称，用作将样式应用于 View、Activity 或应用的资源 ID。parent样式资源。对此样式应从中继承样式属性的样式的引用。

      • <item>

        定义样式的单个属性。必须是 <style> 元素的子元素。属性：name属性资源。必需。要定义的样式属性的名称，必要时带有包前缀（例如 android:textColor）。

      示例：

      • 样式的 XML 文件（保存在 res/values/ 中）：
        <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <style name="CustomText" parent="@style/Text">
            <item name="android:textSize">20sp</item>
            <item name="android:textColor">#008</item>
        </style>
    </resources>

    将样式应用于 TextView 的 XML 文件（保存在 res/layout/ 中）：

         <?xml version="1.0" encoding="utf-8"?>
    <EditText
        style="@style/CustomText"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
        android:text="Hello, World!" />

    更多资源类型

    目录Bool颜色尺寸ID

    本页面定义了更多类型的可具体化的资源，包括：

    • Bool

      带有布尔值的 XML 资源。

    • 颜色

      带有颜色值（十六进制颜色）的 XML 资源。

    • 尺寸

      带有尺寸值（包含度量单位）的 XML 资源。

    • ID

      提供应用资源和组件的唯一标识符的 XML 资源。

    • 整数

      带有整数值的 XML 资源。

    • 整数数组

      提供整数数组的 XML 资源。

    • 类型化数组

      提供 TypedArray（可用于可绘制对象数组）的 XML 资源。

    Bool

    在 XML 中定义的布尔值。

    注意：Bool 是使用 name 属性中提供的值（而不是 XML 文件的名称）引用的简单资源。因此，您可以在一个 XML 文件中将 bool 资源与其他简单资源合并到一个 <resources> 元素下。

    • 文件位置：

      res/values/*filename*.xml 文件名可以任意设置。<bool> 元素的 name 将用作资源 ID。

    • 资源引用：

      在 Java 中：R.bool.*bool_name* 在 XML 中：@[*package*:]bool/*bool_name*

    • 语法：

          <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <bool
            name="bool_name"
            >[true | false]</bool>
    </resources>

      • <resources>

        必需。该元素必须是根节点。没有属性。

      • <bool>

        布尔值：true 或 false。属性：name字符串。Bool 值的名称。该名称将用作资源 ID。

      示例：

      保存在 res/values-small/bools.xml 的 XML 文件：

          <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <bool name="screen_small">true</bool>
        <bool name="adjust_view_bounds">true</bool>
    </resources>

      以下布局 XML 会将该布尔值应用到属性：

          <ImageView
        android:layout_height="fill_parent"
        android:layout_width="fill_parent"
        android:src="@drawable/logo"
        android:adjustViewBounds="@bool/adjust_view_bounds" />

      颜色

    在 XML 中定义的颜色值。颜色使用 RGB 值和 alpha 通道指定。您可以在接受十六进制颜色值的任何地方使用颜色资源。当 XML 中需要可绘制资源时，您也可以使用颜色资源（例如，android:drawable="@color/green"）。

    该值始终以井号 (#) 字符开头，后跟以下某种格式的“透明度、红、绿、蓝”(Alpha-Red-Green-Blue) 信息：

    • #RGB
    • #ARGB
    • #RRGGBB
    • #AARRGGBB

    注意：颜色是使用 name 属性中提供的值（而不是 XML 文件的名称）引用的简单资源。因此，您可以在一个 XML 文件中将颜色资源与其他简单资源合并到一个 <resources> 元素下。

    • 文件位置：

      res/values/colors.xml 该文件名可以任意设置。<color> 元素的 name 将用作资源 ID。

    • 资源引用：

      在 Java 中：R.color.*color_name* 在 XML 中：@[*package*:]color/*color_name*

    • 语法：

      <?xml version="1.0" encoding="utf-8"?> <resources> <color name="*color_name*" >*hex_color*</color> </resources>

    • 元素：

      <resources>必需。该元素必须是根节点。没有属性。<color>以十六进制表示的颜色，如上所述。属性：name字符串。颜色的名称。该名称将用作资源 ID。

    • 示例：

      保存在 res/values/colors.xml 的 XML 文件： <?xml version="1.0" encoding="utf-8"?> <resources> <color name="opaque_red">#f00</color> <color name="translucent_red">#80ff0000</color> </resources> 以下应用代码会检索颜色资源：KOTLINJAVA val color: Int = resources.getColor(R.color.opaque_red) 以下布局 XML 会将该颜色应用到属性： <TextView android:layout_width="fill_parent" android:layout_height="wrap_content" android:textColor="@color/translucent_red" android:text="Hello"/>

    尺寸

    在 XML 中定义的尺寸值。尺寸由数字后跟度量单位来指定。例如：10px、2in、5sp。Android 支持以下度量单位：

    • dp

      密度无关像素 - 基于屏幕物理密度的抽象单位。这些单位相对于 160 dpi（每英寸点数）屏幕确立，在该屏幕上 1dp 大致等于 1px。在更高密度的屏幕上运行时，用于绘制 1dp 的像素数量会根据屏幕 dpi 按照适当的系数增加。同样，在更低密度的屏幕上，用于绘制 1dp 的像素数量会相应减少。dp 对像素的比率会随着屏幕密度的变化而变化，但不一定成正比。要使布局中的视图尺寸根据不同的屏幕密度正确调整大小，一种简单的解决办法就是使用 dp 单位（而不是 px 单位）。换句话说，它可在不同设备上提供一致的界面元素大小。

    • sp

      缩放无关像素 - 这和 dp 单位类似，但它也会根据用户的字体大小偏好设置进行缩放。建议您在指定字体大小时使用此单位，以便字体大小会根据屏幕密度和用户偏好设置进行调整。

    • pt

      点 - 1/72 英寸，基于屏幕的物理尺寸，假设屏幕密度为 72dpi。

    • px

      像素 - 对应于屏幕上的实际像素数。建议不要使用这种度量单位，因为不同设备的实际呈现效果可能不同；每台设备的每英寸像素数可能不同，屏幕上的总像素数也可能有差异。

    • mm

      毫米 - 基于屏幕的物理尺寸。

    • in

      英寸 - 基于屏幕的物理尺寸。

    注意：尺寸是使用 name 属性中提供的值（而不是 XML 文件的名称）引用的简单资源。因此，您可以在一个 XML 文件中将尺寸资源与其他简单资源合并到一个 <resources> 元素下。

    • 文件位置：

      res/values/*filename*.xml 该文件名可以任意设置。<dimen> 元素的 name 将用作资源 ID。

    • 资源引用：

      在 Java 中：R.dimen.*dimension_name* 在 XML 中：@[*package*:]dimen/*dimension_name*

    • 语法：

      <?xml version="1.0" encoding="utf-8"?> <resources> <dimen name="*dimension_name*" >*dimension*</dimen> </resources>

    • 元素：

      <resources>必需。该元素必须是根节点。没有属性。<dimen>定义一个尺寸，由浮点数后跟度量单位（dp、sp、pt、px、mm、in）表示，如上所述。属性：name字符串。尺寸的名称。该名称将用作资源 ID。

    • 示例：

      保存在 res/values/dimens.xml 的 XML 文件： <?xml version="1.0" encoding="utf-8"?> <resources> <dimen name="textview_height">25dp</dimen> <dimen name="textview_width">150dp</dimen> <dimen name="ball_radius">30dp</dimen> <dimen name="font_size">16sp</dimen> </resources> 以下应用代码会检索尺寸：KOTLINJAVA val fontSize: Float = resources.getDimension(R.dimen.font_size) 以下布局 XML 会将尺寸应用到属性： <TextView android:layout_height="@dimen/textview_height" android:layout_width="@dimen/textview_width" android:textSize="@dimen/font_size"/>

    ID

    在 XML 中定义的唯一资源 ID。Android 开发者工具可使用您在 <item> 元素中提供的名称，在您项目的 R.java 类中创建唯一的整数，供您用作应用资源（例如，界面布局中的 View）的标识符，或创建唯一的整数，供您在应用代码中使用（例如，作为对话框的 ID 或结果代码）。

    注意：ID 是使用 name 属性中提供的值（而不是 XML 文件的名称）引用的简单资源。因此，您可以在一个 XML 文件中将 ID 资源与其他简单资源合并到一个 <resources> 元素下。另外请注意，ID 资源并不引用实际的资源项；它只是一个唯一 ID，您可以将其附加到其他资源，或者在应用中作为唯一整数使用。

    • 文件位置：

      res/values/*filename.xml* 该文件名可以任意设置。

    • 资源引用：

      在 Java 中：R.id.*name* 在 XML 中：@[*package*:]id/*name*

    • 语法：

          <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <dimen
            name="dimension_name"
            >dimension</dimen>
    </resources>

    • 元素：

      • <resources>

        必需。该元素必须是根节点。没有属性。

      • <dimen>

        定义一个尺寸，由浮点数后跟度量单位（dp、sp、pt、px、mm、in）表示，如上所述。属性：name字符串。尺寸的名称。该名称将用作资源 ID。

    • 保存在 res/values/dimens.xml 的 XML 文件：

          <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <dimen name="textview_height">25dp</dimen>
        <dimen name="textview_width">150dp</dimen>
        <dimen name="ball_radius">30dp</dimen>
        <dimen name="font_size">16sp</dimen>
    </resources>

      以下应用代码会检索尺寸：

      KOTLINJAVA

          val fontSize: Float = resources.getDimension(R.dimen.font_size)

      以下布局 XML 会将尺寸应用到属性：

        <TextView    android:layout_height="@dimen/textview_height"    android:layout_width="@dimen/textview_width"    android:textSize="@dimen/font_size"/>

    ID

    在 XML 中定义的唯一资源 ID。Android 开发者工具可使用您在 <item> 元素中提供的名称，在您项目的 R.java 类中创建唯一的整数，供您用作应用资源（例如，界面布局中的 View）的标识符，或创建唯一的整数，供您在应用代码中使用（例如，作为对话框的 ID 或结果代码）。

    注意：ID 是使用 name 属性中提供的值（而不是 XML 文件的名称）引用的简单资源。因此，您可以在一个 XML 文件中将 ID 资源与其他简单资源合并到一个 <resources> 元素下。另外请注意，ID 资源并不引用实际的资源项；它只是一个唯一 ID，您可以将其附加到其他资源，或者在应用中作为唯一整数使用。

    • 文件位置：

      res/values/*filename.xml* 该文件名可以任意设置。

    • 资源引用：

      在 Java 中：R.id.*name* 在 XML 中：@[*package*:]id/*name*

    • 语法：

      <?xml version="1.0" encoding="utf-8"?> <resources> <item type="id" name="*id_name*" /> </resources>

    • 元素：

      <resources>必需。该元素必须是根节点。没有属性。<item>定义唯一 ID。不设置值，只有属性。属性：type必须为“id”。name字符串。ID 的唯一名称。

    • 示例：

      保存在 res/values/ids.xml 的 XML 文件：

          <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <item type="id" name="button_ok" />
        <item type="id" name="dialog_exit" />
    </resources>

      然后，以下布局代码段会将“button_ok”ID 应用到按钮微件：

          <Button android:id="@id/button_ok"
        style="@style/button_style" />

      请注意，android:id 值不会在 ID 引用中包含加号，因为此 ID 已存在，如上面的 ids.xml 示例中所定义。（如果使用加号以 android:id="@+id/name" 格式指定 XML 资源的 ID，则表示“name”ID 不存在，应该创建它。）

      再比如，以下代码段使用“dialog_exit”ID 作为对话框的唯一标识符：

      KOTLINJAVA

          showDialog(R.id.dialog_exit)

      在同一应用中，在创建对话框时会比较“dialog_exit”ID：

      KOTLINJAVA

          override fun onCreateDialog(id: Int): Dialog? {
        return when(id) {
            R.id.dialog_exit -> {
                ...
            }
            else -> {
                null
            }
        }
    }

    整数

    在 XML 中定义的整数。

    注意：整数是使用 name 属性中提供的值（而不是 XML 文件的名称）引用的简单资源。因此，您可以在一个 XML 文件中将整数资源与其他简单资源合并到一个 <resources> 元素下。

    • 文件位置：

      res/values/*filename.xml* 该文件名可以任意设置。<integer> 元素的 name 将用作资源 ID。

    • 资源引用：

      在 Java 中：R.integer.*integer_name* 在 XML 中：@[*package*:]integer/*integer_name*

    • 语法：

      <?xml version="1.0" encoding="utf-8"?> <resources> <integer name="*integer_name*" >*integer*</integer> </resources>

    • 元素：

      <resources>必需。该元素必须是根节点。没有属性。<integer>一个整数。属性：name字符串。该整数的名称。该名称将用作资源 ID。

    • 示例：

      保存在 res/values/integers.xml 的 XML 文件：

          <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <integer name="max_speed">75</integer>
        <integer name="min_speed">5</integer>
    </resources>

      以下应用代码会检索整数：KOTLINJAVA` val maxSpeed: Int =

          val maxSpeed: Int = resources.getInteger(R.integer.max_speed)

    整数数组

    在 XML 中定义的整数数组。

    注意：整数数组是使用 name 属性中提供的值（而不是 XML 文件的名称）引用的简单资源。因此，您可以在一个 XML 文件中将整数数组资源与其他简单资源合并到一个 <resources> 元素下。

    • 文件位置：

      res/values/*filename*.xml 该文件名可以任意设置。<integer-array> 元素的 name 将用作资源 ID。

    • 编译后的资源数据类型：

      指向整数数组的资源指针。

    • 资源引用：

      在 Java 中：R.array.*integer_array_name* 在 XML 中：@[*package*:]array.*integer_array_name*

    • 语法：

          <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <integer-array
            name="integer_array_name">
            <item
                >integer</item>
        </integer-array>
    </resources>

    • 元素：

      <resources>必需。该元素必须是根节点。没有属性。<integer-array>定义一个整数数组。包含一个或多个 <item> 子元素。属性：android:name字符串。数组的名称。此名称将用作引用数组的资源 ID。<item>一个整数。该值可以是对另一个整数资源的引用。必须是 <integer-array> 元素的子元素。没有属性。

    • 示例：

      保存在 res/values/integers.xml 的 XML 文件：

          <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <integer-array name="bits">
            <item>4</item>
            <item>8</item>
            <item>16</item>
            <item>32</item>
        </integer-array>
    </resources>

      以下应用代码会检索整数数组：KOTLINJAVA

          val bits: IntArray = resources.getIntArray(R.array.bits)

    在 XML 中定义的 TypedArray。您可以使用这种资源创建其他资源（例如可绘制对象）的数组。请注意，此类数组不要求所含的资源具有相同的类型，因此您可以创建混合资源类型的数组，但必须知道数组中有哪些数据类型及其位置，以便可以使用 TypedArray 的 get...() 方法正确获取每一项数据。

    注意：类型化数组是使用 name 属性中提供的值（而不是 XML 文件的名称）引用的简单资源。因此，您可以在一个 XML 文件中将类型化数组资源与其他简单资源合并到一个 <resources> 元素下。

    • 文件位置：

      res/values/*filename*.xml 该文件名可以任意设置。<array> 元素的 name 将用作资源 ID。

    • 编译后的资源数据类型：

      指向 TypedArray 的资源指针。

    • 资源引用：

      在 Java 中：R.array.*array_name* 在 XML 中：@[*package*:]array.*array_name*

    • 语法：

      <?xml version="1.0" encoding="utf-8"?> <resources> <array name="*integer_array_name*"> <item>*resource*</item> </array> </resources>

    • 元素：

      <resources>必需。该元素必须是根节点。没有属性。<array>定义一个数组。包含一个或多个 <item> 子元素。属性：android:name字符串。数组的名称。此名称将用作引用数组的资源 ID。<item>通用资源。该值可以是对资源或简单数据类型的引用。必须是 <array> 元素的子元素。没有属性。

    • 示例：

      保存在 res/values/arrays.xml 的 XML 文件： <?xml version="1.0" encoding="utf-8"?> <resources> <array name="icons"> <item>@drawable/home</item> <item>@drawable/settings</item> <item>@drawable/logout</item> </array> <array name="colors"> <item>#FFFF0000</item> <item>#FF00FF00</item> <item>#FF0000FF</item> </array> </resources> 以下应用代码会检索每个数组，然后获取每个数组中的第一个条目：KOTLINJAVA val icons: TypedArray = resources.obtainTypedArray(R.array.icons) val drawable: Drawable = icons.getDrawable(0) val colors: TypedArray = resources.obtainTypedArray(R.array.colors) val color: Int = colors.getColor(0,0)

【推广】 免费学中医，健康全家人
原文地址：https://www.cnblogs.com/liguo-wang/p/13129257.html