Tạo giao diện trình chỉnh sửa của Google

Với tiện ích bổ sung của Google Workspace, bạn có thể cung cấp các giao diện tuỳ chỉnh trong trình chỉnh sửa, bao gồm Google Tài liệu, Google Trang tính và Google Trang trình bày. Điều này cho phép bạn cung cấp cho người dùng thông tin liên quan, tự động hoá các tác vụ và kết nối các hệ thống của bên thứ ba với trình chỉnh sửa.

Truy cập vào giao diện người dùng của tiện ích bổ sung

Bạn có thể mở tiện ích bổ sung của Google Workspace trong trình chỉnh sửa nếu biểu tượng của tiện ích bổ sung đó xuất hiện trong bảng điều khiển bên truy cập nhanh của Google Workspace trong giao diện người dùng của Tài liệu, Trang tính và Trang trình bày.

Tiện ích bổ sung của Google Workspace có thể hiển thị các giao diện sau:

Giao diện trang chủ: Nếu tệp kê khai của tiện ích bổ sung có trình kích hoạt EDITOR_NAME.homepageTrigger cho trình chỉnh sửa mà người dùng mở tiện ích bổ sung trong đó, thì tiện ích bổ sung sẽ tạo và trả về một thẻ trang chủ dành riêng cho trình chỉnh sửa đó. Nếu tệp kê khai của tiện ích bổ sung không có EDITOR_NAME.homepageTrigger cho trình chỉnh sửa mà người dùng mở tiện ích bổ sung trong đó, thì một thẻ trang chủ chung sẽ xuất hiện thay thế.
Giao diện API REST: Nếu tiện ích bổ sung sử dụng API REST, bạn có thể thêm các trình kích hoạt yêu cầu quyền truy cập vào từng tệp của một tài liệu bằng phạm vi drive.file. Sau khi được cấp, một điều kiện kích hoạt khác có tên là EDITOR_NAME.onFileScopeGrantedTrigger sẽ thực thi và hiển thị một giao diện dành riêng cho tệp đó.
Giao diện xem trước đường liên kết: Nếu tiện ích bổ sung của bạn tích hợp với một dịch vụ của bên thứ ba, bạn có thể tạo các thẻ xem trước nội dung từ URL của dịch vụ đó.

Tạo giao diện cho tiện ích bổ sung của Trình chỉnh sửa

Tạo giao diện cho tiện ích bổ sung của Trình chỉnh sửa cho các trình chỉnh sửa bằng cách làm theo các bước sau:

Thêm các trường addOns.common, addOns.docs, addOns.sheets, và addOns.slides thích hợp vào tệp kê khai dự án tập lệnh của tiện ích bổ sung .
Thêm mọi phạm vi Trình chỉnh sửa cần thiết vào tệp kê khai dự án tập lệnh.
Nếu bạn đang cung cấp một trang chủ dành riêng cho trình chỉnh sửa, hãy triển khai hàm EDITOR_NAME.homepageTrigger để tạo giao diện. Nếu không, hãy sử dụng giao diện common.homepageTrigger để tạo một trang chủ chung cho các ứng dụng lưu trữ.
Nếu bạn sử dụng API REST, hãy triển khai quy trình uỷ quyền phạm vi drive.file và luồng hàm trình kích hoạt EDITOR_NAME.onFileScopeGrantedTrigger để hiển thị một giao diện dành riêng cho tệp đang mở. Để biết thêm thông tin, hãy xem phần Giao diện API REST.
Nếu bạn đang định cấu hình bản xem trước đường liên kết từ một dịch vụ của bên thứ ba, hãy triển khai phạm vi https://www.googleapis.com/auth/workspace.linkpreviewquy trình uỷ quyền và linkPreviewTriggers hàm. Để biết thêm thông tin, hãy xem phần Giao diện xem trước đường liên kết.
Triển khai các hàm gọi lại được liên kết cần thiết để phản hồi các lượt tương tác của người dùng với giao diện người dùng, chẳng hạn như lượt nhấp vào nút.

Trang chủ của trình chỉnh sửa

Bạn phải cung cấp một hàm trình kích hoạt trang chủ trong dự án tập lệnh của tiện ích bổ sung để tạo và trả về một single Card hoặc một mảng các Card đối tượng tạo nên trang chủ của tiện ích bổ sung.

Hàm trình kích hoạt trang chủ được truyền một đối tượng sự kiện dưới dạng tham số chứa thông tin như nền tảng của ứng dụng. Bạn có thể sử dụng dữ liệu đối tượng sự kiện để điều chỉnh cấu trúc của trang chủ.

Bạn có thể hiển thị một trang chủ chung hoặc một trang chủ dành riêng cho trình chỉnh sửa mà người dùng mở tiện ích bổ sung của bạn trong đó.

Hiển thị trang chủ chung

Để hiển thị trang chủ chung của tiện ích bổ sung trong trình chỉnh sửa, hãy thêm các trường của Trình chỉnh sửa thích hợp, chẳng hạn như addOns.docs, addOns.sheets hoặc addOns.slides vào tệp kê khai của tiện ích bổ sung.

Ví dụ sau đây cho thấy phần addons của tệp kê khai tiện ích bổ sung của Google Workspace. Tiện ích bổ sung này mở rộng Tài liệu, Trang tính và Trang trình bày, đồng thời hiển thị trang chủ chung trong mỗi ứng dụng lưu trữ.

{
 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "sheets": {},
    "slides": {}
  }
}

Hiển thị trang chủ dành riêng cho Trình chỉnh sửa

Để hiển thị một trang chủ dành riêng cho người chỉnh sửa, hãy thêm EDITOR_NAME.homepageTrigger vào tệp kê khai của tiện ích bổ sung.

Ví dụ sau đây cho thấy phần addons của tệp kê khai tiện ích bổ sung của Google Workspace. Tiện ích bổ sung này được bật cho Tài liệu, Trang tính và Trang trình bày. Tiện ích bổ sung này hiển thị trang chủ chung trong Tài liệu và Trang trình bày, đồng thời hiển thị một trang chủ riêng biệt trong Trang tính. Hàm callback onSheetsHomepage tạo thẻ trang chủ dành riêng cho Trang tính.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "slides": {},
    "sheets": {
     "homepageTrigger": {
       "runFunction": "onSheetsHomepage"
     },
  }
}

Giao diện API REST

Nếu tiện ích bổ sung của bạn sử dụng API REST, chẳng hạn như API Google Trang tính, thì bạn có thể sử dụng hàm onFileScopeGrantedTrigger để hiển thị một giao diện mới dành riêng cho tệp đang mở trong ứng dụng lưu trữ trình chỉnh sửa.

Bạn phải thêm quy trình uỷ quyền phạm vi drive.file để sử dụng hàm onFileScopeGrantedTrigger. Để tìm hiểu cách yêu cầu drive.file phạm vi, hãy xem bài viết Yêu cầu quyền truy cập vào tệp cho tài liệu hiện tại.

Khi người dùng cấp phạm vi drive.file, EDITOR_NAME.onFileScopeGrantedTrigger.runFunction sẽ kích hoạt. Khi điều kiện kích hoạt kích hoạt, điều kiện kích hoạt này sẽ thực thi hàm trình kích hoạt theo bối cảnh do trường EDITOR_NAME.onFileScopeGrantedTrigger.runFunction chỉ định trong tệp kê khai của tiện ích bổ sung.

Để tạo giao diện API REST cho một trong các trình chỉnh sửa, hãy hoàn tất các bước sau. Thay thế EDITOR_NAME bằng ứng dụng lưu trữ trình chỉnh sửa mà bạn chọn sử dụng, ví dụ: sheets.onFileScopeGrantedTrigger:

Thêm EDITOR_NAME.onFileScopeGrantedTrigger vào phần Trình chỉnh sửa thích hợp trong tệp kê khai. Ví dụ: nếu bạn muốn tạo giao diện này trong Google Trang tính, hãy thêm trình kích hoạt vào phần "sheets".
Triển khai hàm có tên trong phần EDITOR_NAME.onFileScopeGrantedTrigger Hàm này chấp nhận một đối tượng sự kiện làm đối số và phải trả về một đối tượng Card hoặc một mảng các đối tượng Card.
Giống như mọi thẻ, bạn phải triển khai các hàm gọi lại dùng để cung cấp khả năng tương tác của tiện ích cho giao diện. Ví dụ: nếu bạn thêm một nút vào giao diện, thì nút đó phải có một Hành động được đính kèm Action và một hàm callback đã triển khai chạy khi nút được nhấp.

Ví dụ sau đây cho thấy phần addons của tệp kê khai tiện ích bổ sung của Google Workspace. Tiện ích bổ sung này sử dụng API REST, vì vậy, onFileScopeGrantedTrigger được thêm vào cho Google Trang tính. Khi người dùng cấp phạm vi drive.file, hàm gọi lại onFileScopeGrantedSheets sẽ tạo một giao diện dành riêng cho tệp.

{
  "addOns": {
    "common": {
      "name": "Productivity add-on",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",
      "layoutProperties": {
        "primaryColor": "#669df6",
        "secondaryColor": "#ee675c"
      }
    },
    "sheets": {
      "homepageTrigger": {
        "runFunction": "onEditorsHomepage"
      },
      "onFileScopeGrantedTrigger": {
        "runFunction": "onFileScopeGrantedSheets"
      }
    }
  }
}

Giao diện xem trước đường liên kết cho các dịch vụ của bên thứ ba

Để bật tính năng xem trước đường liên kết cho một dịch vụ của bên thứ ba, bạn phải định cấu hình tính năng xem trước đường liên kết trong tệp kê khai của tiện ích bổ sung và tạo một hàm trả về thẻ xem trước. Đối với các dịch vụ yêu cầu người dùng uỷ quyền, hàm của bạn cũng phải gọi quy trình uỷ quyền.

Để biết các bước bật tính năng xem trước đường liên kết, hãy xem bài viết Xem trước đường liên kết bằng khối thông minh.

Đối tượng sự kiện

Một đối tượng sự kiện được tạo và truyền đến các hàm trình kích hoạt, chẳng hạn như EDITOR_NAME.homepageTrigger hoặc EDITOR_NAME.onFileScopeGrantedTrigger. Hàm trình kích hoạt sử dụng thông tin trong đối tượng sự kiện để xác định cách tạo thẻ tiện ích bổ sung hoặc kiểm soát hành vi của tiện ích bổ sung.

Cấu trúc đầy đủ của các đối tượng sự kiện được mô tả trong bài viết Đối tượng sự kiện.

Khi một trình chỉnh sửa là ứng dụng lưu trữ đang hoạt động của tiện ích bổ sung, các đối tượng sự kiện sẽ bao gồm các trường đối tượng sự kiện của Tài liệu, Trang tính hoặc Trang trình bày mang thông tin về ứng dụng.

Nếu tiện ích bổ sung không có quyền uỷ quyền phạm vi drive.file cho người dùng hoặc tài liệu hiện tại, thì đối tượng sự kiện chỉ chứa trường docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission hoặc slides.addonHasFileScopePermission. Nếu tiện ích bổ sung có quyền uỷ quyền, thì đối tượng sự kiện sẽ chứa tất cả các trường đối tượng sự kiện của trình chỉnh sửa.

Ví dụ sau đây cho thấy một đối tượng sự kiện của trình chỉnh sửa được truyền đến hàm sheets.onFileScopeGrantedTrigger. Trong ví dụ này, tiện ích bổ sung có quyền uỷ quyền phạm vi drive.file cho tài liệu hiện tại:

{
  "commonEventObject": { ... },
  "sheets": {
    "addonHasFileScopePermission": true,
    "id":"A_24Q3CDA23112312ED52",
    "title":"How to get started with Sheets"
  },
  ...
}

Tạo giao diện trình chỉnh sửa của Google Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.