Google Editor arayüzleri oluşturma

Google Workspace eklentileriyle Google Dokümanlar, E-Tablolar ve Slaytlar dahil olmak üzere Düzenleyiciler'de özelleştirilmiş arayüzler sunabilirsiniz. Bu sayede kullanıcıya alakalı bilgiler sağlayabilir, görevleri otomatikleştirebilir ve üçüncü taraf sistemleri Düzenleyiciler'e bağlayabilirsiniz.

Eklenti kullanıcı arayüzüne erişme

Dokümanlar, E-Tablolar ve Slaytlar kullanıcı arayüzlerinin sağ tarafındaki Google Workspace hızlı erişim yan panelinde simgesi görünen Google Workspace eklentilerini Düzenleyiciler'de açabilirsiniz.

Google Workspace eklentileri aşağıdaki arayüzleri sunabilir:

  • Ana sayfa arayüzleri: Eklentinin manifest dosyasında, kullanıcının eklentiyi açtığı Düzenleyici için EDITOR_NAME.homepageTrigger tetikleyici varsa eklenti, söz konusu Düzenleyici için özel olarak bir ana sayfa kartı oluşturur ve döndürür. Eklentinin manifest dosyasında, kullanıcının açtığı Düzenleyici için EDITOR_NAME.homepageTrigger yoksa bunun yerine genel bir ana sayfa kartı gösterilir.

  • REST API arayüzleri: Eklenti REST API'leri kullanıyorsa drive.file kapsamını kullanarak bir dokümana dosya başına erişim isteyen tetikleyiciler ekleyebilirsiniz. İzin verildikten sonra EDITOR_NAME.onFileScopeGrantedTrigger adlı başka bir tetikleyici çalıştırılır ve dosyaya özgü bir arayüz görüntülenir.

  • Bağlantı önizleme arayüzleri: Eklentiniz bir üçüncü taraf hizmetiyle entegreyse hizmetinizin URL'lerindeki içeriği önizleyen kartlar oluşturabilirsiniz.

Düzenleyici eklentileri için arayüz oluşturma

Düzenleyiciler için düzenleyici eklenti arayüzleri oluşturmak üzere aşağıdaki adımları uygulayın:

  1. Eklenti komut dosyası projesi manifest dosyasına uygun addOns.common, addOns.docs, addOns.sheets ve addOns.slides alanlarını ekleyin.
  2. Komut dosyası proje manifestinize gerekli tüm düzenleyici kapsamlarını ekleyin.
  3. Düzenleyiciye özel bir ana sayfa sağlıyorsanız arayüzü oluşturmak için EDITOR_NAME.homepageTrigger işlevini uygulayın. Aksi takdirde, barındırılan uygulamalarınız için ortak bir ana sayfa oluşturmak üzere common.homepageTrigger arayüzünü kullanın.
  4. REST API'leri kullanıyorsanız açık dosyaya özgü bir arayüz görüntülemek için drive.file kapsam yetkilendirme akışını ve EDITOR_NAME.onFileScopeGrantedTrigger tetikleyici işlevini uygulayın. Daha fazla bilgi için REST API arayüzleri bölümüne bakın.
  5. Üçüncü taraf hizmetinden bağlantı önizlemelerini yapılandırıyorsanız https://www.googleapis.com/auth/workspace.linkpreview kapsam yetkilendirme akışını ve linkPreviewTriggers işlevini uygulayın. Daha fazla bilgi için Bağlantı önizleme arayüzleri başlıklı makaleyi inceleyin.
  6. Kullanıcının kullanıcı arayüzü etkileşimlerine (ör. düğme tıklamaları) yanıt vermek için gereken ilişkili geri çağırma işlevlerini uygulayın.

Düzenleyici ana sayfaları

Eklentinizin komut dosyası projesinde, tek bir Card veya eklentinin ana sayfasını oluşturan bir dizi Card nesnesi oluşturup döndüren bir ana sayfa tetikleyici işlevi sağlamanız gerekir.

Ana sayfa tetikleyici işlevine, istemcinin platformu gibi bilgileri içeren bir parametre olarak bir etkinlik nesnesi iletilir. Ana sayfanın yapısını özelleştirmek için etkinlik nesnesi verilerini kullanabilirsiniz.

Ortak bir ana sayfa veya kullanıcının eklentinizi açtığı Düzenleyici'ye özel bir ana sayfa sunabilirsiniz.

Ortak ana sayfayı gösterme

Eklentinizin ortak ana sayfasını Düzenleyiciler'de göstermek için addOns.docs, addOns.sheets veya addOns.slides gibi uygun Düzenleyici alanları ekleyin.

Aşağıdaki örnekte, bir Google Workspace eklentisi manifest'inin addons kısmı gösterilmektedir. Eklenti, Dokümanlar, E-Tablolar ve Slaytlar'ı genişletir ve her ana uygulamada ortak ana sayfayı gösterir.

 "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": {}
  }
}

Düzenleyiciye özel bir ana sayfa gösterme

Bir düzenleyiciye özel bir ana sayfa sunmak için EDITOR_NAME.homepageTrigger öğesini eklenti manifest dosyasına ekleyin.

Aşağıdaki örnekte, bir Google Workspace eklentisi manifestinin addons kısmı gösterilmektedir. Eklenti, Dokümanlar, E-Tablolar ve Slaytlar için etkinleştirilmiştir. Dokümanlar ve Slaytlar'da ortak ana sayfayı, E-Tablolar'da ise benzersiz bir ana sayfayı gösterir. onSheetsHomepage geri çağırma işlevi, E-Tablolar'a özel ana sayfa kartını oluşturur.

 "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"
     },
  }
}

REST API arayüzleri

Eklentiniz Google E-Tablolar API gibi REST API'leri kullanıyorsa Düzenleyici ana uygulamasında açık olan dosyaya özel yeni bir arayüz görüntülemek için onFileScopeGrantedTrigger işlevini kullanabilirsiniz.

onFileScopeGrantedTrigger işlevini kullanmak için drive.file kapsam yetkilendirme akışını eklemeniz gerekir. drive.file kapsamını nasıl isteyeceğinizi öğrenmek için Mevcut doküman için dosya erişimi isteme başlıklı makaleyi inceleyin.

Bir kullanıcı drive.file kapsamını verdiğinde EDITOR_NAME.onFileScopeGrantedTrigger.runFunction tetiklenir. Tetikleyici etkinleştirildiğinde, eklenti manifest dosyasında EDITOR_NAME.onFileScopeGrantedTrigger.runFunction alanı tarafından belirtilen bağlama dayalı tetikleyici işlevini yürütür.

Düzenleyicilerden biri için REST API arayüzü oluşturmak üzere aşağıdaki adımları uygulayın. EDITOR_NAME yerine, kullanmak istediğiniz Editor ana makine uygulamasını (ör. sheets.onFileScopeGrantedTrigger) girin.

  1. EDITOR_NAME.onFileScopeGrantedTrigger simgesini manifestinizin uygun Düzenleyici bölümüne ekleyin. Örneğin, bu arayüzü Google E-Tablolar'da oluşturmak istiyorsanız tetikleyiciyi "sheets" bölümüne ekleyin.
  2. EDITOR_NAME.onFileScopeGrantedTrigger bölümünde belirtilen işlevi uygulayın. Bu işlev, bağımsız değişken olarak bir etkinlik nesnesi kabul eder ve tek bir Card nesnesi veya Card nesnesi dizisi döndürmelidir.
  3. Her kartta olduğu gibi, arayüzde widget etkileşimi sağlamak için kullanılan geri çağırma işlevlerini uygulamanız gerekir. Örneğin, arayüze bir düğme eklerseniz düğmeye ekli bir İşlem ve düğme tıklandığında çalışan bir geri çağırma işlevi olmalıdır.

Aşağıdaki örnekte, bir Google Workspace eklentisi manifest'inin addons kısmı gösterilmektedir. Eklenti REST API'leri kullandığından Google E-Tablolar için onFileScopeGrantedTrigger eklenir. Kullanıcı drive.file kapsamını verdiğinde geri çağırma işlevi onFileScopeGrantedSheets dosyaya özel bir arayüz oluşturur.

"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"
     }
   }

Üçüncü taraf hizmeti için bağlantı önizlemelerini etkinleştirmek istiyorsanız eklentinizin manifest dosyasında bağlantı önizlemelerini yapılandırmanız ve bir önizleme kartı döndüren bir işlev oluşturmanız gerekir. Kullanıcı yetkilendirmesi gerektiren hizmetler için işlevinizin yetkilendirme akışını da çağırması gerekir.

Bağlantı önizlemelerini etkinleştirme adımları için Akıllı çipleri kullanarak bağlantıları önizleme başlıklı makaleyi inceleyin.

Etkinlik nesneleri

Bir etkinlik nesnesi oluşturulur ve EDITOR_NAME.homepageTrigger veya EDITOR_NAME.onFileScopeGrantedTrigger gibi tetikleyici işlevlerine iletilir. Tetikleyici işlevi, eklenti kartlarının nasıl oluşturulacağını belirlemek veya eklenti davranışını başka bir şekilde kontrol etmek için etkinlik nesnesinde bulunan bilgileri kullanır.

Etkinlik nesnelerinin tam yapısı Etkinlik nesneleri bölümünde açıklanmıştır.

Eklentinin etkin ana uygulaması bir Düzenleyici olduğunda etkinlik nesneleri, istemci bilgilerini taşıyan Dokümanlar, E-Tablolar veya Slaytlar etkinlik nesnesi alanlarını içerir.

Eklenti, geçerli kullanıcı veya doküman için drive.file kapsam yetkisine sahip değilse etkinlik nesnesi yalnızca docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission veya slides.addonHasFileScopePermission alanını içerir. Eklentide yetki varsa etkinlik nesnesi, tüm Editor etkinlik nesnesi alanlarını içerir.

Aşağıdaki örnekte, bir sheets.onFileScopeGrantedTrigger işlevine iletilen bir Düzenleyici etkinlik nesnesi gösterilmektedir. Burada, eklenti mevcut doküman için drive.file kapsam yetkisine sahiptir:

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