그룹(자동 레이아웃)

.group()은 자식의 크기를 측정해 행이나 열로 자동 배치합니다. 자식마다 좌표를 정할 필요 없이 그룹의 위치만 지정하면 됩니다. 제목이 길어지거나 배지가 추가되면 각 자식의 원래 크기를 바탕으로 위치를 다시 계산하므로 같은 명세를 계속 쓸 수 있습니다. LLM으로 생성하는 레이아웃에도 적합한 방식입니다.

시그니처

canvas.group(
    children,
    direction="column",
    gap=0,
    padding=0,
    position=None,
    align=None,
    item_align="start",
)

매개변수

매개변수	자료형	기본값	설명
`children`	`list`	필수	쌓을 순서의 자식 레이어. dict 또는 `text`, `image`, `shape`, `svg`, `chart`, `qr_code`, 중첩된 `group` 레이어 모델입니다.
`direction`	`str`	`"column"`	주축 방향입니다. `"column"`은 위에서 아래로, `"row"`는 왼쪽에서 오른쪽으로 쌓습니다.
`gap`	`int`	`0`	주축에서 인접한 자식 사이의 간격(픽셀). 0 이상이어야 합니다.
`padding`	`int \\| tuple`	`0`	안쪽 여백. 정수 하나, `(vertical, horizontal)` 또는 `(top, right, bottom, left)`입니다.
`position`	`tuple \\| None`	`None`	그룹 상자의 기준점. 픽셀이나 백분율 문자열로 지정합니다.
`align`	`str \\| Align \\| tuple \\| None`	`None`	이미지 레이어처럼 `position`이 가리키는 그룹 상자의 기준점입니다. Align을 참고하세요.
`item_align`	`str`	`"start"`	각 자식의 교차축 배치. `"start"`, `"center"`, `"end"` 중 하나입니다.

자식에 position을 설정하지 마세요

그룹이 위치를 지정합니다. 자식에 position을 설정하면 ValidationError가 발생하며 자식의 align은 무시됩니다. 대신 그룹의 item_align을 사용하세요.

예제

세로로 쌓은 제목 블록

canvas = Canvas(1280, 720).background(color="#16213E").group(
    children=[
        {"type": "shape", "shape": "pill", "width": 120, "height": 36, "color": "#E94560"},
        {"type": "text", "content": "AUTO LAYOUT", "size": 96, "color": "#FFFFFF", "weight": 900},
        {"type": "text", "content": "No coordinates were harmed", "size": 40, "color": "#A2A8D3"},
    ],
    direction="column",
    gap=24,
    position=("8%", "50%"),
    align=("left", "middle"),
)

가로 배지 행

def chip(label):
    return {
        "type": "text",
        "content": label,
        "size": 24,
        "color": "#22D3EE",
        "weight": 700,
        "effects": [
            {"type": "background", "color": "#1D2547", "padding": [8, 14], "border_radius": 18},
        ],
    }

canvas.group(
    children=[chip("GROUPS"), chip("TOKENS"), chip("LINT")],
    direction="row",
    gap=14,
    position=("50%", "88%"),
    align=("center", "middle"),
)

중첩된 그룹

그룹은 중첩할 수 있으므로 열 안에 행을 넣거나 그 반대로 구성할 수 있습니다.

canvas.group(
    children=[
        {"type": "text", "content": "RELEASE 0.5", "size": 96, "color": "#FFFFFF", "weight": 900},
        {
            "type": "group",
            "direction": "row",
            "gap": 14,
            "children": [chip("GROUPS"), chip("TOKENS"), chip("LINT")],
        },
    ],
    direction="column",
    gap=28,
    position=("7%", "50%"),
    align=("left", "middle"),
)

교차축 정렬

canvas.group(
    children=[
        {"type": "text", "content": "CENTERED", "size": 80, "color": "#FFFFFF", "weight": 900},
        {"type": "text", "content": "Both children share a center line", "size": 36, "color": "#A2A8D3"},
    ],
    direction="column",
    gap=18,
    item_align="center",            # cross-axis: center each child horizontally
    position=("50%", "50%"),
    align=("center", "middle"),
)

크기 결정 방식

각 자식의 원래 크기(텍스트 경계, 이미지 크기, 도형의 width/height)를 측정합니다.
주축을 따라 gap만큼 간격을 두고 자식을 차례로 배치합니다.
자식들의 합집합에 padding을 더해 그룹 상자를 정합니다.
align에 따라 상자 전체의 기준점을 position에 맞춥니다.

JSON 표현

그룹도 다른 레이어와 같은 방식으로 직렬화합니다. 전체 스키마는 JSON Schema 문서를 참고하세요.

{
  "type": "group",
  "direction": "column",
  "gap": 24,
  "position": ["8%", "50%"],
  "align": ["left", "middle"],
  "item_align": "start",
  "children": [
    { "type": "text", "content": "AUTO LAYOUT", "size": 96, "color": "#FFFFFF", "weight": 900 }
  ]
}

검증 규칙

children은 비어 있지 않은 목록이어야 합니다.
자식은 position을 설정하면 안 됩니다. 그룹이 위치를 지정합니다.
유효한 자식 종류는 text, image, shape, svg, group입니다.
gap과 padding 값은 음수일 수 없습니다. 여백 튜플은 항목이 2개 또는 4개여야 합니다.