跳到主要内容

<Element/>

Element 在实体上绘制文本、图像或不可见组，位于 Screen 下，可使用屏幕或世界空间。type 为 text、image 或 group，anchor 和 pivot 控制相对布局。

用法​

在 Screen 后代实体中添加 Element。文本指定 type=text 与 fontAsset，可通过 useFont 加载。

<Entity name="label">
  <Element
    type="text"
    fontAsset={font}
    text="Hello, World!"
    fontSize={84}
    anchor={[0.5, 0.5, 0.5, 0.5]}
    pivot={[0.5, 0.5]}
  />
</Entity>

以下显示屏幕空间文本，MSDF 字体由 font-tools 创建，再由 useFont 加载。

屏幕空间文本 - 查看代码

详见 ElementComponent。

属性​

名称类型与说明默认值
screen?
Entity | null
此组件所属的带 ScreenComponent 的实体。组件位于 ScreenComponent 的子层级时自动设置。
-
anchor?
[number, number, number, number]
设置或获取元素锚点，按左、下、右、上指定相对父级的位置，各值范围 0 到 1。[0, 0, 0, 0] 锚定左下角，[1, 1, 1, 1] 锚定右上角。左右或上下值不同时为分离锚点，元素会调整尺寸覆盖对应区域，例如 [0, 0, 1, 1] 与父级尺寸一致。更新时使用 setter。
-
batchGroupId?
number
设置或获取元素所属的批处理组（BatchGroup），默认 -1，即无分组。
-
bottom?
number
设置或获取相对锚点底边的距离。结合分离锚点可使元素底边始终与底部相距 bottom 个单位。
-
calculatedWidth?
number
设置或获取元素实际渲染宽度。通常与 width 相同，但受 LayoutGroupComponent 等布局控制时，calculatedWidth 可能大于或小于编辑器中设置的宽度。
-
calculatedHeight?
number
设置或获取元素实际渲染高度。通常与 height 相同，但受 LayoutGroupComponent 等布局控制时，calculatedHeight 可能大于或小于编辑器中设置的高度。
-
drawOrder?
number
设置或获取组件绘制顺序，值越大越显示在其他组件上方。
-
height?
number
设置或获取编辑器中指定的元素高度。受 LayoutGroupComponent 等控制时，可能不同于实际渲染高度；读取实际高度请使用 calculatedHeight。
-
layers?
readonly number[]
设置或获取元素所属图层 ID 数组（Layer#id）。不要直接 push、pop、splice 或修改数组，应赋入新数组。
-
left?
number
设置或获取相对锚点左边的距离。结合分离锚点可让元素左边始终距左侧 left 个单位。
-
margin?
[number, number, number, number]
设置或获取相对锚点左、下、右、上边缘的距离。若锚点为 [0, 0, 1, 1]、边距为 [0, 0, 0, 0]，元素宽高与父级一致。更新边距时使用 setter。
-
pivot?
[number, number]
设置或获取组件枢轴相对锚点的位置，各值范围 0 到 1。[0, 0] 为左下角，[1, 1] 为右上角。更新时使用 setter。
-
right?
number
设置或获取相对锚点右边的距离。结合分离锚点可让元素右边始终距右侧 right 个单位。
-
top?
number
设置或获取相对锚点顶边的距离。结合分离锚点可让元素顶边始终距顶部 top 个单位。
-
type?
string
设置或获取元素类型。ELEMENTTYPE_GROUP 用于组织布局组，如面板；ELEMENTTYPE_IMAGE 渲染图像；ELEMENTTYPE_TEXT 渲染文字。
-
useInput?
boolean
设置或获取组件是否接收鼠标与触摸输入事件。
-
fitMode?
string
设置或获取元素适配模式，仅用于 ELEMENTTYPE_IMAGE。FITMODE_STRETCH 拉伸到元素边界；FITMODE_CONTAIN 保持源纹理或精灵宽高比并完整容纳；FITMODE_COVER 保持宽高比并覆盖整个元素边界。
-
width?
number
设置或获取编辑器中指定的元素宽度。受 LayoutGroupComponent 等控制时可能不同于实际渲染宽度，读取实际宽度请使用 calculatedWidth。
-
fontSize?
number
设置或获取字号，单位与元素宽高相同，因此屏幕实际尺寸取决于屏幕空间或世界空间模式。默认 32，仅用于 ELEMENTTYPE_TEXT。
-
minFontSize?
number
设置或获取 autoFitWidth 或 autoFitHeight 为 true 时可缩放到的最小字号，默认 8。
-
maxFontSize?
number
设置或获取 autoFitWidth 或 autoFitHeight 为 true 时可缩放到的最大字号，默认 32。
-
maxLines?
number | null
设置元素最多换行数，剩余文字追加到最后一行。设为 null 表示不限；获取时若无限制则返回 -1。
-
autoFitWidth?
boolean
设置或获取是否自动缩放字号和行高以适应元素宽度，字号范围为 minFontSize 至 maxFontSize。autoWidth 为 true 时忽略 autoFitWidth。
-
autoFitHeight?
boolean
设置或获取是否自动缩放字号和行高以适应元素高度，字号范围为 minFontSize 至 maxFontSize。autoHeight 为 true 时忽略 autoFitHeight。
-
color?
string
设置或获取元素在 sRGB 色彩空间中的颜色，IMAGE 用于图像、TEXT 用于文字。仅使用 RGB，忽略 Alpha，透明度请使用 opacity。更新颜色时使用 setter。
-
font?
Font | CanvasFont
设置或获取渲染文字的字体，仅适用于 ELEMENTTYPE_TEXT。
-
fontAsset?
number | Asset<string> | null
设置渲染文字的字体资源，可传 Asset 或资源 ID，仅适用于 ELEMENTTYPE_TEXT。获取时返回字体资源 ID。
-
spacing?
number
设置或获取文字字距，以默认字符前进量的倍率表示，默认 1。小于 1 更紧凑，大于 1 更疏松，仅用于 ELEMENTTYPE_TEXT。
-
lineHeight?
number
设置或获取文字行高，单位与 fontSize 相同，但独立于字号，可调整垂直行距。默认 32，仅用于 ELEMENTTYPE_TEXT。
-
wrapLines?
boolean
设置或获取是否根据元素宽度自动换行。仅适用于 ELEMENTTYPE_TEXT，且 autoWidth 必须为 false。
-
justify?
boolean
设置或获取是否通过扩展词间距使换行后的文本两端对齐。末行、显式换行结束的行和没有可扩展间隙的行仍按 alignment 对齐。仅用于 ELEMENTTYPE_TEXT，且 wrapLines 为 true、元素宽度固定时有效。
-
alignment?
[number, number]
设置或获取文字的水平和垂直对齐，范围 0 到 1。[0, 0] 为左下角，[1, 1] 为右上角，仅用于 ELEMENTTYPE_TEXT。
-
autoWidth?
boolean
设置或获取是否自动将组件宽度设为 textWidth，仅用于 ELEMENTTYPE_TEXT。
-
autoHeight?
boolean
设置或获取是否自动将组件高度设为 textHeight，仅用于 ELEMENTTYPE_TEXT。
-
rtlReorder?
boolean
设置或获取是否为从右向左书写的语言重排文字，使用 app.systems.element.registerRtlReorder 注册的函数。
-
unicodeConverter?
boolean
设置或获取是否转换 Unicode 字符，使用 app.systems.element.registerUnicodeConverter 注册的函数。
-
text?
string
设置或获取待渲染文本，仅用于 ELEMENTTYPE_TEXT。可用方括号标记覆盖逐字符样式：color 覆盖 color，例如 [color="#ff0000"]red text[/color]，绿色和蓝色分别可用 #00ff00、#0000ff；outline 覆盖 outlineColor 和 outlineThickness，例如 [outline color="#ffffff" thickness="0.5"]text[/outline]；shadow 覆盖 shadowColor 和 shadowOffset，例如 [shadow color="#ffffff" offset="0.5"]text[/shadow] 或 [shadow color="#000000" offsetX="0.1" offsetY="0.2"]text[/shadow]。只有 enableMarkup 为 true 时才处理这些标记。
-
key?
string
设置或获取从 Application#i18n 获取本地化文本的键，仅用于 ELEMENTTYPE_TEXT。
-
texture?
Texture
设置或获取待渲染纹理，仅用于 ELEMENTTYPE_IMAGE。
-
textureAsset?
number | Asset<string> | null
设置待渲染纹理资源，可传 Asset 或资源 ID，仅用于 ELEMENTTYPE_IMAGE。获取时返回资源 ID。
-
material?
Material
设置或获取图像渲染使用的材质，仅用于 ELEMENTTYPE_IMAGE。
-
materialAsset?
number | Asset<string> | null
设置图像渲染使用的材质资源，可传 Asset 或资源 ID，仅用于 ELEMENTTYPE_IMAGE。获取时返回资源 ID。
-
sprite?
Sprite
设置或获取待渲染精灵，仅用于可显示纹理或精灵的 ELEMENTTYPE_IMAGE。
-
spriteAsset?
number | Asset<string> | null
设置待渲染精灵资源，可传 Asset 或资源 ID，仅用于可显示纹理或精灵的 ELEMENTTYPE_IMAGE。获取时返回资源 ID。
-
spriteFrame?
number
设置或获取要渲染的精灵帧，仅用于已指定精灵的 ELEMENTTYPE_IMAGE。
-
pixelsPerUnit?
number | null
设置或获取每个 PlayCanvas 单位对应的像素数，仅影响使用九宫格或平铺精灵的 ELEMENTTYPE_IMAGE。设为 null 时使用精灵自身的像素单位比。
-
opacity?
number
设置或获取元素不透明度，适用于 ELEMENTTYPE_IMAGE 和 ELEMENTTYPE_TEXT。
-
rect?
Readonly<Vec4> | null
设置或获取渲染图像所用纹理区域，以 0 到 1 范围表示 u、v、width、height。仅用于 ELEMENTTYPE_IMAGE，更新区域时使用 setter。
-
mask?
boolean
设置或获取是否将 Image 元素作为遮罩。遮罩本身不绘制到场景，而是限制子元素仅在其覆盖范围内渲染。
-
outlineColor?
string
设置或获取文字描边颜色与不透明度，颜色使用 sRGB 空间，仅用于 ELEMENTTYPE_TEXT。
-
outlineThickness?
number
设置或获取文字描边宽度，范围 0（无描边）到 1（最大厚度），默认 0。结合 outlineColor 设置样式，仅用于 ELEMENTTYPE_TEXT。
-
shadowColor?
string
设置或获取文字阴影颜色与不透明度，颜色使用 sRGB 空间，仅用于 ELEMENTTYPE_TEXT。
-
shadowOffset?
[number, number]
设置或获取文字阴影相对文字的偏移。阴影是按 shadowColor 着色的文字副本，各分量范围 -1 到 1，并与字号成比例，因此缩放时保持一致。正 X 向右，正 Y 向上。阴影只绘制在超出字形的部分，默认 [0, 0] 不显示，需非零偏移。仅用于 ELEMENTTYPE_TEXT。
-
enableMarkup?
boolean
设置或获取是否启用文字标记处理，默认 false，仅用于 ELEMENTTYPE_TEXT。
-
rangeStart?
number
设置或获取首个渲染字符的索引，仅用于 ELEMENTTYPE_TEXT。
-
rangeEnd?
number
设置或获取最后一个渲染字符的索引，仅用于 ELEMENTTYPE_TEXT。
-
system?
ComponentSystem
创建此组件的 ComponentSystem。
-
entity?
Entity
此组件挂载的 Entity。
-
enabled?
boolean
设置或获取组件的启用状态。
-