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 sẽ 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 của 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ể là 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 hàm homepageTrigger (xem phần Cấu hình trang chủ).
Bạn có thể có nhiều trang chủ, mỗi trang chủ 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 dùng trong các máy chủ 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 trong ứng dụng lưu trữ (sau khi được uỷ quyền).
- Khi người dùng chuyển từ ngữ cảnh theo ngữ cảnh sang ngữ cảnh không theo ngữ 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 đến Lịch chính.
- Khi người dùng nhấp vào nút quay lại đủ số lần để đẩy mọi thẻ khác ra 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 ngữ 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 thẻ nào, thì một thẻ chung chứa tên tiện ích bổ sung của bạn sẽ được dùng bất cứ khi nào người dùng chuyển đến trang chủ.
Cấu hình trang chủ
Tiện ích bổ sung của Google Workspace sử dụng trường addOns.common.homepageTrigger để định cấu hình nội dung mặc định trên trang chủ (không theo bối cảnh) của tiện ích bổ sung cho các ứng dụng lưu trữ trong manifest của tiện ích bổ sung:
{
"addOns": {
"common": {
"homepageTrigger": {
"runFunction": "myFunction",
"enabled": true
}
}
}
}
runFunction: Tên của hàm Google Apps Script mà khung bổ trợ Google Workspace gọi để kết xuất các thẻ bổ trợ trên 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 đối tượngCardtạ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ó nên bật thẻ trang chủ cho phạm vi này hay không. Trường này không bắt buộc và mặc định sẽ được đặt làtrue. Nếu bạn đặt giá trị này thànhfalse, các thẻ trên trang chủ sẽ bị vô hiệu hoá cho tất cả các máy chủ (trừ phi bị ghi đè cho máy chủ đó; hãy xem cấu hình dành riêng cho máy chủ).
Để một máy chủ 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 máy chủ lưu trữ đều phải có trong tệp kê khai của 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ị vô hiệu hoá đối với Gmail và sẽ không hiển thị trang chủ hoặc chức năng khác trong máy chủ lưu trữ đó.
Ngoài cấu hình chung, các chế độ ghi đè cho mỗi máy chủ có cấu trúc giống hệt nhau có trong cấu hình của từng ứng dụng lưu trữ, tại addOns.gmail.homepageTrigger, addOns.calendar.homepageTrigger và các trình kích hoạt khác dành riêng cho máy chủ.
Ví dụ sau đây cho thấy một tệp kê khai trong đó một 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ị vô hiệu hoá cho Gmail. Trong cấu hình này, hàm buildHomePage chung không bao giờ thực thi vì hàm này bị ghi đè hoặc máy chủ lưu trữ bị vô hiệu hoá.
{
...
"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": {},
...
}
}
Bạn không bắt buộc phải điền vào bất kỳ phần nào trong số homepageTrigger. Giao diện người dùng xuất hiện 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 biết 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:
Đối tượng sự kiện trê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ừ ngữ cảnh gọi.
Các đối tượng sự kiện trê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 chỉ giới hạn ở các trường đối tượng sự kiện chung sau đây:
commonEventObject.clientPlatformcommonEventObject.hostAppcommonEventObject.userLocalevàcommonEventObject.userTimezone(xem phần Truy cập vào ngôn ngữ và múi giờ của người dùng để biết thông tin về quy định hạn chế).
Hãy xem Đố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 của tiện ích bổ sung có thể chứa các thẻ bổ sung không theo bối cảnh và không phải là trang chủ. Ví dụ: trang chủ của bạn có thể có một nút mở thẻ "Cài đặt" để điều chỉnh chế độ cài đặt của tiện ích bổ sung (những chế độ cài đặt này thường độc lập với bối cảnh).
Thẻ không theo bối cảnh được tạo giố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ẻ. Hãy xem phần Phương thức điều hướng để biết thông tin chi tiết về cách tạo hiệu ứng chuyển đổi giữa các thẻ.