使用智能条状标签预览链接

本页面介绍了如何构建 Google Workspace 插件，让 Google 文档、表格和幻灯片用户可以预览第三方服务中的链接。

Google Workspace 插件可以检测您服务的链接，并提示用户预览这些链接。您可以将插件配置为预览多个网址模式，例如支持请求、销售线索和员工个人资料的链接。

用户如何预览链接

如需预览链接，用户需要与智能条状标签 和卡片互动。

用户预览卡片

当用户在文档或电子表格中输入或粘贴网址时，Google 文档或 Google 表格 会提示用户将链接替换为智能条状标签。智能条状标签会显示一个图标以及链接内容的简短标题或说明。当用户将鼠标悬停在条状标签上时，会看到一个卡片界面，其中会预览有关文件或链接的更多信息。

以下视频展示了用户如何将链接转换为智能条状标签并预览卡片：

用户如何在幻灯片中预览链接

幻灯片中的链接预览不支持第三方智能条状标签。当用户在演示文稿中输入或粘贴网址时，幻灯片会提示用户将链接替换为其标题（作为链接文本），而不是替换为条状标签。当用户将鼠标悬停在链接标题上时，会看到一个卡片界面，其中会预览有关链接的信息。

下图展示了链接预览在幻灯片中的呈现方式：

Google 幻灯片的链接预览示例

前提条件

Apps 脚本

Node.js

Python

Java

可选：设置对第三方服务的身份验证

如果您的插件连接到需要授权的服务，用户必须向该服务进行身份验证才能预览链接。这意味着，当用户首次将您服务中的链接粘贴到 Google 文档、表格或幻灯片文件中时，您的插件必须调用授权流程。

如需设置 OAuth 服务或自定义授权提示，请参阅将插件连接到第三方服务。

本部分介绍了如何为插件设置链接预览，包括以下步骤：

  1. 在插件的清单中配置链接预览 。
  2. 为链接构建智能条状标签和卡片界面。

配置链接预览

如需配置链接预览，请在插件的清单中指定以下部分和字段：

  1. 在 addOns 部分下，添加 docs 字段以扩展 Google 文档，添加 sheets 字段以扩展 Google 表格，添加 slides 字段以扩展 Google 幻灯片。

  2. 在每个字段中，实现 linkPreviewTriggers 触发器 ，该触发器包含 runFunction（您将在以下 部分“构建智能条状标签和卡片”中定义此函数）。

    如需了解您可以在 linkPreviewTriggers 触发器中指定哪些字段，请参阅 Apps 脚本 清单的参考文档或其他 运行时的部署资源的参考文档。

  3. 在 oauthScopes 字段中，添加范围 https://www.googleapis.com/auth/workspace.linkpreview，以便用户可以授权插件代表他们预览链接。

例如，请参阅以下清单的 oauthScopes 和 addons 部分，该清单为支持请求服务配置了链接预览。

{
  "oauthScopes": [
    "https://www.googleapis.com/auth/workspace.linkpreview"
  ],
  "addOns": {
    "common": {
      "name": "Preview support cases",
      "logoUrl": "https://www.example.com/images/company-logo.png",
      "layoutProperties": {
        "primaryColor": "#dd4b39"
      }
    },
    "docs": {
      "linkPreviewTriggers": [
        {
          "runFunction": "caseLinkPreview",
          "patterns": [
            {
              "hostPattern": "example.com",
              "pathPrefix": "support/cases"
            },
            {
              "hostPattern": "*.example.com",
              "pathPrefix": "cases"
            },
            {
              "hostPattern": "cases.example.com"
            }
          ],
          "labelText": "Support case",
          "logoUrl": "https://www.example.com/images/support-icon.png",
          "localizedLabelText": {
            "es": "Caso de soporte"
          }
        }
      ]
    },
    "sheets": {
      "linkPreviewTriggers": [
        {
          "runFunction": "caseLinkPreview",
          "patterns": [
            {
              "hostPattern": "example.com",
              "pathPrefix": "support/cases"
            },
            {
              "hostPattern": "*.example.com",
              "pathPrefix": "cases"
            },
            {
              "hostPattern": "cases.example.com"
            }
          ],
          "labelText": "Support case",
          "logoUrl": "https://www.example.com/images/support-icon.png",
          "localizedLabelText": {
            "es": "Caso de soporte"
          }
        }
      ]
    },
    "slides": {
      "linkPreviewTriggers": [
        {
          "runFunction": "caseLinkPreview",
          "patterns": [
            {
              "hostPattern": "example.com",
              "pathPrefix": "support/cases"
            },
            {
              "hostPattern": "*.example.com",
              "pathPrefix": "cases"
            },
            {
              "hostPattern": "cases.example.com"
            }
          ],
          "labelText": "Support case",
          "logoUrl": "https://www.example.com/images/support-icon.png",
          "localizedLabelText": {
            "es": "Caso de soporte"
          }
        }
      ]
    }
  }
}

在该示例中，Google Workspace 插件会预览公司支持请求服务的链接。该插件指定了三个网址模式来预览链接。每当链接与其中一个网址模式匹配时，回调函数 caseLinkPreview 都会在 Google 文档、表格或幻灯片中构建并显示卡片和智能条状标签，并将网址替换为链接标题。

构建智能条状标签和卡片

如需为链接返回智能条状标签和卡片，您必须实现 linkPreviewTriggers 对象中指定的任何函数。

当用户与匹配指定网址格式的链接互动时， linkPreviewTriggers 触发器会触发，其回调函数会将事件 对象 EDITOR_NAME.matchedUrl.url 作为实参传递。您可以使用此事件对象的载荷为链接预览构建智能条状标签和卡片。

例如，如果用户在 Google 文档中预览链接 https://www.example.com/cases/123456，则会返回以下事件载荷：

JSON 

{
  "docs": {
    "matchedUrl": {
        "url": "https://www.example.com/support/cases/123456"
    }
  }
}

如需创建卡片界面，您可以使用微件来显示有关链接的信息。您还可以构建操作，让用户打开链接或修改其内容。如需查看可用微件和操作的列表，请参阅预览卡片支持的 组件。

如需为链接预览构建智能条状标签和卡片，请执行以下操作：

  1. 实现您在插件清单的 linkPreviewTriggers 部分中指定的函数：
    1. 该函数必须接受包含 EDITOR_NAME.matchedUrl.url的事件对象作为实参，并返回 单个 Card对象。
    2. 如果您的服务需要授权，该函数还必须 调用授权流程。
  2. 对于每个预览卡片，实现任何为界面提供微件互动性的回调函数。例如，如果您添加了一个显示“查看链接”的按钮，则可以创建一个操作，用于指定回调函数以在新窗口中打开链接。如需详细了解 微件互动，请参阅插件操作。

以下代码为 Google 文档创建了回调函数 caseLinkPreview：

Apps 脚本

apps-script/3p-resources/3p-resources.gs
/**
* Entry point for a support case link preview.
*
* @param {!Object} event The event object.
* @return {!Card} The resulting preview link card.
*/
function caseLinkPreview(event) {

  // If the event object URL matches a specified pattern for support case links.
  if (event.docs.matchedUrl.url) {

    // Uses the event object to parse the URL and identify the case details.
    const caseDetails = parseQuery(event.docs.matchedUrl.url);

    // Builds a preview card with the case name, and description
    const caseHeader = CardService.newCardHeader()
      .setTitle(`Case ${caseDetails["name"][0]}`);
    const caseDescription = CardService.newTextParagraph()
      .setText(caseDetails["description"][0]);

    // Returns the card.
    // Uses the text from the card's header for the title of the smart chip.
    return CardService.newCardBuilder()
      .setHeader(caseHeader)
      .addSection(CardService.newCardSection().addWidget(caseDescription))
      .build();
  }
}

/**
* Extracts the URL parameters from the given URL.
*
* @param {!string} url The URL to parse.
* @return {!Map} A map with the extracted URL parameters.
*/
function parseQuery(url) {
  const query = url.split("?")[1];
  if (query) {
    return query.split("&")
    .reduce(function(o, e) {
      var temp = e.split("=");
      var key = temp[0].trim();
      var value = temp[1].trim();
      value = isNaN(value) ? value : Number(value);
      if (