제품 및 API 안내

표 데이터 빌더

빌더 열기

캔버스에서 표를 선택하세요. 속성 패널의 데이터 탭에서 데이터 빌더 열기를 선택합니다. 필드, 원본, 미리 보기 탭은 표 구조와 데이터를 분리해 다룹니다.

열과 요약 행

필드에서 열을 추가하고 각 제목과 데이터 필드를 설정합니다. 필요에 따라 너비, 서식, 고급 모양을 조정하세요. 표 아래에 합계, 소계, 메모 행을 추가할 수 있습니다. 계산 방법은 합계 섹션에서 설명합니다.

합계

합계나 소계 행에서 계산을 선택하세요. 합계, 평균, 최솟값, 최댓값, 행 수를 사용할 수 있습니다. 결과는 값 열에 표시되며, 해당 열의 모든 행을 기준으로 계산합니다. 행에 별도 서식이 없으면 열의 서식을 사용합니다.

JSON 
"summaryRows": [
  { "type": "total", "label": "총합계",
    "aggregate": "sum", "targetColumnKey": "total" }
]

숫자로 전달된 셀만 계산에 포함합니다. 빈 셀은 건너뛰며, 금액을 텍스트(“1,250.00”)로 보내면 결과가 비어 있습니다. 소계도 페이지별이 아니라 모든 행을 대상으로 합니다. 대신 데이터 필드를 선택하면 값 상자는 표가 아니라 데이터의 루트에서 읽습니다. 예를 들어 {{ grandTotal }}입니다.

원본 및 샘플 JSON

원본에서 표의 데이터 배열을 선택하고 샘플 JSON을 편집하세요. 열의 field는 배열 안 객체의 속성과 일치해야 합니다. 예를 들어 items의 quantity를 표시하려면 열의 field를 quantity로 설정합니다. 유효하지 않은 JSON 경고는 계속하기 전에 해결하세요.

기본 표 모양

품목 수량 합계
고장 진단21.700,00
연결 모듈12.850,00
현장 교정1850,00

다음 크기는 제품 기본값입니다. 머리글 40px, 행 40px, 셀 안쪽 여백 10px, 테두리 1px입니다. 템플릿에서 각각 바꿀 수 있습니다.

표 요소의 전체 작업 과정

표는 데이터의 배열에 바인딩되며 각 항목당 한 행을 그립니다. 아래 요소는 청구서 템플릿에 포함된 요소이며 그 아래 호출은 같은 표에 세 행의 데이터를 전달합니다.

JSON 
{
  "id": "invoice-items",
  "type": "table",
  "placementMode": "flow",
  "binding": "lineItems",
  "layout": { "x": 0, "y": 330, "width": 100, "widthUnit": "percent", "height": 220 },
  "style": {
    "tableHeaderHeight": 36,
    "tableRowHeight": 34,
    "tableRepeatHeader": true,
    "tablePreventRowSplit": true
  },
  "columns": [
    { "key": "name", "label": "설명", "valueTemplate": "{{ name }}",
      "align": "left", "widthPercent": 46 },
    { "key": "quantity", "label": "수량", "valueTemplate": "{{ quantity }}",
      "align": "right", "widthPercent": 14 },
    { "key": "unitPrice", "label": "단가", "valueTemplate": "{{ unitPrice }}",
      "align": "right", "widthPercent": 20,
      "format": { "kind": "currency", "currency": "USD", "decimals": 2 } },
    { "key": "total", "label": "금액", "valueTemplate": "{{ total }}",
      "align": "right", "widthPercent": 20,
      "format": { "kind": "currency", "currency": "USD", "decimals": 2 } }
  ]
}
cURL 
curl -X POST https://api.pdfgine.com/api/v1/render \
  -H "X-PDFgine-Key: $PDFGINE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "templateCode": "invoice",
        "format": "pdf",
        "locale": "ko",
        "data": {
          "document": { "title": "청구서 요약" },
          "referenceNo": "DOC-2026-0042",
          "issueDate": "2026-09-06",
          "currency": "USD",
          "customer": "Northwind Trading Ltd.",
          "lineItems": [
            { "name": "고장 진단", "quantity": 2, "unitPrice": 850.00 },
            { "name": "연결 모듈", "quantity": 1, "unitPrice": 2850.00 },
            { "name": "현장 교정", "quantity": 1, "unitPrice": 850.00 }
          ]
        }
      }'

binding은 데이터의 배열을, key는 각 항목의 필드를, valueTemplate은 출력할 내용을 지정합니다. tableRepeatHeader는 모든 페이지에 머리글을 반복하고 tablePreventRowSplit은 페이지 나눔에서 행이 잘리는 것을 막습니다.

긴 표 적용 및 테스트

미리 보기에서 열 순서, 빈 필드, 요약을 확인한 후 표에 변경 사항을 적용하세요. 이어 문서 미리 보기에서 0행, 1행, 많은 행을 테스트하세요. 긴 텍스트, 머리글 높이, 행 높이는 페이지 분할에 영향을 줍니다. 짧은 샘플만으로 판단하지 마세요.

차트와 보고서 →

dataset 요소

dataset 요소는 바인딩된 컬렉션을 표로 렌더링하며 데이터에서 열을 자동으로 정하므로 직접 선언하지 않습니다. 컬렉션의 구조가 템플릿이 아닌 페이로드로 정해질 때 사용하세요.

바인딩된 값 문서에 표시되는 내용
[{ "name": "…", "quantity": 2 }] 필드가 처음 나타나는 순서대로 필드당 하나의 열을 만듭니다. 어떤 행에 필드가 없어도 해당 열은 유지됩니다.
[{ "party": { "name": "…" } }] 중첩 객체는 최대 세 단계까지 party.name 같은 점 구분 열로 펼쳐집니다. 행 안의 배열은 한 셀에 유지됩니다.
["urgent", "warranty"] 값 자체가 셀에 들어가는 하나의 열이며 제목은 binding의 마지막 부분입니다.
{ "status": "released" } 한 행으로 표시되며 객체의 필드마다 하나의 열이 생깁니다.
[] 아무것도 그리지 않습니다. 바인딩되지 않은 dataset 요소도 아무것도 그리지 않습니다.

열 제목은 필드 이름입니다. dataset 요소에는 자체 라벨이 없으므로 열 이름을 직접 지정하려면 table 요소를 사용하세요.

자주 발생하는 문제

  • 데이터에 없는 배열을 binding으로 지정하면 오류가 아닌 빈 표를 그립니다. 표가 비어 있으면 binding과 요청의 키를 비교하세요.
  • 열의 key는 해당 배열 객체의 속성입니다. 키 하나의 철자가 틀리면 나머지 표는 정상이어도 그 열만 비게 됩니다.
  • 금액과 수량은 숫자로 전송해야 합니다. 문자열은 서식 설정을 건너뛰므로 열 정렬과 천 단위 구분 기호가 사라집니다.
  • 긴 표는 여러 페이지로 이어집니다. tableRepeatHeader가 없으면 두 번째 페이지가 제목 없이 시작되고 tablePreventRowSplit이 없으면 행이 반으로 잘릴 수 있습니다.
  • 0행, 1행, 여러 행을 테스트하세요. 세 행으로만 시험한 표에서는 빈 경우와 페이지 나눔 문제가 드러나지 않습니다.