取得 Google Workspace 外掛程式使用者的語言代碼和時區

本指南說明外掛程式如何取得使用者的語言代碼和時區，然後使用該資訊自訂介面和行為。如需 Google Apps Script 專屬指南，請參閱 Apps Script 開發人員說明文件中的「取得使用者語言代碼和時區」一節。

設定外掛程式的部署資源

如要允許外掛程式取得使用者的語言代碼和時區，請設定外掛程式的部署資源：

1. 在外掛程式的部署資源中，將 addOns.common.useLocaleFromApp 欄位設為 true。
2. 將 https://www.googleapis.com/auth/script.locale 授權範圍新增至部署資源的 oauthScopes 清單。此範圍可授予外掛程式使用者查看其國家/地區、語言和時區的權限。
3. 儲存更新後的部署資源。

將範圍新增至外掛程式的 oauthScopes 清單後，使用者必須在下次使用外掛程式時重新授權。

取得語言代碼和時區資訊

事件物件包含使用者語言代碼資訊，您可以從下列 commonEventObject 屬性取得這些資訊：

• commonEventObject.userLocale：使用者的語言和國家/地區 ID。例如，en-US 代表美國朗讀的英文語言。
• commonEventObject.timeZone.offset：使用者的時區偏移 (以毫秒為單位)，從世界標準時間 (UTC) 開始。
• commonEventObject.timeZone.id：使用者的時區 ID。例如 America/New_York。
• commonEventObject.timeZone：使用者的時區 ID 和偏移量。

事件物件會在使用者與外掛程式互動 (例如點選按鈕) 時，傳遞至 action 回呼函式、homepageTrigger 函式和 contextualTrigger 函式。每個回呼或觸發條件函式都能從事件物件取得語言代碼和時區資訊，並視需要加以使用。舉例來說，前往新資訊卡的回呼函式在決定要加入資訊卡的文字時，可能會參照語言代碼字串。