在自訂應用程式中使用 RSClientPrint 控制項Using the RSClientPrint Control in Custom Applications

MicrosoftMicrosoft ActiveX 控制項 RSPrintClient 提供在 HTML 檢視器中檢視的報表之用戶端列印。The MicrosoftMicrosoft ActiveX control, RSPrintClient, provides client-side printing for reports viewed in HTML Viewer. 它提供 [列印] 對話方塊,讓使用者能夠起始列印工作、預覽報表、指定要列印的頁面,以及變更邊界。It provides a Print dialog box so that a user can initiate a print job, preview a report, specify pages to print, and change the margins. 在用戶端列印作業期間,報表伺服器會在影像 (EMF) 轉譯延伸模組中轉譯報表,然後使用作業系統的列印功能來建立列印工作,並將它傳送到印表機。During a client-side print operation, the report server renders the report in the Image (EMF) rendering extension and uses the print capabilities of the operating system to create the print job and send it to a printer.

用戶端列印提供控制及改善 HTML 報表的列印輸出品質的方式,亦即,利用使用者電腦上的瀏覽器列印設定,而不使用報表的頁面維度、邊界、頁首和頁尾文字,來建立列印輸出。Client-side printing provides a way to control and improve the quality of a printout for an HTML report by side-stepping browser print settings on the user's computer, and instead using the page dimensions, margins, header, and footer text of the report to create the print output. 列印控制項會讀取報表的屬性值,來設定頁面的大小和邊界。The print control reads property values of the report to set page size and margins.

想要在協力廠商工具列或檢視器上啟用用戶端列印功能的開發人員,可以透過 RSClientPrint COM 物件來存取 ActiveX 控制項。Developers who want to enable the client-side printing feature in third-party toolbars or viewers can access the ActiveX control through the RSClientPrint COM object. 此控制項可以自由散發。The control can be distributed freely. 下列清單提供使用此控制項的一些建議:The following list provides recommendations for using the control:

  • 使用此控制項即可改善網路架構報表的列印功能。Use the control to improve printing for Web-based reports. 您可以用任何與 MicrosoftMicrosoft .NET Framework.NET Framework 相容的程式設計語言或指令碼來指定物件。You can specify the object in any of the MicrosoftMicrosoft .NET Framework.NET Framework-compatible programming languages or in script. 此控制項並不是要用於 MicrosoftMicrosoft Windows Form 應用程式。The control is not intended for MicrosoftMicrosoft Windows Forms applications.

  • Reporting ServicesReporting Services 程式檔案複製 .cab 檔,然後將它加入自訂應用程式的程式碼庫。Copy the .cab file from the Reporting ServicesReporting Services program files and add it to your custom application code base.

  • 使用 <OBJECT> 標記即可指定控制項。Use an <OBJECT> tag to specify the control.

  • 在 OBJECT CODEBASE 屬性中,指定 .cab 檔的相對 URL 或完整 URL。Specify a relative or fully qualified URL to the .cab file in the OBJECT CODEBASE attribute.

  • 對 .cab 檔指定您自己的應用程式版本資訊,以追蹤在應用程式中使用的版本。Specify your own application version information for the .cab file to track which version is used in your application.

RSPrintClient 概觀RSPrintClient Overview

控制項會顯示自訂列印對話方塊,其中支援與其他列印對話方塊一樣的一般功能,包括預覽列印、可指定要列印的特定頁面及範圍、頁面邊界和列印方向等選擇。The control displays a custom print dialog box that supports features common to other print dialog boxes, including print preview, page selections for specifying specific pages and ranges, page margins, and orientation. 此控制項已封裝成 CAB 檔。The control is packaged as a CAB file. [列印] 對話方塊中的文字,已當地語系化成 SQL ServerSQL Server 支援的所有語言。The text in the Print dialog box is localized into all of the languages supported in SQL ServerSQL Server. RSPrintClient ActiveX 控制項會使用影像轉譯延伸模組 (EMF) 來列印報表。RSPrintClient ActiveX control uses the Image rendering extension (EMF) to print the report. 其中使用下列 EMF 裝置資訊:StartPage、EndPage、MarginBottom、MarginLeft、MarginTop、MarginRight、PageHeight 和 PageWidth。The following EMF device information is used: StartPage, EndPage, MarginBottom, MarginLeft, MarginTop, MarginRight, PageHeight, and PageWidth. 影像轉譯的其他裝置資訊設定則不支援。Other device information settings for image rendering are not supported.

語言支援Language Support

列印控制項會以不同的語言呈現使用者介面文字,並接受根據不同度量系統所輸入的值。The print control provides user interface text in different languages, and accepts input values calibrated to different measurement systems. 所使用的語言和度量系統是由 CultureUICulture 屬性來決定。The language and measurement system used are determined by the Culture and UICulture properties. 這兩個屬性都接受 LCID 值。Both properties accept LCID values. 如果您指定的 LCID 是受支援語言的變異語言,就會呈現最相近的語言。If you specify an LCID for a language that is a variation on a supported language, you will get the language that provides the closest match. 如果您指定的 LCID 不受支援,而且找不到其他相近的 LCID,就會呈現英文 (美國)。If you specify an LCID that is not supported and for which no other LCID is a close match, you will get English (United States).

在程式碼中使用 RSClientPrintUsing RSClientPrint in Code

RSClientPrint 物件的作用,是可以透過程式設計的方式存取 ActiveX 控制項及其方法和屬性。The RSClientPrint object is used to gain access programmatically to the ActiveX control and its methods and properties. 此控制項會提供預覽列印的強制回應對話方塊。The control provides a modal dialog for print preview.

指定預設值Specifying Default Values

您可以利用報表的邊界和頁面值,將 [列印] 對話方塊初始化。You can initialize the Print dialog box with margin and page values of the report. 根據預設,[列印] 對話方塊會以報表定義的值初始化。By default, the Print dialog box is initialized with values from the report definition. 您可以使用預設值,或設定物件的屬性來指定不同的值。You can use the defaults, or specify different values by setting properties on the object.

所有維度均以公釐表示。All dimensions are set in millimeters. 如果 CultureUICulture 已設定為不使用公制度量的地區,則度量的轉換會在執行階段發生。Measurement conversion occurs at run time if the Culture and UICulture are set to locales that do not use metric measurements.

若要了解哪些值用於頁面維度和邊界,您可以使用 GetProperties 方法來擷取預設值:To understand which values are used for page dimensions and margins, you can use the GetProperties method to retrieve the default values:

  • PageHeightPageWidth 會指定預設頁高和頁寬。PageHeight and PageWidth specify the default page height and width. 啟動列印控制項之後,就可以使用這些屬性值來選取目前選定印表機可用的最接近紙張大小。When the print control is launched, these property values are used to select the closest paper size available for the currently selected printer. 如果 PageWidth 大於 PageHeight,列印方向就會設定為 [橫向]。If PageWidth is great than PageHeight, the orientation is set to Landscape. 否則,就會設定為 [縱向]。Otherwise, it is set to Portrait.

  • 根據預設,LeftMarginRightMarginTopMarginBottomMargin 全部都設定為 12.2 公釐。LeftMargin, RightMargin, TopMargin, and BottomMargin are all set to 12.2 millimeters by default.

這些屬性是儲存在報表伺服器上的 Item 屬性集合內。These properties are stored in the Item properties collection on the report server. 每次更新報表定義時,就會覆寫這些值。The values are overwritten each time a report definition is updated.

RSClientPrint 屬性RSClientPrint Properties

屬性Property 類型Type RWRW 預設Default 描述Description
MarginLeftMarginLeft DoubleDouble RWRW 報表設定report setting 取得或設定左邊界。Gets or sets the left margin. 如果開發人員未設定或報表中未指定,則預設值為 12.2 公釐。The default value if not set by the developer or specified in the report is 12.2 millimeters.
MarginRightMarginRight DoubleDouble RWRW 報表設定report setting 取得或設定右邊界。Gets or sets the right margin. 如果開發人員未設定或報表中未指定,則預設值為 12.2 公釐。The default value if not set by the developer or specified in the report is 12.2 millimeters.
MarginTopMarginTop DoubleDouble RWRW 報表設定report setting 取得或設定上邊界。Gets or sets the top margin. 如果開發人員未設定或報表中未指定,則預設值為 12.2 公釐。The default value if not set by the developer or specified in the report is 12.2 millimeters.
MarginBottomMarginBottom DoubleDouble RWRW 報表設定report setting 取得或設定下邊界。Gets or sets the bottom margin. 如果開發人員未設定或報表中未指定,則預設值為 12.2 公釐。The default value if not set by the developer or specified in the report is 12.2 millimeters.
PageWidthPageWidth DoubleDouble RWRW 報表設定report setting 取得或設定頁寬。Gets or sets the page width. 如果開發人員未設定或是報表定義為 215.9 公釐,則為預設值。The default value if not set by the developer or the report definition is 215.9 millimeters.
PageHeightPageHeight DoubleDouble RWRW 報表設定report setting 取得或設定頁高。Gets or sets the page height. 如果開發人員未設定或是報表定義為 279.4 公釐,則為預設值。The default value if not set by the developer or the report definition is 279.4 millimeters.
文化特性Culture Int32Int32 RWRW 瀏覽器地區設定Browser locale 指定地區設定識別碼 (LCID)。Specifies the locale identifier (LCID). 此值會決定使用者輸入的度量單位。This value determines the unit of measurement for user input. 例如,若使用者鍵入 3,當語言為法文時,此值的度量單位是公釐,若語言為英文 (美國),則度量單位是英吋。For example, if a user types 3, the value will be measured in millimeters if the language is French or inches if the language is English (United States). 有效值包括:1028、1031、1033、1036、1040、1041、1042、2052、3082。Valid values include: 1028, 1031, 1033, 1036, 1040, 1041, 1042, 2052, 3082.
UICultureUICulture StringString RWRW 用戶端文化特性Client culture 指定對話方塊的字串當地語系化。Specifies string localization of the dialog box. [列印] 對話方塊中的文字會採用下列語言的當地語系化:簡體中文、繁體中文、英文、法文、德文、義大利文、日文、韓文和西班牙文。Text in the Print dialog is localized into these languages: Chinese-Simplified, Chinese Traditional, English, French, German, Italian, Japanese, Korean, and Spanish. 有效值包括:1028、1031、1033、1036、1040、1041、1042、2052、3082。Valid values include: 1028, 1031, 1033, 1036, 1040, 1041, 1042, 2052, 3082.
AuthenticateAuthenticate BooleanBoolean RWRW FalseFalse 指定控制項是否對報表伺服器發出 GET 命令,以起始連接來執行工作階段外的列印。Specifies whether the control issues a GET command against the report server to initiate a connection for out-of-session printing.

何時設定驗證屬性When to Set the Authenticate Property

當您在瀏覽器工作階段中列印時,不必設定 Authenticate 屬性。When you print from within a browser session, you do not need to set the Authenticate property. 在使用中工作階段的環境內,從列印控制項至報表伺服器的全部要求均透過瀏覽器來處理。Within the context of an active session, all requests from the print control to the report server are handled through the browser. 瀏覽器會設定對報表伺服器通訊的必要工作階段變數。The browser sets the session variables necessary for communication to the report server.

如果在工作階段外列印 (例如,未先開啟報表,就直接將報表傳送到印表機),列印控制項必須發出 HTTP GET 要求,以設定與報表伺服器之間的工作階段。If you print out-of-session (for example, sending a report directly to a printer without first opening it), the print control must issue an HTTP GET request to set up the session with the report server. 若要發出 GET 要求,請將 Authenticate 設為 TrueTo issue the GET request, you set Authenticate to True.

唯有使用 Windows 整合式安全性或基本驗證時,才需要發出 GET 要求。You only need to issue the GET request if you are using Windows integrated security or Basic authentication. 如果您使用表單驗證,則會忽略 Authenticate 屬性。If you are using forms authentication, the Authenticate property is ignored. 您的應用程式程式碼必須設定工作階段,並使用您提供的自訂安全性延伸模組來驗證使用者。Your application code must set the session and authenticate the user using the custom security extension that you provide. 如果您使用表單驗證,請將驗證 Cookie 的逾期值設定為可讓工作階段保留一段合理間隔時間的值。If you are using forms authentication, be sure to set the expiration value on the authentication cookie to a value that preserves sessions for a reasonable interval. 如果此值太小,則 Cookie 每次過期時,就會提示使用者提供登入認證。If the value is too low, users will be prompted to provide logon credentials each time the cookie expires.

CLSIDCLSIDs

當您執行內部部署報表時,會使用下列 CLSID 值。When you are running the report on-premises, you use the following CLSID values.

  • 41861299-EAB2-4DCC-986C-802AE12AC49941861299-EAB2-4DCC-986C-802AE12AC499

  • 5554DCB0-700B-498D-9B58-4E40E58144055554DCB0-700B-498D-9B58-4E40E5814405

  • 60677965-AB8B-464f-9B04-4BA871A2F17F60677965-AB8B-464f-9B04-4BA871A2F17F

當您在 Azure SQL Reporting 執行報表時,會使用下列 CLSID 值。When you are running the report in Azure SQL Reporting, you use the following CLSID values.

  • 3DD32426-554D-48C0-A200-65D3BF880E383DD32426-554D-48C0-A200-65D3BF880E38

  • 05662494-ACF9-446A-BE4C-7D3F7EA7F62F05662494-ACF9-446A-BE4C-7D3F7EA7F62F

RSPrintClient 支援 Print 方法RSPrintClient Support for the Print Method

RSClientPrint 物件支援用來啟動 [列印] 對話方塊的 Print 方法。The RSClientPrint object supports the Print method used to launch the Print dialog box. Print 方法具有下列引數。The Print method has the following arguments.

引數Argument I/OI/O 類型Type 描述Description
ServerPathServerPath In StringString 指定報表伺服器虛擬目錄 (例如 https://adventure-works/reportserver)。Specifies the report server virtual directory (for example, https://adventure-works/reportserver).
ReportPathParametersReportPathParameters In StringString 在報表伺服器資料夾命名空間內指定報表的全名,包括參數在內。Specifies the full name to the report in the report server folder namespace, including parameters. 報表是透過 URL 存取來擷取。Reports are retrieved through URL access. 例如:"/AdventureWorks Sample Reports/Employee Sales Summary&EmpID=1234"For example: "/AdventureWorks Sample Reports/Employee Sales Summary&EmpID=1234"
ReportNameReportName In StringString 報表的簡短名稱 (在上述範例中,簡短名稱為 Employee Sales Summary)。The short name of the report (in the example above, the short name is Employee Sales Summary). 它會出現在 [列印] 對話方塊及列印佇列中。It appears in the Print dialog box and in the print queue.

範例Example

下列 HTML 範例顯示如何在 JavaScript 中指定 .cab 檔、Print 方法和屬性:The following HTML example shows how to specify the .cab file, Print method, and properties in JavaScript:

<BODY onload="Print()">

<OBJECT ID="RSClientPrint" CLASSID="CLSID: 5554DCB0-700B-498D-9B58-4E40E5814405D3" CODEBASE="<URL to the .CAB file>#Version=<your application version information>" VIEWASTEXT></OBJECT>

<script language="javascript">

function Print()

{

RSClientPrint.MarginLeft = 12.7;

RSClientPrint.MarginTop = 12.7;

RSClientPrint.MarginRight = 12.7;

RSClientPrint.MarginBottom = 12.7;

RSClientPrint.Culture = 1033;

RSClientPrint.UICulture = 9;

RSClientPrint.Print('https://localhost/rtm', '%2fEmployee_Sales_Summary&ReportMonth=6&ReportYear=2004&EmpID=20', 'Employee_Sales_Summary')

}

</script>

</BODY>

另請參閱See Also

使用列印控制項從瀏覽器列印報表 (報表產生器及 SSRS) Print Reports from a Browser with the Print Control (Report Builder and SSRS)
列印報表 (報表產生器及 SSRS) Print Reports (Report Builder and SSRS)
影像裝置資訊設定Image Device Information Settings