跳到主要内容

<pc-element>

<pc-element> 添加界面基础元素组件，通过 type 选择 group、image 或 text，各类型支持的属性不同。

它不是基类或通用包装，而是引擎的二维 UI 组件 entity.element，为宿主提供可绘制图像、文本或不绘制内容的矩形。

通常在 <pc-screen> 上布局，但并非必需，例如文本示例的滚动字幕没有屏幕。没有屏幕祖先时，按实体变换定位，尺寸使用世界单位，32 × 32 就是 32 米，详见无屏幕元素。

用法
备注

图像可绘制纹理或精灵，包括由精灵 <pc-asset> 的 sliced 或 tiled 模式提供的九宫格和平铺，也可作为 mask 裁切后代。只有文本需要 font-asset。

属性​

属性类型默认值说明
alignmentVector2"0.5 0.5"文本水平和垂直对齐，各分量 0 到 1。0.5 0.5 居中，0 1 左上，仅文本
anchorVector4"0 0 0 0"父项上的左、下、右、上锚点，各分量 0 到 1，0 0 0 0 为左下，1 1 1 1 为右上。某轴两值不等则分离，按父项和 margin 拉伸，忽略对应 width 或 height。anchor="0 0 1 1" 配 margin="0 0 0 0" 填满父项，详见锚点
auto-fit-heightBoolean"false"从 max-font-size 缩小到 min-font-size 以适应高度，忽略 font-size，需关闭 auto-height，仅文本
auto-fit-widthBoolean"false"从 max-font-size 缩小到 min-font-size 以适应宽度，忽略 font-size，需关闭 auto-width，仅文本
auto-heightBoolean"true"是否按文本自动调整高度，仅文本
auto-widthBoolean"true"是否按文本自动调整宽度，仅文本
colorColor"1 1 1 1"图像或文字颜色，与纹理相乘，白纹理可染任意色。Alpha 忽略，透明度请用 opacity
enable-markupBoolean"false"是否解析局部样式标签，例如颜色标记，详见标记，仅文本
enabledBoolean"true"组件启用状态
fit-modeEnum"stretch"stretch 拉伸填满并忽略比例；contain 保持比例完整容纳；cover 保持比例填满但可能溢出，可用父 mask 裁切，仅图像
font-asset资源 ID-必须引用 font 类型 <pc-asset>，仅文本必需
font-sizeNumber"32"屏幕单位字号，仅文本
heightNumber"32"屏幕单位高度，垂直分离锚点或文本 auto-height 时忽略
justifyBoolean"false"通过扩大词间距将换行对齐两侧，需 wrap-lines 和固定宽度。最后一行与显式换行行仍遵循 alignment，仅文本
letter-spacingNumber"0"类似 CSS letter-spacing，按字号比例附加字间距。0.1 增加字号十分之一，负值收紧，在 spacing 之外叠加，仅文本
line-heightNumber"32"相邻行基线的屏幕单位距离，不随 font-size 自动变化，增大字号时应同时调整以免重叠，仅文本
marginVector4-分离锚点轴上的左、下、右、上边距，正值向内。省略时保留默认 0 0 -32 -32，导致右上各超出 32，因此分离锚点时应显式设置，详见边距
maskBoolean"false"是否按矩形或纹理／精灵不透明形状裁切后代。遮罩自身不显示，color 无效，详见遮罩，仅图像
max-font-sizeNumber"32"自动适配的最大及起始字号，仅文本
max-linesNumber-换行的最大行数，剩余文本追加到末行，省略不限制，仅文本
min-font-sizeNumber"8"自动适配最小字号，仅文本
opacityNumber"1"不透明度，0 透明，1 不透明，不影响子项
outline-colorColor"0 0 0 1"描边颜色，outline-thickness 大于 0 才绘制，仅文本
outline-thicknessNumber"0"描边厚度，0 无，最大 1，仅文本
pivotVector2"0 0"定位、旋转和缩放的轴心，按自身尺寸比例。0 0 为左下，0.5 0.5 为中央
pixels-per-unitNumber-覆盖精灵每单位像素数，决定切片或平铺边框宽度。b 像素边框为 b / pixels-per-unit 个屏幕单位。简单精灵直接拉伸，因此此值无效，仅图像
shadow-colorColor"0 0 0 1"阴影颜色，shadow-offset 非 0 0 才绘制，仅文本
shadow-offsetVector2"0 0"阴影 X Y 偏移，范围 -1 到 1，按字号比例。正值向右和上，0 0 不绘制，仅文本
spacingNumber"1"正常字间距的倍率，仅文本
sprite-asset资源 ID-要渲染的精灵 <pc-asset> ID，仅图像
sprite-frameNumber"0"精灵帧索引，仅图像
textString-显示文本，仅文本
texture-asset资源 ID-要渲染的纹理 <pc-asset> ID，仅图像
typeEnum"group"元素类型：group、image 或 text
use-inputBoolean"false"是否接收鼠标、触摸和 XR 并触发事件。按钮、滚动内容拖动和滚动条滑块均需要，详见启用输入
widthNumber"32"屏幕单位宽度，水平分离锚点或文本 auto-width 时忽略
wrap-linesBoolean"false"是否按元素宽度换行，需要 auto-width=false 或水平分离锚点，仅文本

示例​

image 面板上放两个 text，第二个启用标记以局部染色。可修改 text、font-size 或面板 color：

实时示例
<pc-app>
    <pc-asset src="https://developer.playcanvas.com/assets/fonts/arial.json" type="font" id="arial"></pc-asset>
    <pc-scene>
        <pc-entity name="camera">
            <pc-camera clear-color="#1d1f2b"></pc-camera>
        </pc-entity>
        <pc-entity name="ui">
            <pc-screen screen-space="true" scale-mode="blend" reference-resolution="640 320"></pc-screen>
            <pc-entity name="panel">
                <pc-element type="image" anchor="0.5 0.5 0.5 0.5" pivot="0.5 0.5"
                            width="400" height="150" color="#2a2d36" opacity="0.9"></pc-element>
                <pc-entity name="heading" position="0 35 0">
                    <pc-element type="text" anchor="0.5 0.5 0.5 0.5" pivot="0.5 0.5"
                                font-asset="arial" font-size="36" text="<pc-element>"></pc-element>
                </pc-entity>
                <pc-entity name="body" position="0 -25 0">
                    <pc-element type="text" anchor="0.5 0.5 0.5 0.5" pivot="0.5 0.5"
                                font-asset="arial" font-size="20" enable-markup="true"
                                text='Comes in [color="#ff8a3c"]group[/color], [color="#7ab8ff"]image[/color] and [color="#8ce99a"]text[/color] types'></pc-element>
                </pc-entity>
            </pc-entity>
        </pc-entity>
    </pc-scene>
</pc-app>

JavaScript 接口​

可以通过 ElementComponentElement API创建和操作元素。

component 是底层 ElementComponent，就绪前为 null，其余功能可通过它访问。

另请参阅​

示例：二维屏幕、文本和界面布局。