uni-app
uni-app x
uniCloud
HBuilder X
uni 小程序 sdk
uni-ad广告
开发者服务
uni-app x
uni-app
uni-app x
uniCloud
HBuilder X
uni 小程序 sdk
uni-ad广告
开发者服务
简体中文
CSS
background-color
uni-app x 兼容性
语法
值限制
默认值
tips
示例
参见

# background-color

background-color 属性用于设置元素的背景色，属性的值为颜色值或关键字"transparent"。

# uni-app x 兼容性

Web Android iOS HarmonyOS HarmonyOS(Vapor)
4.0 3.9 4.11 4.61 5.0

# 语法

background-color: <color>;

# 值限制

  • color

# 默认值

transparent

# tips

  • App-Harmony 平台，背景仅延伸到内边距（padding）区域，不会绘制到边框区域，效果与 background-clip 为 padding-box 一致。

# 示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

扫码体验（手机浏览器跳转到App直达页）

示例

<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex: 1">
  <!-- #endif -->
    <view style="flex-grow: 1">
      <text class="uni-tips">说明：左边是正常版本，右边是拍平版本</text>
      <view>
        <text>background-color: blue</text>
        <view class="demo-box">
          <view class="common" style="background-color: blue"></view>
          <view class="common" style="background-color: blue" flatten></view>
        </view>
      </view>

      <view>
        <text>background-color: #0000ff</text>
        <view class="demo-box">
          <view class="common" style="background-color: #0000ff"></view>
          <view class="common" style="background-color: #0000ff" flatten></view>
        </view>
      </view>

      <view>
        <text>background-color: #00f</text>
        <view class="demo-box">
          <view class="common" style="background-color: #00f"></view>
          <view class="common" style="background-color: #00f" flatten></view>
        </view>
      </view>

      <view>
        <text>background-color: #0000ff80</text>
        <view class="demo-box">
          <view class="common" style="background-color: #0000ff80"></view>
          <view class="common" style="background-color: #0000ff80" flatten></view>
        </view>
      </view>

      <view>
        <text>background-color: #00f8</text>
        <view class="demo-box">
          <view class="common" style="background-color: #00f8"></view>
          <view class="common" style="background-color: #00f8" flatten></view>
        </view>
      </view>

      <view>
        <text>background-color: rgb(0, 0, 255)</text>
        <view class="demo-box">
          <view class="common" style="background-color: rgb(0, 0, 255)"></view>
          <view class="common" style="background-color: rgb(0, 0, 255)" flatten></view>
        </view>
      </view>

      <view>
        <text>background-color: rgba(0, 0, 255, 0.5)</text>
        <view class="demo-box">
          <view class="common" style="background-color: rgba(0, 0, 255, 0.5)"></view>
          <view class="common" style="background-color: rgba(0, 0, 255, 0.5)" flatten></view>
        </view>
      </view>
      <view>
        <text>background-color: #0000ff80</text>
        <view class="demo-box">
          <view class="common" style="background-color: #0000ff80"></view>
          <view class="common" style="background-color: #0000ff80" flatten></view>
        </view>
      </view>
      <view style="margin-left: 30px;margin-right: 30px;">
        <button type="default" @click="jumpToCheckBoxWithBackgroundColor">应用background-color示例</button>
      </view>

      <view class="uni-common-mt">
        <text class="uni-title-text">text 组件 background-color </text>
      </view>

      <view>
        <text>background-color: blue</text>
        <view class="demo-box">
          <text class="common" style="background-color: blue">文字内容</text>
          <text class="common" style="background-color: blue" flatten>文字内容</text>
        </view>
      </view>

      <view>
        <text>background-color: rgba(0, 0, 255, 0.5)</text>
        <view class="demo-box">
          <text class="common" style="background-color: rgba(0, 0, 255, 0.5)">文字内容</text>
          <text class="common" style="background-color: rgba(0, 0, 255, 0.5)" flatten>文字内容</text>
        </view>
      </view>

      <view>
        <text>background-color: #00ff00</text>
        <view class="demo-box">
          <text class="common" style="background-color: #00ff00">文字内容</text>
          <text class="common" style="background-color: #00ff00" flatten>文字内容</text>
        </view>
      </view>

      <view>
        <text>background-color: #0000ff80</text>
        <view class="demo-box">
          <text class="common" style="background-color: #0000ff80">文字内容</text>
          <text class="common" style="background-color: #0000ff80" flatten>文字内容</text>
        </view>
      </view>

      <view class="uni-common-mt">
        <text class="uni-title-text">image 组件 background-color </text>
      </view>

      <view>
        <text>background-color: blue (无src时显示背景色)</text>
        <view class="demo-box">
          <image class="common-image" style="background-color: blue"></image>
          <image class="common-image" style="background-color: blue" flatten></image>
        </view>
      </view>

      <view>
        <text>background-color: rgba(0, 0, 255, 0.5) (无src时显示背景色)</text>
        <view class="demo-box">
          <image class="common-image" style="background-color: rgba(0, 0, 255, 0.5)"></image>
          <image class="common-image" style="background-color: rgba(0, 0, 255, 0.5)" flatten></image>
        </view>
      </view>

      <view>
        <text>background-color: #00ff00 (无src时显示背景色)</text>
        <view class="demo-box">
          <image class="common-image" style="background-color: #00ff00"></image>
          <image class="common-image" style="background-color: #00ff00" flatten></image>
        </view>
      </view>

      <view>
        <text>background-color: #0000ff80 (无src时显示背景色)</text>
        <view class="demo-box">
          <image class="common-image" style="background-color: #0000ff80"></image>
          <image class="common-image" style="background-color: #0000ff80" flatten></image>
        </view>
      </view>

      <view>
        <text>background-color: yellow (有src时，背景色在图片加载失败或透明区域显示)</text>
        <view class="demo-box">
          <image class="common-image" style="background-color: yellow" src="/static/test-image/logo.png"></image>
          <image class="common-image" style="background-color: yellow" src="/static/test-image/logo.png" flatten></image>
        </view>
      </view>

      <view class="uni-common-mt">
        <text class="uni-title-text">setProperty 设置与 getPropertyValue 获取 background-color </text>
      </view>

      <!-- 普通版本 -->
      <view class="test-container">
        <!-- view 组件测试 -->
        <view class="test-item">
          <text class="uni-subtitle-text">view 组件</text>
          <text class="uni-info">设置值: {{backgroundColor}}</text>
          <text class="uni-info">获取值: {{backgroundColorActual}}</text>
          <view class="test-box">
            <view ref="viewRef" class="common-view test-view" :style="{ backgroundColor: backgroundColor }">
              <text style="font-size: 12px;">view</text>
            </view>
          </view>
        </view>

        <!-- text 组件测试 -->
        <view class="test-item">
          <text class="uni-subtitle-text">text 组件</text>
          <text class="uni-info">设置值: {{backgroundColor}}</text>
          <text class="uni-info">获取值: {{backgroundColorActualText}}</text>
          <view class="test-box">
            <text ref="textRef" class="common-text test-text" :style="{ backgroundColor: backgroundColor }">text</text>
          </view>
        </view>

        <!-- image 组件测试 -->
        <view class="test-item">
          <text class="uni-subtitle-text">image 组件</text>
          <text class="uni-info">设置值: {{backgroundColor}}</text>
          <text class="uni-info">获取值: {{backgroundColorActualImage}}</text>
          <view class="test-box">
            <image ref="imageRef" class="common-image test-image" :style="{ backgroundColor: backgroundColor }" src="/static/test-image/logo.png"></image>
          </view>
        </view>
      </view>

      <!-- 拍平版本 -->
      <view class="test-container">
        <!-- view 组件拍平测试 -->
        <view class="test-item">
          <text class="uni-subtitle-text">view 组件拍平</text>
          <text class="uni-info">设置值: {{backgroundColor}}</text>
          <text class="uni-info">获取值: {{backgroundColorActualFlat}}</text>
          <view class="test-box">
            <view ref="viewRefFlat" class="common-view test-view-flatten" :style="{ backgroundColor: backgroundColor }" flatten>
              <text style="font-size: 12px;">view</text>
            </view>
          </view>
        </view>

        <!-- text 组件拍平测试 -->
        <view class="test-item">
          <text class="uni-subtitle-text">text 组件拍平</text>
          <text class="uni-info">设置值: {{backgroundColor}}</text>
          <text class="uni-info">获取值: {{backgroundColorActualTextFlat}}</text>
          <view class="test-box">
            <text ref="textRefFlat" class="common-text test-text-flatten" :style="{ backgroundColor: backgroundColor }" flatten>text</text>
          </view>
        </view>

        <!-- image 组件拍平测试 -->
        <view class="test-item">
          <text class="uni-subtitle-text">image 组件拍平</text>
          <text class="uni-info">设置值: {{backgroundColor}}</text>
          <text class="uni-info">获取值: {{backgroundColorActualImageFlat}}</text>
          <view class="test-box">
            <image ref="imageRefFlat" class="common-image test-image-flatten" :style="{ backgroundColor: backgroundColor }" flatten src="/static/test-image/logo.png"></image>
          </view>
        </view>
      </view>

      <!-- 测试控制区域 -->
      <view class="uni-common-mt uni-common-mb">
        <text class="uni-tips">第一个枚举值，'' (空字符串) - 空值情况</text>
        <enum-data :compact="true" :items="backgroundColorEnum" title="background-color 枚举值" @change="radioChangeBackgroundColor"></enum-data>
        <input-data :defaultValue="backgroundColor" title="background-color 自定义值" type="text" @confirm="inputChangeBackgroundColor"></input-data>
      </view>
    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>

<script setup>
  import { ItemType } from '@/components/enum-data/enum-data-types'

  const backgroundColor = ref('cyan')
  const backgroundColorActual = ref('')
  const backgroundColorActualText = ref('')
  const backgroundColorActualImage = ref('')
  const backgroundColorActualFlat = ref('')
  const backgroundColorActualTextFlat = ref('')
  const backgroundColorActualImageFlat = ref('')
  const viewRef = ref(null as UniElement | null)
  const textRef = ref(null as UniTextElement | null)
  const imageRef = ref(null as UniImageElement | null)
  const viewRefFlat = ref(null as UniElement | null)
  const textRefFlat = ref(null as UniTextElement | null)
  const imageRefFlat = ref(null as UniImageElement | null)

  const backgroundColorEnum: ItemType[] = [
    { value: 0, name: '' },
    { value: 1, name: 'green' },
    { value: 2, name: '#88abf0' },
    { value: 3, name: 'rgb(0, 255, 0)' },
    { value: 4, name: 'rgba(0, 255, 0, 0.5)' },
    { value: 5, name: '#ddd' },
    { value: 6, name: 'transparent' }
  ]

  const getPropertyValues = () => {
    backgroundColorActual.value = viewRef.value?.style.getPropertyValue('background-color') ?? ''
    backgroundColorActualFlat.value = viewRefFlat.value?.style.getPropertyValue('background-color') ?? ''
    backgroundColorActualText.value = textRef.value?.style.getPropertyValue('background-color') ?? ''
    backgroundColorActualTextFlat.value = textRefFlat.value?.style.getPropertyValue('background-color') ?? ''
    backgroundColorActualImage.value = imageRef.value?.style.getPropertyValue('background-color') ?? ''
    backgroundColorActualImageFlat.value = imageRefFlat.value?.style.getPropertyValue('background-color') ?? ''
  }

  const changeBackgroundColor = (color: string) => {
    backgroundColor.value = color
    viewRef.value?.style.setProperty('background-color', color)
    viewRefFlat.value?.style.setProperty('background-color', color)
    textRef.value?.style.setProperty('background-color', color)
    textRefFlat.value?.style.setProperty('background-color', color)
    imageRef.value?.style.setProperty('background-color', color)
    imageRefFlat.value?.style.setProperty('background-color', color)
    // 使用 nextTick 确保样式已应用后再获取值
    nextTick(() => {
      getPropertyValues()
    })
  }

  const radioChangeBackgroundColor = (index: number) => {
    const selectedItem = backgroundColorEnum.find((item): boolean => item.value === index)
    if (selectedItem != null) {
      changeBackgroundColor(selectedItem.name)
    }
  }

  const inputChangeBackgroundColor = (value: string) => {
    changeBackgroundColor(value)
  }

  const jumpToCheckBoxWithBackgroundColor = () => {
    uni.navigateTo({
      url:"/pages/CSS/background/background-color-check-box"
    })
  }

  onReady(() => {
    getPropertyValues()
  })

  defineExpose({
    radioChangeBackgroundColor
  })
</script>

<style>
  .common {
    width: 150px;
    height: 50px;
  }

  .demo-box {
    flex-direction: row;
    margin-top: 10px;
    justify-content: space-around;
  }

  /* 多组件横向布局样式 */
  .test-container {
    flex-direction: row;
    justify-content: space-between;
    margin-top: 10px;
  }

  .test-item {
    flex: 1;
    margin: 0 5px;
  }

  .test-box {
    width: 100%;
    height: 60px;
    background-color: gray;
  }


  .common-view {
    height: 50px;
    background-color: yellow;
  }

  .common-text {
    height: 50px;
    background-color: yellow;
    font-size: 12px;
  }

  .common-image {
    width: 50px;
    height: 50px;
    background-color: yellow;
  }
</style>

# 参见

本页导读
background-color
uni-app x 兼容性
语法
值限制
默认值
tips
示例
参见