8.3.3.2 JavaScript API

在业务应用系统的网页中使用HTML5报表查看器时，可以调用葡萄城报表提供的JavaScript API以控制报表查看页面的行为。

（1）初始化选项

在使用HTML5查看器时，可以在初始化期间或运行时设置以下选项。

• uiType
  说明：设置HTML5 Viewer的界面模式。
  类型：字符串可接受值：'Custom', 'Mobile' 或者 'Desktop'
  示例：
  viewer.option('uiType', 'Mobile');
  
  
• element
  说明：JQuery选择器，指定承载HTML5 Viewer控件的元素。
  注意：此选项仅在初始化期间使用。
  类型：字符串
  示例：
  var viewer = GrapeCity.ActiveReports.Viewer({element: '#viewerContainer2', reportService: {url: '/ActiveReports.ReportService.asmx'},});
  
  
• reportService
  说明：可以使用葡萄城报表服务。
  类型：具有url和可选securityToken属性的对象
  示例：
  reportService: {url: 'http://remote-ar-server.com/api', securityToken: '42A9CD80A4F3445A9BB60A221D042FCC', resourceHandler: ' http://remote-ar-server.com/cache'};
  
  
• reportService.url
  说明：提供报表相关信息和输出的葡萄城报表服务的URL。
  类型：字符串
  示例：
  reportService: { url: 'http://remote-ar-server.com/api' };
  
  
• reportService.securityToken
  说明：登录葡萄城报表服务器所需的安全密钥。
  类型：字符串
  示例：
  reportService: { securityToken: '42A9CD80A4F3445A9BB60A221D042FCC'};
  
  
• reportService.resourceHandler
  说明：葡萄城报表服务器资源处理程序的URL。
  类型：字符串
  示例： reportService: { resourceHandler: ' http://remote-ar-server.com/cache'};
  
  

• report 
  说明：显示在葡萄城报表服务器中的报表。
  类型：具有id和参数属性的对象。 
  示例： 
  report: {
      id: 'CustomersList',
      parameters: [
      {
         name: 'CustomerID',
         value: 'ALFKI'
      }
     ]
   };
  
  

• reportID 
  说明：要由HTML5查看器显示的报表的ID。 
  类型：字符串
  示例： 
  report: {
      id: 'CustomersList',
      parameters: [
      {
         name: 'CustomerID',
         value: 'ALFKI'
      }]
   };

• reportParameters 
  说明：描述用于运行报表的参数值的{name，value}对的数组。
   类型：数组 
  示例： report: {
      id: 'CustomersList',
      parameters: [
      {
         name: 'CustomerID',
         value: 'ALFKI'
      },
      {
         name: 'productIDs',
         value: [10248, 10249],
         multivalue: true
      }]
   };

• reportLoaded
  说明：当HTML5查看器获取有关请求的报表的信息时调用的回调。
  reportInfo对象在回调中传递，包括目录信息，参数信息以及指向呈现的报表结果的链接。
  类型：function(reportInfo)
  示例：
  var reportLoaded = function reportLoaded(reportInfo){ console.log(reportInfo.parameters); };
  viewer.option('reportLoaded', reportLoaded);
  
  
• action
  说明：在HTML5查看器之前调用的回调打开超链接，书签链接，向下钻取报表或切换报表控件的可见性。
  类型：function(actionType, actionParams)
  示例：
  function onAction(actionType, actionParams){
    if (actionType === 0){ window.open(params.url, "Linked from report", "height=200,width=200"); }
  }
  viewer.option('action', onAction);
  
  

• availableExports 
  说明：通过HTML5查看器的导出功能可用的导出类型数组。 默认情况下，PDF，Word，图像，Mht和Excel导出可用。
  类型：数组 
  示例： 
  viewer.option("availableExports", ['Pdf']);

• maxSearchResults
  说明：单次查找收到的查找结果数量调用。
  类型：数字
  示例：
  maxSearchResults:10
  
  
• error
  说明：在显示报表的过程中发生错误时调用的回调。 如果回调返回true，则不显示默认错误面板。 错误参数是一个具有消息属性的对象，允许用户自定义错误消息。
  类型：function(error)
  示例：隐藏默认错误面板
  var options = {
    error: function(error){
      if (error.message) {
        // show error message.
        alert("Internal error! Please ask administrator.");
        return true; // do not show default error message.
      }
    },
    // other properties.
  };
  var viewer = GrapeCity.ActiveReports.Viewer(options);
  示例：自定义错误消息
  var options = {
    error: function(error){ error.message = "My error message"; },
    // other properties
  };
  var viewer = GrapeCity.ActiveReports.Viewer(options);
  
  
• documentLoaded
  说明：当文档完全加载到服务器时调用的回调。
  类型：function()
  示例：
  var documentLoaded = function documentLoaded(){ setPaginator(); }; 
  viewer.option('documentLoaded', documentLoaded);
  
  
• localeUri
  说明：包含本地化字符串的文件的URL。
  注意：此选项仅在初始化期间使用。
  类型：字符串
  示例：
  var viewer = GrapeCity.ActiveReports.Viewer({ localeUri: 'Scripts/i18n/ru.txt' });
  
  
• showOnlyLastError
  说明：删除错误面板中的显示详细信息按钮，仅显示最后一个错误。
  类型：字符串示例：隐藏"显示详细信息"按钮
  var viewer = GrapeCity.ActiveReports.Viewer({ showOnlyLastError: true });

（2）公共的方法和属性

初始化HTML5 Viewer后，可以使用以下API方法和属性。
方法

• option 
  说明：通过名称获取选项值，如果指定了value参数，则设置选项值。
  语法：option(name, [value]) Object
  参数：
    name：要获取或设置的选项名称。
    value：（可选）要设置的选项值。 如果省略此参数，则该方法返回当前选项值。
  示例： 
  viewer.option('uiType', 'mobile');
  viewer.option('report', {
    id: 'my report'
  });
  返回值：当前选项值。
  
  

• refresh 
  说明：刷新报表预览。
  语法：option(name, [value]) Object 
  示例： 
  viewer.refresh() 
  返回值：void
  
  

• print
  说明：打印当前显示的报表。
  语法：print() void
  示例： viewer.print()
  返回值：void
  
  
• goToPage
  说明：使查看器显示特定页面，滚动到特定的offset（可选），并在调用完成后调用回调。
  语法：goToPage(number, offset, callback) void
  参数：
    number：要去的页数。
    offset：对象，如{left：12.2，top：15}。
    callback：执行动作后调用的函数。
  示例：
  viewer.goToPage(1, { 2, 3}, function(){});
  返回值：void
  
  
• backToParent
  说明：使查看器显示向下钻取报表的父报表。
  语法：backToParent() void
  示例： viewer.backToParent()
  返回值：void
• destroy
  说明：从HTML元素中删除查看器示例。
  语法：destroy() void
  示例： viewer.destroy()
  返回值：void
  
  
• export
  说明：导出当前显示的报表。
  语法：export(exportType, callback, saveAsDialog, settings) void
  参数：
    exportType：指定导出格式。
    callback：导出结果可用时调用的函数（其Url在回调中传递）。
    saveAsDialog：指示导出结果准备就绪后是否立即显示另存为对话框。
    settings：导出设置适用于RenderingExtensions。 注意：在区域报表中，导出设置不会启用。 在页面报表和RDL报表中，导出设置在使用导出过滤器（Export Filter）将文件导出为PDF时不启用。
  示例：
  function exportToExcel(){ viewer.export('Xls', downloadReport, true, { FileName: "DefaultName.xls" }); } // function fetches the report from uri(callback function)
  var downloadReport = function (uri) {
    var newWin = null;
    // open uri in new window
    try { newWin = window.open(uri); } catch (e) { }
    // if browser rejects opening new window, open uri in current window
    if (!newWin) { window.location = uri; } };
  返回值：void
  
  
• search
  说明：使用特定的查找选项（匹配大小写，全字）执行查找，并在查找的完成时执行回调。
  语法：search(searchTerm, searchOptions, callback) void
  参数：
    searchTerm：要查找的字符串。
    searchOptions：设置查找选项：
      matchCase：是否大小写敏感。
      wholePhrase：是否全字匹配。
    callback：执行搜索后调用的功能。
  示例：
  viewer.search('a', { matchCase: true, wholePhrase: false }, function (results){ console.log(results); });
  返回值：void
  
  
• getToc
  说明：获取报表的目录信息，并调用将结果作为参数传递的回调函数。
  语法：getToc(callback) void
  参数： callback：回调处理目录树。
  示例：
  viewer.getToc(function (toc){ console.log(toc); })
  返回值：void

属性

• pageCount
  说明：获取当前显示的报表的页数。
  语法：viewer.pageCount
  示例：
  console.log(viewer.pageCount)
  返回值：表示页数的整数。
  
  
• currentPage
  说明：获取当前显示的页码。
  语法：viewer.currentPage
  示例：console.log(viewer.currentPage)
  返回值：表示当前显示的页码的整数。
  
  
• Toolbar
  说明：返回在桌面界面模式下显示工具栏的HTML元素。
  语法：viewer.Toolbar
  示例：
  // Toolbar, MobileToolbarTop, MobileToolbarBottom
  $(viewer.toolbar).hide();
  $(viewer.toolbarTop).hide();
  $(viewer.toolbarBottom).hide();
  
  
• ToolbarTop
  说明：返回在移动界面模式下显示顶部工具栏的HTML元素。
  语法：viewer.ToolbarTop
  示例：
  // Toolbar, MobileToolbarTop, MobileToolbarBottom
  $(viewer.toolbar).hide();
  $(viewer.toolbarTop).hide();
  $(viewer.toolbarBottom).hide();
  
  
• ToolbarBottom
  说明：返回以移动界面模式显示底部工具栏的HTML元素。
  语法：viewer.ToolbarBottom
  示例：
  // Toolbar, MobileToolbarTop, MobileToolbarBottom
  $(viewer.toolbar).hide();
  $(viewer.toolbarTop).hide();
  $(viewer.toolbarBottom).hide();

有个葡萄城报表JavaScript API更详细的说明，参见：

http://help.grapecity.com/activereports/webhelp/AR11/index.html#HTML5WorkingwithViewerUsingJavascript.html