На этой странице объясняется, как создать надстройку для Google Workspace, которая позволит пользователям Google Docs, Sheets и Slides просматривать ссылки из стороннего сервиса.
Дополнение для Google Workspace может распознавать ссылки на ваши сервисы и предлагать пользователям предварительно просмотреть их. Вы можете настроить дополнение для предварительного просмотра различных шаблонов URL-адресов, таких как ссылки на обращения в службу поддержки, потенциальных клиентов и профили сотрудников.
Как пользователи просматривают ссылки
Для предварительного просмотра ссылок пользователи взаимодействуют со смарт-чипами и картами .
Когда пользователи вводят или вставляют URL-адрес в документ или электронную таблицу, Google Docs или Google Sheets предлагают им заменить ссылку на смарт-чип. Смарт-чип отображает значок и краткое название или описание содержимого ссылки. При наведении курсора на чип появляется карточный интерфейс, который отображает дополнительную информацию о файле или ссылке.
В следующем видео показано, как пользователь преобразует ссылку в смарт-чип и просматривает предварительный просмотр карты:
Как пользователи просматривают ссылки в слайдах презентации.
В Slides не поддерживаются сторонние смарт-чипы для предварительного просмотра ссылок. Когда пользователи вводят или вставляют URL-адрес в презентацию, Slides предлагает им заменить ссылку её заголовком в виде текста ссылки, а не чипа. При наведении курсора на заголовок ссылки отображается карточка с предварительной информацией о ссылке.
На следующем изображении показано, как отображается предварительный просмотр ссылки в презентации Slides:

Предварительные требования
Apps Script
- Учетная запись Google Workspace .
- Надстройка для Google Workspace. Чтобы создать надстройку, следуйте этому краткому руководству .
Node.js
- Учетная запись Google Workspace .
- Надстройка для Google Workspace. Чтобы создать надстройку, следуйте этому краткому руководству .
Python
- Учетная запись Google Workspace .
- Надстройка для Google Workspace. Чтобы создать надстройку, следуйте этому краткому руководству .
Java
- Учетная запись Google Workspace .
- Надстройка для Google Workspace. Чтобы создать надстройку, следуйте этому краткому руководству .
Необязательно: настройте аутентификацию в стороннем сервисе.
Если ваше дополнение подключается к сервису, требующему авторизации, пользователям необходимо пройти аутентификацию в этом сервисе для предварительного просмотра ссылок. Это означает, что когда пользователи впервые вставляют ссылку из вашего сервиса в файл Docs, Sheets или Slides, ваше дополнение должно запустить процесс авторизации.
Чтобы настроить службу OAuth или пользовательский запрос авторизации, см. раздел «Подключение вашего дополнения к сторонней службе» .
Настройте предварительный просмотр ссылок для вашего дополнения.
В этом разделе объясняется, как настроить предварительный просмотр ссылок для вашего дополнения, включая следующие шаги:
- Настройте предварительный просмотр ссылок в манифесте вашего дополнения.
- Создайте интерфейс для смарт-чипов и карт для ваших каналов связи.
Настройка предварительного просмотра ссылок
Для настройки предварительного просмотра ссылок укажите следующие разделы и поля в манифесте вашего дополнения:
- В разделе
addOnsдобавьте полеdocsдля расширения библиотеки Docs, полеsheetsдля расширения библиотеки Sheets и полеslidesдля расширения библиотеки Slides. В каждом поле реализуйте триггер
linkPreviewTriggers, включающий функциюrunFunction(эту функцию вы определяете в следующем разделе « Создание смарт-чипа и карты »).Чтобы узнать, какие поля можно указать в триггере
linkPreviewTriggers, см. справочную документацию по манифестам Apps Script или ресурсам развертывания для других сред выполнения .В поле
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"
}
}
]
}
}
}
In the example, the Google Workspace add-on previews links for a company's support case service. The add-on specifies three URL patterns to preview links. Whenever a link matches one of the URL patterns, the callback function caseLinkPreview builds and displays a card and a smart chip in Docs, Sheets, or Slides, and replaces the URL with the link title.
Создайте смарт-чип и карту.
Для возврата смарт-чипа и карты по ссылке необходимо реализовать все функции, указанные в объекте linkPreviewTriggers .
Когда пользователь взаимодействует со ссылкой, соответствующей указанному шаблону URL, срабатывает триггер linkPreviewTriggers , и его функция обратного вызова передает в качестве аргумента объект события EDITOR_NAME .matchedUrl.url . Вы используете полезную нагрузку этого объекта события для создания смарт-чипа и карты для предварительного просмотра ссылки.
Например, если пользователь просматривает ссылку https://www.example.com/cases/123456 в Docs, возвращается следующая полезная нагрузка события:
JSON
{ "docs": { "matchedUrl": { "url": "https://www.example.com/support/cases/123456" } } }
Для создания интерфейса карточки используются виджеты, отображающие информацию о ссылке. Также можно создавать действия, позволяющие пользователям открывать ссылку или изменять её содержимое. Список доступных виджетов и действий см. в разделе «Поддерживаемые компоненты для карточек предварительного просмотра» .
Для создания смарт-чипа и карты для предварительного просмотра соединения:
- Реализуйте функцию, указанную в разделе
linkPreviewTriggersманифеста вашего дополнения:- Функция должна принимать в качестве аргумента объект события, содержащий
EDITOR_NAME .matchedUrl.url, и возвращать один объектCard. - Если для работы вашего сервиса требуется авторизация, функция также должна запускать процесс авторизации .
- Функция должна принимать в качестве аргумента объект события, содержащий
- Для каждой карточки предварительного просмотра реализуйте любые функции обратного вызова, обеспечивающие интерактивность виджета в интерфейсе. Например, если вы добавите кнопку с надписью «Просмотреть ссылку», вы можете создать действие, которое задает функцию обратного вызова для открытия ссылки в новом окне. Чтобы узнать больше о взаимодействии виджетов, см. раздел «Действия дополнений» .
Следующий код создает функцию обратного вызова caseLinkPreview для Docs:
Apps Script
Node.js
Python
Java
Поддерживаемые компоненты для карт предварительного просмотра
Дополнения Google Workspace поддерживают следующие виджеты и действия для карточек предварительного просмотра ссылок:
Apps Script
| Поле «Карточная служба» | Тип |
|---|---|
TextParagraph | Виджет |
DecoratedText | Виджет |
Image | Виджет |
IconImage | Виджет |
ButtonSet | Виджет |
TextButton | Виджет |
ImageButton | Виджет |
Grid | Виджет |
Divider | Виджет |
OpenLink | Действие |
Navigation | Действие Поддерживается только метод updateCard . |
JSON
Поле "Карточка" ( google.apps.card.v1 ) | Тип |
|---|---|
TextParagraph | Виджет |
DecoratedText | Виджет |
Image | Виджет |
Icon | Виджет |
ButtonList | Виджет |
Button | Виджет |
Grid | Виджет |
Divider | Виджет |
OpenLink | Действие |
Navigation | Действие Поддерживается только метод updateCard . |
Полный пример: Дополнение для обработки обращений в службу поддержки.
В следующем примере показано дополнение Google Workspace, которое отображает предварительный просмотр ссылок на обращения в службу поддержки компании в Google Docs.
В примере выполняется следующее:
- Предварительный просмотр содержит ссылки на обращения в службу поддержки, например,
https://www.example.com/support/cases/1234. На смарт-чипе отображается значок службы поддержки, а в карточке предварительного просмотра указывается идентификатор обращения и его описание. - Если в настройках пользователя установлен испанский язык, смарт-чип локализует
labelTextна испанский.
Манифест
Apps Script
JSON
{
"oauthScopes": [
"https://www.googleapis.com/auth/workspace.linkpreview"
],
"addOns": {
"common": {
"name": "Preview support cases",
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png",
"layoutProperties": {
"primaryColor": "#dd4b39"
}
},
"docs": {
"linkPreviewTriggers": [
{
"runFunction": "URL",
"patterns": [
{
"hostPattern": "example.com",
"pathPrefix": "support/cases"
},
{
"hostPattern": "*.example.com",
"pathPrefix": "cases"
},
{
"hostPattern": "cases.example.com"
}
],
"labelText": "Support case",
"localizedLabelText": {
"es": "Caso de soporte"
},
"logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
}
]
}
}
}
Код
Apps Script
Node.js
Python
Java
Связанные ресурсы
- Предварительный просмотр ссылок из Google Books с помощью смарт-чипов
- Протестируйте свой аддон
- манифест Google Docs
- Карточные интерфейсы для предварительного просмотра ссылок