教程 4：调用脚本

应用制作工具中级技能

大约 45 分钟。

您将构建的内容

您将构建一个允许用户撰写和发送富文本 (HTML) 电子邮件消息的应用。该应用使用客户端脚本和服务器脚本。

您将学到的内容

本教程将指导您如何执行以下操作：

• 创建并调用客户端脚本
• 创建并调用服务器脚本
• 使用“Text Editor”微件的值，发送带有 HTML 正文的电子邮件消息。

创建应用

1. 登录雇主或学校提供的 G Suite 帐号。
2. 打开应用制作工具。
3. 创建一个空应用：
   • 如果应用制作工具显示欢迎对话框，点击 Create New App。
   • 否则，点击 “Menu” New Blank Application。
4. 重命名应用。删除默认名称 Untitled App，然后输入 Email Sender。

创建界面

您将构建一个如下所示的表单：

要创建此界面，请执行以下操作：

1. 重命名该页面：

   1. 在左侧边栏中，将鼠标悬停在 NewPage 上方，并点击“More” Rename。

   2. 输入 Email，然后点击 OK。

      提示：有效字符包括字母、非前导数字和非前导下划线。

2. 添加用于收件人的文本框：

   1. 点击“Widgets” 并将“Text Box” 拖动到画布左上角附近。

   2. 拖动右侧手柄，以增加文本框的长度。

   3. 在属性编辑器中，将文本框的 name 属性更改为 To 并输入 To: 作为 label 属性。

3. 为主题添加文本框：

   1. 点击“Widgets” 并将“Text Box” 拖动到“To”文本框下方。

   2. 拖动右侧手柄，以增加文本框的长度。

   3. 在属性编辑器中，将文本框的 name 属性更改为 Subject 并输入 Subject: 作为 label 属性。

4. 添加一个文本编辑器以用于电子邮件消息的正文：

   1. 点击“Widgets” 并将“Text Editor” 拖动到“Subject”文本框下方。

   2. 在属性编辑器中，将文本编辑器的 name 属性更改为 Msg。

      提示：对于纯文本条目，您可以使用“Text Area”微件。

5. 添加一个按钮，供用户点击以发送电子邮件消息：

   1. 将“Widgets” 中的“Button” 拖动到“To”文本框右侧的画布上。双击该按钮，将其重命名为 Send Email。

6. 定义当用户点击“Send Email”按钮时要采取的操作。

   1. 点击 Send Email。

   2. 在属性编辑器 “Button”部分，点击 onClick 属性并选择 Custom Action。

   3. 使用 JavaScript 定义该操作。在“Client Script”对话框中，复制并粘贴以下脚本：

          var widgets = widget.parent.descendants;
          var to = widgets.To.value;
          var subject = widgets.Subject.value;
          var msg = widgets.Msg.value;
          widgets.EmailStatus.text = 'Sending email...';
          sendMessage(to, subject, msg); 

      在 action 中，请注意以下对应用制作工具对象和属性的引用：
      • widget.parent.descendants—“Send Email”按钮的父级微件是页面的顶级面板。该面板的后代包括页面上的所有微件。
      • widgets.To.value、widgets.Subject.value、widgets.Msg.value 和 widgets.EmailStatus.text— - 三个微件的 value 属性和第四个微件的 text 属性。

   4. 按 Esc 关闭对话框。

7. 添加一个按钮，供用户点击以清除表单上的所有字段：

   1. 将“Widgets” 中的“Button” 拖动到文本编辑器下方的画布上。双击该按钮，将其重命名为 Clear Form。

8. 定义当用户点击“Clear Form”按钮时要采取的操作。

   1. 点击 Clear Form。

   2. 在属性编辑器 “Button”部分，点击 onClick 属性并选择 Custom Action。

   3. 使用 JavaScript 定义该操作。在“Client Script”对话框中，复制并粘贴以下脚本：

      clearEmailForm();

9. 添加一个标签来指示状态：

   1. 将“Widgets” 中的“Label” 拖动到文本框下方的画布上。

   2. 在属性编辑器中，将 name 属性设置为 EmailStatus。删除 text 属性。

10. 点击 “Close” 关闭对话框。

了解应用将使用的脚本

在此步骤中，您将复制您的应用发送电子邮件和清除表单所需的 JavaScript 函数，并将它们粘贴到应用中的脚本。脚本是应用制作工具中的容器，与脚本文件类似：

• 客户端脚本 - 包含浏览器的 JavaScript 引擎运行的 JavaScript。
• 服务器脚本 - 包含应用制作工具服务器上的 JavaScript 引擎运行的 JavaScript。

提示：您可以将所有客户端 JavaScript 函数置于一个客户端脚本中，将所有服务器 JavaScript 函数置于一个服务器脚本中，但我们建议将您的 JavaScript 函数整理到多个脚本中。例如，将重要的函数分别置于单独的脚本中，将辅助函数置于相关脚本中。

客户端脚本函数

clearEmailForm

clearEmailForm 函数可清除整个电子邮件清单。

sendMessage

sendMessage 函数

• 调用 sendEmailMessage 服务器脚本以发送电子邮件消息
• 调用 clearEmailForm 客户端脚本以清除电子邮件表单

服务器脚本函数

sendEmailMessage

sendEmailMessage 服务器脚本函数调用 MailApp.sendEmail 函数以发送电子邮件消息。MailApp.sendEmail 的 htmlBody 选项表示消息正文为 HTML。

创建客户端脚本

1. 创建客户端脚本，其中包含客户端将要运行的函数。

   1. 将鼠标悬停在 Scripts 上方，然后点击 以添加脚本。

   2. 出现“Create script”对话框后，使 Client 保持选中状态，取消勾选 Generate sample code，然后点击 Create。

2. 重命名客户端脚本：

   1. 在左侧边栏中，将鼠标悬停在 NewPage 上方，并点击 More Rename。

   2. 输入 ClientScript，然后点击 OK。

3. 复制此 JavaScript 并将其粘贴到 ClientScript：

   /**
       * Clears the entire email form
       */
       function clearEmailForm(){
         var formWidgets = app.pages.Email.descendants;
         formWidgets.EmailStatus.text = "";
         formWidgets.To.value = "";
         formWidgets.Subject.value = "";
         formWidgets.Msg.value = "";
       }
       /**
       * Sends an email message.
       * @param {string} to - Message recipient
       * @param {string} subject - Message subject
       * @param {string} msg - Body of message (HTML from Text Editor)
       */
       function sendMessage(to, subject, msg){
         var status = app.pages.Email.descendants.EmailStatus;
         google.script.run
          .withFailureHandler(function(error) {
             // An error occurred, so display an error message.
             status.text = error.message;
           })
         .withSuccessHandler(function(result) {
            // Report that the email was sent.
            status.text = 'Email sent...';
         clearEmailForm();
          })
        .sendEmailMessage(to, subject, msg);
       }
       

请注意，对象引用 app.pages.Email.descendants，它引用属于 Email 页面后代的所有对象，即所有微件。在此应用中，该引用可以替代 Send Email 按钮的 onClick 操作中使用的等效引用 (widget.parent.descendants)。（这些引用是否等效取决于对象层次结构。）

创建服务器脚本

1. 创建服务器脚本，其中包含服务器将要运行的函数：

   1. 将鼠标悬停在 Scripts 上方，然后点击 以添加脚本。

   2. 出现“Create Script”对话框后，点击 Server，使 Generate sample code 保持取消勾选状态，然后点击 Create。

2. 重命名服务器脚本：

   1. 在左侧边栏中，将鼠标悬停在 NewPage 上方，并点击“More” Rename。

   2. 输入 ServerScript，然后点击 OK。

3. 复制此 JavaScript 并将其粘贴到 ServerScript：

    /**
         * Sends an email message.
         * @param {string} to - Message recipient
         * @param {string} subject - Message subject
         * @param {string} msg - Body of message (HTML from Text Editor)
         * The body of the message is not a complete HTML document. It
         * doesn't need to be. When calling MailApp.sendEmail, you do
         * need to specify the option htmlBody for the message body, so that
         * MailApp.sendEmail will include the correct Content-Type header.
         */
        function sendEmailMessage(to, subject, msg){
          MailApp.sendEmail(to, subject, msg, {htmlBody: msg});
        }
       

   请注意收件人、主题和消息如何传递到实际发送电子邮件的函数。为“Send Email”按钮的 onClick 属性定义的操作会调用客户端脚本中的 SendMessage 函数，将收件人、主题和消息传递给该函数。SendMessage 函数将这些相同的参数传递给服务器脚本中的 sendEmailMessage 函数，sendEmailMessage 函数再将参数传递给 MailApp.SendMail 函数。MailApp.SendMail 函数会发送电子邮件。

预览和测试应用

预览您的 Send Email 应用，以查看其操作状况。

1. 点击右上角的 Preview，在新的浏览器标签页中运行您的应用。
2. 点击 Allow 以允许您的应用使用特定信息。
3. 输入电子邮件地址和主题。
4. 在文本编辑器中，输入一条简短的消息。
5. 点击 Clear Form。现在，您必须重新开始。
6. 输入电子邮件地址和主题。
7. 在文本编辑器中，输入一条简短的消息。
8. 使用文本编辑器工具栏中的工具为您的消息设计样式。
9. 点击 Send Email。Send Email 应用会发送电子邮件，并清除表单。

恭喜！您刚刚使用应用制作工具构建了一个使用客户端脚本和服务器脚本发送电子邮件的应用。

后续步骤

1. 学习教程 5 - 了解关系。
2. 详细了解应用制作工具脚本。
3. 浏览应用制作工具示例列表中的其他应用。

4. 详细了解本教程的关键概念，例如：

   • 详细了解 Apps 脚本。

   • 详细了解不同类型的回调。