编写第一个客户端脚本

准备编写你的第一个客户端脚本来实际观察其运行效果吗？ 让我们开始吧。 我们将保持简单。

目标

完成本演练后，了解如何在模型驱动应用中使用 JavaScript 代码。 此过程涉及以下高级步骤：

  • 找到或创建一个解决方案，将你的工作添加到其中。
  • 编写 JavaScript 代码以解决业务问题
  • 将代码作为 Web 资源上传
  • 将 Web 资源关联到窗体
  • 配置表单和字段事件
  • 测试代码

步骤 1：查找或创建解决方案

使用解决方案将自定义项从一个环境传输到另一个环境。 在开发环境中编写和测试 JavaScript 代码，作为非托管解决方案的一部分。 完成测试后，将解决方案导出为托管解决方案，并将其导入或安装到生产环境中。

现有解决方案可能已可供你使用。 想要使用脚本自定义的模型驱动应用应已是解决方案的一部分。 可以编辑该解决方案，也可以创建依赖于另一个现有解决方案的新解决方案。

创建新解决方案

  1. 转到 Power Apps。

  2. 在左侧导航窗格中，选择解决方案，然后选择新建解决方案。

  3. 在浮出对话框中，输入显示名称、名称和发布服务器。

    大多数公司都有一个他们始终使用的现有发布者。 使用该发布者。 如果你是第一个人，请创建自己的发布者。

    选择 “新建发布服务器 ”以打开 “新建发布服务器 ”对话框。 本演练中，请使用具有以下定义的发布者工具：

    用于创建包含示例发布服务器信息的新发布者表单

    请注意 前缀 值。 此值应标识你的公司。 在本例中，请使用 example。

    这是您在本演练中使用的解决方案。

    第一个客户端脚本解决方案的解决方案窗体

  4. 找到或向解决方案添加模型驱动应用。

    新解决方案不包含任何模型驱动应用。 需要添加现有的模型驱动应用或创建新的应用。

    注释

    为了本演练，请确保应用包含账户表。 下面的脚本和说明要求在帐户表的窗体中找到字段。

    选项 A：将现有模型驱动应用添加到解决方案

    1. 在解决方案中，选择“ 添加现有的>应用>模型驱动应用”。

    添加现有的模型驱动应用

    1. 选择现有应用，然后选择“ 添加”。

    选项 B：在解决方案中创建新的模型驱动应用

    在解决方案中，选择“新建>应用>”。

    请参阅 生成第一个模型驱动应用 教程。 创建包含帐户表的应用。

步骤 2：编写 JavaScript 代码

第一步是使用客户端脚本确定要解决的业务问题。 确定问题时，请编写包含解决业务问题的自定义业务逻辑的 JavaScript 代码。

模型驱动应用不提供 JavaScript 编辑器。 使用专门支持编辑 JavaScript 文件功能的外部编辑工具，例如 Notepad++、Visual Studio Code 或 Microsoft Visual Studio。

本演练使用以下 JavaScript 代码：

// A namespace defined for the sample code
// As a best practice, you should always define 
// a unique namespace for your libraries
var Example = window.Example || {};
(function () {
    // Define some global variables
    var myUniqueId = "_myUniqueId"; // Define an ID for the notification
    var currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName; // get current user name
    var message = currentUserName + ": Your JavaScript code in action!";

    // Code to run in the form OnLoad event
    this.formOnLoad = function (executionContext) {
        var formContext = executionContext.getFormContext();

        // Display the form level notification as an INFO
        formContext.ui.setFormNotification(message, "INFO", myUniqueId);

        // Wait for 5 seconds before clearing the notification
        window.setTimeout(function () { formContext.ui.clearFormNotification(myUniqueId); }, 5000);
    }

    // Code to run in the column OnChange event 
    this.attributeOnChange = function (executionContext) {
        var formContext = executionContext.getFormContext();

        // Automatically set some column values if the account name contains "Contoso"
        var accountName = formContext.getAttribute("name").getValue();
        if (accountName.toLowerCase().search("contoso") != -1) {
            formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
            formContext.getAttribute("telephone1").setValue("425-555-0100");
            formContext.getAttribute("description").setValue("Website URL, Phone and Description set using custom script.");
        }
    }

    // Code to run in the form OnSave event 
    this.formOnSave = function () {
        // Display an alert dialog
        Xrm.Navigation.openAlertDialog({ text: "Record saved." });
    }
}).call(Example);

将此代码复制到文本文件中，并将其另存为 Example-form-script.js。

详细的代码说明

让我们详细查看代码：

  • 定义命名空间：代码首先定义自定义脚本的命名空间。 最佳实践是始终创建具有命名空间的 JavaScript 库，以避免您的函数被另一个库中的函数覆盖。

    var Example = window.Example || {};

    在这种情况下，可以使用此库中定义的所有函数作为 Example.[functionName]. 选择与解决方案发布者名称匹配的命名空间。

  • 定义全局变量：以下部分定义要在脚本中使用的一些全局变量。 可以使用 Xrm.Utility.getGlobalContext 方法全局访问上下文信息。

    // Define some global variables
var myUniqueId = "_myUniqueId"; // Define an ID for the notification
var currentUserName = Xrm.Utility.getGlobalContext().userSettings.userName; // get current user name
var message = currentUserName + ": Your JavaScript code in action!";

  • 在 OnLoad 事件上执行的函数：本节包含在帐户窗体加载时执行的函数。 例如，创建新帐户记录或打开现有帐户记录时。

    该 Example.formOnLoad 函数使用 executionContext 参数获取 formContext 对象。 稍后使用表单事件附加代码时，请选择将 执行上下文 传递给此函数的选项。

    此函数使用 formContext.ui.setFormNotification 方法显示窗体级别通知。

    最后，此函数使用 JavaScript setTimeOut 方法 延迟 formContext.ui.clearFormNotification 方法的执行，以在 5 秒后清除通知。

    // Code to run in the form OnLoad event
this.formOnLoad = function (executionContext) {
    var formContext = executionContext.getFormContext();

    // Display the form level notification as an INFO
    formContext.ui.setFormNotification(message, "INFO", myUniqueId);

    // Wait for 5 seconds before clearing the notification
    window.setTimeout(function () { formContext.ui.clearFormNotification(myUniqueId); }, 5000);        
}

  • 在 OnChange 事件上执行的函数：将 Example.attributeOnChange 函数与帐户窗体中的 “帐户名称 ”列相关联，以便 仅在 更改帐户名称值时执行该函数。

    该函数在帐户Contoso中执行对name的不区分大小写的搜索，如果找到，则为账户表单中的websiteurl、telephone1和description列设置值。

    // Code to run in the column OnChange event 
this.attributeOnChange = function (executionContext) {
    var formContext = executionContext.getFormContext();

    // Automatically set some column values if the account name contains "Contoso"
    var accountName = formContext.getAttribute("name").getValue();
    if (accountName.toLowerCase().search("contoso") != -1) {
        formContext.getAttribute("websiteurl").setValue("https://www.contoso.com");
        formContext.getAttribute("telephone1").setValue("425-555-0100");
        formContext.getAttribute("description").setValue("Website URL, Phone and Description set using custom script.");
    }
}

  • 在 OnSave 事件上执行的函数：该 Example.formOnSave 函数使用 Xrm.Navigation.openAlertDialog 方法显示警报对话框。 此对话框显示一条消息，其中包含 “确定 ”按钮。 用户可以通过选择 “确定”关闭警报。

    注释

    此函数不使用执行上下文，因为 Xrm.Navigation 。方法不需要它。

    // Code to run in the form OnSave event 
this.formOnSave = function () {
    // Display an alert dialog
    Xrm.Navigation.openAlertDialog({ text: "Record saved." });
}

步骤 3：将代码作为 Web 资源上传

代码准备就绪后，请将其上传到解决方案中。

  1. 在解决方案中，选择“ 新建>更多>Web 资源”。

    向解决方案添加新的 Web 资源

  2. 在“ 新建 Web 资源 ”对话框中，选择 “选择文件 ”，然后选择 Example-form-script.js 之前保存的文件。

  3. 输入显示名称、名称，以及可选的说明。 确保类型为 JavaScript （JS）。

    用于创建示例表单脚本的“新建 Web 资源”对话框

    注释

    • 名称具有与解决方案发布者自定义前缀匹配的前缀。 还有其他方法可以创建 Web 资源，但通过这种方式创建 Web 资源可确保 Web 资源是解决方案的一部分。
    • Web 资源的名称为 example_example-form-script.

步骤 4：将 Web 资源关联到窗体

  1. 在解决方案中，选择“对象>应用>你的应用”，然后单击“编辑”。

    在解决方案中编辑应用

  2. 展开 “帐户 ”，然后选择 “帐户”窗体。 单击信息窗体右侧的省略号（...），然后选择“编辑”。

    编辑帐户信息表单

  3. 在左侧导航中，选择 “窗体库 ”，然后单击“ 添加库”。

    将库添加到表单

  4. 在“添加 JavaScript 库”对话框中，搜索按名称创建的 JavaScript Web 资源： Example Script

    “添加 JavaScript 库”对话框

  5. 选择 示例脚本 Web 资源，然后单击“ 添加”。

步骤 5：配置表单和字段事件

  1. 选择“ 事件 ”选项卡。

    表单事件处理程序

配置窗体的“On Load”事件

  1. 选择加载事件处理程序，然后单击+ 事件处理程序。

    在加载处理程序上配置窗体

    请确保以下设置正确：

    • 事件类型为“加载时”。
    • 已选择 example_example-form-script 库。
    1. 在 函数 字段中键入函数的名称。 在本例中，输入 Example.formOnLoad。
    2. 选择“ 传递执行上下文”作为第一个参数。
    3. 单击完成。

配置“保存时”事件的窗体

  1. 选择“ 保存时 ”事件处理程序，然后选择“ + 事件处理程序”。

    配置表单的保存时处理程序

    请确保以下设置正确：

    • 事件类型为“保存时触发”。
    • 已选择 example_example-form-script 库。
    1. 在 函数 字段中键入函数的名称。 在本例中，输入 Example.formOnSave。

      注释

      无需选择 “传递执行上下文”作为此函数的第一个参数 ，因为它不使用它。

    2. 选择“ 完成”。

配置“更改事件时”字段

  1. 选择 “帐户名称 ”字段和“ 事件 ”选项卡。

    选择“帐户名称”字段事件

  2. 选择 On Change 事件处理程序，然后单击 + 事件处理程序。

    配置字段 OnChange 处理程序

    请确保以下设置正确：

    • 事件类型为 On Change。
    • 已选择 example_example-form-script 库。
    1. 在 函数 字段中键入函数的名称。 在此案例中，ID 为 Example.attributeOnChange。
    2. 选择“ 传递执行上下文”作为第一个参数。
    3. 选择“ 完成”。

保存和发布更改

保存 窗体，然后单击“ 发布”。

步骤 6：测试代码

刷新浏览器，确保更改在模型驱动应用实例中生效。

要测试你的代码：

  1. 转到 Power Apps。

  2. 在左侧导航中，选择 “应用”。

  3. 打开刚刚编辑的模型驱动应用，或选择它并选择“ 播放”。

    打开应用进行测试

加载时的测试表单函数

  1. 选择列表中的任意帐户记录将其打开。

  2. 验证是否显示通知。

    有关表单加载的通知

  3. 验证通知在 5 秒内消失。

更改函数上的测试字段

  1. 编辑帐户名称以在名称中包含“Contoso”，然后按 Tab 移动到下一列。

  2. 验证设置为 “主电话”、“ 网站”和 “说明 ”列的预期值。

    字段更改时设置的值

“保存”函数上的测试窗体

  1. 选择“保存”。

  2. 验证警报对话框是否显示代码中配置的消息。

    保存窗体时的警报对话框

  3. 选择 “确定” 关闭警报。

调试模型驱动应用的 JavaScript 代码
模型驱动应用的表单和网格中的事件
Form OnLoad 事件
模型驱动应用中的 Form OnSave 事件（客户端 API 参考）
列 OnChange 事件（客户端 API 参考）

  • Last updated on