UI 背景

设置 UI 实体的背景和边框。

以下属性用于为 UI 实体设置背景和边框。

背景

一个 uiBackground 组件为实体的区域提供颜色或纹理。它使用实体的 uiTransform.

以下字段可以配置，全部都是可选的：

• color：要在实体上使用的颜色，作为一个 Color4 值。

💡 提示：通过将 Color4 的第 4 个值设置为小于 1，使实体半透明。

• 纹理：要显示在实体上的纹理，这里传入一个包含纹理各种参数的对象。可用属性与 3D 实体上的 材质中的纹理.

  • src：要用作纹理的图像文件路径。（字符串）

  • filterMode: （可选） 决定纹理中的像素在渲染时如何被拉伸或压缩。参见 纹理缩放。（FilterMode = 'point' | 'bi-linear' | 'tri-linear'）

  • wrapMode: （可选） 决定纹理如何平铺到实体上。这里使用来自 TextureWrapMode 枚举的值。参见 [纹理包裹]((查看文档）。(WrapMode = 'repeat' | 'clamp' | 'mirror')

  提示：你可以将这两个 纹理 和 color 属性组合在同一个 uiBackground 组件上，以生成带色调的纹理。

• textureMode：选择你希望纹理如何适应其所应用实体的尺寸。（TextureMode = 'nine-slices' | 'center' | 'stretch'）枚举，支持以下值：

  • center：纹理不会被拉伸，它会居中放置在实体上，并且其部分内容可能会根据实体大小被裁剪。

  • 拉伸：纹理会被拉伸以匹配实体的整个表面。

  • 九宫格切片：纹理的某些部分会被拉伸以匹配实体的整个表面，而边距保持不变。参见 九宫格纹理.

• avatarTexture：基于头像 ID 显示头像个人资料缩略图。参见 [头像肖像]((查看文档).

• textureSlices：在使用九宫格纹理模式时，确定要使用的边距，参见 九宫格纹理。设置一个小于 1 的数值，作为图像总宽度或总高度的分数。

简单颜色：

ui.tsx 文件：

import { ReactEcs, UiEntity } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400
    }}
    uiBackground={{
		color: Color4.create(0.5, 0.8, 0.1, 0.6)
	}}
  />
)

index.ts 文件：

import { ReactEcsRenderer } from '@dcl/sdk/react-ecs'
import { uiMenu } from './ui'

export function main() {
    ReactEcsRenderer.setUiRenderer(uiMenu, { virtualWidth: 1920, virtualHeight: 1080 })
}

📔 注意：本页下面的所有代码片段都假设你有一个 .ts 类似于上面的内容，正在运行 ReactEcsRenderer.setUiRenderer() 函数。

重复纹理图案：

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400
    }}
    uiBackground={{
		textureMode: 'center',
		texture: {
			src: "images/brick-wall-texture.png",
			wrapMode: 'repeat'
		}
	}}
  />
)

边框

有一些属性用于为 UI 实体设置边框。这些属性存在于 uiTransform 组件上。它们都允许你为边框的所有边设置单个值，或者为每一边设置不同的值。

• borderColor：要在实体上使用的颜色，作为一个 Color4 值。

• borderWidth：边框的宽度，单位为像素。它也支持百分比值，例如 borderWidth: '2%' 会将边框宽度设置为实体宽度的 2%。

• borderRadius：使用此属性可以让实体的角变成圆角边框。它以像素设置角的半径。

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      borderColor: Color4.Red(),
      borderWidth: 4,
      borderRadius: 10
    }}
  />
)

borderWidth, borderColor 和 borderRadius 也可以为实体的每一边设置不同的值。

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      borderColor: { top: Color4.White(), left: Color4.Red(), right: Color4.Blue(), bottom: Color4.Gray() },
      borderRadius: { topLeft: 20, topRight: 20, bottomLeft: 20, bottomRight:0 },
      borderWidth: { top: 3, left: 2, right: 3, bottom: 4 }
    }}
  />
)

不透明度

使用 opacity 属性在 uiTransform 中的 UiEntity 用于为实体及其所有子元素添加透明度。opacity 属性的值范围为 0 到 1，其中 0 表示完全透明，1 表示完全不透明。

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      opacity: 0.7
    }}
    uiBackground={{ color: Color4.Green() }}
  >
    <UiEntity
        uiTransform={{
          width: 100,
          height: 30,
        }}
        uiText={{
          value: "这段文字也同样是透明的",
          fontSize: 40
        }}
      />
   </UiEntity>
)

不透明度值会影响 UiEntity 的所有子元素，对背景颜色、文本颜色和背景图像都应用透明度。当父级和子级都设置了不透明度值时，子级最终的不透明度是其自身值与父级值的乘积。

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 700,
      height: 400,
      opacity: 0.7
    }}
    uiBackground={{ color: Color4.Green() }}
  >
    <UiEntity
      uiTransform={{
        width: 100,
        height: 30,
        opacity: 0.7
      }}
      uiText={{
        value: "这段文字的透明度更高",
        fontSize: 40
      }}
    />
  </UiEntity>
)

九宫格纹理

你可以使用 九切片缩放 配合你的纹理使用，以确保角落和边距不会被不均匀地拉伸。

使用这种流行的技术，你将一张图片切成 9 个部分，并以不同方式拉伸，以保持边距和角落的比例。例如，可用它来定义适配任意尺寸的圆角背景。请看下面这张图片（借自 维基百科):

在这张图片中，我们看到原始纹理（左上），以及以传统方式缩放后的结果（右上）；注意角落是如何变形的。其下方，我们看到被分割为 9 个切片的纹理（左下），然后是按照九宫格方法拉伸后的结果（右下）。

以下是每个切片的受影响方式，以上图为参考。

• 第 5 个切片是图片中唯一在 x 和 y 轴上都完全被拉伸的部分。

• 第 1、3、7 和 9 个切片（角落）完全不会被拉伸。

• 第 2 和 8 个切片只会在水平方向上拉伸

• 第 4 和 6 个切片只会在垂直方向上拉伸。

要在实体上使用九宫格拉伸，请将 textureMode 为 'nine-slices'。你还可以可选地在 textureSlices.

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'

export const uiMenu = () => (
  <UiEntity
    uiTransform={{ width: 700, height: 400 }}
    uiBackground={{
      textureMode: 'nine-slices',
      texture: {
        src: 'images/rounded_alpha_square.png'
      },
      textureSlices: {
        top: 0.2,
        bottom: 0.2,
        left: 0.2,
        right: 0.2
      }
	}}
  />
)

纹理 UV

使用 uvs 属性在一个 uiBackground 组件上，用于显示纹理的特定区域。这对于从精灵表中选取单个精灵，或用于旋转图像非常有用。

该 uvs 字段接受一个包含 8 个数字的数组，表示纹理区域四个角的 4 对 UV 坐标。顺序如下： 左下, 左上, 右上, 右下。每个值的范围为 0 到 1，其中 (0, 0) 是图像的左下角，而 (1, 1) 是右上角。

💡 提示：当使用自定义 uvs，请将 textureMode 为 'stretch' 时，以便所选区域填满实体的区域。

来自精灵表的精灵

要显示较大图像的一部分（例如，来自包含多个卡牌的精灵表中的一张卡牌），请将 uvs 设置为该区域的坐标。

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'

// 显示纹理的左半部分（例如，2 列精灵表中的第一张卡）
export const uiMenu = () => (
  <UiEntity
    uiTransform={{ width: 200, height: 300 }}
    uiBackground={{
      textureMode: 'stretch',
      texture: { src: 'images/card-atlas.png' },
      uvs: [
        // 左下、左上、右上、右下
        0, 0,
        0, 1,
        0.5, 1,
        0.5, 0
      ]
    }}
  />
)

对于带有帧网格的精灵表（例如，4 列 2 行的表），请根据你想要的帧所在的列和行来计算 UV：

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'

// 从网格精灵表中选取一个单独的帧
function getFrameUVs(col: number, row: number, totalCols: number, totalRows: number): number[] {
  const stepU = 1 / totalCols
  const stepV = 1 / totalRows
  const left = col * stepU
  const right = (col + 1) * stepU
  const top = 1 - row * stepV
  const bottom = 1 - (row + 1) * stepV
  return [
    left, bottom,
    left, top,
    right, top,
    right, bottom
  ]
}

// 显示 4x2 精灵表中的第 2 列、第 0 行
export const uiMenu = () => (
  <UiEntity
    uiTransform={{ width: 128, height: 128 }}
    uiBackground={{
      textureMode: 'stretch',
      texture: { src: 'images/spritesheet.png' },
      uvs: getFrameUVs(2, 0, 4, 2)
    }}
  />
)

使用 UV 旋转图像

你可以通过对 UV 坐标应用二维旋转来旋转纹理。这对于旋转指示器或加载动画很有用，而无需基于变换的旋转。

import { UiEntity, ReactEcs } from '@dcl/sdk/react-ecs'
import { engine } from '@dcl/sdk/ecs'

// 围绕中心旋转一个二维点
function rotate2D(angle: number, x: number, y: number, cx: number, cy: number): number[] {
  const cos = Math.cos(angle)
  const sin = Math.sin(angle)
  return [
    cos * (x - cx) - sin * (y - cy) + cx,
    sin * (x - cx) + cos * (y - cy) + cy
  ]
}

// 构建旋转后的 UV 坐标
function rotateUVs(angle: number): number[] {
  const uv00 = rotate2D(angle, 0, 0, 0.5, 0.5)
  const uv01 = rotate2D(angle, 0, 1, 0.5, 0.5)
  const uv11 = rotate2D(angle, 1, 1, 0.5, 0.5)
  const uv10 = rotate2D(angle, 1, 0, 0.5, 0.5)
  return [uv00[0], uv00[1], uv01[0], uv01[1], uv11[0], uv11[1], uv10[0], uv10[1]]
}

let spinnerAngle = 0

// 每帧更新角度的系统
engine.addSystem((dt: number) => {
  spinnerAngle += dt * 5
})

export const uiMenu = () => (
  <UiEntity
    uiTransform={{ width: 128, height: 128 }}
    uiBackground={{
      textureMode: 'stretch',
      texture: { src: 'images/spinner.png' },
      uvs: rotateUVs(spinnerAngle)
    }}
  />
)

该 rotateUVs 函数会围绕中心点按给定的弧度角旋转四个 UV 角点 (0.5, 0.5) 。由于这会被类似 React 的渲染器在每一帧调用，因此旋转指示器会平滑更新。

💡 提示：在 UI 动画 示例场景中查看包含精灵、动画精灵表、旋转指示器等内容的完整可运行示例。