天添加客户端

SKY 添加客户端库为自定义添加创建提供便利,以在 Blackbaud 应用程序中扩展 UI 体验. 开发者可以使用他们的SKY API应用程序来注册添加的URL,在运行时,添加会被加载到应用程序内的iframe. 此库必须用在添加中, 才能在 Blackbaud 应用程序内渲染。这个 AddinClient class 将与主机页面整合,在主机和添加的iframe之间传递数据和命令.

对SKY来说在 SKY UX 中添加 SKY UX 添加客户端库可以在这个下层库上用作更方便角的包装.

有关创建 SKY 添加的更多信息,请查看 SKY API 开发者门户网站。。。 .

安装

先决条件

这个图书馆广泛使用 ES6型承诺,所以为了支持还没有本地支持“承诺”的浏览器(如Internet Explorer 11),您需要包含“承诺”的多填充,例如 es6-promise 并使用自动填充特性用于图书馆的 Promise 被添加到全球环境中。这将需要在添加库前加载到您的页面 .

ES6/ 类型脚本

确保您拥有节点v6+和国家预防机制v3+。要验证, 运行 node -v 财务报告和审定财务报表 npm -v 在命令线.
通过运行将库安装为您的项目的依赖性 npm install --save @blackbaud/sky-addin-client 在您的项目文件夹中 .

香草爪哇脚本/ES5

SKY 添加客户端库也作为UMD捆绑发行. 如果你使用ES5 带节点或者像浏览器这样的工具 require() 内容:

var BBSkyAddinClient = require('@blackbaud/sky-addin-client');
var client = new BBSkyAddinClient.AddinClient({...});

如果您不使用模块加载器, 或者更愿意通过 CDN 引用文件, 您可以通过 CDN 将文件加载到您的页面 <script> 标签.

如果使用国家预防机制,请添加提及 dist/bundles/sky-addin-client.umd.js 或将该文件与您页面的其余 JavaScript 合并.

如果使用SKY UX CDN,请添加引用 https://sky.blackbaudcdn.net/static/sky-addin-client/[VERSION]/sky-addin-client.umd.min.js时 [VERSION] 您想要使用的版本。从版本开始 1.0.15,向国家预防机制发布的所有版本也通过CDN提供。也可以参考最新的主要版本. 示例版本:

https://sky.blackbaudcdn.net/static/sky-addin-client/1.0.15/sky-addin-client.umd.min.js
https://sky.blackbaudcdn.net/static/sky-addin-client/1/sky-addin-client.umd.min.js

你现在可以通过全球访问 BBSkyAddinClient 变量 :

// BBSkyAddinClient is global here.
var client = new BBSkyAddinClient.AddinClient({...});

使用量

初始化添加

所有添加必须使用此库才能在主机应用程序中显示。您需要建造 AddinClient 并注册您要处理的主机页面中的任何召回。你个必须注册 init,它将将关键上下文信息传递到您的添加.

 init 函数将调用一个参数对象,其中包含:

envId - 主机页面的环境标识
context - 主机页面的额外上下文,不同扩展点的上下文不同.
addinType (Version 1.8+) - 识别主机对加载的显示模式('action-button', (中文(简体) ), 'box', (中文(简体) ), 'button', (中文(简体) ), 'dataset', (中文(简体) ), 'flyout', (中文(简体) ), 'generic', (中文(简体) ), 'modal', (中文(简体) ), 'page', (中文(简体) ), 'tab', (中文(简体) ), 'tile',或 'vertical-tab-form') (中文(简体) ). 当您添加到多个显示模式中时有用。只有兼容的主机提供此值, 所以它是 undefined 当主机不提供它或提供该版本库无法识别的类型时.
supportedEventTypes - 主机页面处理的支持事件类型.
themeSettings - 主页的UX主题.
ready - 调回通知添加客户端该添加已初始化并准备显示.

使用《公约》提供的资料 init 参数,添加应确定是否以及如何进行。那它应该叫 ready 调用,通知主机页面.

var client = new AddinClient({
  callbacks: {
    init: (args) => {
      args.ready({
        showUI: true,
        title: 'My Custom Tile Title'
      });
    }
  }
});

您也可以允许您添加的客户端在一个 Blackbaud 主机页面内运行的额外来源。其他出处作为正则表达式模式提供. 这个 AddinClient 默认已允许多个 Blackbaud 主机来源。如果您发现需要扩展默认值,您可以通过充入 AddinClientConfig是因为 allowedOrigins 属性.

var client = new AddinClient({
  callbacks: {
    init: (args) => {
      args.ready({
        showUI: true,
        title: 'My Custom Tile Title'
      });
    }
  },
  allowedOrigins: [
    /^https\:\/\/[\w\-\.]+\.additionalblackbauddomain\.com$/,
  ]
});

平板加载

对于瓦片加入,加入的URL将在页面上一个可见的iframe中渲染出,您可以在其中提供自定义的内容. iframe最初会被隐藏到初始化协议在主机和添加之间完成.

主机页面将处理在添加的 Iframe 周围渲染瓦片组件。当呼叫 ready 调回, 调回 title 字段将显示瓷砖的标题。最初,整个瓷砖将被隐藏,如果 showUI 设置为 true 在召回。你可以设置它 false 来表示不应根据当前记录的用户权限或上下文等来显示瓷砖.

地砖加入支持一个可选配置对象,可以用来在主机应用程序内进一步控制地砖的外观/外观/行为. 对于例如,控制是否在平板倒塌时显示任何额外的摘要文本/图像,并控制“内置帮助”或“设置”图标是否出现在瓷砖头.

平板加载支持可选回调 inlineHelpClick 财务报告和审定财务报表 settingsClick,当用户分别点击"内置帮助"或"设置"图标时,将引用:

var client = new AddinClient({
  callbacks: {
    init: (args) => {
      args.ready({
        showUI: true,
        title: 'My Custom Tile Title',
        tileConfig: {
          summaryStyle: BBSkyAddinClient.AddinTileSummaryStyle.Text,
          summaryText: '18 records',
          showInlineHelp: true,
          showSettings: true
        }
      });
    },
    inlineHelpClick: () => {
      // The user has clicked the "Inline Help" icon in the tile header
    },
    settingsClick: () => {
      // The user has clicked the "Settings" icon in the tile header
    }
  }
});

平板加载还支持可选 helpPopoverContent 财务报告和审定财务报表 helpPopoverTitle 配置属性以指定在“ 内置帮助” 图标点击时在弹出器中显示的帮助文本 .

var client = new AddinClient({
  callbacks: {
    init: (args) => {
      args.ready({
        showUI: true,
        title: 'My Custom Tile Title',
        tileConfig: {
          showInlineHelp: true,
          helpPopoverContent: 'Help popover content text',
          helpPopoverTitle: 'Help popover title'
        }
      });
    },
    inlineHelpClick: () => {
      // The user has clicked the "Inline Help" icon in the tile header
    }
  }
});

Tab 添加( 尚未支持, 但即将到来)

对于标签加入,加入的 URL 将在页面上一个可见的 Iframe 中提供,您可以在此渲染自定义的内容。 iframe最初会被隐藏到初始化协议在主机和添加之间完成.

主机页面将处理在添加的 iframe 周围渲染标签组件。当呼叫 ready 调回, 调回 title 字段将显示标签组件的标题。最初,整个标签将被隐藏,如果 showUI 设置为 true 在召回。你可以设置它 false 以表示标签不应显示,基于当前记录的用户权限或上下文等.

Tab 添加支持一个可选配置对象,可以用来进一步控制主机应用程序中标签的外观/feel/行为. 对于示例,以控制是否在标签标题旁边显示任何额外的摘要文本/图像 :

var client = new AddinClient({
  callbacks: {
    init: (args) => {
      args.ready({
        showUI: true,
        title: 'My Custom Tab Title',
        tabConfig: {
          style: 'Text',
          summary: '20'
        }
      });
    }
  }
});

Tab 加入会自动跟踪加入内容的高度并相应调整容器大小.

说明:此时仅支持按钮和泰尔加入. 塔克加注被计划作为未来的增强.

按键添加

对于按钮加入,添加的iframe将永远被隐藏. 这个 init 协议仍在使用,其中 showUI 表示该按钮是否应在页面上显示。这个 title 字段将指定按钮的标签.

当进行按钮添加时, 额外调用 buttonClick 应当配置。当用户点击该按钮时, 将引用此语句, 供添加者采取行动 .

按键加入支持一个可选配置对象,可以用来进一步控制主机应用程序内按钮的外观/feel/行为. 对于示例,用于控制是否在按钮文本旁边显示任何额外的图标 :

var client = new AddinClient({
  callbacks: {
    init: (args) => {
      args.ready({
        showUI: true,
        title: 'My Custom Button Text',
        buttonConfig: {
          style: 'Add'
        }
      });
    },
    buttonClick: () => {
      // Show a modal or take action.
    }
  }
});

条目表单添加

对于输入表加入,加入的URL将在条目表单上以可见的iframe提供,在此可以提供自定义内容. iframe最初会被隐藏到初始化协议在主机和添加之间完成.

主机页面将处理置入iframe周围的容器渲染. 当呼叫 ready 调回, 调回 title 字段将显示窗体中垂直标签的标题。初始时, 垂直标签会被隐藏, 并且仅在表单上显示 showUI 设置为 true 在召回。你可以设置它 false 以表示标签和添加内容不应根据用户权限或用户界面是否适合您的使用.

条目表添加支持特定的形式事件,当用户互动导致数据形成变化时,或者当一个表格被保存或被取消时可能发生. 要处理窗体事件,请拨打 addEventHandler 方法 AddinClient 分类,在事件发生时传递事件类型和召回函数:

var client = new AddinClient({
  callbacks: {
    init: (args) => {
      args.ready({
        showUI: true,
        title: 'Custom entry form tab'
      });
    }
  }
});

// To handle add-in events, call the addEventHandler method
client.addEventHandler(
  'form-data-update',
  function (context) {
    // get updated data from context object
  }
);

条目表也可能支持 form-save 财务报告和审定财务报表 form-cancel 事件类型。这些事件类型允许添加客户端在窗体关闭时执行同步任务(如调用后端服务). 召回的电话 done() 函数必须调用以关闭窗体.

var client = new AddinClient({
  callbacks: {
    init: (args) => {
      args.ready({
        showUI: true,
        title: 'Custom entry form tab'
      });
    }
  }
});

// To handle add-in events, call the addEventHandler method
client.addEventHandler(
  'form-save',
  function (context, done) {
    // handle the save event, asynchronously

    done(); // When done, call the done function (tells the entry form it's OK to close)
  }
);

添加可以启动"模式"用户体验,以显示更多细节或从用户收集额外输入. 模式将在一个单独的全屏iframe中提供,以尽量扩大现有的房地产(也就是说,其范围将不局限于添加的iframe的界限).

要启动模式,请呼叫 showModal 函数,通过模式的URL和模式所需的任何上下文数据:

// Parent add-in launching a modal
var client = new AddinClient({...});
client.showModal({
  url: '<modal-addin-url>',
  context: { /* arbitrary context object to pass to modal */ }
});

主机页面将为所提供的 URL 启动一个全屏幕 iframe, 并加载它作为添加, 和其他类型的添加一样. 模式页还必须在 SKY 添加客户端库中拉动并使用 AddinClient。。。 .

模式加成将负责使模式要素本身(包括模式内容周围的任何铬)。为了创建本土模式经验,添加内容可以使其文件背景透明,并在其全屏幕iframe中推出SKY UX模式.

从1.8版本开始,模式添加可以独立配置其文档背景并覆盖主机 modalConfig.style数字 :

选项	行为
`transparentBackground: true`	使文档添加 `html` 财务报告和审定财务报表 `body` 背景透明.
`transparentBackground: false` 或省略	保留添加的文档背景 .
`hostOverlay: false`	要求主机使其覆盖透明. 不支持此选项的主机忽略它 .
`hostOverlay: true` 或省略	保护主机可见的覆盖.

这些选项是独立的, 此库不会默认它们。图书馆适用 transparentBackground 作为内线 !important 样式,并在后面恢复以前的内行样式 ready 调用省略,否则客户端被销毁.

args.ready({
  showUI: true,
  modalConfig: {
    style: {
      transparentBackground: true,
      hostOverlay: false
    }
  }
});

与典型的加法一样,加法模式应当为 init 调用并接收 envId 在争论中。这个 context 参数字段将匹配上下文对象 showModal 由父加进的电话。请注意,这是跨越了iframes,所以该对象已经被序列化并被去序列化. 它可用于传递数据而不能用于函数.

模式加法负责触发与 closeModal 函数。它能够将上下文信息传递回父添加:

// Modal add-in rendered in full screen iframe
var client = new AddinClient({...});
client.closeModal({
  context: { /* arbitrary context object to pass to parent add-in */ }
});

父加进可以透过 modalClosed 答应从 showModal。承诺将在模式关闭时解决,并将包括从模式返回的上下文数据:

// Parent add-in launching a modal
var client = new AddinClient({...});
var modal = client.showModal({
  url: '<modal-addin-url>',
  context: { /* arbitrary context object to pass to modal */ }
});

modal.modalClosed.then((context) => {
  // Handle that the modal is closed.
  // Use the context data passed back from closeModal.
});

导航主页

添加者可以根据用户交互选择浏览母页. 要做到这一点,打电话 navigate 方法 AddinClient 对象。此函数带有属性对象参数 url 用来导航应使用完全合格的url.

var client = new AddinClient({...});
client.navigate({ url: '<target_url>' });

加入可以指示母页显示"帮助"flyout,并指定要显示的话题. 要做到这一点,打电话 openHelp 方法 AddinClient 对象。此函数带有属性对象参数 helpKey 用于显示帮助主题的名称。一个单一的.html文件应该命名.

var client = new AddinClient({...});
client.openHelp({ helpKey: '<target_page>.html' });

举起手来

添加可以指示母页显示敬酒. 要做到这一点,打电话 showToast 方法 AddinClient 对象。此函数带有属性的对象参数 message 财务报告和审定财务报表 style 代表吐司的内容和显示风格.

var client = new AddinClient({...});
client.showToast({ message: 'toast message', style: AddinToastStyle.Info });

添加可以启动"飞出"用户体验来显示额外信息.

发射飞出,呼叫 showFlyout 函数,通过飞出所需的URL和任何上下文数据:

// Parent add-in launching a flyout
var client = new AddinClient({...});
client.showFlyout({
  url: '<flyout-addin-url>',
  context: { /* arbitrary context object to pass to flyout */ }
});

主机页面将启动一个iframe用于提供URL,并按其他类型添加的方式加载. 飞出页还必须在 SKY 添加客户端库中拉出并使用 AddinClient。。。 .

与典型的加法一样,飞出加法应当登记 init 调用并接收 envId 在争论中。这个 context 参数字段将匹配上下文对象 showFlyout 由父加进的电话。请注意,这是跨越了iframes,所以该对象已经被序列化并被去序列化. 它可用于传递数据而不能用于函数.

加上一个可以关闭飞出通过呼叫 closeFlyout 函数:

// Close an open flyout from the client
var client = new AddinClient({...});
client.closeFlyout();

父加进可以透过 flyoutClosed 答应从 showFlyout承诺会解决的当飞行关闭:

// Parent add-in launching a flyout
var client = new AddinClient({...});
var flyout = client.showFlyout({
  url: '<flyout-addin-url>',
  context: { /* arbitrary context object to pass to flyout */ }
});

flyout.flyoutClosed.then(() => {
  // Handle that the flyout is closed.
});

显示确认对话框

加入可以指示母页显示确认对话框。要做到这一点,打电话 showConfirm 方法 AddinClient 对象。此函数带有属性的对象参数 message, (中文(简体) ), body,以及 buttons 代表要显示在确认对话框中的标题、正文和按钮 .

var client = new AddinClient({...});
client.showConfirm(
  {
    message: 'confirm title',
    body: 'confirm message body',
    buttons: [
      {
        action: 'ok',
        text: 'OK',
        autofocus: true,
        style: AddinConfirmButtonStyle.Primary
      },
      {
        action: 'cancel',
        text: 'Cancel',
        style: AddinConfirmButtonStyle.Link
      }
    ]
  }).then((action: string) {
    // Handle the action returned from the confirm dialog.
  });

显示错误对话框

添加可以指示母页显示错误对话框。要做到这一点,打电话 showError 方法 AddinClient 对象。此函数带有属性的对象参数 closeText, (中文(简体) ), description 财务报告和审定财务报表 title 表示用于在错误对话框上显示的按钮文本、去除错误和错误标题.

var client = new AddinClient({...});
client.showError(
  {
    closeText: 'OK',
    description: 'An unexpected error occurred',
    title: 'Error'
  });

隔页等待指标

加入可以指示母页显示一个页面屏蔽等待指示. 要做到这一点,打电话 showWait 方法 AddinClient 对象.

var client = new AddinClient({...});
client.showWait();

结束等待指标

添加可调用 hideWait 函数:

var client = new AddinClient({...});
client.hideWait();

将自定义事件发送到主机页面

添加可以发送自定义事件到主机页面,只要主机支持事件类型. 在将事件发送到主机页面之前,您必须注册 init 检查一下 supportedEventTypes 属性以确定主机页面将处理何种事件.

var supportedEventTypes;

var client = new AddinClient({
  callbacks: {
    init: (args) => {
      supportedEventTypes = args.supportedEventTypes;

      args.ready({
        showUI: true
      });
    }
  }
});

// Before sending event, check to make sure the event is supported by the host page
if (supportedEventTypes.includes('my-event-type')) {
  // To send add-in events to the host, call the sendEvent method
  client.sendEvent({
    type: 'my-event-type',
    context: { /* context object to pass to host page */ }
  }).then(() => {
    // host page received the event
  }).catch((err) => {
    // an error occurred while attempting to send the event
  });
}

为了确定支持自定义事件的扩展点, 请看 https://developer.blackbaud.com/skyapi/docs/addins/概念/extension-points (英语)。。。 .

认证

SKY 添加支持一个能用于将 Blackbaud 用户与添加的本地系统中的用户相连接的单签名(SSO)机制.

这个 AddinClient 页:1 getUserIdentityToken 从主机页面获取短寿命“用户身份标志”的函数。此令牌是向 SKY API 应用程序发行的签名值,并代表了 Blackbaud 用户的身份.

一般流量是,当一个添加被即时化时,它可以使用 getUserIdentityToken 函数。主机页面会将用户身份令牌还原为添加. 添加后可以将符号传递到自己的后端,在那里可以验证并用于查找添加后本地系统中的用户. 如果用户映射存在,那么添加可以向用户呈现内容. 如果没有用户映射,添加可以促使用户登录. 一旦用户在原生系统中的身份被了解后,添加可以坚持用户的映射,这样在后续加载时用户就不必再登录(甚至跨设备).

注意用户身份符是一款由SKY API OAuth 2.0服务署名的JWT,但不能用于给SKY API打电话. 为了让SKY API打电话,必须获得适当的SKY API访问令牌.

获取用户身份标识符

这个 getUserIdentityToken 函数将返回以符号值解决的许诺.

var client = new AddinClient({...});
client.getUserIdentityToken().then((token: string) => {
  // use the token.
  var userIdentityToken = token;
  . . .
});

验证符号

在从主机页面获得用户身份令牌后,添加后可以将令牌传递到自己的后端. 后端应首先对 SKY API OpenIDConnect 端点进行验证,以确保它没有过期或以任何方式被更改. 为了让后端信任用户身份符号,需要这个验证步骤.

OpenIDconnect 配置可见于 https://oauth2.sky.blackbaud.com/. well-chnow/openid-configulation 互联网档案馆的存檔,存档日期2014-12-21。。。 .

开发者在.NET中构建添加功能可以使用由Blackbaud提供的库来协助验证用户身份符. 此库作为 NuGet 软件包分发 Blackbaud.Addin.TokenAuthentication。该软件包将验证用户身份符号JWT的逻辑包裹起来,可以在 https://www.nuget.org/packages/ Blackbaud.Addin.TokenAuthentication (英语)。。。 .

以下 C# 代码片段显示如何使用 Blackbaud.Addin.TokenAuthentication 库以验证从添加客户端传递的 JWT 原始符号值 :

// this represents the user identity token returned from getUserIdentityToken()
var rawToken = "(raw token value)";

// this is the ID of the developer's SKY API application
var applicationId = "(some application ID)";

// create and validate the user identity token
UserIdentityToken uit;
try
{
    uit = await UserIdentityToken.ParseAsync(rawToken, applicationId);

    // if valid, the UserId property contains the Blackbaud user's ID
    var userId = uit.UserId;
}
catch (TokenValidationException ex)
{
    // process the exception
}

一旦该令牌被验证,添加后端将会知道Blackbaud用户ID,并且可以确定添加后端系统中是否有用户映射. 如果映射存在,那么添加后端可以立即显示添加的内容. 如果没有用户映射,添加可以促使用户登录.

关于Blackbaud的 SKY 添加框架的更多信息,请参见: https://developer.blackbaud.com/skyapi/docs/addins 页面存档备份,存于互联网档案馆。。。 .

版本	发布日期	距今
`1.8.0`latest	2026/10/01	1 个月前
`1.7.4`	2026/08/29	2 个月前
`1.7.3`	2026/03/25	7 个月前
`1.7.2`	2025/07/16	1.3 年前
`1.7.1`	2025/07/11	1.3 年前
`1.7.0`	2025/04/02	1.6 年前

@blackbaud/sky-addin-client

天添加客户端

安装

先决条件

ES6/ 类型脚本

香草爪哇脚本/ES5

使用量

初始化添加

平板加载

Tab 添加( 尚未支持, 但即将到来)

按键添加

条目表单添加

导航主页

打开 Blackbaud 帮助飞出( 仅内部使用)

举起手来

显示飞出

飞出添加

关闭飞出

显示确认对话框

显示错误对话框

隔页等待指标

结束等待指标

将自定义事件发送到主机页面

认证

获取用户身份标识符

验证符号

版本与发布记录

关于 @blackbaud/sky-addin-client 的常见问题

@blackbaud/sky-addin-client 是什么？

如何安装 @blackbaud/sky-addin-client？

@blackbaud/sky-addin-client 支持 TypeScript 吗？

@blackbaud/sky-addin-client 支持 ESM 还是 CommonJS？

@blackbaud/sky-addin-client 可以商用吗？

@blackbaud/sky-addin-client 的下载量有多少？

@blackbaud/sky-addin-client 还在维护吗？

@blackbaud/sky-addin-client

天添加客户端

安装

先决条件

ES6/ 类型脚本

香草爪哇脚本/ES5

使用量

初始化添加

平板加载

Tab 添加( 尚未支持, 但即将到来)

按键添加

条目表单添加

显示模式

模块加载

关闭模式

导航主页

打开 Blackbaud 帮助飞出( 仅内部使用)

举起手来

显示飞出

飞出添加

关闭飞出

显示确认对话框

显示错误对话框

隔页等待指标

结束等待指标

将自定义事件发送到主机页面

认证

获取用户身份标识符

验证符号

版本与发布记录

关于 @blackbaud/sky-addin-client 的常见问题

@blackbaud/sky-addin-client 是什么？

如何安装 @blackbaud/sky-addin-client？

@blackbaud/sky-addin-client 支持 TypeScript 吗？

@blackbaud/sky-addin-client 支持 ESM 还是 CommonJS？

@blackbaud/sky-addin-client 可以商用吗？

@blackbaud/sky-addin-client 的下载量有多少？

@blackbaud/sky-addin-client 还在维护吗？