promiseUtils

方法列表

方法详细说明

create(executor){Promise}

用于创建和解析 promise 的便利实用程序方法。

参数：

executor Executor 将使用两个方法调用的函数，resolve 和 reject 。

返回值：

类型	描述
Promise	由执行者来完成的 promise。

示例代码：

function fetchImage(url) {
  return promiseUtils.create(function(resolve, reject){
    const image = document.createElement("img");
    image.onload = function() {
      image.load = image.onerror = null;
      resolve(image);
    };

    image.onerror = function() {
      image.load = image.onerror = null;
      reject(new Error("Error while loading the image"));
    }

    image.src = url;
  });
}

fetchImage(".........")
  .then(function(image){
    console.log(image);
  });

// 有条件地加载多个模块
require([
  "geoscene/core/promiseUtils"
], function( promiseUtils ) {
  // 根据用户是否选择加载模块
  // 一个 UI 选项，用于将类分隔符应用于图层
  if (classBreaksSelected) {
    return promiseUtils.create(function(resolve, reject) {
      require([ "geoscene/renderers/ClassBreaksRenderer" ], resolve);
    }).then(function(ClassBreaksRenderer) {
      // 创建渲染器并将其应用到所需的图层

    });
  }
});

createAbortError(){Error}

创建一个特殊的错误对象，用于在承诺链中发出中止请求的信号。由于中止信号而被拒绝的承诺应该拒绝这种错误。

返回值：

类型	描述
Error	一个特殊的错误对象，用于发出中止请求的信号。

示例代码：

// 请求多个文件并以数组形式返回结果
function requestMultiple(urls, abortSignal) {
  // 发出请求
  let promises = urls.map(url => request(url, { signal: abortSignal });

  // 等待所有请求得到解决或被拒绝
  promiseUtils.eachAlways(urls)
    .then(results => {
      if (abortSignal && abortSignal.aborted) {
        // 如果用户触发了中止信号，所有请求都将做出反应并拒绝
        // 每个请求总是使用一个数组进行解析，该数组包含每个请求的拒绝错误。
        // 因此，我们不应该返回这个数组，而应该拒绝返回给用户的带有中止错误的promise。
        throw promiseUtils.createAbortError();
      }
      return results;
  });
}

debounce(callback){Function}static

起始版本： GeoScene API for JavaScript 4.22

用于确保输入函数不会同时被调用多次的实用程序。这对于高度交互式的应用程序非常有用，例如那些对鼠标移动或鼠标拖动事件执行统计查询的应用程序。您可以"去抖动"或取消函数执行，而不是对每个此类事件执行查询，直到上一次执行同一函数调用完成。这提高了此类应用程序的性能和用户体验。

参数：

callback Function 一个函数，用于防止在执行对同一函数的上一个调用期间执行。这通常是可以在鼠标移动或鼠标拖动事件时调用的函数。

返回值：

类型	描述
Function	与回调具有相同签名的函数。

另参阅：

• 使用 debounce() 方法的示例

示例代码：

// 查询图层中与指针位置1公里缓冲区相交的要素数。
// debounce()方法防止updateStatistics函数在同一函数的前一次调用完成之前执行。
const updateStatistics = promiseUtils.debounce(function (geometry) {
  return layerView.queryFeatures({
    geometry,
    distance: 1,
    units: "kilometers",
    outStatistics: [{
      onStatisticField: "*",
      outStatisticFieldName: "feature_count",
      statisticType: "count"
    }]
  }).then(function(featureSet) {
    console.log(`Feature Count: ${featureSet.features[0].attributes["feature_count"]}`);
  });
});

view.on("drag", (event) => updateStatistics(view.toMap(event)));

eachAlways(promises){Promise|Object}

方便实用程序方法等待许多承诺解决或拒绝。生成的 promise 解析为包含 promise 的结果对象数组，如果 promise 解析，则解析为一个值，如果 promise 被拒绝，则解析为一个错误。

参数：

promises Promise[]|Object promise 数组，或每个属性都是 promise 的对象。

返回值：

类型	描述
Promise | Object	如果使用 promise 数组调用，则解析为包含原始 promise 和值（如果 promise 已解决）或错误（如果 promise 被拒绝）的结果对象数组。如果使用每个属性都是 promise 的对象调用，则解析为具有相同属性的对象，其中每个属性值都是结果对象。

示例代码：

const controller = new AbortController();

// 查询来自多个要素图层的要素数量
function queryLayerFeatureCount(whereClauses) {
  // 将每个 whereClauses 项传递到回调函数中
  return promiseUtils.eachAlways(whereClauses.map(function (whereClause) {
    return layer.queryFeatureCount(whereClause, {
      signal: controller.signal
    });
  }));
}

queryLayerFeatureCount(whereClauses).then(function(eachAlwaysResults) {
   eachAlwaysResults.forEach(function(result) {
     // 如果 promise 被拒绝，您可以检查被拒绝的错误
     if (result.error) {
       console.log("There was an error in your query.", result.error);
     }
     // promise 的结果将在value属性中返回
     else {
       console.log("The number of features are: " + result.value);
     }
   });
});

filter(input, predicate){Promise}

一种方便的实用程序方法，用于使用异步谓词函数过滤值数组。

参数：

input Array 要过滤的输入值的数组。

predicate FilterPredicateCallback 返回 promise 的谓词函数。仅保留返回的 promise 包含 true 的数组条目。

返回值：

类型	描述
Promise	包含通过谓词检查的值数组的 promise。

isAbortError(error){Boolean}

检查提供的错误对象是否是 promise 中止时被拒绝的特殊类型的错误。

参数：

error Error 要测试的错误对象。

返回值：

类型	描述
Boolean	如果错误是中止错误为 true，否则为 false。

示例代码：

// 此函数通过 HTTP 获取文档，并在可用时将其内容记录到控制台
function logHTTPDocumentToConsole(url, abortSignal) {
  // 将中止信号传递到“请求”中，使其可取消
  request(url, { signal: abortSignal })
    .then((response) => {
      console.log(response.data);
    })
    .catch((error) => {
      if (!promiseUtils.isAbortError(error)) {
        // 只记录请求失败并忽略取消
        console.error("request error", error);
      }
    });
}

let controller = new AbortController();

let url = "https://sampleserver6.geosceneonline.cn/arcgis/rest/services/Census/MapServer";
logHTTPDocumentToConsole(url, controller.signal);

// 取消请求
controller.abort();

reject(error){Promise}

已废弃 起始版本 4.19。 使用原生 Promise.reject() 方法代替。

使用提供的错误值创建已被拒绝的 Promise 的便捷实用方法。

参数:

error Object 可选 拒绝产生的承诺的错误。

返回值:

类型	描述
Promise	由于所提供的错误而被拒绝的承诺。

示例代码:

if (!data || !data.url) {
  return promiseUtils.reject(new Error("url is a required options property"));
}

resolve(value){Promise}

已废弃 起始版本4.19。使用原生 Promise.resolve() 方法代替。

用于创建将使用提供的值解决的 Promise 的便捷实用方法。

参数:

value * 可选 用于解析结果承诺的值。

返回值:

类型	描述
Promise	使用提供的值解决的承诺。

示例代码:

// createGraphics will return a Promise that
// resolves to graphics array
function createGraphics() {
  let graphics = geoJson.features.map(function(feature, i) {
     return new Graphic({
       geometry: new Point({
         x: feature.geometry.coordinates[0],
         y: feature.geometry.coordinates[1]
       }),

       attributes: {
         ObjectID: i,
         title: feature.properties.title
       }
     });
  });

  return promiseUtils.resolve(graphics);
}

类型定义

EachAlwaysResult Object

传递给 promiseUtils.eachAlways 的 promise 的结果对象。

属性：

promise Promise 已经完成的 promise。

value * optional promise 解决的值。仅当 promise 解决时才定义。

error * optional promise 被拒绝的错误。仅当 promise 被拒绝时才定义。

Executor(resolve, reject)

一个函数，用于定义如何解决和拒绝在 create() 中创建的 promise。

参数：

resolve ResolveCallback 处理解决 promise 的函数。

reject RejectCallback 处理拒绝 promise 的函数。

FilterPredicateCallback(value, index){Promise}

要为要过滤的数组的每个条目调用的回调。

参数：

value * 数组条目的值。

index Number 数组中条目的索引。

返回值：

类型	描述
Promise	解析为布尔值的 promise，指示是否应将条目保留在过滤的数组中。

RejectCallback(error)

一个函数，它将拒绝在 create() 中创建的 promise。

参数：

error * optional promise 被拒绝的错误。仅当 promise 被拒绝时才定义。

ResolveCallback(value)

一个函数，它将解析在 create() 中创建的 promise。

参数：

value *|Promise<*> optional promise 解决的值。仅在执行 promise 时定义。