> 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에 텍스트를 추가하려면 다음을 생성하세요 `라벨` 엔터티.
하나의 `라벨` 엔터티에는 다음과 같이 설정할 수 있는 필드가 있습니다:
* `value`: 표시할 문자열
* `fontSize`: 텍스트의 크기이며, 숫자로 지정합니다.
> 참고: `fontSize` 해당 텍스트는 자신의 엔터티나 상위 엔터티의 크기의 영향을 받지 않습니다.
* `color`: 텍스트의 색상이며, [Color4](/creator/content-creator-ko/sdk7/3d/color-types.md).
* `font`: 사용할 글꼴입니다. 지원되는 값은 다음과 같습니다:
* `'serif'`
* `'sans-serif'` *(기본값)*
* `'monospace'`
* `fontSrc`: 다음으로의 경로 `.ttf` 장면의 글꼴 파일로, 텍스트를 사용자 지정 글꼴로 렌더링합니다. `font` 대체 글꼴로 사용됩니다. 다음을 참조하세요: [사용자 지정 글꼴](#custom-fonts).
* `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 %}
하나의 `라벨` 엔터티에는 다른 유형의 UI 엔터티에서 찾을 수 있는 다른 공통 구성 요소도 포함할 수 있습니다. 예를 들면 `uiTransform` 및 `uiBackground`.
***ui.tsx 파일:***
```ts
import { UiEntity, Label, ReactEcs } from '@dcl/sdk/react-ecs'
import { Color4 } from '@dcl/sdk/math'
export const uiMenu = () => (
)
```
***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 = () => (
)
```
명시적인 `height` 또는 `width` 가 다음에 설정되어 있지 않으면 `uiTransform` 컨테이너는 다음 값을 사용합니다: `auto`이며, 이는 모든 텍스트에 맞게 조정됩니다. 다음을 설정할 수 있습니다: `maxWidth` 및 `maxHeight` 를 설정해 특정 한계를 넘지 않도록 할 수 있습니다. 또한 다음도 사용할 수 있습니다: `minWidth` 및 `minHeight` 텍스트가 더 짧더라도 컨테이너가 너무 작아지지 않도록 합니다.
{% hint style="warning" %}
**📔 참고**: 텍스트의 자동 맞춤에 의존하지 마세요. 하나의 `라벨` 엔터티가 크기를 설정하지 않았을 때 차지하는 공간은 익스플로러마다 다릅니다. Bevy 기반 익스플로러는 렌더링된 텍스트를 측정하여 그에 맞게 배치합니다. Unity 익스플로러는 높이를 거의 주지 않지만 글자는 계속 그리므로, 쌓인 라벨들이 서로 겹치고 텍스트로 크기가 정해진 부모는 아무것도 남지 않게 됩니다.
모든 `라벨` 엔터티에 `width` **및** `height` 명시적인 `uiTransform`높이를 지정하세요. 그리고 라벨을 쌓는 모든 컨테이너에도 명시적인 높이를 지정하세요. 줄바꿈된 텍스트의 경우 줄 수에 맞게 높이를 정하세요: 두 줄은 `fontSize: 20` 에는 약 `height: 60`.
이것은 익스플로러마다 다르므로, 한 클라이언트에서 올바르게 보이는 미리보기가 다른 클라이언트에서도 레이아웃이 올바르다는 뜻은 아닙니다.
{% endhint %}
## 사용자 지정 글꼴
렌더링하려면 `라벨` 사용자 지정 글꼴로, TrueType(`.ttf`) 글꼴 파일을 장면 폴더에 추가하고 `fontSrc` 속성을 장면의 루트 폴더를 기준으로 한 해당 경로로 설정하세요. 또한 `font` 도 함께 설정해 두세요. 사용자 지정 글꼴을 불러올 수 없을 때마다 사용되는 대체 글꼴입니다.
{% hint style="warning" %}
**📔 참고**: `fontSrc` 에는 7.30.1보다 새로운 SDK 버전이 필요합니다. 7.30.1 이하에서는 이 속성이 존재하지 않습니다.
{% endhint %}
```tsx
```
다음 `버튼` 엔터티, `uiText` 의 `UiEntity` 및 [`Input` 및 `Dropdown`](/creator/content-creator-ko/sdk7/2d-ui/ui_special_types.md) 엔터티도 허용합니다 `fontSrc` 또한 다음도 마찬가지입니다: [`TextShape`](/creator/content-creator-ko/sdk7/3d/text.md#custom-fonts) 3D 공간의 텍스트용 컴포넌트입니다.
사용자 지정 글꼴을 사용할 때는 다음 사항을 유의하세요:
* **오직 `.ttf` 파일만 지원됩니다**. CFF 윤곽선을 사용하는 OpenType 글꼴(보통 `.otf`), 글꼴 컬렉션과 웹 글꼴은 지원되지 않으며, 텍스트는 대체 글꼴로 렌더링됩니다 `font`.
* **글꼴은 장면 안의 파일이어야 합니다**. `fontSrc` 외부 URL을 가리킬 수 없으며, 글꼴 패밀리 이름(예: Google Fonts의 이름)도 지원되지 않습니다. 다음 `.ttf` 파일을 다운로드하여 장면 폴더에 포함하세요. 라이선스가 재배포를 허용하는지 확인하세요.
* **데스크톱 클라이언트에서는 장면의 에셋이 최적화된 후에야 사용자 지정 글꼴이 표시됩니다**. 장면을 게시하면 글꼴은 3D 모델과 함께 최적화된 에셋 번들로 변환되며, 변환이 완료되면 사용자 지정 글꼴이 나타납니다. 그 전까지 텍스트는 대체 글꼴을 사용합니다 `font`. 로컬 미리보기에도 동일하게 적용됩니다. 사용자 지정 글꼴은 최적화된 에셋으로 미리보기할 때만 표시됩니다( **에셋 압축** 옵션 또는 `npm run start -- --asset-bundles` CLI에서). 다음을 참조하세요: [최적화된 에셋으로 미리보기](/creator/content-creator-ko/sdk7/getting-started/preview-scene.md#preview-with-optimized-assets). Bevy 웹 클라이언트는 다음을 로드합니다 `.ttf` 파일을 직접 불러오므로, 거기서는 사용자 지정 글꼴이 로컬 미리보기에서도 바로 표시됩니다.
* **모바일에서는 지원되지 않습니다**. Decentraland 모바일 앱은 다음을 무시하고 `fontSrc` 대체 글꼴로 렌더링합니다 `font`. 여전히 자연스럽게 보이는 대체 글꼴을 선택하고, 텍스트가 고정된 공간에 맞도록 사용자 지정 글꼴에 의존하지 마세요. 다음을 참조하세요: [모바일에서의 누락된 기능](/creator/content-creator-ko/build-for-mobile/mobile-client/missing-features.md).
* **글꼴에 포함되지 않은 문자는** 내장 sans-serif 글꼴로 그려집니다. 글꼴에 포함된 비라틴 문자는 처음 나타날 때 렌더링되며, 이로 인해 잠깐 끊김이 발생할 수 있습니다.
최대 파일 크기와 같은 제한의 전체 목록은 다음을 참조하세요: [사용자 지정 글꼴](/creator/content-creator-ko/sdk7/3d/text.md#custom-fonts) Text 페이지에서.
## UI 텍스트에 이모지를 사용하지 마세요
어떤 `라벨` 또는 `버튼` `value`, `uiText.value`, `Input` `placeholder`, 그리고 `Dropdown` 옵션.
SDK에는 이모지 글리프가 포함되어 있지 않습니다. 이모지가 표시될지는 각 익스플로러가 함께 제공하는 글꼴에 달려 있으며, Unity 익스플로러에는 없어서 문자가 빈 상자로 나오거나 아예 사라집니다. 화살표나 박스 그리기 문자 같은 다른 장식용 유니코드에도 같은 주의가 필요합니다.
그림형 라벨의 경우, 대신 아트를 제공하세요: 작은 `UiEntity` 텍스트 옆에 이미지를 배치하고, 다음을 사용하여 `uiBackground` 가 있는 `texture`. 다음을 참조하세요: [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 = () => (
)
```
## 반응형 텍스트 크기
다음 함수를 사용하세요: `scaleFontSize()` 플레이어의 화면 크기에 맞게 조정되는 글꼴 값을 제공하는 함수입니다. 텍스트 UI 엔터티의 `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 = () => (
)
```
다음 `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()` 는 다음을 반환합니다: **숫자**이므로, 그 결과는 *가상* 픽셀입니다. 그러나 여전히 다음 값에 곱해집니다: [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 = () => (
)
```
{% 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/2d-ui/ui_text.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.