Trang chủ

Trang chủ là một tính năng của tiện ích bổ sung Google Workspace, cho phép bạn xác định một hoặc nhiều thẻ không theo bối cảnh. Thẻ không theo bối cảnh hiển thị giao diện người dùng khi người dùng không ở trong một bối cảnh cụ thể, chẳng hạn như khi xem hộp thư đến Gmail mà không có thư hoặc bản nháp nào đang mở.

Trang chủ cho phép bạn hiển thị nội dung không theo bối cảnh, tương tự như các ứng dụng Google trong bảng điều khiển bên truy cập nhanh (Google Keep, Lịch Google và Google Tasks). Trang chủ cũng có thể cung cấp một nơi bắt đầu ban đầu khi người dùng mở tiện ích bổ sung của bạn lần đầu tiên và hữu ích cho việc hướng dẫn người dùng mới cách tương tác với tiện ích bổ sung của bạn.

Xác định trang chủ cho tiện ích bổ sung bằng cách chỉ định trang chủ đó trong tệp kê khai dự án và triển khai một hoặc nhiều homepageTrigger hàm (xem phần Định cấu hình trang chủ).

Bạn có thể có nhiều trang chủ, mỗi trang dành cho một ứng dụng lưu trữ mà tiện ích bổ sung của bạn mở rộng. Bạn cũng có thể xác định một trang chủ mặc định chung duy nhất được sử dụng trong các ứng dụng lưu trữ mà bạn chưa chỉ định trang chủ tuỳ chỉnh.

Trang chủ của tiện ích bổ sung sẽ xuất hiện trong những trường hợp sau:

  • Khi tiện ích bổ sung được mở lần đầu tiên trong ứng dụng lưu trữ (sau khi được uỷ quyền).
  • Khi người dùng chuyển từ bối cảnh theo bối cảnh sang bối cảnh không theo bối cảnh trong khi tiện ích bổ sung đang mở. Ví dụ: từ việc chỉnh sửa một sự kiện trên Lịch sang Lịch chính.
  • Khi người dùng nhấp vào nút quay lại đủ số lần để bật mọi thẻ khác khỏi các ngăn xếp nội bộ.
  • Khi một hoạt động tương tác trên giao diện người dùng trong thẻ không theo bối cảnh dẫn đến lệnh gọi Navigation.popToRoot.

Bạn nên thiết kế trang chủ. Nếu bạn không xác định trang chủ nào, thì một thẻ chung có chứa tên tiện ích bổ sung sẽ được sử dụng bất cứ khi nào người dùng chuyển đến trang chủ.

Định cấu hình trang chủ

Tiện ích bổ sung Google Workspace sử dụng trường addOns.common.homepageTrigger để định cấu hình nội dung tiện ích bổ sung trang chủ mặc định (không theo bối cảnh) cho các ứng dụng lưu trữ trong tệp kê khaitiện ích bổ sung:

{
  "addOns": {
    "common": {
      "homepageTrigger": {
        "runFunction": "myFunction",
        "enabled": true
      }
    }
  }
}

  • runFunction: Tên của hàm Google Apps Script mà khung tiện ích bổ sung Google Workspace gọi để kết xuất thẻ tiện ích bổ sung trang chủ. Hàm này là hàm kích hoạt trang chủ. Hàm này phải tạo và trả về một mảng các Card đối tượng tạo nên giao diện người dùng trang chủ. Nếu có nhiều thẻ được trả về, ứng dụng lưu trữ sẽ hiển thị tiêu đề thẻ trong một danh sách mà người dùng có thể chọn (xem phần Trả về nhiều thẻ).

  • enabled: Liệu các thẻ trang chủ có được bật cho phạm vi này hay không. Trường này là không bắt buộc và mặc định là true. Việc đặt trường này thành false sẽ khiến các thẻ trang chủ bị tắt cho tất cả các ứng dụng lưu trữ (trừ phi bị ghi đè cho ứng dụng lưu trữ đó; hãy xem phần cấu hình dành riêng cho ứng dụng lưu trữ).

Để một ứng dụng lưu trữ sử dụng trang chủ chung, cả addOns.common.homepageTrigger và tài nguyên cấp cao nhất của ứng dụng lưu trữ phải có trong tệp kê khai tiện ích bổ sung . Ví dụ: nếu addOns.gmail không có trong tệp kê khai, thì tiện ích bổ sung sẽ bị tắt cho Gmail và sẽ không hiển thị trang chủ hoặc chức năng khác trong ứng dụng lưu trữ đó.

Ngoài cấu hình chung, các chế độ ghi đè cho mỗi ứng dụng lưu trữ có cấu trúc giống hệt nhau có trong cấu hình của mỗi ứng dụng lưu trữ, tại addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger và các trình kích hoạt dành riêng cho ứng dụng lưu trữ khác.

Ví dụ sau đây cho thấy một tệp kê khai trong đó trình kích hoạt trang chủ chung được xác định nhưng bị ghi đè bằng các hàm tuỳ chỉnh cho Lịch và Drive, đồng thời bị tắt cho Gmail. Trong cấu hình này, hàm buildHomePage chung không bao giờ thực thi vì bị ghi đè hoặc ứng dụng lưu trữ bị tắt.

{
  ...
  "addOns": {
    ...
    "common": {
      "homepageTrigger": { "runFunction": "buildHomePage" }
    },
    "calendar": {
      "homepageTrigger": { "runFunction": "buildCalendarHomepage" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "buildDriveHomepage" }
    },
    "gmail": {
      "homepageTrigger": { "enabled": false }
    },
    ...
  }
}

Đoạn trích tệp kê khai sau đây tương đương với ví dụ trước, mặc dù homepageTrigger mặc định và cấu hình Gmail bị bỏ qua:

{
  "addOns": {
    "common": {},
    "calendar": {
      "homepageTrigger": { "runFunction": "myCalendarFunction" }
    },
    "drive": {
      "homepageTrigger": { "runFunction": "myDriveFunction" }
    },
    "gmail": {},
    ...
  }
}

Không có phần homepageTrigger nào là bắt buộc. Giao diện người dùng hiển thị cho một tiện ích bổ sung trong một sản phẩm lưu trữ phụ thuộc vào sự hiện diện của trường tệp kê khai tương ứng và liệu có homepageTrigger được liên kết hay không. Ví dụ sau đây cho thấy những hàm kích hoạt tiện ích bổ sung nào được thực thi để tạo giao diện người dùng trang chủ cho các cấu hình tệp kê khai khác nhau:

Sơ đồ minh hoạ quy trình thực thi hàm kích hoạt trang chủ của tiện ích bổ sung

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

Khi được gọi, hàm kích hoạt trang chủ (runFunction) được mô tả trước đó sẽ được truyền một đối tượng sự kiện chứa dữ liệu từ bối cảnh lời gọi.

Đối tượng sự kiện trang chủ không bao gồm thông tin về tiện ích hoặc thông tin theo bối cảnh. Thông tin được truyền bị giới hạn ở các trường đối tượng sự kiện chung sau đây:

Xem bài viết Đối tượng sự kiện để biết thêm thông tin.

Các thẻ không theo bối cảnh khác

Giao diện người dùng tiện ích bổ sung có thể chứa các thẻ không theo bối cảnh khác không phải là trang chủ. Ví dụ: trang chủ có thể có một nút mở thẻ "Cài đặt" để điều chỉnh các chế độ cài đặt tiện ích bổ sung (các chế độ cài đặt như vậy thường độc lập với bối cảnh).

Các thẻ không theo bối cảnh được xây dựng như mọi thẻ khác; điểm khác biệt duy nhất là hành động hoặc sự kiện nào tạo và hiển thị thẻ. Xem Phương thức điều hướng để biết thông tin chi tiết về cách tạo quá trình chuyển đổi giữa các thẻ.