SKY UX 添加客户端库

SKY UX 添加客户端库包裹下层 SKY 添加客户端库 并提供Angular服务,可以更方便地被SKY UX SPA所消耗. 它还提供了一个可选的插件,可以用来自动将环境标识上下文注入到您的 SKY UX SPA 中,从而去除在每个组件中跟踪和管理环境标识的需要.

安装

使用 npm 将库安装为您的工程的依赖 。 SKY UX 添加客户端库直接依赖SKY添加客户端库,因此不需要单独安装:

npm install --save @blackbaud/skyux-lib-addin-client

使用

要使用服务,请导入您的 SPA 服务 app-extras.module.ts 文件并添加到 providers 数组 :

import {
  NgModule
} from '@angular/core';

import {
  AddinClientService
} from '@blackbaud/skyux-lib-addin-client';

@NgModule({
  providers: [AddinClientService]
})

export class AppExtrasModule { }

然后,把它注入到你的组件中,作为构建器的一部分:

import {
  Component,
  OnInit
} from '@angular/core';

import {
  AddinClientService
} from '@blackbaud/skyux-lib-addin-client';

import {
  AddinClientInitArgs
} from '@blackbaud/sky-addin-client';

@Component({
  selector: 'my-tile',
  templateUrl: './my-tile.component.html',
  styleUrls: ['./my-tile.component.scss']
})
export class MyTileComponent implements OnInit {
  public context: any;

  constructor(private addinClientService: AddinClientService) {}

  public ngOnInit() {
    this.addinClientService.args.subscribe((args: AddinClientInitArgs) => {
      this.context = args.context;

      args.ready({
        showUI: true,
        title: 'My tile',
        tileConfig: {
          summaryStyle: AddinTileSummaryStyle.Text,
          summaryText: 'Summary text',
          showInlineHelp: true,
          showSettings: true
        }
      });
    });

    // Handle tile inline help icon click
    this.addinClientService.inlineHelpClick.subscribe(() => {
      this.showHelp();
    });

    // Handle tile settings icon click
    this.addinClientService.settingsClick.subscribe(() => {
      this.showSettings();
    });
  }

  private showHelp() {
    // Define what happens when the inline help icon is clicked
  }

  private showSettings() {
    // Define what happens when the settings icon is clicked
  }

}

这个 AddinClientService 为低级执行提供了包装方法。 这样您就可以使用 getUserIdentityToken() 函数(以前名为 getAuthToken():

this.addinClientService.getUserIdentityToken().subscribe((token: string) => {
  this.userIdentityToken = token;
});

您可以使用 navigate 方法 :

this.addinClientService.navigate({
  url: someUrl
});

帮助窗口可以使用 openHelp 方法 :

this.addinClientService.openHelp({
  helpKey: someHelpKey
});

您可以打开直接支持 a 的 SKY UX 组件的帮助 helpKey 通过提供 AddinClientHelpService数字 :

import {
  AddinClientService,
  provideAddinClientHelp,
} from '@blackbaud/skyux-lib-addin-client'

private openModal() {
  const options: SkyModalConfigurationInterface = {
    providers: [
      {
        ...
      }
      provideAddinClientHelp(),
    ],
  };

  const modalInstance = this.modalService.open(
    MyModalComponent,
    options,
  );
}

您可以使用 showModal 方法 :

this.addinClientService.showModal({
  url: someUrl,
  context: someContextObject
}).subscribe((modalResponse: any) => {
  // Define response from closing a modal
});

你可以用这个来表示敬酒 showToast 方法 :

this.addinClientService.showToast({
  message: someMessage,
  style: AddinToastStyle.Info
});

您可以使用 showFlyout 方法 :

this.addinClientService.showFlyout({
  url: someUrl,
  context: someContextObject
}).subscribe(() => {
  // Define what happens when a flyout has closed
});

您可以使用 showConfirm 方法 :

this.addinClientService.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
    }
  ]
}).subscribe((action) => {
  // Handle the action returned when the dialog closes
});

您可以使用 showError 方法 :

this.addinClientService.showError({
  closeText: 'OK',
  description: 'An unexpected error occurred',
  title: 'Error'
});

您可以使用 addEventHandler 方法 :

this.addinClientService.addEventHandler({
  eventType: 'form-data-update'
}).addinEvent.subscribe((addinEvent: AddinEvent) => {
  // get updated data from addinEvent.context object
});

this.addinClientService.addEventHandler({
  eventType: 'form-save'
}).addinEvent.subscribe((addinEvent: AddinEvent) => {
  // handle the save event, asynchronously

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

this.addinClientService.addEventHandler({
  eventType: 'form-cancel'
}).addinEvent.subscribe((addinEvent: AddinEvent) => {
  // handle the cancel event, asynchronously

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

this.addinClientService.addEventHandler({
  eventType: 'load-data'
}).addinEvent.subscribe((addinEvent: AddinEvent) => {
  // retrieve data based on the addinEvent.context object
  const data = [
    { id: 1, name: 'Item 1' },
    { id: 2, name: 'Item 2' }
  ];

  addinEvent.done(data);
});

只要主机支持事件类型,就可以将自定义事件发送到主机页面. 在将事件发送到主机页面之前, 您必须订阅 AddinClientService 的输入 args 事件并检查 supportedEventTypes 属性以决定主机页面的类型 将处理.

this.addinClientService.args.subscribe((args: AddinClientInitArgs) => {
  this.supportedEventTypes = args.supportedEventTypes;

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

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

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

最后,你可以显示/隐藏一个 页面屏蔽等待使用 showWait 财务报告和审定财务报表 hideWait 方法:

this.addinClientService.showWait();
// Execute code
this.addinClientService.hideWait();

额外配置

SKY UX 添加客户端允许通过扩展指定额外配置 AddinClientConfigService。 。 。 .

您可以允许您添加的客户端在一个 Blackbaud 主机页面中运行的额外来源 。 其他出处作为正则表达式模式提供. 这个 AddinClientService 默认已允许多个 Blackbaud 主机来源 。 如果您发现需要延长默认值,您可以通过压倒 AddinClientConfigService是因为 getAddinClientConfig() 方法.

class AddinConfigService extends AddinClientConfigService {
  public override getAddinClientConfig(): AddinClientConfig {
    return {
      allowedOrigins: [
        /^https\:\/\/[\w\-\.]+\.additionalblackbauddomain\.com$/
      ]
    };
  }
}

@NgModule({
  // specify providers
  providers: [
    AddinClientService,
    {
      provide: AddinClientConfigService,
      useClass: AddinConfigService
    }
  ]
})
export class MyModule { }

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

主机添加背景

从15.0.0版本开始,添加客户端给出添加文档SKY UX 在当前主题和模式下匹配添加所在位置的背景 :

• Modal 加入获得透明背景, 因此 SKY UX 模式背景显示后面 模式.
• 框、平板、平板和垂直标签表加载使用 SKY UX 容器背景, 如 SKY UX盒,瓷砖, 和飞出它们自己的内容.
• 页面、标签、通用、全页模式、按钮、动作按钮和数据集添加内容保留 本身的背景。 SKY UX 标签不提供内容背景, 所以一个 Tab 添加到 匹配其选项卡后的任何内容,通常是页面。 一个通用加载器被嵌入 sky-addin 而非更具体的类型,通常作为页面的一部分.
• 当客户端无法确定添加主机所在时, 它会使用 SKY UX 容器 背景情况.

客户加一个 <style> 这些背景的元素。 如果添加的内容 安全政策受到限制 style-src,通过 CSP_NONCE 或者说 页:1 ngCspNonce 属性,因为 Angular 需要组件样式。 客户申请 同样的非ce.

删除历史样式覆盖

Modal 添加先前需要的全局样式覆盖使其文档透明 并隐藏 SKY UX 模式背景 。 删除它们 :

::ng-deep body { background: transparent; }
::ng-deep .sky-modal-host-backdrop { display: none; }

客户端现在使文档本身透明, 并保持 SKY UX 模式的背景 可见。 在您删除这些规则之前,客户端会推翻隐藏规则 上下文,所以现有的加进继续工作.

不打开 SKY UX 模式的模块加载

一种使其内容直接化的模式,而不是打开SKY UX模式, 应保持自己的背景。 发送空样式 ready()数字 :

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

任意 modalConfig.style,包括一个空对象,关闭 那个 ready() 电话 见 模块样式。 。 。 .

选择添加的背景

要选择背景而不是自动背景,请扩展 AddinClientConfigService (见 额外配置)并覆盖 getHostedSurfaceMode()。它可以返回 :

每个客户都问 ready() 如果 任何,和增加的论据传递给 ready()。这样可以增加一个在 为每个选择几个位置, 例如按路由 :

class AddinConfigService extends AddinClientConfigService {
  readonly #router = inject(Router);

  public override getHostedSurfaceMode(
    context: AddinClientHostedSurfaceContext
  ): AddinClientHostedSurfaceMode {
    // The list page renders as part of the host's page, so it keeps the page background.
    return this.#router.url.startsWith('/single-list') ? 'preserve' : 'automatic';
  }
}

模式添加仍然可以设置 modalConfig.style 明确,无论模式如何.

模块样式

一个模式加载可以设置其文档背景,主机的覆盖可以明确通过 modalConfig.style。这两个选项是独立的:

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

在两个选项都设置之后,添加的文档和主机的覆盖都是透明的,所以 SKY UX模式背景是唯一可见的相片. 定义 modalConfig.style,包括 空对象, 关闭自动背景 ready() 电话.