[Slack API 教程] 为你的 Slack 应用搭建家园🏡

由 Mux 赞助的 DEV 全球展示挑战赛：展示你的项目！

您的 Slack 应用的“应用主页”是 Slack 中一个专注的、一对一的空间，供用户与您的应用共享。在每个应用主页中，用户都会找到多个标签页：“关于”、“消息”以及新推出的“主页”标签页。“主页”标签页是一个动态且持久的视觉界面，允许用户与您的应用进行私密互动。您的应用可以向用户问好、展示自定义内容，甚至可以添加一些趣味元素！

等等，我不是已经有 App Home 了吗？

这项新功能您可能并不陌生！其实app_home_opened，当用户从左侧菜单选择应用时，就会触发一个事件。本教程将向您展示如何利用这个事件，向用户发送包含及时信息的欢迎消息。

通过主页标签，您的应用可以超越消息传递，以模块形式在独立于对话的持久位置显示更有条理、更动态的内容。

应用主页标签

这就是 Google Calendar Slack 应用的新界面：

您可以在应用的“首页”标签页查看每日日程，并在此处修改邀请回复或加入 Zoom 会议。在“消息”标签页，应用会向您发送直接消息，例如，在 Google 日历中，应用会在会议开始前 1 分钟发送消息提醒您。在“关于”标签页，您可以查看有关应用的信息。

创建应用主页

为了演示 App Home 的功能，我将以一款名为Stickies的应用为例进行讲解，该应用允许用户在“主页”选项卡中存储简短的私人笔记。

用户流程

1. 用户点击Slack 客户端左侧菜单“应用”下的应用名称
2. 默认情况下应打开“主页”选项卡。
3. 用户可以通过点击窗格中的按钮来添加新笔记。
4. 用户在模态窗口中填写表单，然后点击“创建”。
5. “主页”窗格应自动更新为新的笔记条目。

应用流程

1. 当用户打开应用主页时，app_home_opened会向应用服务器触发事件​​。
2. 该应用程序使用事件有效负载中的用户 ID 来显示带有按钮的初始视图，该按钮的views.publish方法如下：
3. 当用户点击“添加便笺”按钮时，会触发一个交互事件。
4. views.open应用程序使用该方法打开一个带有表单输入的模态框。
5. 用户提交表单后，会触发另一种交互，这种交互的类型是：view_submission
6. views.publish使用以下方法更新应用程序主页

现在，让我们为你的工作区创建 Stickies 应用。该应用的源代码位于 Glitch 上，你可以在那里“重新混编”并运行，而无需部署代码！

🎏🥫 Glitch上的源代码

🎏🍴 Remix（fork）Glitch 仓库

设置您的应用

首先，您需要在 Slack 上设置您的应用。请前往Slack 应用管理页面创建应用。

接下来，前往“功能”>“机器人用户”启用机器人用户。您可以根据需要更改默认机器人名称。

然后，前往“功能”>“OAuth 和权限”指定机器人令牌范围。选择chat.write。（实际上，此示例应用不会发送任何消息，但现在只需按照此说明操作即可。要了解有关这种更细粒度的新型机器人权限模型的更多信息，请阅读“使用 OAuth 2.0 版本 2 进行安装”！）

现在，前往“功能”>“应用主页”（参见下方截图中的步骤 1）。截至本教程发布于 2019 年 11 月，此功能仍处于测试阶段，因此请点击“注册”，然后阅读并同意使用该功能的协议（参见下方截图中的步骤 1）。

注册后，“首页”选项卡和“消息”选项卡默认应该处于选中状态，不过，在本教程中，“消息”选项卡是可选的。

接下来，前往“功能”>“事件订阅”启用事件（参见下方截图中的步骤 1）。然后输入您的请求 URL（步骤 2）。如果您修改了示例 Glitch 代码，则您的请求 URL 应为 `<Request URL>` https://_your-project_.glitch.me/slack/events。（Glitch 会在您创建项目时生成项目名称。因此，您的项目名称可能由两个随机单词组成，例如 ` fluffy-umbrella`。您可以像我一样自定义项目名称。如果您在自己的服务器上运行，请在 URL 前添加 `<Request URL> /slack/events`。）

然后向下滚动到“订阅机器人事件”以添加app_home_opened事件（步骤 3）。然后保存（步骤 4）。

同样，您需要前往“功能”>“交互和操作”来告诉 Slack 将交互式有效负载发送到哪里。使用您的请求 URL，https://_your-project_.glitch.me/slack/actions然后保存。

我们先安装一次应用。前往“安装应用”，点击将应用安装到您的工作区，然后按照屏幕提示操作。OAuth 安装过程完成后，您应该会在屏幕上看到您的 OAuth 访问令牌。

现在，请在浏览器或 IDE 中打开 Glitch 项目窗口。环境变量就存储在这里。复制以 `<bot_token>` 开头的机器人令牌，xoxb并将其粘贴到 Glitch 项目的 ` .env`文件中。

另外，在 Slack 应用配置页面中，在“设置”>“基本信息”中获取您的签名密钥，然后将其复制并粘贴到.env文件中。

显示应用主页

设置您的 Express 服务器

在本教程中，我使用 Node.js 和Express作为 Web 服务器。所有 API 调用都通过简单的 HTTP 请求和响应完成，因此希望无论您使用何种编程语言，代码都能轻松理解。

⚡️如果您更喜欢使用Bolt框架进行开发，源代码也已提供。但这里的说明使用的是“原生”代码！

在你的 Node.js 代码中，引入依赖项并启动你的 Express 服务器。你需要评估原始请求负载以验证来自 Slack 的签名密钥。index.js文件中的第 31-38 行和第 143-145 行展示了如何使用 Express 运行服务器，并演示了如何检查 HTTP 标头以验证请求签名。（有关在 Node.js 中使用 Express 和 Body Parser 的签名密钥的更多详细信息，请参阅之前教程中的“验证请求”部分。）

触发app_home_opened事件

接下来，使用 HTTP POST 方法创建一个端点来接收事件负载。当事件触发时，Slack API 服务器会通过此端点向您发送 JSON 负载。收到数据后，检查事件类型是否正确app_home_opened，然后准备显示应用主页视图。

以下是简化后的代码片段（完整代码请参见index.js 文件中的第 45-70 行）：

app.post('/slack/events', async(req, res) => {
  const {type, user, channel, tab, text, subtype} = req.body.event;

  if(type === 'app_home_opened') {
    displayHome(user);
  }
}

现在，让我们在应用首页视图中使用丰富的消息布局和Block Kit显示丰富的内容：

const displayHome = async(user, data) => {

  const args = {
    token: process.env.SLACK_BOT_TOKEN,
    user_id: user,
    view: await updateView(user)
  };
  const result = await axios.post('/views.publish', qs.stringify(args));
};

要在应用首页显示内容，请调用view.publish该方法。在本例中，我使用该axios模块通过 HTTP POST 请求处理 API 调用。

使用积木套件构建视图

在这个代码示例中，我调用了另一个函数来创建 JSON，从而构建要显示的视图。当以后添加新内容更新视图时，可以重用此函数。

这段代码片段展示了如何构建和显示初始视图：

const updateView = async(user) => {
    let blocks = [ 
    {
      // Section with text and a button
      type: "section",
      text: {
        type: "mrkdwn",
        text: "*Welcome!* \nThis is a home for Stickers app. You can add small notes here!"
      },
      accessory: {
        type: "button",
        action_id: "add_note", 
        text: {
          type: "plain_text",
          text: "Add a Stickie"
        }
      }
    },
    // Horizontal divider line 
    {
      type: "divider"
    }
  ];

  let view = {
    type: 'home',
    title: {
      type: 'plain_text',
      text: 'Keep notes!'
    },
    blocks: blocks
  }

  return JSON.stringify(view);
};

blocks上面代码片段中定义的数组是用Block Kit Builder 构建的原型。

在实际源代码中，该函数会接收动态内容，这些内容来自交互式按钮和模态框。我将在后面的章节中解释这部分内容。

触发用户点击按钮

当用户点击按钮时，会弹出一个模态窗口。

请注意，action_id消息构建块中指定了该标识符。使用该标识符可以获取我们需要的数据。用户点击按钮后，API 服务器会将包含用户操作的有效负载发送到您的请求 URL trigger_id。您需要此有效负载来打开模态框。

app.post('/slack/actions', async(req, res) => {
  const { token, trigger_id, user, actions, type } = JSON.parse(req.body.payload);
  if(actions && actions[0].action_id.match(/add_/)) {
    openModal(trigger_id);
  } 
});

打开模态对话框

这就是在模态视图中创建表单元素（输入框和带有提交按钮的下拉菜单）的方法。在本练习中，我们先创建一个简单的表单，包含一个多行文本输入框，用于选择颜色。

要打开模态框，请调用以下views.open方法：

const openModal = async(trigger_id) => {

  const modal = {
    type: 'modal',
    title: {
      type: 'plain_text',
      text: 'Create a stickie note'
    },
    submit: {
      type: 'plain_text',
      text: 'Create'
    },
    blocks: [
      // Text input
      {
        "type": "input",
        "block_id": "note01",
        "label": {
          "type": "plain_text",
          "text": "Note"
        },
        "element": {
          "action_id": "content",
          "type": "plain_text_input",
          "placeholder": {
            "type": "plain_text",
            "text": "Take a note... "
          },
          "multiline": true
        }
      },

      // Drop-down menu      
      {
        "type": "input",
        "block_id": "note02",
        "label": {
          "type": "plain_text",
          "text": "Color",
        },
        "element": {
          "type": "static_select",
          "action_id": "color",
          "options": [
            {
              "text": {
                "type": "plain_text",
                "text": "yellow"
              },
              "value": "yellow"
            },
            {
              "text": {
                "type": "plain_text",
                "text": "blue"
              },
              "value": "blue"
            }
          ]
        }
      }
    ]
  };

  const args = {
    token: process.env.SLACK_BOT_TOKEN,
    trigger_id: trigger_id,
    view: JSON.stringify(modal)
  };

  const result = await axios.post('/views.open', qs.stringify(args));
};

这段代码看起来很长，但正如你所看到的，它主要只是为表单用户界面构建一个 JSON 数据！看看它是如何用 Block Kit Builder 构建的。

处理表单提交

用户提交的内容的处理方式与“首页”选项卡上的按钮点击的处理方式相同。

当模态框中的表单提交时，会向操作的同一端点发送一个有效负载。您可以通过检查type有效负载数据中的参数来区分不同的提交。（要查看完整代码，请参阅index.js 中的第 107-133 行）：

app.post('/slack/actions', async(req, res) => {
  const { type, user, view } = JSON.parse(req.body.payload);
  else if(type === 'view_submission') {
    res.send(''); // Make sure to respond to the server to avoid an error

    const data = {
      note: view.state.values.note01.content.value,
      color: view.state.values.note02.color.selected_option.value
    }
    displayHome(user.id, data);
  }
});

更新应用主页视图

然后，将从用户处新获取的数据附加到当前视图块，并使用以下方法重新渲染主页选项卡视图views.publish。

在这个示例应用中，我使用了一个简单的持久化数据库模块node-json-db。每次用户添加新笔记时，数据都会被添加到数据数组中。我创建了一个新的 JSON 数据块，然后将其追加到现有的 JSON 数据块中，最后通过调用 `.show()` 方法显示新的视图views.publish。

您可以在 appHome.js 的第 17-152 行看到源代码，但如何实现此流程取决于您自己。

试用您的应用

现在你的应用应该可以正常工作了。要启用它，请前往你的 Slack 工作区，点击侧边栏菜单中的“应用”，你会看到所有已安装应用的列表，然后点击你的应用。亲自体验一下应用，看看“应用主页”是如何运作的吧！

提升用户体验

希望这篇教程能给你一些启发，帮助你了解如何将 App Home 应用于你现有的应用或全新的应用！

本教程仅涵盖了使用方法和模态框构建 App Home 体验的基本部分views，但在下一个教程中，Shay DeWael 将通过扩展此便笺应用程序来解释设计最佳实践，使其更加实用，敬请期待！

有问题或意见吗？请联系我，Tomomi @girlie_mac或@SlackAPI。