Report Viewer

TsgcHTMLComponent_ReportViewer는 매개변수 패널, PDF 미리 보기, PDF 다운로드, 인쇄, Excel로 내보내기와 함께 웹 페이지에 보고서를 표시합니다. 보고서는 TsgcHTMLReport이며, sgcHTML의 PDF 엔진으로 그룹, 합계, 차트, 바코드, 하위 보고서를 PDF로 출력하는 밴드형 보고서 엔진입니다. 외부 보고서 도구, 프린터 드라이버, DLL이 필요 없습니다. Delphi, C++ Builder, .NET에서 사용할 수 있습니다.

TsgcHTMLComponent_ReportViewer 및 TsgcHTMLReport

보고서를 밴드와 Parameters로 정의하고 뷰어에 연결한 다음 렌더링합니다. 뷰어는 매개변수로 폼을 만들며, 미리 보기, 다운로드, 인쇄는 사용자가 적용한 값으로 서버에서 생성한 동일한 PDF이므로 사용자가 보는 것이 곧 인쇄되는 것입니다. 서버는 요청 사이에 아무것도 보관하지 않습니다.

컴포넌트 클래스

TsgcHTMLComponent_ReportViewer는 뷰어이고, TsgcHTMLReport는 뷰어가 표시하는 비시각 보고서 엔진입니다

렌더링

매개변수 패널, PDF 뷰어의 내장 pdf.js로 그리는 미리 보기, PDF 다운로드, 인쇄, Excel로 내보내기 링크

언어

Delphi, C++ Builder, .NET

브라우저에서 보는 매개변수가 있는 판매 보고서

보고서는 필수 기간과 지역을 선언합니다. 뷰어는 이를 필드로 바꾸고, 보고서는 사용자가 적용한 값으로 자신의 OnBeforeGenerate 이벤트에서 데이터를 필터링합니다.

uses
  sgcHTML_Export_PDF, sgcHTML_Report, sgcHTML_Component_ReportViewer;

// 보고서
oReport := TsgcHTMLReport.Create(Self);
oReport.Title := 'Sales';
oReport.FileName := 'sales';
oReport.DataSet := qrySales;
oParam := oReport.Parameters.Add;
oParam.Name := 'Period';
oParam.Caption := 'Period';
oParam.Kind := rpkDateRange;
oParam.DefaultValue := '2026-01-01;2026-12-31';
oParam.Required := True;
oParam := oReport.Parameters.Add;
oParam.Name := 'Region';
oParam.Caption := 'Region';
oParam.Kind := rpkSelect;
oParam.Options.Add('EU=Europe');
oParam.Options.Add('US=United States');
oReport.OnBeforeGenerate := ReportBeforeGenerate;

// 세부 밴드: 행마다 한 줄
oBand := oReport.Bands.Add;
oBand.Kind := rbkDetail;
oItem := oBand.Items.Add;
oItem.Text := '[Product]';
oItem.Width := 100;
oItem := oBand.Items.Add;
oItem.Text := '[Amount:#,##0.00]';
oItem.Left := 100;
oItem.Width := 80;
oItem.Align := paRight;

// 뷰어
oViewer := TsgcHTMLComponent_ReportViewer.Create(Self);
oViewer.Name := 'SalesViewer';
oViewer.HTMXEngine := sgcHTMXEngine1;
oViewer.Report := oReport;
oViewer.TokenSecret := LoadSecretFromConfig;
oTemplate.BodyContent := oViewer.HTML;

// 보고서는 뷰어의 값으로 데이터를 필터링합니다
procedure TForm1.ReportBeforeGenerate(Sender: TObject; aParams: TStrings);
var
  vPeriod: string;
begin
  vPeriod := aParams.Values['Period'];   // from;to
  qrySales.Close;
  qrySales.ParamByName('FromDate').AsString := Copy(vPeriod, 1, Pos(';', vPeriod) - 1);
  qrySales.ParamByName('ToDate').AsString := Copy(vPeriod, Pos(';', vPeriod) + 1, 10);
  qrySales.ParamByName('Region').AsString := aParams.Values['Region'];
  qrySales.Open;
end;
@* Views/Reports/Sales.cshtml: SalesReport는 오래 유지되는 TsgcHTMLReport입니다 *@
@model ReportsModel

<sgc-report-viewer name="sales" report="@Model.SalesReport"
                   show-export-xlsx="true" zoom="page-width"
                   css-height="720px" token-lifetime="300"
                   on-before-generate="Model.CheckAccess" />
using esegece.sgcWebSockets;

// 보고서
var report = new TsgcHTMLReport();
report.Title = "Sales";
report.FileName = "sales";
var param = report.Parameters.Add();
param.Name = "Period";
param.Caption = "Period";
param.Kind = TsgcHTMLReportParameterKind.rpkDateRange;
param.DefaultValue = "2026-01-01;2026-12-31";
param.Required = true;
report.OnBeforeGenerate += (sender, values) => LoadSales(values);

// 뷰어
var viewer = new TsgcHTMLComponent_ReportViewer();
viewer.Name = "SalesViewer";
viewer.HTMXEngine = engine;
viewer.Report = report;
viewer.TokenSecret = configuration["Reports:Secret"];
template.BodyContent = viewer.HTML;

// 뷰어 없이 같은 보고서: 3분기 PDF
var values = new List<string> { "Period=2026-07-01;2026-09-30" };
report.SaveToFile("q3.pdf", values);

사용자가 얻는 것

값을 고르고, 보고서를 확인한 다음, 다운로드하거나 인쇄하거나 Excel에서 데이터를 여십시오.

매개변수 패널

보고서의 모든 매개변수는 레이블이 있는 필드가 됩니다. 텍스트, 숫자, 날짜, 시작과 종료가 있는 날짜 범위, Options 선택, 체크박스가 있습니다. 필수 매개변수는 별표가 표시되고 적용하기 전에 브라우저에서, 그리고 서버에서 다시 검사합니다. 초기화는 모든 필드를 기본값으로 되돌립니다.

PDF 미리 보기

미리 보기는 TsgcHTMLComponent_PDFViewer의 내장 pdf.js를 사용하며, 도구 모음, 페이지 이동, 확대/축소, 검색이 있습니다. 첫 페이지가 그려질 때까지 보고서 생성 중... 텍스트가 있는 스피너가 미리 보기를 덮습니다. AutoGenerate를 사용하면 미리 보기가 기본값으로 즉시 로드됩니다.

다운로드, 인쇄, Excel

PDF 다운로드와 인쇄는 미리 보기와 같은 PDF이며, 다운로드 파일 이름은 FileName을 따릅니다. Excel로 내보내기는 ExportToXLSX로 보고서의 데이터를 기록합니다. ShowDownload, ShowPrint, ShowExportXLSX로 각각 표시하거나 숨깁니다.

명확한 메시지

필수 값이 없으면 해당 필드가 표시되고 포커스가 그곳으로 이동합니다. 출력할 행이 없으면 미리 보기는 빈 PDF 대신 선택한 매개변수에 대한 데이터가 없습니다를 표시합니다. 거부되거나 실패한 생성은 그 사유를 표시하고 링크를 비활성화합니다. 텍스트는 라이브러리의 로캘에서 가져옵니다.

접근성과 키보드

뷰어는 레이블이 있는 영역입니다. 모든 필드에 레이블이 있고, 날짜 범위는 legend가 있는 fieldset이며, 필수 필드에는 aria-required가 있고 값이 없으면 aria-invalid가 설정됩니다. 필드에서 Enter 키를 누르면 매개변수가 적용되며, polite 라이브 리전이 필수 필드, 데이터 없음, 거부, 오류를 알립니다.

PDF로 출력하는 밴드형 보고서

뷰어 뒤에 있는 엔진은 독립된 비시각 컴포넌트입니다. sgcHTML의 PDF 엔진인 TsgcHTMLExportPDF로 PDF를 기록하며, 같은 보고서를 Excel 시트로도 기록할 수 있습니다.

밴드

보고서 머리글, 페이지 머리글, 머리글과 바닥글이 있는 중첩 그룹, 세부 행, 페이지 바닥글, 보고서 바닥글을 지원합니다. 그룹 머리글은 새 페이지마다 반복할 수 있고, KeepTogether는 그룹을 한 페이지에 유지하며, NewPageBefore와 NewPageAfter는 페이지를 나누고, NewPageAfter가 있는 보고서 머리글은 표지가 됩니다.

항목

밴드에는 텍스트, 이미지, 선, 사각형, 차트, 서식 있는 텍스트, 바코드, QR 코드, 하위 보고서를 넣을 수 있습니다. 텍스트는 상자에 맞게 잘리고, AutoHeight가 있는 항목은 줄바꿈된 텍스트에 맞게 밴드를 늘립니다.

식과 PrintIf

텍스트에는 [ ] 사이의 식을 넣을 수 있습니다. [Amount:#,##0.00]처럼 마스크가 있는 필드, [Sum(Field)], [Count], [Avg(Field)], [Min(Field)], [Max(Field)], [RunningSum(Field)], [Page] / [Pages], [Param.Name], [GroupValue]가 있습니다. 밴드와 항목은 Amount > 1000처럼 PrintIf 조건이 참일 때만 출력됩니다.

데이터 소스

행은 DataSet, Grid, RowsJSON의 JSON 배열 또는 OnGetRow 이벤트에서 가져옵니다. LoadFromGrid는 TsgcHTMLComponent_Grid의 열로 표 보고서를 만들며, 모든 페이지의 제목, 줄무늬 행, 숫자 열의 합계, 페이지 번호가 포함됩니다.

차트, 바코드, QR 코드

차트 항목은 밴드의 행을 벡터 그래픽으로 그립니다. 막대, 가로 막대, 누적 막대, 선, 영역, 원형, 도넛형이 있으며 그룹 밴드에서는 그룹마다 차트 하나를 그립니다. ChartSource는 TsgcHTMLComponent_Chart를 웹 페이지에 표시되는 모습 그대로 출력합니다. 바코드 항목은 Code 128을 그리고, QR 코드 항목은 오류 정정 수준 M을 사용합니다.

하위 보고서와 서식 있는 텍스트

하위 보고서 항목은 밴드 안에 다른 보고서, 예를 들어 주문의 품목을 출력하며, LinkFields로 마스터 행에 연결되고 최대 5단계까지 중첩되며 다음 페이지에서 이어집니다. 서식 있는 텍스트 항목은 HTML을 출력하고, AutoHeight가 있으면 페이지 머리글 뒤에서 여러 페이지에 걸쳐 흐릅니다.

글꼴과 언어

항목은 기본적으로 Windows-1252 문자를 담는 Base-14 글꼴로 출력됩니다. 키릴 문자, 그리스 문자, 아랍 문자, 히브리 문자, 중국어, 일본어, 한국어 또는 기호를 출력하려면 Fonts에 TrueType 글꼴을 등록하십시오. 출력된 글리프만 포함되며, FallbackFonts와 AutoFallback이 글꼴에 없는 문자를 대신합니다.

어디서나 같은 출력

숫자와 날짜는 컴퓨터의 지역 설정이 아니라 보고서의 DecimalSeparator, ThousandSeparator, DateFormat, TimeFormat으로 출력되므로, 보고서는 모든 컴퓨터와 .NET에서 똑같이 출력됩니다. CreationDate를 고정하면 같은 입력이 같은 PDF 바이트를 만듭니다.

JSON으로 보는 정의

SaveToJSON은 페이지 설정, 글꼴, 밴드, 항목, 매개변수를 기록하고, LoadFromJSON은 전체 정의를 검증한 뒤 오류의 JSON 경로와 함께 다시 읽습니다. 사용자는 Report Designer로 브라우저에서 보고서를 디자인하며, 보고서를 더블 클릭하면 Delphi IDE에서 같은 디자이너가 열립니다.

보고서 하나, 요청 여러 개

Generate, SaveToFile, SaveToStream, GetPDFBytes, ExportToXLSX, HasData는 각각 행과 레이아웃의 자체 사본을 만듭니다. 보고서 하나가 웹 서버의 여러 요청을 동시에 처리하며 각 요청은 자신의 매개변수로 필터링되고, 사용자 고유의 잠금은 필요 없습니다.

주요 속성, 메서드 및 이벤트

뷰어에서 가장 자주 사용하는 멤버입니다.

Report와 OnGetReport

Report는 표시할 TsgcHTMLReport입니다. 뷰어 하나가 모든 사용자를 처리하므로, 테넌트나 역할별 등 사용자마다 다른 보고서를 보여 주려면 요청의 스레드에서 발생하는 OnGetReport(Sender, aParams, aReport)에서 반환하십시오. 여기서 sgcHTMLRequestSession이 세션을 제공합니다.

OnBeforeGenerate

OnBeforeGenerate(Sender, aParams, aAccept, aErrorMessage)는 뷰어가 렌더링될 때, 적용할 때마다, 링크의 GET마다 생성을 수락하거나 거부하므로 복사한 링크도 거부됩니다. 권한과, 기간이 최대 1년이어야 하는 것처럼 매개변수 사이의 규칙에 사용하십시오.

서명된 링크

모든 파일 링크는 컴포넌트, 형식, 매개변수 값, 세션, 만료에 대한 HMAC-SHA256 토큰을 담고 있으며, 그것을 렌더링한 세션에서만 동작합니다. 링크는 TokenLifetime초(기본값 300) 후에 만료되고, 스크립트는 열어 둔 페이지를 위해 새 링크에 서명합니다. 로드 밸런서 뒤의 모든 서버에 같은 TokenSecret을 설정하십시오.

서버 상태 없음

값은 링크에 담겨 전달되고, 보고서는 OnGetReport와 OnBeforeGenerate가 다시 실행된 뒤 GET에서 생성됩니다. 파일은 Cache-Control: private, no-store로 제공되며, 잘못된 요청, 잘못된 토큰, 거부는 400 또는 403으로 응답합니다.

미리 보기 옵션

ShowParameters, ShowToolbar, ShowPageNav, ShowZoomControls, ShowSearch는 뷰어가 표시할 항목을 정하고, Zoom은 auto, page-width, fit 또는 백분율을 받으며, Theme과 CSSHeight는 미리 보기의 모양을 정합니다.

엔진 없이

ActionURL이 있고 HTMXEngine이 없으면, 호스트가 적용 전송을 DispatchComponentEvent로, 파일 링크를 DispatchComponentFile로 라우팅합니다. GetReportURL은 사용자 고유의 코드를 위해 같은 링크에 서명하며, 예를 들어 메시지에 한 기간의 PDF 링크를 담아 보낼 때 사용합니다.

ASP.NET Core

Razor 뷰에서는 <sgc-report-viewer> Tag Helper가 뷰어를 렌더링합니다. report는 오래 유지되는 TsgcHTMLReport를 받으며, 생략하고 on-get-report를 사용해도 됩니다. 적용은 컴포넌트 이벤트 엔드포인트로 전송되고 PDF 및 Excel 링크는 UseSgcHtml의 컴포넌트 파일 라우트가 제공하므로, 따로 매핑할 것이 없습니다.

데모

Demos\60.HTML\01.RunTime\31.ReportViewer는 포트 8133에서 동작하는 서버 sgc Sales Reports로 보고서 세 개가 있습니다. 지역별 막대 차트와 지역별 비중 도넛 차트가 있는 지역별 판매, 로고와 결제용 QR 코드와 Code 128 바코드가 있는 청구서, 그리드 출력물입니다. 새 주문 버튼은 주문을 추가하고, 모든 브라우저에서 열려 있는 미리 보기는 페이지의 WebSocket을 통해 매개변수를 다시 적용합니다. 디자인 타임, Lazarus, .NET 버전도 같은 구성입니다.

계속 살펴보기

온라인으로 체험eSeGeCe 데모 서버에서 실시간으로 실행되는 리포트 뷰어 데모로 확인해 보세요.
온라인 도움말뷰어의 전체 API 레퍼런스와 사용 가이드입니다.
TsgcHTMLReport 도움말보고서 엔진의 밴드, 식, 차트, 하위 보고서, 글꼴, JSON 정의입니다.
Report Designer 컴포넌트브라우저에서 보고서의 밴드, 항목, 매개변수를 디자인합니다.
PDF Viewer 컴포넌트보고서 미리 보기를 그리는 pdf.js 뷰어입니다.
모든 sgcHTML 컴포넌트80개 이상 컴포넌트의 전체 기능 매트릭스를 살펴보십시오.
무료 체험판 다운로드30일 체험판에는 60.HTML 데모 프로젝트가 포함되어 있습니다.
가격전체 소스 코드가 포함된 Single, Team 및 Site 라이선스.
최고의 가성비: All-Access모든 eSeGeCe 제품과 프리미엄 지원이 포함되어 연 €1,059부터 이용할 수 있어요.
All-Access 가격 보기

시작할 준비가 되셨습니까?

무료 체험판을 다운로드하고 Delphi, C++ Builder 및 .NET에서 웹 UI를 구축하기 시작하십시오.