Google Editor arayüzleri oluşturma

Google Workspace eklentileriyle, Google Dokümanlar, Google E-Tablolar ve Google Slaytlar dahil olmak üzere düzenleyicilerde özelleştirilmiş arayüzler sağlayabilirsiniz. Bu sayede kullanıcıya alakalı bilgiler sağlayabilir, görevleri otomatik hale getirebilir ve üçüncü taraf sistemlerini düzenleyicilere bağlayabilirsiniz.

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

Google Workspace eklentisinin simgesi Dokümanlar, E-Tablolar ve Slaytlar kullanıcı arayüzlerindeki Google Workspace hızlı erişim yan panelinde görünüyorsa eklentiyi düzenleyicilerde açabilirsiniz.

Google Workspace eklentisi 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 tetikleyici EDITOR_NAME.homepageTrigger varsa eklenti, özellikle bu düzenleyici için bir ana sayfa kartı oluşturup döndürür. Eklentinin manifest dosyasında, kullanıcının eklentiyi 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 belgeye 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 özel bir arayüz gösterilir.

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

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

Aşağıdaki adımları uygulayarak düzenleyiciler için Build Editor eklenti arayüzleri oluşturun:

  1. Eklenti komut dosyası projesine uygun addOns.common, addOns.docs, addOns.sheets ve addOns.slides alanlarını ekleyin.
  2. Gerekli Editor kapsamlarını komut dosyası proje manifestinize ekleyin.
  3. Editöre ö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ıcı uygulamalarınız için ortak bir ana sayfa oluşturmak üzere common.homepageTrigger arayüzünü kullanın.
  4. REST API'lerini kullanıyorsanız drive.file kapsam yetkilendirme akışını uygulayın ve EDITOR_NAME.onFileScopeGrantedTrigger açık dosyaya özel bir arayüz görüntülemek için tetikleyici işlevini kullanın. Daha fazla bilgi için REST API arayüzleri başlıklı makaleyi inceleyin.
  5. Üçüncü taraf hizmetinden bağlantı önizlemeleri 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.

Editör ana sayfaları

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

Ana sayfa tetikleyici işlevine, parametre olarak istemcinin platformu gibi bilgileri içeren bir event object 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üzenleyiciye özel bir ana sayfa sunabilirsiniz.

Ortak ana sayfayı görüntüleme

Eklentinizin ortak ana sayfasını düzenleyicilerde göstermek için eklentinin manifest dosyasına uygun düzenleyici alanlarını (ör. addOns.docs, addOns.sheets veya addOns.slides) ekleyin.

Aşağıdaki örnekte, Google Workspace eklentisi manifest dosyasının addons bölümü gösterilmektedir. Eklenti, Dokümanlar, E-Tablolar ve Slaytlar'ı genişletir ve her ana makine uygulamasında 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örüntüleme

Bir düzenleyiciye özel ana sayfa sunmak için eklenti manifestine EDITOR_NAME.homepageTrigger ekleyin.

Aşağıdaki örnekte, Google Workspace eklentisi manifest dosyasının addons bölümü gösterilmektedir. Eklenti, Dokümanlar, E-Tablolar ve Slaytlar için etkinleştirilir. Dokümanlar ve Slaytlar'da ortak ana sayfa, E-Tablolar'da ise benzersiz bir ana sayfa gösterilir. Geri çağırma işlevi onSheetsHomepage, 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 Sheets API gibi REST API'leri kullanıyorsa onFileScopeGrantedTrigger işlevini kullanarak düzenleyici ana uygulamasında açık olan dosyaya özel yeni bir arayüz görüntüleyebilirsiniz.

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 belge için dosya erişimi iste başlıklı makaleye bakın.

Kullanıcı drive.file kapsamı verdiğinde EDITOR_NAME.onFileScopeGrantedTrigger.runFunction tetiklenir. Tetikleyici tetiklendiğinde, eklenti manifestosundaki EDITOR_NAME.onFileScopeGrantedTrigger.runFunction alanı tarafından belirtilen bağlamsal tetikleyici işlevi yürütülür.

Düzenleyicilerden biri için REST API arayüzü oluşturmak üzere aşağıdaki adımları tamamlayın. EDITOR_NAME yerine kullanmayı tercih ettiğiniz düzenleyici ana makine uygulamasını (ör. sheets.onFileScopeGrantedTrigger) girin:

  1. Manifest dosyanızın uygun Düzenleyici bölümüne EDITOR_NAME.onFileScopeGrantedTrigger 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 event object kabul eder ve tek bir Card nesnesi ya da Card nesneleri dizisi döndürmelidir.
  3. Diğer kartlarda olduğu gibi, arayüz için widget etkileşimi sağlamak üzere kullanılan geri çağırma işlevlerini uygulamanız gerekir. Örneğin, arayüze bir düğme eklerseniz bu düğmeye bir Action eklenmeli ve düğme tıklandığında çalışan bir geri çağırma işlevi uygulanmalıdır.

Aşağıdaki örnekte, bir Google Workspace eklenti manifestinin addons bölümü gösterilmektedir. Eklenti, REST API'lerini kullandığı için Google E-Tablolar'da onFileScopeGrantedTrigger yer alır. 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 ö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şlevlere iletilir. Tetikleyici işlevi, eklenti kartlarının nasıl oluşturulacağını veya eklenti davranışının nasıl kontrol edileceğini belirlemek için etkinlik nesnesindeki bilgileri kullanır.

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

Bir düzenleyici, eklentinin etkin ana makine uygulaması olduğunda etkinlik nesneleri, istemci bilgilerini taşıyan Docs, Sheets veya Slides etkinlik nesnesi alanlarını içerir.

Eklentinin mevcut kullanıcı veya doküman için drive.file kapsamı yetkilendirmesi yoksa etkinlik nesnesi yalnızca docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission veya slides.addonHasFileScopePermission alanını içerir. Eklentinin yetkisi varsa etkinlik nesnesi, tüm düzenleyici etkinlik nesnesi alanlarını içerir.

Aşağıdaki örnekte, sheets.onFileScopeGrantedTrigger işlevine iletilen bir düzenleyici etkinliği nesnesi gösterilmektedir. Burada, eklenti geçerli doküman için drive.file kapsamlı yetkilendirmeye sahip:

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