> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/2d-ui/ui_text.md).

# UI 텍스트

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

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

하나의 `Label` 엔티티에는 다음과 같은 구성 가능한 필드가 있습니다:

* `값`: 표시할 문자열
* `fontSize`: 텍스트의 크기를 숫자로 나타낸 값입니다.

  > 참고: `fontSize` 는 자신의 엔터티나 부모 엔터티의 크기에 영향을 받지 않습니다.
* `color`: 텍스트 색상, 다음 형식으로 [Color4](/creator/content-creator-ko/sdk7/3d/color-types.md).
* `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'`.

{% hint style="warning" %}
**📔 참고**:  `fontSize` 는 자신의 엔터티나 부모 엔터티의 크기에 영향을 받지 않습니다.
{% endhint %}

하나의 `Label` 엔티티에는 다른 유형의 UI 엔티티에서도 찾을 수 있는 다른 공통 컴포넌트도 있을 수 있으며, 예를 들어 `uiTransform` 및 `uiBackground`.

***ui.tsx 파일:***

```ts
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 파일:***

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

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

{% hint style="warning" %}
**📔 참고**: 이 페이지의 다음 모든 스니펫은 여러분이 `.ts` 와 유사한 `ReactEcsRenderer.setUiRenderer()` 함수를 실행 중이라고 가정합니다.
{% endhint %}

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

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

```ts
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` 텍스트가 더 짧더라도 컨테이너가 너무 작아지지 않도록 합니다.

{% hint style="warning" %}
**📔 참고**: 텍스트의 자동 맞춤에 의존하지 마세요. 다음이 차지하는 공간은 `Label` 의 크기를 지정하지 않았을 때 차지하는 공간은 탐색기마다 다릅니다. Bevy 기반 탐색기는 렌더링된 텍스트를 측정하여 그에 맞게 배치합니다. Unity 탐색기는 높이를 거의 주지 않지만 문자 자체는 계속 그리므로, 여러 레이블을 쌓아 놓으면 서로 겹치고 텍스트로 크기를 정한 부모는 아무것도 없는 것처럼 접혀버립니다.

모든 `Label` 명시적인 `width` **및** `height` 을 `uiTransform`, 그리고 레이블을 쌓는 모든 컨테이너에는 명시적인 높이를 지정하세요. 줄바꿈된 텍스트의 경우, 줄 수에 맞게 높이를 정하세요: 다음에서 두 줄은 `fontSize: 20` 약 `height: 60`.

이는 탐색기마다 다르므로, 한 클라이언트에서 올바르게 보이는 미리보기가 다른 클라이언트에서도 레이아웃이 올바르다는 것을 증명하지는 않습니다.
{% endhint %}

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

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

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

그림으로 된 레이블이 필요하다면, 대신 이미지를 포함하세요: 작은 `UiEntity` 텍스트 옆에 다음을 사용해 `uiBackground` 와 함께 `텍스처`. 자세한 내용은 [UI 배경](/creator/content-creator-ko/sdk7/2d-ui/ui_background.md).

```ts
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` 속성을 설정할 때는 단일 숫자 대신 이 함수를 전달하세요.

```ts
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"`

{% hint style="info" %}
**💡 팁**: 이 함수는 CSS의 `calc()` 함수를 실행 중이라고 가정합니다.
{% endhint %}

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

다음 공식은 `scaleFontSize()` 뒤따릅니다. 화면 너비 또는 높이에 `scaleUnit`를 곱하고, 거기에 `fontSize` 첫 번째 매개변수로 전달된 값을 더합니다.

```ts
최종 글꼴 = fontSize + (screen width * scaleUnit / 100)
```

예를 들어, 아래 스니펫은 `scaleUnit` 값 0.8을 사용합니다. 화면 너비가 *1280px*이면, 텍스트 크기는 **25.24**가 되며, 다음 수식을 따르게 됩니다 `15 + (1280 * 0.8 / 100)`.

{% hint style="warning" %}
**📔 참고**: `scaleFontSize()` 다음을 반환합니다: **number**, 따라서 결과는 *가상* 픽셀 단위의 크기입니다 — 하지만 그려지기 전에 여전히 [UI 배율 계수](/creator/content-creator-ko/sdk7/2d-ui/onscreen-ui.md#screen-virtual-scale) 에 곱해집니다. 위 예시에서 기본 `1920x1080` 가상 화면과 너비 1280px 캔버스를 사용하면, 스케일 팩터는 `1280 / 1920 = 0.667`이므로 텍스트는 약 16.8px로 렌더링됩니다. 가상 화면을 무시하고 캔버스를 기준으로 직접 측정되는 글꼴 크기를 원한다면, 다음을 전달하세요 `vw`/`vh` **문자열** 바로 `fontSize` 대신 사용하세요 — 예를 들어 `fontSize: '1.8vh'`.
{% endhint %}

```ts
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)
    }}
  />
)
```

{% hint style="info" %}
**💡 팁**: 테스트할 서로 다른 화면 크기가 없다면, Web Explorer를 사용하고 미리보기를 실행하는 창의 크기를 조절해 보세요. 창을 변경할 때마다 텍스트가 즉시 조정됩니다.
{% endhint %}

다음의 대안으로 `scaleFontSize()`, 다음을 전달하세요 `vw`/`vh` 문자열을 직접 다음 값으로 `fontSize` — 예를 들어 `fontSize: '1.8vh'` — 이 경우 텍스트 크기는 캔버스를 기준으로 정해지며 UI 스케일 팩터는 완전히 무시됩니다. 하지 마세요 **아닙니다** 글꼴 크기에 직접 계산한 배율을 곱하지 마세요 `UiCanvasInformation`: SDK가 이미 하나를 적용합니다. 다음을 참고하세요 [반응형 UI 크기](/creator/content-creator-ko/sdk7/2d-ui/ui-positioning.md#responsive-ui-size).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/2d-ui/ui_text.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.