Kütüphaneler

Kitaplık, işlevleri diğer komut dosyalarında yeniden kullanılabilen bir komut dosyası projesidir.

Bir kitaplık kullanan komut dosyası, tüm kod tek bir komut dosyası projesinde yer alsaydı olduğu kadar hızlı çalışmaz. Kitaplıklar geliştirme ve bakımı kolaylaştırsa da hızın kritik olduğu projelerde bunları dikkatli bir şekilde kullanın. Bu sorun nedeniyle, Google Workspace eklentilerinde kitaplık kullanımı sınırlandırılmalıdır.

Kitaplığa erişim kazanma

Projenize bir kitaplık eklemek için kitaplığa en az görüntüleme düzeyinde erişiminiz olmalıdır. Eklemek istediğiniz kitaplığın yazarı siz değilseniz yazarla iletişime geçerek erişim isteğinde bulunun.

Dahil etmek istediğiniz kitaplığın komut dosyası kimliğine ihtiyacınız vardır. Kitaplığa erişiminiz olduğunda Proje Ayarları sayfasında komut dosyası kimliğini bulun.

Senaryo projenize kitaplık ekleme

  1. Apps Komut Dosyası Düzenleyicisi'nin sol tarafında, "Kitaplıklar"ın yanındaki Kitaplık ekle'yi tıklayın.
  2. "Script ID" (Komut Dosyası Kimliği) alanına kitaplığın komut dosyası kimliğini yapıştırın.
  3. Ara'yı tıklayın.
  4. Sürüm açılır listesini tıklayın ve kullanılacak kitaplık sürümünü seçin.
  5. Varsayılan "Tanımlayıcı" adının bu kitaplıkla kullanmak istediğiniz ad olup olmadığını kontrol edin. Bu, komut dosyanızın kütüphaneyi ifade etmek için kullandığı addır. Örneğin, Test olarak ayarlarsanız bu kitaplığın bir yöntemini şu şekilde çağırın: Test.libraryMethod.
  6. Ekle'yi tıklayın.

Kitaplık kullanma

Dahil edilen kitaplığınızı varsayılan bir hizmet gibi kullanın. Örneğin, kitaplığınızın tanımlayıcısı Test ise kitaplıktaki yöntemlerin listesini görmek için Test yazıp hemen ardından nokta girin.

Aşağıdaki adımları uygulayarak dahil edilen bir kitaplığın referans belgelerini açın:

Komut dosyası düzenleyicisinin sol tarafında, kitaplık adının yanında Diğer > Yeni sekmede aç'ı tıklayın.

Kitaplık kaldırma

Komut dosyası düzenleyicinin sol tarafında, kitaplık adının yanında Diğer > Kaldır > Kitaplığı kaldır'ı tıklayın.

Bir kitaplık yazar tarafından silinirse yine de bu kitaplığı dahil edilen kitaplıklar listenizden kaldırmanız gerekir.

Kitaplığı güncelleme

Kitaplığın sürümünü değiştirme veya tanımlayıcısını güncelleme

  1. Düzenleyicinin sol tarafındaki "Kitaplıklar" bölümünde kitaplığın adını tıklayın.
  2. Değişiklikleri yapın ve Kaydet'i tıklayın.

Kitaplık oluşturma ve paylaşma

Senaryo projenizi kitaplık olarak kullanmak ve paylaşmak için aşağıdaki adımları uygulayın:

  1. Komut dosyanızın sürüm oluşturulmuş bir dağıtımını oluşturun.
  2. Kitaplığın tüm potansiyel kullanıcılarıyla en az görüntüleme düzeyinde erişimi paylaşın.
  3. Bu kullanıcılara, Project Settings (Proje Ayarları) sayfasında bulabileceğiniz komut dosyası kimliğini verin.

En iyi uygulamalar

Kitaplık yazarken uyulması gereken bazı kurallar aşağıda verilmiştir:

  1. Kitaplığınız başkaları tarafından eklendiğinde varsayılan tanımlayıcı olarak kullanıldığından projeniz için anlamlı bir ad seçin.
  2. Komut dosyanızdaki bir veya daha fazla yöntemin kitaplık kullanıcılarınıza görünmemesi (veya bu kullanıcılar tarafından kullanılamaması) için yöntemin adını alt çizgiyle bitirin. Örneğin, myPrivateMethod_.
  3. Kitaplık kullanıcıları yalnızca numaralandırılabilir genel özellikleri görebilir. Buna işlev bildirimleri, var ile bir işlevin dışında oluşturulan değişkenler ve genel nesnede açıkça ayarlanan özellikler dahildir. Örneğin, Object.defineProperty() ile enumerable, false olarak ayarlandığında kitaplığınızda kullanabileceğiniz bir sembol oluşturur ancak bu sembole kullanıcılarınız erişemez.

  4. Kitaplığınızın kullanıcılarının komut dosyası düzenleyicide otomatik tamamlamayı ve otomatik olarak oluşturulan dokümanları kullanabilmesini sağlamak için tüm işlevlerinizde JSDoc tarzı dokümanlar kullanın. Aşağıda bununla ilgili bir örnek verilmiştir:

    /**
 * Raises a number to the given power, and returns the result.
 *
 * @param {number} base the number we're raising to a power
 * @param {number} exp the exponent we're raising the base to
 * @return {number} the result of the exponential calculation
 */
function power(base, exp) { ... }

Kaynak kapsamı

Kitaplıklarla çalışırken iki tür kaynak vardır: paylaşılan ve paylaşılmayan. Paylaşılan kaynak, hem kitaplığın hem de dahil edilen komut dosyasının kaynağın aynı örneğine yerleşik erişimi olduğu anlamına gelir. Aşağıdaki diyagramda, Kullanıcı Özellikleri örneği kullanılarak paylaşılan bir kaynak gösterilmektedir:

Paylaşılan Kaynak

Paylaşılmayan bir kaynak, hem kitaplığın hem de onu içeren komut dosyasının yalnızca kaynağın kendi örneğine yerleşik erişimi olduğu anlamına gelir. Ancak bir kitaplık, üzerinde çalışan açık işlevlere sahip olarak paylaşılmayan kaynaklarına erişim sağlayabilir. Kitaplığınıza ekleyerek komut dosyası özelliklerini kullanıma sunacağınız bir işlev örneğini aşağıda bulabilirsiniz:

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

Aşağıdaki diyagramda, Script Properties örneği kullanılarak paylaşılmayan bir kaynak gösterilmektedir:

Paylaşılmayan kaynak örneği

Bu tabloda, referansınız için paylaşılan ve paylaşılmayan kaynaklar listelenmiştir:

Kaynak Paylaşılanlar* Paylaşılmayan** Notlar
Kilitle Kitaplıkta oluşturulan aynı örnek, komut dosyaları da dahil olmak üzere herkes tarafından görülebilir.
Komut Dosyası Özellikleri Kitaplıkta oluşturulan aynı örnek, komut dosyaları da dahil olmak üzere herkes tarafından görülebilir.
Önbellek Kitaplıkta oluşturulan aynı örnek, komut dosyaları da dahil olmak üzere herkes tarafından görülebilir.
Tetikleyiciler Kitaplıkta oluşturulan basit tetikleyiciler, dahil edilen komut dosyası tarafından tetiklenmez.
ScriptApp
UiApp
Kullanıcı Özellikleri
Günlük kaydedici ve yürütme dökümü
Siteler, E-Tablolar ve diğer kapsayıcılar getActive işlevine yapılan bir çağrı, komut dosyası da dahil olmak üzere getActive kapsayıcısını döndürür.
MailApp ve GmailApp
* Bu, kitaplığın özelliğin/kaynağın kendi örneğine sahip olmadığı ve bunun yerine, onu çağıran komut dosyası tarafından oluşturulanı kullandığı anlamına gelir.
** Bu, kitaplığın kaynağın/özelliğin kendi örneğine sahip olduğu ve kitaplığı kullanan tüm komut dosyalarının aynı örneği paylaşıp bu örneğe erişebildiği anlamına gelir.

Kitaplık test etme

Kitaplığınızı test etmek için ana dağıtımı kullanın. Komut dosyasına düzenleyici düzeyinde erişimi olan herkes, ana dağıtımı kullanabilir.

Kitaplığın en az bir sürümünü kaydetmeniz gerekir.

Kitaplıkta hata ayıklama

Kitaplık içeren bir komut dosyasında hata ayıklarken kitaplık koduna adım atamaz veya kitaplık kodunda kesme noktaları ayarlayamazsınız. Hata ayıklama modunda bir kitaplık işlevine girmeye çalışırsanız hata ayıklayıcı işlevi atlar ve çağıran komut dosyasındaki sonraki satıra geçer.

Kitaplık sürümü için HEAD (Geliştirme Modu) kullanıldığında kitaplığa adım atılamaz veya kitaplıkta kesme noktalarına ulaşılamaz.

Kitaplık kodunda hata ayıklamak için aşağıdaki yöntemlerden birini kullanın:

  • Kitaplık projesinden hata ayıklama: Kitaplık komut dosyası projesini Apps Komut Dosyası düzenleyicide açın. Kitaplık işlevlerini belirli bağımsız değişkenlerle test etmek için kitaplık projesinde kitaplık işlevlerinizi çağıran geçici bir "test" işlevi oluşturun ve bu test işlevini hata ayıklama modunda çalıştırın.
  • Günlüğe kaydetme: Kitaplık işlevlerinizde console.log() kullanarak bilgileri yürütme günlüklerine aktarın. Kitaplık başka bir komut dosyası tarafından çağrıldığında bu günlükler, çağıran komut dosyasının yürütme günlüklerinde görünür.