UI 텍스트

UI 엔티티에 텍스트를 씁니다.

텍스트를 UI에 추가하려면 다음을 생성하세요 Label 엔티티를 사용해 플레이어 카메라 위치에서 앞으로 레이를 추적합니다.

하나의 Label 엔터티에는 다음과 같이 구성할 수 있는 필드가 있습니다:

value: 표시할 문자열
fontSize: 텍스트의 크기로, 숫자입니다.
참고: fontSize 는 해당 엔터티나 상위 엔터티의 크기에 영향을 받지 않습니다.
color: 텍스트의 색상, 다음 형식으로 Color4.
font: 사용할 글꼴. 지원되는 값은 다음과 같습니다:
- 'serif'
- 'sans-serif' (기본값)
- 'monospace'
textAlign: 텍스트가 부모와 어떻게 정렬될지 설정합니다. 다음의 값 중 하나를 사용합니다. TextAlignType 형식. TextAlignType = 'top-left' | 'top-center' | 'top-right' | 'middle-left' | 'middle-center' | 'middle-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
textWrap: 텍스트가 최대 너비를 초과하지 않도록 줄 바꿈을 사용할지 설정합니다. 기본값은 켜져 있습니다('wrap'), 비활성화하려면 값을 전달하세요 'nowrap'.

📔 참고: fontSize 는 해당 엔터티나 상위 엔터티의 크기에 영향을 받지 않습니다.

하나의 Label 엔터티에는 다른 유형의 UI 엔터티에서 볼 수 있는 다른 공통 컴포넌트도 포함할 수 있습니다. 예: uiTransform 과 uiBackground.

ui.tsx 파일:

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

export const uiMenu = () => (
	<UiEntity uiTransform={{ width: 'auto', height: 'auto' }}>
		<Label
			value="이것은 레이블입니다"
			color={Color4.Red()}
			fontSize={29}
			font="sans-serif"
			textAlign="top-left"
		/>
	</UiEntity>
)

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() 함수.

한 줄의 텍스트가 할당된 너비나 컨테이너의 최대 너비에 맞기에는 너무 길면, 텍스트는 다음 줄로 이어집니다. 다음의 값을 변경하면 이를 비활성화할 수 있습니다. textWrap 속성을 'nowrap'.

또한 명시적으로 다음을 추가하여 줄 바꿈을 강제할 수도 있습니다. \n 를 문자열에.

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

export const uiMenu = () => (
	<UiEntity uiTransform={{ width: 700, height: 400 }}>
		<Label 
			value="안녕하세요 세계!\n이 다른 부분은 꽤 깁니다. 아마 한 줄에 들어가지 않을 것이므로, 어딘가에서 줄 바꿈이 포함될 것입니다.\n네 번째 줄"
			textWrap= {`nowrap`} 
		/>
	</UiEntity>
)

명시적인 height 또는 width 가 설정되지 않은 uiTransform 경우 컨테이너는 값 auto를 사용합니다. 이는 모든 텍스트에 맞게 조정됩니다. 다음을 설정할 수 있습니다. maxWidth 와 하나의 maxHeight 를 사용하여 특정 한도를 초과하지 않도록 할 수 있습니다. 또한 다음을 사용할 수도 있습니다. minWidth 과 minHeight 를 사용하여 텍스트가 더 짧더라도 컨테이너가 너무 작아지지 않도록 합니다.

📔 참고: 텍스트의 자동 맞춤에 의존하지 마세요. 다음이 차지하는 공간은 Label 크기를 지정하지 않았을 때 차지하는 공간은 탐색기마다 다릅니다. Bevy 기반 탐색기는 렌더링된 텍스트를 측정해 그에 맞게 배치합니다. Unity 탐색기는 높이를 거의 주지 않지만 글자는 여전히 그리므로, 쌓인 레이블이 서로 겹치고 텍스트 크기로 정해진 부모는 아무것도 없는 것처럼 축소됩니다.

모든 Label 에 명시적인 width 과 height 를 uiTransform에 지정하고, 레이블을 쌓는 모든 컨테이너에는 명시적인 높이를 지정하세요. 줄 바꿈 텍스트의 경우 줄 수에 맞게 높이를 정하세요. 예를 들어 fontSize: 20 에는 약 height: 60.

가 필요합니다.

UI 텍스트에 이모지를 사용하지 마세요

어떤 Label 또는 Button value, uiText.value, Input placeholder, 그리고 드롭다운 옵션을 제공합니다.

SDK에는 이모지 글리프가 포함되어 있지 않습니다. 이모지가 표시되는지는 각 탐색기에 번들로 포함된 글꼴에 따라 달라지며, Unity 탐색기에는 아예 없으므로 문자는 빈 상자로 나오거나 완전히 사라집니다. 화살표나 박스 그리기 문자 같은 다른 장식용 유니코드에도 같은 주의가 적용됩니다.

그림이 있는 레이블은 대신 아트를 제공하세요: 작은 UiEntity 텍스트 옆에 이미지를 배치하고, 다음을 사용하세요. uiBackground 및 텍스처. 참고: UI 배경.

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

export const uiMenu = () => (
	<UiEntity
		uiTransform={{
			minWidth: 100,
			maxWidth: 300,
			height: 'auto',
			alignSelf: 'center',
			padding: 10,
		}}
		uiBackground={{
			color: Color4.Red(),
		}}
		uiText={{
			value: 'Hello world!',
			fontSize: 18,
		}}
	/>
)

반응형 텍스트 크기

다음을 사용하세요 scaleFontSize() 함수는 플레이어의 화면 크기에 맞춰 조정되는 글꼴 값을 제공합니다. 다음을 설정할 때 fontSize 속성에는 단일 숫자 대신 이 함수를 전달하세요.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 'auto',
      height: 'auto',
      alignSelf: 'center',
      padding: 10,
    }}
    uiText={{
      value: 'Hello world!',
      fontSize: scaleFontSize(15)
    }}
  />
)

이 scaleFontSize() 함수는 두 개의 매개변수를 필요로 합니다:

fontSize: 사용할 기본 글꼴 크기.
scaleUnit (선택 사항): 스케일링 계수. 이는 텍스트를 화면 너비 또는 높이를 기준으로 조정할지와, 얼마나 조정할지를 결정합니다. 기본값: 0.39 (숫자이며, 따라서 다음에 대한 상대값으로 해석됩니다. width). 값은 다음과 같습니다:
- 숫자: 단순한 숫자. 이 경우 다음에 대한 상대값으로 해석됩니다. width
- 다음으로 끝나는 문자열 vw: 이렇게 하면 숫자가 뷰 너비에 상대적이 됩니다. 예: "0.8vw"
- 다음으로 끝나는 문자열 vh: 이렇게 하면 숫자가 뷰 높이에 상대적이 됩니다. 예: "0.8vh"

💡 팁이 함수는 CSS의 calc() 함수.

의 값은 scaleUnit 창 너비 또는 높이의 백분율입니다. 따라서 scaleUnit 의 "100vw" 는 화면 너비의 100%이고, 값 "0.5vw" 는 화면 너비의 0.5%입니다.

다음 공식은 scaleFontSize() 이어지며, 화면 너비 또는 높이에 다음을 곱합니다. scaleUnit에, 그리고 여기에 fontSize 첫 번째 매개변수로 전달된 값을 더합니다.

final font = fontSize + (screen width * scaleUnit / 100)

예를 들어, 아래 스니펫은 scaleUnit 0.8의 값을 사용합니다. 화면 너비가 1280px이면, 이는 다음 크기의 텍스트를 생성합니다. 25.24다음 식을 따른 결과입니다. 15 + (1280 * 0.8 / 100).

📔 참고: scaleFontSize() 는 다음을 반환합니다. number따라서 결과는 가상 픽셀 단위의 크기입니다 — 이는 여전히 UI 스케일 팩터 에 곱해진 후 그려집니다. 위 예시에서는 기본 1920x1080 가상 화면과 너비 1280px의 캔버스를 사용하면 스케일 계수는 1280 / 1920 = 0.667이며, 따라서 텍스트는 약 16.8px로 렌더링됩니다. 가상 화면을 무시하고 캔버스를 기준으로 직접 측정되는 글꼴 크기를 원한다면, 다음을 vw/vh 문자열 에 바로 fontSize 대신 전달하세요 — 예: fontSize: '1.8vh'.

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

export const uiMenu = () => (
  <UiEntity
    uiTransform={{
      width: 'auto',
      height: 'auto',
      alignSelf: 'center',
      padding: 10,
    }}
    uiText={{
      value: 'Hello world!',
      fontSize: scaleFontSize(15, 0.8)
    }}
  />
)

💡 팁: 테스트할 다른 화면 크기가 없다면 Web Explorer를 사용하고 미리보기를 실행하는 창의 크기를 조정해 볼 수 있습니다. 창을 변경할 때마다 텍스트가 즉시 조정됩니다.

다음의 대안으로 scaleFontSize(), 다음을 전달하세요 vw/vh 문자열을 직접 다음으로 fontSize — 예: fontSize: '1.8vh' — 이는 캔버스를 기준으로 텍스트 크기를 정하고 UI 스케일 계수는 완전히 무시합니다. 하지 아닙니다 다음에서 직접 계산한 계수로 글꼴 크기를 곱하지 마세요 UiCanvasInformation: SDK가 이미 하나를 적용합니다. 다음을 보세요 반응형 UI 크기.

이전UI 특수 유형

다음동적 UI

마지막 업데이트 2일 전