Kütüphaneler

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

Uyarı: Kitaplığı kullanan bir komut dosyası, tüm kodların tek bir komut dosyası projesinde yer aldığı durumlardaki kadar hızlı çalışmaz. Kitaplıklar, geliştirme ve bakımı daha rahat hale getirebilse de hızın önemli olduğu projelerde bunları tutumlu bir şekilde kullanın. Bu sorun nedeniyle, eklentilerde kitaplık kullanımı sınırlı olmalıdır.

Kitaplığa erişim elde etme

Projenize bir kitaplık ekleyebilmek için en az görüntüleme düzeyinde erişiminizin olması gerekir. Dahil etmek istediğiniz kitaplığın yazarı siz değilseniz yazarla iletişime geçerek erişim isteyin.

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

Komut dosyası projenize kitaplık ekleme

1. Apps Komut Dosyası düzenleyicisinin sol tarafında, "Kitaplıklar"ın yanındaki Kitaplık ekle'yi tıklayın.
2. "Komut dosyası kimliği" alanına, kitaplığın komut dosyası kimliğini yapıştırın.
3. Ara'yı tıklayın.
   Bir hatayla karşılaşırsanız dahil etmeye çalıştığınız projeye en azından görüntüleme düzeyinde erişiminizin olduğundan emin olun.
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 kitaplığa başvuruda kullandığı addır. Örneğin, Test olarak ayarlarsanız bu kitaplığın yöntemini şu şekilde çağırabilirsiniz: Test.libraryMethod().
   MailApp gibi mevcut bir hizmetin veya önceden eklenmiş bir kitaplığın adıyla eşleşen bir tanımlayıcı adı kullanırsanız en son eklediğiniz kitaplık, mevcut hizmeti veya kitaplığı geçersiz kılar.
6. Ekle'yi tıklayın.

Kitaplık kullanma

Dahil edilen kitaplığınızı varsayılan bir hizmeti kullanıyormuş gibi kullanın. Örneğin, Test, kitaplığınızın tanımlayıcısıysa Test yazın ve ardından nokta ekleyerek kitaplıktaki yöntemlerin listesini görün.

Dahil edilen bir kitaplığın referans dokümanları şu adımlar uygulanarak açılabilir:

Komut dosyası düzenleyicinin solunda, kitaplık adının yanındaki Diğer > Yeni sekmede aç'ı tıklayın.

Kitaplığı kaldırma

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

Bir kitaplığın yazar tarafından silinmesi durumunda bu kitaplığı yine de dahil edilen kitaplıklar listenizden kaldırmanız gerekir.

Kitaplığı güncelleme

Kitaplığın sürümünü değiştirebilir veya tanımlayıcısını güncelleyebilirsiniz.

1. Düzenleyicinin solunda, "Kitaplıklar"ın altında kütüphanenin adını tıklayın.
2. Değişiklikleri yapıp Kaydet'i tıklayın.

Kitaplık oluşturma ve paylaşma

Komut dosyası projenizi kitaplık olarak kullanmak ve paylaşmak için aşağıdaki adımları izleyin.

1. Komut dosyanızın sürümü olan bir dağıtımını oluşturun.
2. Kütüphanenin tüm potansiyel kullanıcılarıyla en azından görüntüleme düzeyinde erişimi paylaşın.
3. Bu kullanıcılara komut dosyası kimliğini verin. Bu kimliği Proje ayarları sayfasında bulabilirsiniz.

En iyi uygulamalar

Kitaplık yazarken uyulması gereken bazı yönergeler şunlardır:

1. Kitaplığınız başkaları tarafından dahil edildiğ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ız tarafından görünmesini (veya kullanılamaz) olmasını istiyorsanız yöntemin adını alt çizgiyle sonlandırabilirsiniz. Ö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 global nesnede açıkça ayarlanmış özellikler dahildir. Örneğin, enumerable değeri false olarak ayarlanmış Object.defineProperty(), kitaplığınızda kullanabileceğiniz bir simge oluşturur ancak kullanıcılarınız bu sembole erişemez.

4. Kitaplık kullanıcılarınızın komut dosyası düzenleyicideki otomatik tamamlama özelliğinden ve otomatik olarak oluşturulan dokümanlardan yararlanmasını istiyorsanız tüm işlevleriniz için JSDoc tarzı belgelere sahip olmanız gerekir. Aşağıda 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 bulunur: paylaşılan ve paylaşılmayan. Paylaşılan kaynak, hem kitaplığın hem de dahil edilen komut dosyasının aynı kaynak örneğine yerleşik erişime sahip olması anlamına gelir. Aşağıdaki şemada, Kullanıcı Özellikleri örneği kullanılarak paylaşılan bir kaynak gösterilmektedir:

Paylaşılmayan kaynak, hem kitaplığın hem de dahil edilen komut dosyasının yalnızca kendi kaynak örneğine yerleşik erişime sahip olduğu anlamına gelir. Ancak bir kitaplık, üzerinde çalışan açık işlevlere sahip olarak paylaşılmayan kaynaklarına da erişim sağlayabilir. Aşağıda, Komut Dosyası Özelliklerini görüntülemek için kitaplığınıza dahil edebileceğiniz bir işlev örneği verilmiştir:

  function getLibraryProperty(key) {
    return ScriptProperties.getProperty(key);
  }

Aşağıdaki şemada, paylaşılmayan bir kaynak, Komut Dosyası Özellikleri örneği kullanılarak gösterilmektedir:

Paylaşılan ve paylaşılmayan kaynaklar aşağıdaki tabloda listelenmiştir:

Kaynak	Paylaşılan*	Paylaşılmıyor**	Notlar
Kilitle			Aynı örnek, kitaplıkta oluşturulan komut dosyaları dahil herkes tarafından görülebilir.
Komut Dosyası Özellikleri			Aynı örnek, kitaplıkta oluşturulan komut dosyaları dahil herkes tarafından görülebilir.
Önbellek			Aynı örnek, kitaplıkta oluşturulan komut dosyaları dahil herkes tarafından görülebilir.
Tetikleyiciler			Kitaplıkta oluşturulan basit tetikleyiciler, dahil etme komut dosyası tarafından tetiklenmez.
ScriptApp
UiApp
Kullanıcı Özellikleri
Günlükçü ve yürütme dökümü
Sites, E-Tablolar ve diğer kapsayıcılar			getActive() çağrısı, dahil etme komut dosyasının kapsayıcısını döndürür.
MailApp ve GmailApp
* Bu, kitaplığın kendi özellik/kaynak örneği olmadığı ve bunun yerine özelliği/kaynağı çağıran komut dosyası tarafından oluşturulan örneği kullandığı anlamına gelir. ** Bu, kitaplığın kendi kaynak/özellik örneği olduğu ve kitaplığı kullanan tüm komut dosyalarının aynı örneği paylaşıp erişime sahip olduğu anlamına gelir.

Bir kitaplığı test etme

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

Yine de kitaplığın en az bir sürümünü kaydetmiş olmanız gerekir.

Kitaplıkta hata ayıklama

Hata ayıklayıcıyı kitaplık içeren bir projede kullandığınızda, dahil edilen kitaplığın bir işlevine girebilirsiniz. Kod, hata ayıklayıcıda salt görüntüleme modunda ve doğru sürümde gösterilir.