SuiteScript 2.0 API 介绍

SuiteScript 2.0 Hello World

SuiteScript 2.0 是为增强和扩展 NetSuite 提供广泛选择的 JavaScript API。您可以使用 SuiteScript 自定义页面行为，创建自定义工作流，安排任务等等。

为了帮助您了解 SuiteScript 2.0 的工作原理，此主题将向您介绍基本自定义的实施。完成此主题中的步骤后，只要加载 NetSuite 任务记录，系统就会显示“Hello, World!”消息。

此主题包含以下部分：

  • 关键概念

  • 步骤一：启用功能

  • 步骤二：创建脚本文件

  • 步骤三：将脚本文件上传至 NetSuite

  • 步骤四：创建脚本记录和脚本部署记录

  • 步骤五：测试脚本

  • 后续步骤

关键概念

开始执行此主题中的步骤前，了解一些对于 SuiteScript 2.0 开发至关重要的概念和术语可能非常有用。其中一些术语在本主题后面出现的步骤中引用。您现在可阅读这些概念，或直接进入步骤一：启用功能。

SuiteScript 2.0 脚本类型和入口点

如果您之前编写过脚本，则可能更习惯于在编码前思考一些基本问题。这些问题可能包括：脚本需要完成哪些任务？脚本应在浏览器中运行还是应在服务器上运行？触发脚本的特定事件应是什么？

使用 SuiteScript 2.0，此过程的一部分涉及确定应使用系统的哪些预定义脚本类型。每种脚本类型均是针对特定类型的情况和特定类型的触发事件而设计的。以下是一些可用的SuiteScript 2.0 脚本类型：

  • SuiteScript 2.0 客户端脚本类型设计用于应在浏览器中运行的脚本。

  • SuiteScript 2.0 预定脚本类型适用于应在特定时间或按经常性计划运行的服务器端脚本。

  • SuiteScript 2.0 RESTlet 脚本类型适用于应由 NetSuite 外部应用程序通过 HTTP 调用时执行的服务器端脚本。

每种脚本类型均包括一个或多个专用于该类型的入口点。入口点表示系统将 NetSuite 应用程序的控制权授予脚本的接合点。将入口点包括在脚本中时，您告知系统在调用该入口点时应执行某些操作。具体来说，您告诉系统它应该执行脚本中定义的函数。该函数称为入口点函数。

对于许多脚本类型，可用入口点类似于事件类型 - 可能发生的各种事情 - 以触发脚本。例如，客户端脚本类型的入口点表示在浏览器会话期间可能发生的事件。这些入口点包括表示字段值更改的 fieldChanged 和表示页面加载的 pageInit。相比之下，预定脚本类型仅有一个入口点，称为 execute。表示计划执行脚本的时间点或用户手动执行脚本的时间点。

在本主题中使用的示例中，您希望在浏览器中工作的用户加载 NetSuite 任务记录页面时，系统将显示一个对话框警告。为此，此示例使用客户端脚本类型和 pageInit 入口点。

SuiteScript 2.0 模块

SuiteScript 2.0 有一个模块化架构。作为其中的一项指示，所有 SuiteScript 2.0 API 均被组织成一系列标准模块。每个模块的名称都反映了它的功能。例如，N/record 模块让您能够与 NetSuite 记录进行交互。N/https 模块让您能够将 https 请求发送至外部 Web 服务。

在脚本可以访问模块的 API 前，该脚本必须显式加载大部分模块。在非常高的层次上，加载 JavaScript 模块类似于在 Java 中导入库。这是种提供权限以访问在其他地方定义的逻辑的方式。在入口点脚本中，您可通过使用 define 对象加载模块。列出您想要加载为 define 函数参数的模块。

相反，一些 API 全局可用。当一个对象、方法或函数全局可用时，即使您没有显式加载它所属的模块，也可以使用它。全局可用的 API 列在SuiteScript 2.0 全局对象中。

本主题中的示例使用两种方法：它使用全局可用的 API。它还使用仅在加载适当模块后才可用的方法。

入口点脚本与自定义模块脚本

此主题中的示例脚本相对简单。其所有逻辑均包含在一个脚本文件中。但是，您可能希望创建依赖于其他脚本文件中定义的逻辑的脚本。在 SuiteScript 2.0 中，这些支持脚本文件称为自定义模块脚本。

相反，主脚本文件 - 确定脚本类型、入口点和入口点函数的文件 - 被称为入口点脚本。系统对入口点脚本施加格式要求，这些要求与自定义模块脚本的格式要求不同。此主题中的其余步骤强调了入口点脚本存在的一些要求。

自定义模块脚本不包含在此主题中。有关自定义脚本模块的信息，请参阅 SuiteScript 2.0 自定义模块。

 

步骤一：启用功能

完成此主题中的其余步骤前，必须在 NetSuite 账户中启用客户端 SuiteScript 功能。

如果不确定是否已启用该功能，可通过导航至Customization > Scripting > Scripts进行查看。如果可访问该路径，则说明该功能已启用。如果未出现该选项，可能是因为您没有访问权限，或该菜单路径已自定义。如果您不能确定，请咨询您的账户管理员。

可以由账户管理员或具有“启用功能”权限的用户启用该项功能。要启用该功能，授权用户应完成以下步骤。

要启用客户端 SuiteScript 功能：

  1. 选择Setup > Company > Setup Tasks > Enable Features。

  2. 点击 SuiteCloud 子标签。

  3. 找到客户端 SuiteScript 选项。如果已勾选此框，则跳转至步骤二：创建脚本文件。如果未勾选，请勾选此框。系统显示列出服务条款的窗口。

  4. 如果同意这些条款，请滚动至窗口底部并点击我同意。
  5. 此主题中所述步骤无需服务器 SuiteScript。但是，如果您打算进一步进行 Suitescript 部署，考虑勾选服务器 SuiteScript 框。如果您勾选此框，系统会显示另一个窗口，以列出服务条款。点击同意。

  6. 点击保存。

步骤二：创建脚本文件

继续前，必须创建名为 helloWorld.js 的脚本文件。要创建此文件，您可以使用以下任一种方法：

  • 如果要直接从本帮助主题复制和粘贴已完成脚本，请跳转至复制完整脚本。

  • 如果要了解如何自我构建脚本，请参考逐步创建脚本。

逐步创建脚本

以下步骤将引导您完成创建 helloWorld.js 示例脚本。对于任何入口点脚本均需此过程中的许多步骤。

要创建脚本文件：

        1. 在所选文本编辑器中打开新文件。

        2. 添加两个 JSDoc 标记：@NApiVersion 和 @NScriptType。在每个标记之后，添加适当的值，如下面的代码段所示。

          /**
 *@NApiVersion 2.0
 *@NScriptType ClientScript
 */

...

          这些标记反映以下内容：

            • 正在使用的 SuiteScript 版本。

            • 正在使用的脚本类型。

              • 每个 SuiteScript 2.0 入口点脚本必须包括这些标签。对于每个标签，您只能添加一个值。有关更多信息和有效值列表，请参阅
          SuiteScript 2.0 JSDoc 标记。
        3. 添加define 对象。每个入口点脚本都必须使用此函数。 使用 [‘N/ui/dialog’] 作为 define 函数的第一个参数。第一个参数是一个字符串值数组，表示函数应加载的模块。 
          ...
define(['N/ui/dialog'],

    // In Step 4, you put additional code here.

);

          N/ui/dialog 模块包括显示各类型对话框的方法。您加载此模块，以便脚本可以使用这些方法之一。

        4. 声明一个回调函数。回调函数是 define 函数的第二个参数。给这个函数一个名为对话框的参数。 
          ...     
    function(dialog) { 

        // In Step 5, you put additional code here.

    } 
...

          如果不熟悉回调函数，请记住，此函数将包含脚本的所有其他逻辑。另外，请记住，回调函数使用的参数数量必须等于 define 函数加载的模块数量。每个参数都是一个对象，允许您访问它所代表的模块。作为最佳实践，为每个参数指定一个类似于相应模块的名称。

          在此示例中，define 函数仅加载一个模块，因此回调函数只有一个参数。

          　　

        5. 在回调函数中，声明一个名为 helloWorld 的函数。 
          ...
        function helloWorld() {

            // In steps 6-10, you put additional code here.

        }
...

          稍后，您将 helloWorld 函数指定为脚本的入口点函数。每个入口点脚本都必须有一个入口点函数。

          仅当函数链接到入口点时，才将该函数视为入口点函数。您在步骤 11 中创建此链接。

        6. 在入口点函数中，创建一个名为选项的对象。

          许多 SuiteScript 2.0 方法要求或可接收普通 JavaScript 对象作为其参数。用于创建“Hello, World！”对话框的方法属于这一类别。 此方法接受具有两个参数（标题和消息）的对象。

          ... 
            var options = {
                title: 'Hello!',
                message: 'Hello, World!'
            };
...

           

        7. 添加 try/catch 语句。该语句并非必填项。但是，此方法可让您的脚本从容地处理错误。也就是说，如果发生错误并由 try/catch 语句处理，则可继续执行脚本以及页面中部署的任何其他内容。使用 try/catch 语句还可以帮助您了解问题发生的原因。请注意，try/catch 关键词是 JavaScript 的一部分，并非特定于 Suitescript 2.0。

          基本 try/catch 语句由两部分组成。try 块包含您想要执行的代码。catch 块则包含在 try 块期间遇到 JavaScript 错误时应执行的逻辑。

          将 try/catch 语句添加到在步骤 6 中创建的对象后。

          ...
            try {

                // In steps 8 and 9, you put additional code here.

            } catch (e) {

                // In Step 10, you put additional code here.

            }
...

           

        8. 对于 try 块的首个操作，调用 N/ui/dialog 模块’s alert() 方法。此方法创建包含标题、消息和“确定”按钮的对话框。

          您可以使用在步骤 4 中命名为对话框的对象来调用此方法。您还可以使用方法的名称警告。要定义对话框的标题和消息，请进入标题为 options 的对象。

          ...
                dialog.alert(options);
...

          有关此方法的更多详细信息，请参阅dialog.alert(options)参考页面。请注意，dialog.alert(options)参考页面的标题与您添加到脚本中的代码相匹配。但请注意，标准模块方法的参考页面可能并不总是反映您的命名约定。例如，如果在声明回调函数时指定了名为 message 的参数，则可以使用表达式 message.alert(options) 调用警告方法。

          同样地，请注意在文档中，各方法参数通常被引用为名为 options 的对象。但可在脚本中将对象命名为任何名称。您还可以直接创建对象，作为调用该方法过程的一部分。

        9. 系统成功显示对话框后，添加逻辑以创建日志条目。为此，请使用全局可用的 log.debug(options) 方法。

          在日志对象上调用 debug() 方法。与您必须采取步骤访问的对话框对象不同，日志对象可供每个脚本使用。因此，您不必为此对象指定名称，这样您就可以总是编写 log.debug 来调用此方法。

          此方法采用一个具有两个属性（标题和详细消息）的对象。这一次，直接创建对象。将此样式与您在步骤 5 中创建对象的方式进行对比，然后通过名称将该对象传至 alert() 方法。

          ...
                log.debug ({
                    title: 'Success',
                    details: 'Alert displayed successfully'
                });
...

          当用户触发对话框警告时，将在 UI 中创建日志条目。步骤五：测试脚本中介绍了如何查找此日志的说明。

        10. 在 catch 块中，如果发生错误，则添加逻辑以创建日志条目。请使用全局可用的log.error(options)方法。log.error() 方法类似于 log.debug() 方法。唯一的区别是，使用 log.error() 时，日志条目被归类为类型错误的条目，而不是调试。 
          ...
                log.error ({ 
                    title: e.name,
                    details: e.message
                });           
...

           

        11. 紧随入口点函数后添加 return 语句。在每一个 SuiteScript 2.0 入口点脚本中，return 语句必须至少包括一个具有两个组件的行：

            • 在这种情况下入口点是 pageInit。

            • 在这种情况下函数是 helloWorld。

              ...
        return {
            pageInit: helloWorld
        };
...

              由于这个引用，helloWorld 被认为是入口点函数。

              尽管此脚本仅使用一个入口点，return 语句可包括多个入口点。允许使用多个入口点，只要它们都属于文件顶部的 @NScriptType 标签可以识别的脚本类型即可。例如，除了pageInit之外，客户端脚本类型还包括saveRecord。假设您希望此脚本在页面加载时执行某项操作，然后在用户点击“保存”时执行另一项操作，您可以使用两个入口点。有关使用多个入口点的脚本示例，请参阅 SuiteScript 客户端脚本示例。

           

        12. 保存文件，并将其命名为 helloWorld.js。

          复制完整脚本

          以下部分显示的是完整示例脚本。如果尚未使用逐步创建脚本中所述步骤创建脚本文件，请将以下代码复制并粘贴到文本文件中。保存文件并将其命名为 helloWorld.js。

                     
                dialog.alert(options);
           
                log.debug ({
                    title: 'Success',
                    details: 'Alert displayed successfully'
                });
        
            } catch (e) {
           
                log.error ({ 
                    title: e.name,
                    details: e.message
                });           
            } 
        }
              
    return {
        pageInit: helloWorld
    };
});

          步骤三：将脚本文件上传至 NetSuite

          创建入口点脚本文件后，将其上传至 NetSuite 文件柜。

          要上传脚本文件：

          1. 在 NetSuite UI 中，转到Documents > Files > File Cabinet。

          2. 点击添加文件。

          3. 按照提示在本地环境中找到 helloWorld.js 文件并上传。

          请注意，即使在文件上传后，如有需要也可在“文件柜”内对其进行编辑。有关详细信息，请参阅在文件柜中编辑文件。

          步骤四：创建脚本记录和脚本部署记录

          通常，在账户中可执行入口点脚本前，您必须创建代表入口点脚本文件的脚本记录。您还必须创建脚本部署记录。

          脚本部署记录包括在执行脚本时确定的部分逻辑。其中部分逻辑通过脚本使用的入口点包括在脚本中。例如，通过使用pageInit入口点，您可告知系统脚本应在页面加载时执行。但是，您还必须标识特定页面，该页面在加载时会导致脚本执行。换句话说，您必须告知系统该脚本应执行的记录类型。为此，使用脚本部署记录。

          这些记录可通过编程方式予以创建。此外，还可在 UI 中创建，如以下程序所述。

          要创建脚本记录和脚本部署记录：

          1. 请转到Customization > Scripting > Scripts > New。

          2. 在脚本文件下拉列表中，选择 helloWorld.js。

            请注意，如果尚未上传文件（如步骤三所述），则可从此页面上传文件。使用光标，指向下拉列表右侧以显示加号图标。点击此图标以打开可上传文件的窗口。

          3. 填充下拉列表后，点击创建脚本记录按钮。

            作为响应，系统将显示新的脚本记录，并在脚本子标签上列出 helloWorld.js 文件。

          4. 完成必填正文字段，如下所述：

            • 在名称字段中，输入 Hello World 客户端脚本。

            • 在 ID 字段中，输入 _cs_helloworld。

          5. 点击部署子标签。您可以使用此子标签创建部署记录。

          6. 在子列表中添加一行，如下所述：

            • 将应用于下拉列表设为任务。（请注意，若想要在加载不同类型记录时显示对话框，可从列表中选择其他记录类型。）

            • 在 ID 字段中，输入 _cs_helloworld。

            保留设为其默认值的其他字段。请注意，状态字段应设为正在测试。此值意味着该脚本不会部署用于其他用户。（如果您想稍后更改部署并使此自定义可用于所有用户，则可编辑部署并将状态设置为已发布。）

          7. 点击保存。

            系统创建脚本和脚本部署记录。

            步骤五：测试脚本

            由于脚本已部署，应验证其是否按预期运行。

            要测试脚本：

            1. 请在脚本执行以下操作时验证显示的对话框警告：

              1. 通过转到Vendor Dashboard > Activities > Tasks > New打开任务记录。

              2.  

                如果脚本正常工作，系统将会显示对话框警告。 

                验证预期日志条目是否已保存至脚本部署记录：

                1. 请转到Customization > Scripting > Script Deployments (Administrator)。

                2. 找到部署并点击相应的查看链接。

                   

                   

                  点击执行日志子标签。

                  子标签应显示类似于以下内容的条目。

                  脚本记录的“执行日志”上也会显示相同条目。

                  如果遇到错误，您创建的错误日志条目而不是调试条目将显示。

                3. 后续步骤

                  由于您已部署首个脚本，考虑浏览SuiteScript 2.0 API 介绍中的其他主题。或者，如果您想尝试使用其他脚本示例，请尝试以下操作：

                  • 另一常用脚本类型为用户事件类型。此类型专为服务器端脚本设计，应在用户对记录采取某些操作时执行。要尝试简单的用户事件脚本，请参阅 SuiteScript 2.0 用户事件脚本教程。

                  • 对于略显复杂的用户事件脚本，请参阅 SuiteScript 2.0 用户事件脚本示例。

                  • 有关自定义模块脚本示例以及调用自定义模块函数的用户事件脚本的示例，请参阅 SuiteScript 2.0 自定义模块教程。

posted @ 2019-12-26 15:19  Bruce-Hu  阅读(1140)  评论(0)  编辑  收藏  举报