QML
← 전체 컴포넌트

PDF Viewer

앱 안에서 PDF 문서를 표시하고 페이지 이동과 확대·축소 기능을 제공합니다.

import Syidax.Core.PdfViewer

지원 QML 타입

타입정의 / 역할
PDF를 열고 페이지 이동·확대를 제공하며 QtQuick.Pdf 모듈이 필요합니다.

예제로 보기

미리보기는 Qt 실행 화면의 이미지입니다. 아래 버튼으로 결과를 전환하세요.

01 기본 구성

QtQuick.Pdf 호스트의 PDF 미리보기입니다.

Qt 실행 화면 · 이미지
기본 구성 · 기본
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property string fileName: "quarterly-report.pdf"
        property bool showToolbar: true
        property bool downloadable: true
        property bool printable: true
        property bool fullscreenable: true
        property string emptyText: "선택된 PDF가 없습니다"
    }

    

    SyPdfViewer {
        src: Qt.resolvedUrl("docs/quarterly-report.pdf")
        width: 520
        height: 300
        fileName: storyArgs.fileName
        showToolbar: storyArgs.showToolbar
        downloadable: storyArgs.downloadable
        printable: storyArgs.printable
        fullscreenable: storyArgs.fullscreenable
        emptyText: storyArgs.emptyText
    }

}

02 loaded · failed · pageChanged · zoomChanged · fullscreenChanged · printRequested · downloadRequested

loaded({src,pageCount})는 실제 Ready 이후 발생합니다.

Qt 실행 화면 · 이미지
loaded · failed · pageChanged · zoomChanged · fullscreenChanged · printRequested · downloadRequested · 기본
QML 코드
import QtQuick
import Syidax.Core

Item {
    component EventLog: Rectangle {
        id: logBox
        property var lines: []
        implicitWidth: 440
        implicitHeight: Math.max(56, logText.implicitHeight + 24)
        radius: 4; color: Theme.semantic.backgroundBold
        function log(value) { lines = lines.slice(-3).concat([String(value)]) }
        Text {
            id: logText; x: 12; y: 12; width: parent.width - 24
            text: logBox.lines.length ? logBox.lines.join("\n") : "컨트롤을 조작하면 이벤트 결과가 표시됩니다."
            wrapMode: Text.Wrap; color: Theme.semantic.textDefault
            font.family: Theme.monoFontFamily; font.pixelSize: 12
        }
    }

    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    // Focused Gallery routes: keep only the selected API and its prerequisites.

    id: story

    

    Column {
        spacing: 12
        SyPdfViewer {
            id: pdf
            width: 520; height: 260
            src: Qt.resolvedUrl("docs/quarterly-report.pdf")
            onLoaded: (detail) => { if (true) { output.log(("loaded: %1").arg(detail.src)) } }
            onFailed: (detail) => { if (true) { output.log(("failed: %1").arg(detail.src)) } }
            onPageChanged: { if (true) { output.log(("pageChanged: %1").arg(pdf.page)) } }
            onZoomChanged: { if (true) { output.log(("zoomChanged: %1").arg(pdf.zoom)) } }
            onFullscreenChanged: { if (true) { output.log(("fullscreenChanged: %1").arg(pdf.fullscreen)) } }
            onPrintRequested: (detail) => { if (true) { output.log(("printRequested: %1").arg(detail.fileName)) } }
            onDownloadRequested: (detail) => { if (true) { output.log(("downloadRequested: %1").arg(detail.fileName)) } }
        }
        Row {
            spacing: 8
            SyButton { id: exampleControl1;  visible: true; text: "잘못된 파일 불러오기"; size: "small"; onClicked: pdf.src = Qt.resolvedUrl("docs/missing.pdf") }
            SyButton { id: exampleControl2;  visible: true; text: "샘플 PDF 다시 불러오기"; size: "small"; onClicked: { pdf.src = Qt.resolvedUrl("docs/quarterly-report.pdf"); pdf.reload() } }
        }
        EventLog { id: output }
    }
}

03 setPage · setZoom · reload · setToggle · printPdf

setPage는 native 탐색과 pageCount 범위를, setZoom은 25–400%를 사용합니다.

Qt 실행 화면 · 이미지
setPage · setZoom · reload · setToggle · printPdf · 기본
QML 코드
import QtQuick
import Syidax.Core

Item {
    component EventLog: Rectangle {
        id: logBox
        property var lines: []
        implicitWidth: 440
        implicitHeight: Math.max(56, logText.implicitHeight + 24)
        radius: 4; color: Theme.semantic.backgroundBold
        function log(value) { lines = lines.slice(-3).concat([String(value)]) }
        Text {
            id: logText; x: 12; y: 12; width: parent.width - 24
            text: logBox.lines.length ? logBox.lines.join("\n") : "컨트롤을 조작하면 이벤트 결과가 표시됩니다."
            wrapMode: Text.Wrap; color: Theme.semantic.textDefault
            font.family: Theme.monoFontFamily; font.pixelSize: 12
        }
    }

    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    // Focused Gallery routes: keep only the selected API and its prerequisites.
    id: featureStory

    Column {
        spacing: 24
        SyPdfViewer { id: pdf; width: 520; height: 240; src: Qt.resolvedUrl("docs/quarterly-report.pdf"); onPrintRequested: (detail) => output.log(detail.fileName) }
        Flow {
            width: 520
            spacing: 8
            SyButton { id: exampleControl1;  visible: true; text: "pdf.setPage(3)"; variant: "secondary"; size: "small"; onClicked: pdf.setPage(3) }
            SyButton { id: exampleControl2;  visible: true; text: "pdf.setZoom(150)"; variant: "secondary"; size: "small"; onClicked: pdf.setZoom(150) }
            SyButton { id: exampleControl3;  visible: true; text: "pdf.reload()"; variant: "secondary"; size: "small"; onClicked: pdf.reload() }
            SyButton { visible: true; text: "pdf.setToggle()"; variant: "secondary"; size: "small"; onClicked: pdf.setToggle() }
            SyButton { visible: true; text: "pdf.printPdf()"; variant: "secondary"; size: "small"; onClicked: pdf.printPdf() }
        }
        Text {
            text: "pdf.page === " + pdf.page + "   pdf.zoom === " + pdf.zoom + "   pdf.status === " + JSON.stringify(pdf.status)
            font.family: Theme.monoFontFamily
            font.pixelSize: 12
            color: Theme.semantic.textSubtle
        }
        EventLog { id: output }
    }
}

04 도구 모음 없는 문서

showToolbar 설정을 적용한 도구 모음 없는 문서 예제입니다.

Qt 실행 화면 · 이미지
도구 모음 없는 문서 · 실행 결과
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property string fileName: "quarterly-report.pdf"
        property bool showToolbar: false
        property bool downloadable: true
        property bool printable: true
        property bool fullscreenable: true
        property string emptyText: "선택된 PDF가 없습니다"
    }

    

    SyPdfViewer {
        src: Qt.resolvedUrl("docs/quarterly-report.pdf")
        width: 520
        height: 300
        fileName: storyArgs.fileName
        showToolbar: storyArgs.showToolbar
        downloadable: storyArgs.downloadable
        printable: storyArgs.printable
        fullscreenable: storyArgs.fullscreenable
        emptyText: storyArgs.emptyText
    }

}

05 보기 전용 문서

downloadable · printable 설정을 적용한 보기 전용 문서 예제입니다.

Qt 실행 화면 · 이미지
보기 전용 문서 · 실행 결과
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property string fileName: "quarterly-report.pdf"
        property bool showToolbar: true
        property bool downloadable: false
        property bool printable: false
        property bool fullscreenable: true
        property string emptyText: "선택된 PDF가 없습니다"
    }

    

    SyPdfViewer {
        src: Qt.resolvedUrl("docs/quarterly-report.pdf")
        width: 520
        height: 300
        fileName: storyArgs.fileName
        showToolbar: storyArgs.showToolbar
        downloadable: storyArgs.downloadable
        printable: storyArgs.printable
        fullscreenable: storyArgs.fullscreenable
        emptyText: storyArgs.emptyText
    }

}

06 화면 안의 문서

fullscreenable 설정을 적용한 화면 안의 문서 예제입니다.

Qt 실행 화면 · 이미지
화면 안의 문서 · 실행 결과
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property string fileName: "quarterly-report.pdf"
        property bool showToolbar: true
        property bool downloadable: true
        property bool printable: true
        property bool fullscreenable: false
        property string emptyText: "선택된 PDF가 없습니다"
    }

    

    SyPdfViewer {
        src: Qt.resolvedUrl("docs/quarterly-report.pdf")
        width: 520
        height: 300
        fileName: storyArgs.fileName
        showToolbar: storyArgs.showToolbar
        downloadable: storyArgs.downloadable
        printable: storyArgs.printable
        fullscreenable: storyArgs.fullscreenable
        emptyText: storyArgs.emptyText
    }

}

07 문서 파일 이름

fileName 설정을 적용한 문서 파일 이름 예제입니다.

Qt 실행 화면 · 이미지
문서 파일 이름 · 실행 결과
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property string fileName: "project-brief.pdf"
        property bool showToolbar: true
        property bool downloadable: true
        property bool printable: true
        property bool fullscreenable: true
        property string emptyText: "선택된 PDF가 없습니다"
    }

    

    SyPdfViewer {
        src: Qt.resolvedUrl("docs/quarterly-report.pdf")
        width: 520
        height: 300
        fileName: storyArgs.fileName
        showToolbar: storyArgs.showToolbar
        downloadable: storyArgs.downloadable
        printable: storyArgs.printable
        fullscreenable: storyArgs.fullscreenable
        emptyText: storyArgs.emptyText
    }

}

08 문서가 없는 상태

emptyText 설정을 적용한 문서가 없는 상태 예제입니다.

Qt 실행 화면 · 이미지
문서가 없는 상태 · 실행 결과
기본 실행 화면
QML 코드
import QtQuick
import Syidax.Core

Item {
    implicitWidth: Math.max(360, childrenRect.width)
    implicitHeight: childrenRect.height
    id: story

    property QtObject settings: QtObject {
        id: storyArgs
        property string fileName: "quarterly-report.pdf"
        property bool showToolbar: true
        property bool downloadable: true
        property bool printable: true
        property bool fullscreenable: true
        property string emptyText: "미리 볼 PDF를 선택하세요."
    }

    

    SyPdfViewer {
        width: 520
        height: 300
        fileName: storyArgs.fileName
        showToolbar: storyArgs.showToolbar
        downloadable: storyArgs.downloadable
        printable: storyArgs.printable
        fullscreenable: storyArgs.fullscreenable
        emptyText: storyArgs.emptyText
    }

}

API 36

항목을 가리키거나 선택하면 QML 예제와 복사 버튼이 나타납니다.

속성

이름타입 / 기본값설명
표시 문구와 인쇄·다운로드 요청에 쓰는 파일명입니다. PDF 소스는 바꾸지 않습니다.
뷰어의 이동·동작 도구 막대를 표시합니다.
다운로드 요청 버튼을 표시합니다. 실제 저장은 호스트가 처리합니다.
인쇄 요청 버튼을 표시합니다. 실제 인쇄는 호스트가 처리합니다.
전체 화면 버튼을 표시합니다. Escape로 프레임을 복원합니다.
src가 비어 있을 때의 문구입니다. 오류 대체 문구와는 별개입니다.

메서드

이름타입 / 기본값설명
setPage(n)으로 읽어들인 PDF를 이동합니다. n은 1부터 시작하며 실제 페이지 수 안으로 제한됩니다.
setZoom(percent)로 네이티브 배율을 바꿉니다. 25–400% 범위로 제한됩니다.
현재 소스를 다시 해석합니다. 성공하면 loaded, 실패하면 원인을 포함한 failed가 발생합니다.
전체 화면과 원래 프레임을 전환합니다. Escape로 원래 위치와 크기를 복원합니다.
소스가 있으면 호스트에 printRequested({src, fileName})를 전달합니다. 데모에서는 인쇄 작업을 여는 대신 요청을 표시합니다.

시그널

이름타입 / 기본값설명
PDF 해석이 Ready에 도달한 뒤에만 발생합니다. detail에는 src와 pageCount가 들어 있습니다. 유효한 로컬 PDF를 다시 불러와 확인하세요.
읽을 수 없거나 잘못된 파일, PDF 모듈 없음, 암호 필요, 지원하지 않는 원격 URL에서 발생합니다. detail.error에 원인이 표시됩니다.
이전·다음 버튼으로 페이지를 바꾸면 발생하는 속성 알림입니다. page는 1부터 pageCount까지이며 핸들러에서 page를 읽습니다.
확대·축소로 zoom이 바뀌면 발생합니다. 범위는 25–400%이며 네이티브 확대 동작도 동기화됩니다.
전체 화면과 복원을 전환해 프레임이 오버레이에 있는지 확인합니다. Escape로도 복원할 수 있습니다.
인쇄 버튼이 {src, fileName} 요청을 발생시킵니다. 데모는 요청을 로그에 표시하며 실제 인쇄는 호스트 앱에서 구현합니다.
다운로드 버튼이 {src, fileName} 요청을 발생시킵니다. 데모는 요청을 로그에 표시하며 파일 저장은 호스트 앱에서 구현합니다.

PDF 로딩 계약

항목동작 / 조건
SyPdfViewer는 선택 의존성 QtQuick.Pdf를 사용합니다. src는 로컬 file:/qrc: URL을 지원합니다. HTTP(S)는 호스트가 다운로드 후 로컬 URL을 전달하세요. 암호 문서는 호스트 어댑터가 필요하며 현재 컴포넌트는 준비 완료 대신 오류를 알립니다.

PDF 로딩 계약

상태 / 이벤트의미
src 없음. page=1, pageCount=0
뷰는 존재하지만 PDF 파싱은 끝나지 않음
PDF 해석이 Ready에 도달한 뒤에만 발생합니다. detail에는 src와 pageCount가 들어 있습니다. 유효한 로컬 PDF를 다시 불러와 확인하세요.
모듈 없음, 없는/읽을 수 없는/잘못된 파일, 암호 필요, 미지원 원격 source
읽을 수 없거나 잘못된 파일, PDF 모듈 없음, 암호 필요, 지원하지 않는 원격 URL에서 발생합니다. detail.error에 원인이 표시됩니다.

PDF 로딩 계약

항목동작 / 조건
readonly error로 오류를 읽고 fallbackText로 표시 문구를 지정합니다. src 교체 시 이전 뷰를 제거하고 늦은 콜백을 무시합니다. reload()는 현재 source를 다시 엽니다. QML 객체 생성만으로 loaded가 발생하지 않습니다.

탐색과 호스트 역할

항목동작 / 조건
page는 1부터 시작하며 ready 이후 pageCount로 제한합니다. setPage(n)는 native 탐색 API를 사용합니다. 뷰 안의 페이지 이동도 page에 반영합니다. zoom/setZoom(n)은 25–400%이며 native renderScale과 양방향 동기화합니다. pageChanged/zoomChanged는 일반 property 알림이므로 범위 밖 직접 대입은 정규화 알림도 발생할 수 있습니다. 같은 값 설정은 추가 loaded를 만들지 않습니다.
showToolbar, downloadable, printable, fullscreenable은 기본 true입니다. fileName은 src와 별개인 표시 정보입니다. labels(previous/next/zoomOut/zoomIn/print/download/fullscreen/restore), emptyText, fallbackText는 호스트가 번역합니다. 기본 크기는 480 × 640 논리 px입니다.
printPdf()/download()는 src가 있을 때 printRequested/downloadRequested({src,fileName})만 발생시킵니다. 인쇄·저장·네트워크는 호스트 역할입니다. setFullScreen()/setRestore()/setToggle()은 프레임을 창 overlay로 이동/복원하며 Escape로 복원합니다. document는 native 뷰 관찰용이며 readonly currentPage에 대입하지 마세요.
예제에는 QML 옆의 실제 report.pdf와 QtQuick.Pdf 호스트가 필요합니다. 둘 중 하나가 없으면 오류 경로가 정상입니다.

탐색과 호스트 역할

항목호출 예시
import QtQuick import Syidax.Core.PdfViewer SyPdfViewer { width: 720; height: 540 src: Qt.resolvedUrl("report.pdf") fileName: "report.pdf" onLoaded: (detail) => console.log("페이지", detail.pageCount) onFailed: (detail) => console.log("PDF 오류", detail.error) onPrintRequested: (detail) => console.log("호스트 인쇄 요청", detail.src) }
import QtQuick import Syidax.Core.PdfViewer SyPdfViewer { width: 720; height: 540 src: Qt.resolvedUrl("report.pdf") fileName: "report.pdf" onLoaded: (detail) => console.log("페이지", detail.pageCount) onFailed: (detail) => console.log("PDF 오류", detail.error) onPrintRequested: (detail) => console.log("호스트 인쇄 요청", detail.src) }
import QtQuick import Syidax.Core.PdfViewer SyPdfViewer { width: 720; height: 540 src: Qt.resolvedUrl("report.pdf") fileName: "report.pdf" onLoaded: (detail) => console.log("페이지", detail.pageCount) onFailed: (detail) => console.log("PDF 오류", detail.error) onPrintRequested: (detail) => console.log("호스트 인쇄 요청", detail.src) }
표시 문구와 인쇄·다운로드 요청에 쓰는 파일명입니다. PDF 소스는 바꾸지 않습니다.
PDF 해석이 Ready에 도달한 뒤에만 발생합니다. detail에는 src와 pageCount가 들어 있습니다. 유효한 로컬 PDF를 다시 불러와 확인하세요.
읽을 수 없거나 잘못된 파일, PDF 모듈 없음, 암호 필요, 지원하지 않는 원격 URL에서 발생합니다. detail.error에 원인이 표시됩니다.
인쇄 버튼이 {src, fileName} 요청을 발생시킵니다. 데모는 요청을 로그에 표시하며 실제 인쇄는 호스트 앱에서 구현합니다.