Print

Print 微件可连接应用程序与打印服务，以允许打印地图。它使用 GeoScene 的 ExportWebMap 服务 (可使用自定义布局模板进行配置) 利用服务器端、高质量、完整的制图打印功能。可提供一个微件仅显示地图，而另一个提供具有图例等的布局。Print 微件可与打印配合使用，以生成地图的打印机就绪版本。

Print 微件具有两个必需的属性：view (参考 MapView) 和 printServiceUrl (导出 Web 地图任务的 REST 端点的 URL)。微件可以在打印输出中保留地图比例或地图范围。默认情况下，保留地图范围。请改用 TemplateOptions 来保留比例。

Print 微件可为除 map-only 以外的所有布局打印本地化日期。如果使用自定义打印服务，则每个打印模板均支持 customTextElements。找到的值将在 Print 微件的 Advanced options 下填充。这些值可以在 Print 微件 UI 中被覆盖，或者以编程方式使用 templateCustomTextElements 属性。

有关使用 MAP_ONLY 布局进行打印的更多信息，请参阅 exportOptions。

已知限制

有关已知限制的详细列表，请参阅 print。

另请参阅

示例

const print = new Print({
  view: view,
  // specify your own print service
  printServiceUrl:
     " "
});

// Adds widget below other elements in the top left corner of the view
view.ui.add(print, {
  position: "top-left"
});

构造函数

new Print(properties)

参数

properties Object

optional

有关可能传递给构造函数的所有属性的列表，请参见属性。

示例

// typical usage
let print = new Print({
  view: view,
  printServiceUrl: "https://www.example.com/geoscene/rest/services/Utilities/PrintingTools/GPServer/Export%20Web%20Map%20Task"
});

属性概述

可以设置、检索或侦听任何属性。请参阅使用属性主题。

显示继承属性

隐藏继承属性

类型	描述	类
String\|String []	指定用户可以根据打印服务提供的选项选择的打印输出文件格式。更多详情	Print
String\|String []	指定用户可以根据打印服务提供的选项选择的打印输出布局。更多详情	Print
String\|HTMLElement	包含微件的 DOM 元素的 ID 或节点。更多详情	Widget
String	类的名称。更多详情	Accessor
Collection<FileLink>	从 Print 微件导出的链接集合。更多详情	Print
Object	此选项允许将额外参数 (除 templateOptions 外) 传递给打印 (导出 webmap) 请求。更多详情	extraParameters
Number	指示用于"导出文件"文本的标题级别，用户可以在其中访问导出的地图打印输出。更多详情	Print
String	微件的默认 CSS 图标类。更多详情	Print
String	创建微件时分配给微件的唯一 ID。更多详情	Widget
Boolean	指示是否包含 defaultTemplates。更多详情	Print
String	微件的默认的标注。更多详情	Print
Portal	可以搜索指定门户实例的定位器服务。更多详情	Print
String	导出 Web 地图任务的 REST 端点的 URL。更多详情	Print
Object []	一个对象，其中包含自定义打印服务中每个打印模板的 `customTextElements` 名称-值对对象数组。更多详情	Print
TemplateOptions	定义 Print 微件用于生成打印页面的布局模板选项。更多详情	Print
MapView	对 MapView 的引用。更多详情	Print
PrintViewModel	此微件的视图模型。更多详情	Print
Boolean	指示微件是否可见。更多详情	Widget

属性详细信息

allowedFormats String|String [] 起始版本：GeoScene Maps SDK for JavaScript 4.15

指定用户可以根据打印服务提供的选项选择的打印输出文件格式。此属性可以采用字符串值或字符串值数组。

当此值为 "all" (默认值) 时，可以使用所有打印服务格式。使用字符串值数组时，仅会使用与打印服务提供的选项相匹配的值。如果没有任何输入字符串值与打印服务提供的值相匹配，则 allowedFormats 将回退到默认行为。

默认值："all"

另请参阅

TemplateOptions.format

示例

const print = new Print({
  view: view,
  printServiceUrl:
         " ",
  allowedFormats: ["jpg", "png8", "png32"]
});

allowedLayouts String|String [] 起始版本：GeoScene Maps SDK for JavaScript 4.15

指定用户可以根据打印服务提供的选项选择的打印输出布局。此属性可以采用字符串值或字符串值数组。

当此值为 "all" (默认值) 时，可使用所有打印服务布局。使用字符串值数组时，仅会使用与打印服务提供的选项相匹配的值。如果没有任何输入字符串值与打印服务提供的值相匹配，则 allowedLayouts 将回退到默认行为。

默认值："all"

另请参阅

TemplateOptions.layout

示例

const print = new Print({
  view: view,
  printServiceUrl:
         " ",
  allowedLayouts: ["a3-landscape", "a3-portrait"]
});

container String|HTMLElement inherited

包含微件的 DOM 元素的 ID 或节点。此属性只能设置一次。以下示例都是使用微件时的有效用例。

示例

// Create the HTML div element programmatically at runtime and set to the widget's container
const basemapGallery = new BasemapGallery({
  view: view,
  container: document.createElement("div")
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// Specify an already-defined HTML div element in the widget's container

const basemapGallery = new BasemapGallery({
  view: view,
  container: basemapGalleryDiv
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// HTML markup
<body>
  <div id="viewDiv"></div>
  <div id="basemapGalleryDiv"></div>
</body>

// Specify the widget while adding to the view's UI
const basemapGallery = new BasemapGallery({
  view: view
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

declaredClass Stringreadonly inherited 起始版本：GeoScene Maps SDK for JavaScript 4.7

类的名称。声明的类名称格式化为 geoscene.folder.className。

exportedLinks Collection<FileLink>readonly 起始版本：GeoScene Maps SDK for JavaScript 4.17

从 Print 微件导出的链接集合。

示例

require([
  "geoscene/widgets/Print",
  "geoscene/config"
], function(Print, geosceneConfig) {

  // ...

  view.when(function () {
    print = new Print({
      view: view,
      // specify your own print service
      printServiceUrl:
        " "
    });

    // Add widget to the top right corner of the view
    view.ui.add(print, "top-right");

    // use a requestInterceptor to monitor the print widget
    // for print completion
    geosceneConfig.request.interceptors.push({
      // set the `urls` property to the URL of the print service so that this
      // interceptor only applies to requests made to the print service URL
      urls: print.printServiceUrl,
      // use the AfterInterceptorCallback to interogate the exportedLinks property
      after: function(response) {
        console.log("exportedLinks: ", print.exportedLinks.items[0]);
      }
    });
  });

extraParameters Objectinner 起始版本：GeoScene Maps SDK for JavaScript 4.20

此选项允许将额外参数 (除 templateOptions 外) 传递给打印 (导出 webmap) 请求。

headingLevel Number 起始版本：GeoScene Maps SDK for JavaScript 4.20

指示用于"导出文件"文本的标题级别，用户可以在其中访问导出的地图打印输出。默认情况下，此文本呈现为 3 级标题 (例如，<h3>Exported files</h3>)。根据微件在应用程序中的位置，您可能需要调整此标题以获得正确的语义。这对于满足可访问性标准很重要。

默认值：3

另请参阅

标题元素

示例

// "Exported files" will render as an <h4>
print.headingLevel = 4;

iconClass String 起始版本：GeoScene Maps SDK for JavaScript 4.7

微件的默认 CSS 图标类。

id String inherited

创建微件时分配给微件的唯一 ID。如果不是由开发人员设置的，它将默认为容器 Id，或者如果没有容器 ID，则将自动生成。

includeDefaultTemplates Boolean 起始版本：GeoScene Maps SDK for JavaScript 4.18

指示是否包含 defaultTemplates。

默认值：true

示例

const printWidget = new Print({
   view: view,
   includeDefaultTemplates: false,
   portal: {url: "https://.example.arcgis.com/sharing/"},
   container: "printDiv"
});

label String 起始版本：GeoScene Maps SDK for JavaScript 4.7

微件的默认的标注。

portal Portal 起始版本：GeoScene Maps SDK for JavaScript 4.18

可以搜索指定门户实例的定位器服务。使用此属性可将此 GeoScene Portal 实例设置为搜索。这在使用自定义打印模板时特别有用。

如果设置了此属性，则不必设置 printServiceUrl 属性。

另请参阅

CustomTemplate

示例

const printWidget = new Print({
   view: view,
   portal: {url: "https://example.arcgis.com/sharing/"},
   container: "printDiv"
});

printServiceUrl String

导出 Web 地图任务的 REST 端点的 URL。如果设置了 portal 属性，则不必设置此属性。

templateCustomTextElements Object [] 起始版本：GeoScene Maps SDK for JavaScript 4.22

一个对象，其中包含自定义打印服务中每个打印模板的 customTextElements 名称-值对对象数组。使用此属性以更新页面布局上自定义文本元素的文本。

Print 微件调用 GPServer 上的 Get Layout Templates Info 任务来发现每个模板可能的 customTextElements 值。任务的名称必须匹配 Get Layout Templates Info，模板必须使用 customTextElements 发布，且值必须是字符串。找到的值将在 Print 微件的 Advanced options 下填充。这些值可以在 Print 微件 UI 中被覆盖，或者以编程方式使用此属性。若要列出打印服务上可用的所有打印模板，以查看哪些模板是使用 customTextElements 发布的，请使用 effectiveTemplateCustomTextElements 属性。

示例

const printWidget = new Print({
   view: view,
   // specify your custom print service
   printServiceUrl: "",
   // `customTextElements` are defined per print template
   // this example has one template with `customTextElements`
   templateCustomTextElements: {
      // if there were more applicable templates, then we would
      // create another object with the template name containing
      // an array of more name-value pairs
      "Landscape_TextElements": [
         // the possible values are defined in the print service
         { "headquarters": "Foxborough, Massachusetts" },
         { "division": "AFC East" },
         { "founded": "1959" }
      ]
   }
});

templateOptions TemplateOptionsautocast 起始版本：GeoScene Maps SDK for JavaScript 4.6

定义 Print 微件用于生成打印页面的布局模板选项。

示例

templateOptions: {
  title: "My Print",
  author: "Sam",
  copyright: "My Company",
  legendEnabled: false
}

view MapView

对 MapView 的引用。设置此选项可将微件链接到特定视图。

viewModel PrintViewModelautocast

此微件的视图模型。此类包含控制此微件行为的所有逻辑。请参阅 PrintViewModel 类来访问微件上的所有属性和方法。

visible Boolean inherited

指示微件是否可见。

如果为 false，微件将不再呈现在 web 文档中。这可能会影响文档中其他元素或微件的布局。例如，如果此微件是与视图 UI 右上角关联的三个微件中的第一个，则当此微件不可见时，其他微件将重新定位。有关更多信息，请参阅 CSS display 值 "none"。

默认值：true

示例

// Hides the widget in the view
widget.visible = false;

方法概述

显示继承的方法

隐藏继承的方法

返回值类值	描述	类
	添加一个或多个与对象的生命周期相关联的句柄。更多详情	Accessor
String	用于为微件的 `class` 属性构建值的实用方法。更多详情	Widget
	销毁微件实例。更多详情	Widget
Boolean	在实例上触发事件。更多详情	Widget
Boolean	指示实例上是否存在与提供的事件名称相匹配的事件监听器。更多详情	Widget
Boolean	如果存在指定的句柄组，则返回 true。更多详情	Accessor
Boolean	`isFulfilled()` 可用于验证创建类的实例是否已完成 (已解决或已拒绝)。更多详情	Widget
Boolean	`isRejected()` 可用于验证创建类的实例是否被拒绝。更多详情	Widget
Boolean	`isResolved()` 可用于验证创建类的实例是否已解决。更多详情	Widget
Object	在实例上注册事件处理程序。更多详情	Widget
	添加一个或多个与微件的生命周期相关联的句柄。更多详情	Widget
	此方法主要由开发人员在实现自定义微件时使用。更多详情	Widget
	移除对象拥有的句柄组。更多详情	Accessor
Object	此方法主要由开发人员在实现自定义微件时使用。更多详情	Widget
	立即将微件渲染到 DOM。更多详情	Widget
	此方法主要由开发人员在实现自定义微件时使用。更多详情	Widget
Promise	一旦创建了类的实例，就可以使用`when()` 。更多详情	Widget

方法详细说明

addHandles(handleOrHandles, groupKey)inherited 起始版本：GeoScene Maps SDK for JavaScript 4.25

添加一个或多个与对象的生命周期相关联的句柄。当对象被销毁时，将移除句柄。

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

// Handle gets removed when the object is destroyed.
this.addHandles(handle);

参数

handleOrHandles WatchHandle|WatchHandle []

对象销毁后，标记为要移除的句柄。

groupKey *

optional

标识句柄应添加到的组的键。组中的所有句柄稍后都可使用 Accessor.removeHandles() 进行删除。如果未提供键，则句柄将被添加到默认组。

classes(classNames){String}inherited 起始版本：GeoScene Maps SDK for JavaScript 4.7

用于为微件的 class 属性构建值的实用方法。这有助于简化 CSS 类设置。

参数

classNames String|String []|Object

repeatable

类名称。

类型	描述
String	计算的类名。

另请参阅

指南 - 微件开发 (渲染器)

示例

// .tsx syntax showing how to set CSS classes while rendering the widget

render() {
  const dynamicIconClasses = {
    [CSS.myIcon]: this.showIcon,
    [CSS.greyIcon]: !this.showIcon
  };

  return (
    <div class={classes(CSS.root, CSS.mixin, dynamicIconClasses)} />
  );
}

destroy()inherited

销毁微件实例。

emit(type, event){Boolean}inherited 起始版本：GeoScene Maps SDK for JavaScript 4.5

在实例上触发事件。仅当创建此类的子类时，才应使用此方法。

参数

type String

事件的名称。

event Object

optional

事件有效负载。

类型	描述
Boolean	如果监听器收到通知，则为`true`

hasEventListener(type){Boolean}inherited

指示实例上是否存在与提供的事件名称相匹配的事件监听器。

参数

type String

事件的名称。

类型	描述
Boolean	如果类支持输入事件，则返回 true。

hasHandles(groupKey){Boolean}inherited 起始版本：GeoScene Maps SDK for JavaScript 4.25

如果存在指定的句柄组，则返回 true。

参数

groupKey *

optional

组键。

类型	描述
Boolean	如果存在指定的句柄组，则返回 `true`。

示例

// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

isFulfilled(){Boolean}inherited 起始版本：GeoScene Maps SDK for JavaScript 4.19

isFulfilled() 可用于验证创建类的实例是否已完成 (已解决或已拒绝)。如果满足，则返回 true。

类型	描述
Boolean	指示创建类的实例是否已完成 (已解决或已拒绝)。

isRejected(){Boolean}inherited 起始版本：GeoScene Maps SDK for JavaScript 4.19

isRejected() 可用于验证创建类的实例是否被拒绝。如果被拒绝，则返回 true。

类型	描述
Boolean	指示创建类的实例是否已被拒绝。

isResolved(){Boolean}inherited 起始版本：GeoScene Maps SDK for JavaScript 4.19

isResolved() 可用于验证创建类的实例是否已解决。如果已解决，则返回 true。

类型	描述
Boolean	指示创建类的实例是否已解决。

on(type, listener){Object}inherited

在实例上注册事件处理程序。调用此方法将事件与监听器挂钩。

参数

type String|String []

要侦听的事件或者事件数组。

listener Function

事件触发时要调用的函数。

类型描述

Object

返回具有 remove() 方法的事件处理程序，可调用该方法来停止侦听事件。

属性	类型	描述
remove	Function	调用时，从事件中移除侦听器。

示例

view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

own(handleOrHandles)inherited 起始版本：GeoScene Maps SDK for JavaScript 4.24

添加一个或多个与微件的生命周期相关联的句柄。当微件被销毁时，将移除句柄。

const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true}
);

this.own(handle); // Handle gets removed when the widget is destroyed.

参数

handleOrHandles WatchHandle|WatchHandle []

微件销毁后，标记为要移除的句柄。

postInitialize()inherited

此方法主要由开发人员在实现自定义微件时使用。在微件准备好渲染后执行。

removeHandles(groupKey)inherited 起始版本：GeoScene Maps SDK for JavaScript 4.25

移除对象拥有的句柄组。

参数

groupKey *

optional

要移除的组键或组键的数组或集合。

示例

obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

render(){Object}inherited

此方法主要由开发人员在实现自定义微件时使用。它必须由子类实现以进行渲染。

类型	描述
Object	渲染的虚拟节点。

renderNow()inherited

立即将微件渲染到 DOM。

scheduleRender()inherited

此方法主要由开发人员在实现自定义微件时使用。计划微件渲染。此方法对于影响 UI 的更改非常有用。

when(callback, errback){Promise}inherited 起始版本：GeoScene Maps SDK for JavaScript 4.19

一旦创建了类的实例，就可以使用when() 。此方法接受两个输入参数：callback 函数和 errback 函数。callback 在类的实例加载时执行。errback 在类的实例无法加载时执行。

参数

callback Function

optional

当 promise 解决时调用的函数。

errback Function

optional

当 promise 失败时执行的函数。

类型	描述
Promise	为 `callback` 结果返回一个新的 promise。

示例

// Although this example uses the BasemapGallery widget, any class instance that is a promise may use when() in the same way
let bmGallery = new BasemapGallery();
bmGallery.when(function(){
  // This function will execute once the promise is resolved
}, function(error){
  // This function will execute if the promise is rejected due to an error
});

类型定义

FileLink

表示从 Print 微件的结果导出的地图请求。成功的导出将具有链接到打印输出的 URL。失败的导出将提供有关错误的信息。

属性

count Number

FileLink 元素在数组中的位置。

error String

Print 微件中的错误，如果有。

extension String

打印输出的文件类型。

name String

印输出的 fileName 或 title。

state String

打印输出的状态。"ready" 或 "pending" 或 "error"。

url String

打印输出的 printServiceUrl。

示例

require([
  "geoscene/widgets/Print",
  "geoscene/config"
], function(Print, geosceneConfig) {

  // ...

  view.when(function () {
    print = new Print({
      view: view,
      // specify your own print service
      printServiceUrl:
        " "
    });

    // Add widget to the top right corner of the view
    view.ui.add(print, "top-right");

    // use a requestInterceptor to monitor the print widget
    // for print completion
    geosceneConfig.request.interceptors.push({
      // set the `urls` property to the URL of the print service so that this
      // interceptor only applies to requests made to the print service URL
      urls: print.printServiceUrl,
      // use the AfterInterceptorCallback to interogate the exportedLinks property
      after: function(response) {
        console.log("exportedLinks: ", print.exportedLinks.items[0]);
      }
    });
  });

事件概述

名称	类型	描述	类
	{results: Object,results.link: Collection<FileLink>}	在打印请求完成并返回其结果时触发。更多详情	Print
	{results: Object,results.link: Collection<FileLink>}	在导出请求开始时触发，并返回对导出链接的引用。更多详情	Print

事件详细说明

complete 起始版本：GeoScene Maps SDK for JavaScript 4.17

在打印请求完成并返回其结果时触发。无论导出成功还是失败，都将触发此事件。

属性

results Object

表示打印结果的对象。

规范

link Collection<FileLink>

表示从 Print 微件的结果导出的地图请求。

示例

const printWidget = new Print();

printWidget.on("complete", function(results){
  // The results are stored in the results object
  console.log("Results of the print: ", results.link);
});

submit 起始版本：GeoScene Maps SDK for JavaScript 4.17

在导出请求开始时触发，并返回对导出链接的引用。

属性

results Object

表示提交打印结果的对象。

规范

link Collection<FileLink>

表示从 Print 微件的结果导出的地图请求。

示例

const printWidget = new Print();

printWidget.on("submit", function(results){
  // The results are stored in the event object
  console.log("Results of submitting the print: ", results.link);
});

GeoScene Maps SDK for JavaScript参考手册

构造函数

属性概述

属性详细信息

方法概述

方法详细说明

类型定义

事件概述

事件详细说明