Script Lab 09：异步调用函数，PowerPoint基础操作

Script Lab 的级初入门教程，到今天就要告一段落了。总结部分，我们来实践一个 PPT 的例子吧。相比 Word 和 Excel 来说，PPT 的 API 的完成度并不高，甚至连启动函数也没有实现（目前有 Excel.run、 Word.run、OneNote.run）。

在 PowerPoint 空间下，仅实现了一个方法，没有像 Excel 或 Word 那样，可以操作的较完整的 API 对象集。

var ppt = PowerPoint.createPresentation();

PPT 目前的主要操作，只能集中在一些 Offie 通用的功能上，依托于 Office 空间下的 context 对象来操作。本次举一个较简单的例子，在 PPT 上插入一个 SVG 的形状，这也是 Script Lab 中自带的一个例子（总共也只有 5个 API 案例）。

【完整代码】

$("#insert").click(newImage);
function newImage() {
  Office.context.document.setSelectedDataAsync(
    getImageAsBase64String(),
    {
      coercionType: Office.CoercionType.XmlSvg,
      imageLeft: 50,
      imageTop: 50,
      imageWidth: 400
    },
    function(asyncResult) {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error(asyncResult.error.message);
      }
    }
  );
}
function getImageAsBase64String() {
  // A production add-in code could get an image from an
  // online source and pass it to a library function that
  // converts to base 64.
  var svg =
'<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="100%" height="100%" viewBox="0 0 100 100">  <title>SVG Logo</title>  <a xlink:href="http://www.w3.org/Graphics/SVG/" target="_parent"     xlink:title="W3C SVG Working Group home page">
...
</g>    </g>  </a></svg>';
  return svg;

【代码解析】

取得当前页，并插入 SVG 图标（发未选中，则引出发错）：

Office.context.document.setSelectedDataAsync(...)

其实这种调用模式，我们在前期的代码中并未出现过，所以借此机会，讨论下这里的要点。Office API 应用程序中异步函数有通用签名格式，Office API 应用程序中的所有异步函数都有相同的命名约定和相同的基本签名。 每个异步函数的名称都以"Async"结尾，以本次调用的函数为例：其实所有的步函数的签名都遵循以下基本模式：

functionNameAsync(
requiredParameters,
[, options], [callback]);

必需参数后面另有两个参数：一个包含可选参数的对象和一个回调函数，两者始终都是可选的。异步函数中的可选参数 异步函数签名中的可选 JavaScript 对象是用分号分隔的键/值对的集合，其中的键是参数名称，值是您想对该参数使用的数据。键/值对的顺序无关紧要，只要参数名称正确即可。

以本次调用为例，setSelectedDataAsync 方法具有 Office 应用程序中所有异步函数通用的相同基本签名：

Office.context.document.setSelectedDataAsync(  data [, options], callback);

Document.set SelectedDataAsync 也有一个选项对象，其中包含可选参数，但其选项对象的参数与该 API 中其他异步函数的参数不同，因为此函数的用途是设置数据。 因此，Document.setSelectedDataAsync 的可选参数与设置数据有关：

• coercionType：一个指定所插入数据格式（文本、HTML、OOXML、表或矩阵）的 CoercionType 枚举
  
• asyncContext：一个用户定义的对象，在作为回调函数唯一参数传递给该函数的 AsyncResult 对象中无变化返回。
  

AsyncResult 对象在异步函数中的角色 JavaScript API for Office 中异步函数的通用签名中的第三个参数是可选的回调参数。 当运行时调用回调函数时，它会将 Async Result 对象作为回调函数唯一的参数传入。AsyncResult 对象包含有关异步操作的信息，如：操作是否成功；发生了什么错误（如果有）；以及异步函数的返回值（如果有）。在返回某种数据或对象的所有异步函数中，AsyncResult 都是可以获得返回值的唯一方式。可以使用 AsyncResult.value 属性实现这一点。

if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.error(asyncResult.error.message);

【效果图】