Connect를 통해 페이지 아티팩트 표시하기

한눈에 보기

이 레시피에서는 페이지네이션 크롬(러닝 머리글과 바닥글, 페이지 번호, 워터마크, 배경)을 Connect 전송 계층을 통해 아티팩트 표시 콘텐츠로 감싸는 방법을 다룹니다. 크롬은 페이지에는 그대로 표시되지만, 구조 트리와 보조 기술 읽기 순서에서는 제외됩니다. 이 아티팩트 도구는 Enterprise 등급입니다. NextPDF는 class_exists() 프로브를 통해 이 도구를 발견하며, nextpdf/premium이 서버와 함께 설치된 경우에만 등록합니다. 서브타입은 타입 지정 열거형입니다(Pagination, Layout, Page, Background).

검증할 때는 Enterprise 표준 검사 도구를 사용하십시오. 이 도구는 PDF/UA-2를 기준으로 보고합니다. 통과 결과는 해당 도구의 검사 결과일 뿐이며, 독립적인 적합성 인증이 아닙니다.

설치

composer require nextpdf/server

tools/list 호출로 Enterprise 아티팩트 도구가 있는지 확인하십시오. /connect/tool-catalog/. 를 참조하십시오.

개념 개요

논리 구조의 일부가 아닌 콘텐츠는 아티팩트로 표시되어 읽기 순서에서 제외됩니다(PDF/UA-2 §8.3). 아티팩트는 페이지네이션, 레이아웃, 페이지 또는 배경 콘텐츠이며, 실제 콘텐츠와 구분됩니다(PDF/UA-2 §8.3). 실제 콘텐츠는 구조 트리에 반영되지만, 아티팩트는 반영되지 않습니다(PDF/UA-2 §8.2.4).

이 도구는 요청된 서브타입으로 아티팩트 표시 콘텐츠 시퀀스를 엽니다. 짝이 되는 닫기 호출 전까지 실행되는 모든 그리기 작업은 그 안에 감싸집니다.

API 표면

실행 중인 레지스트리를 기준으로 tools/list에서 도구 이름을 검증하십시오. 기준 카탈로그는 /connect/tool-catalog/.입니다. 이 레시피에서는 도구 개수를 다시 명시하지 않습니다.

코드 샘플 — 빠른 시작

Background 아티팩트를 열고 워터마크를 그린 다음 닫습니다.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Background" }
  }
}

코드 샘플 — 프로덕션

모든 열기 작업이 닫기 작업과 짝을 이루게 하고, 페이지에 고아 콘텐츠가 없는지 확인하십시오.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Page", "attached": "Bottom" }
  }
}

바닥글 텍스트를 그린 뒤 end-artifact 도구로 닫고, PDF/UA-2를 기준으로 표준 검사를 실행하십시오. 구조 트리에는 본문 콘텐츠만 포함되고, 워터마크와 바닥글은 제외되어야 합니다.

엣지 케이스 및 주의사항

알 수 없는 서브타입(예: "Header")은 거부됩니다. Pagination, Layout, Page, Background 중 하나를 전달하십시오.
열기 없는 닫기는 깊이 0 메시지와 함께 오류를 발생시킵니다. 항상 열기와 닫기를 짝지으십시오.
아티팩트나 구조 컨텍스트를 열기 전에 그리기를 수행하면 고아 콘텐츠와 구조 규칙 실패가 발생합니다. 먼저 구조 또는 아티팩트 컨텍스트를 여십시오.
도구 부재. nextpdf/premium이 없으면 Enterprise 아티팩트 도구가 등록되지 않으며, 호출은 알 수 없는 도구 오류로 실패합니다.

성능

프런트매터 예산은 문서에 명시된 상한값입니다. 아티팩트 래핑은 측정 가능한 별도 단계를 추가하지 않습니다.

보안 참고사항

일반적인 Connect 전송 지침을 넘어서는 추가 사항은 없습니다.

적합성

PDF/UA-2 매핑

서브타입	사용 사례
`Pagination`	러닝 headers/footers, 페이지 번호, 내비게이션 크롬
`Layout`	괘선, 구분선, 장식 테두리
`Page`	페이지에 종속된 보조 요소(재단 표시, 견당)
`Background`	워터마크, 배경 채우기, 브랜딩

태그 → ISO 32000-2 §14.9 상호 참조

주장	조항	reference_id
비구조 콘텐츠는 아티팩트로 표시되어 읽기 순서에서 제외됨	PDF/UA-2 §8.3
아티팩트 서브타입: pagination/layout/page/background	PDF/UA-2 §8.3
실제 콘텐츠는 구조 트리에 있지만, 아티팩트는 그렇지 않음	PDF/UA-2 §8.2.4

WCAG 2.2 매핑

장식용 크롬을 읽기 순서에서 제외하면 콘텐츠 수준에서 WCAG 2.2 SC 1.3.1(정보와 관계)을 지원합니다.

표준 검사 통과 결과는 하나의 검사 결과일 뿐, 적합성 인증이 아닙니다. 적합성 판정은 독립적인 검사 도구가 내립니다.

상업적 맥락

이 아티팩트 도구는 Enterprise 등급이며, nextpdf/premium이 서버와 함께 설치된 경우에만 등록됩니다.

Connect 세부사항

전송 계층 가용성(MCP / REST / gRPC)

MCP tools/call, REST 도구 엔드포인트, gRPC 서비스에서 이 도구들을 동일하게 호출할 수 있으며, 모두 공유 도구 실행기를 거칩니다.

HITL 위험 등급

아티팩트 발행과 콘텐츠 그리기는 주의 수준이고, 표준 검사는 읽기 전용입니다. 기본적으로 이들 중 어느 것도 approval_required가 아닙니다. /connect/hitl-risk-tiers/. 를 참조하십시오.

확인 게이트 JSON 엔벨로프

운영자 재정의로 이 중 하나가 approval_required로 상향되지 않는 한, 이 도구들은 게이트를 트리거하지 않습니다. 엔벨로프와 일회용 토큰 계약은 /connect/hitl-risk-tiers/.에 있습니다.

참고 항목

/cookbook/connect/aria-tagged-pdf/ — 랜드마크 역할 매핑.
/cookbook/connect/figure-caption/ — 접근 가능한 이미지 그룹화.
/connect/tool-catalog/ — 등급별 도구 집합 계산.
/connect/hitl-risk-tiers/ — 위험 모델과 게이트.