AGENT SKILL
13-ui-component-size-fitter
暂无简介
适用职业设计师
- License 许可
- MIT
- 最近更新
- 2026-04-12
- Stars
- ★ 0
- Forks
- 0
03 SKILL.md 正文
13-ui-component-size-fitter
Status: ACTIVE AppliesTo: v11
Purpose
UIComponentBaseSizeFitter 계열은 RectTransform 크기/레이아웃을 화면 기준으로 자동 보정하는
ExecuteAlways UI 컴포넌트 묶음이다.
이 스킬은 아래 2개를 통합한다.
UIComponentSafeSizeFitter— safe area 기준 anchor/offset 보정UIComponentCanvasSizeFitter—Image를 부모/canvas 영역에 비율 유지로 맞춤
같은 GameObject에 size-fitter 계열을 2개 이상 붙이는 것은 지원하지 않는다.
조합이 필요하면 parent = safe, child = canvas/image fit 계층으로 분리한다.
Scope
Includes
UIComponentBaseSizeFitter : UIComponentBase- baseline layout capture / restore
- disable / domain reload 시 baseline 복원
OnEnable/ parent 변경 / 해상도 변경 / orientation 변경 refresh- world-space canvas no-op
- same-object size-fitter 중복 guard
UIComponentSafeSizeFitterUIComponentCanvasSizeFitter
Excludes
LayoutGroup과의 우선순위 조정- 같은
GameObject에서 safe fit + canvas fit 동시 적용 - image crop / mask / shader 보정
- device-specific safe area override
SSOT
Code Path
framework-cs/upm/com.devian.foundation/Samples~/UIPackage/Runtime/Component/
├── UIComponentBase.cs
├── UIComponentBaseSizeFitter.cs
├── UIComponentSafeSizeFitter.cs
└── UIComponentCanvasSizeFitter.cs
Classes
namespace Devian
{
public abstract class UIComponentBaseSizeFitter : UIComponentBase
{
public RectTransform Target { get; }
public void Refresh();
}
public sealed class UIComponentSafeSizeFitter : UIComponentBaseSizeFitter
{
public enum SafeAreaApplyMode
{
Anchor,
Offset,
}
}
public sealed class UIComponentCanvasSizeFitter : UIComponentBaseSizeFitter
{
public enum CanvasSizeFitMode
{
Inner,
Outer,
}
}
}
Common Base
Responsibilities
UIComponentBaselifecycle 통합- baseline capture / restore
Refresh()진입 전 baseline 복원 후 재계산WorldSpacecanvas early return- editor domain reload 전 baseline 복원
- same-object 중복 size-fitter warning
OnValidate에서EditorApplication.delayCall로 Refresh 지연 (SendMessage 경고 방지)onInit에서isActiveAndEnabledguard — 비활성화 상태면 Refresh를 건너뛰고OnEnable시 실행
Serialized Base Fields
[SerializeField] private bool _refreshOnEnable = true;
[SerializeField] private bool _refreshOnResolutionChange = true;
[SerializeField] private bool _refreshOnOrientationChange = true;
[SerializeField, HideInInspector] private RectTransform _baselineTarget;
[SerializeField, HideInInspector] private Vector2 _baselineAnchorMin;
[SerializeField, HideInInspector] private Vector2 _baselineAnchorMax;
[SerializeField, HideInInspector] private Vector2 _baselineOffsetMin;
[SerializeField, HideInInspector] private Vector2 _baselineOffsetMax;
[SerializeField, HideInInspector] private Vector2 _baselineSizeDelta;
[SerializeField, HideInInspector] private bool _hasBaseline;
UIComponentSafeSizeFitter
Behavior
- target은 self
RectTransform - safe area source:
- runtime:
Screen.safeArea - editor: simulation profile
- runtime:
Anchor:- safe rect를 0..1 anchor로 변환 (apply 체크된 edge만)
- non-applied edge의 anchor는 원본 유지
Offset:- safe inset을
offsetMin/offsetMax에 반영 (apply 체크된 edge만) - non-applied edge의 offset은 원본 유지
- safe inset을
- non-applied edge 보호:
CaptureCustomRefreshState에서 baseline restore 전 rect 스냅샷(_preRestore)을 캡처ApplySizeFitter말미에RestoreNonAppliedEdges로 non-applied edge의 anchor+offset을_preRestore로 복원_preservePreRestore플래그로onInit/OnDisable→OnEnable경로에서_preRestore오염 방지
- 마지막 적용 상태:
LastAppliedSafeAreaLastOrientationIsApplied
Policy
- 전체 safe root, HUD bar, 화면 모서리 버튼 루트에 사용
- 배경 이미지 stretch 용도에는 직접 쓰지 않는다
UIComponentCanvasSizeFitter
Required Component
Image(RequireComponent(typeof(Image)))
Behavior
- source image:
overrideSprite우선- 없으면
sprite
- fitting area:
- 우선 parent
RectTransform.rect.size - 없으면 root canvas rect
- 우선 parent
- sprite 비율을 유지한다
Inner:- contain
- fitting area 안에 완전히 들어오면서 가장 크게 맞춤
Outer:- cover
- fitting area 전체를 덮으면서 가장 작게 맞춤
RectTransform.SetSizeWithCurrentAnchors()로 width/height만 반영한다
Policy
- fullscreen/background image, splash image, banner image에 사용
- safe area와 같이 써야 하면 parent에
UIComponentSafeSizeFitter, child image에UIComponentCanvasSizeFitter를 둔다 - 같은
GameObject에 2개 이상 size-fitter를 붙이지 않는다
Naming
- 사용자 요구의
outter는 오탈자로 보고 enum 값은Outer를 사용한다. UIComponentCanvasSizeFitter는 raw screen pixel이 아니라 canvas-space fitting을 의미한다.
Reference
- Parent: 00-overview
- Base: 10-ui-component-base
- Debug: UIComponentSafeSizeFitter_Debug_Guide