Trang này được dịch bởi Cloud Translation API.

Xây dựng giao diện Google Editor

Khi sử dụng Tiện ích bổ sung cho Google Workspace, bạn có thể cung cấp giao diện tuỳ chỉnh trong Trình chỉnh sửa, bao gồm cả Google Tài liệu, Trang tính và 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á nhiệm vụ và kết nối các hệ thống 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 Google Workspace trong Trình chỉnh sửa nếu biểu tượng của tiện ích đó xuất hiện trong bảng điều khiển bên truy cập nhanh của Google Workspace ở bên phải giao diện người dùng Tài liệu, Trang tính và Trang trình bày.

Tiện ích bổ sung của Google Workspace có thể trình bày 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 đó, 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 bao gồm EDITOR_NAME.homepageTrigger cho Trình chỉnh sửa mà người dùng mở trong đó, thì một thẻ trang chủ chung sẽ hiển thị.
Giao diện API REST: Nếu tiện ích bổ sung sử dụng API REST, thì bạn có thể thêm các điều kiện kích hoạt yêu cầu quyền truy cập vào mỗi tệp vào một tài liệu bằng phạm vi drive.file. Sau khi được cấp, một trình kích hoạt khác có tên là EDITOR_NAME.onFileScopeGrantedTrigger sẽ thực thi và hiển thị giao diện dành riêng cho tệp.
Liên kết giao diện xem trước: Nếu tiện ích bổ sung của bạn tích hợp với 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ụ.

Xây dựng giao diện cho Tiện ích bổ sung dành cho Trình chỉnh sửa

Tạo giao diện Tiện ích bổ sung dành cho Trình chỉnh sửa cho 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 dự án tập lệnh tiện ích bổ sung tệp kê khai.
Thêm mọi Phạm vi chỉnh sửa bắt buộc vào tệp kê khai dự án tập lệnh.
Nếu bạn cung cấp 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 chưa, hãy sử dụng giao diện common.homepageTrigger để xây dựng trang chủ chung cho các ứng dụng lưu trữ của bạn.
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à hàm kích hoạt EDITOR_NAME.onFileScopeGrantedTrigger để hiển thị giao diện dành riêng cho tệp đang mở. Để biết thêm thông tin, hãy xem nội dung 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 qua một dịch vụ bên thứ ba, hãy triển khai quy trình uỷ quyền phạm vi https://www.googleapis.com/auth/workspace.linkpreview và hàm linkPreviewTriggers. Để biết thêm thông tin, hãy xem bài viết Liên kết giao diện xem trước.
Triển khai các hàm callback được liên kết cần thiết để phản hồi các hoạt động tương tác trên giao diện người dùng của người dùng, chẳng hạn như lượt nhấp vào nút.

Trang chủ của Google Ads Editor

Bạn phải cung cấp hàm 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 Card duy nhất hoặc một mảng các đối tượng Card tạo nên trang chủ của tiện ích bổ sung.

Hàm kích hoạt trang chủ được truyền một đối tượng sự kiện dưới dạng thông số chứa thông tin, chẳng hạn 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.

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 Trình chỉnh sửa thích hợp, chẳng hạn như addOns.docs, addOns.sheets hoặc addOns.slides, trong 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

Để trình bày trang chủ dành riêng cho một Trình 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. Trình đơn này hiển thị trang chủ chung trong Tài liệu và Trang trình bày cũng như một trang chủ riêng biệt trong Trang tính. Hàm gọi lại 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, bạn có thể dùng hàm onFileScopeGrantedTrigger để hiển thị giao diện mới dành riêng cho tệp sẽ mở trong ứng dụng lưu trữ Editor.

Bạn phải bao gồm luồng uỷ quyền phạm vi drive.file để sử dụng hàm onFileScopeGrantedTrigger. Để tìm hiểu cách yêu cầu phạm vi drive.file, 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 kích hoạt, trình kích hoạt sẽ thực thi hàm kích hoạt theo ngữ 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 làm theo các bước dưới đây. Thay thế EDITOR_NAME bằng ứng dụng lưu trữ Editor mà bạn chọn sử dụng, ví dụ: sheets.onFileScopeGrantedTrigger.

Đưa EDITOR_NAME.onFileScopeGrantedTrigger vào mục 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 điều kiện kích hoạt vào mục "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 duy nhất hoặc một mảng gồm các đối tượng Card.
Giống như bất kỳ thẻ nào, bạn phải triển khai các hàm callback được 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 đưa một nút vào giao diện, thì nút đó phải có Hành động đính kèm và một hàm callback được triển khai sẽ chạy khi người dùng nhấp vào nút đó.

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 đưa vào Google Trang tính. Khi người dùng cấp phạm vi drive.file, hàm callback 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"
     }
   }

Liên kết giao diện xem trước của các dịch vụ của bên thứ ba

Để bật bản xem trước đường liên kết cho một dịch vụ bên thứ ba, bạn phải định cấu hình bản 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 sự cho phép của người dùng, hàm của bạn cũng phải gọi luồng uỷ quyền.

Để biết các bước bật bản 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 kích hoạt, chẳng hạn như EDITOR_NAME.homepageTrigger hoặc EDITOR_NAME.onFileScopeGrantedTrigger. Hàm 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 đối tượng sự kiện được mô tả trong Đối tượng sự kiện.

Khi Trình chỉnh sửa là ứng dụng lưu trữ 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 Tài liệu, Trang tính hoặc Trang trình bày chứa thông tin ứng dụng.

Nếu tiện ích bổ sung không có quyền truy cập 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ó ủy 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 Editor.

Ví dụ sau đây cho thấy một đối tượng sự kiện Editor được truyền đến hàm sheets.onFileScopeGrantedTrigger. Ở đây, tiện ích bổ sung có 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"
          },
          ...
        }