Kitaplıklar

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

Uyarı: Kitaplık kullanan bir komut dosyası, tüm kodun tek bir komut dosyası projesinde yer alması halinde kadar hızlı çalışmaz. Kütüphaneler, geliştirme ve bakım işlemlerini daha kolay hale getirebilse de hızın önemli olduğu projelerde bu kütüphaneleri kullanırken dikkatli olun. Bu sorun nedeniyle, eklentilerde kitaplık kullanımı sınırlı olmalıdır.

Bir kitaplığa erişim elde etme

Projenize bir kitaplık eklemek için kitaplıkta en azından görüntüleme düzeyinde erişiminizin olması gerekir. Dahil etmek istediğiniz kitaplığın yazarı siz değilseniz yazarla iletişime geçin ve 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 ekleyin

1. Apps Komut Dosyası düzenleyicisinin solunda, "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ünüm düzeyinde erişiminizin olduğundan emin olun.
4. Sürüm açılır listesini tıklayın ve kullanılacak kitaplığın 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şvurmak için kullandığı addır. Örneğin, değeri Test olarak ayarlarsanız söz konusu kitaplık için şu şekilde bir yöntem çağırabilirsiniz: Test.libraryMethod().
   MailApp gibi zaten mevcut bir hizmetin veya daha önce eklenen bir kitaplıkın adıyla eşleşen bir tanımlayıcı adı kullanıyorsanı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 hizmet gibi kullanın. Örneğin, Test kitaplığınızın tanımlayıcısıysa kitaplıktaki yöntemlerin listesini görmek için hemen Test yazıp bir nokta ekleyin.

Dahil edilen kütüphanenin referans belgeleri şu adımlar uygulanarak açılabilir:

Komut dosyası düzenleyicisinin 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ı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ştirebilir veya tanımlayıcısını güncelleyebilirsiniz.

1. Düzenleyicinin sol tarafındaki "Kitaplıklar"ın altında kitaplığın 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ı uygulayın.

1. Komut dosyanızın sürümlü dağıtımını oluşturun.
2. En azından görüntüleme düzeyinde erişimi, kitaplığın tüm potansiyel kullanıcılarıyla paylaşın.
3. Bu kullanıcılara, Proje ayarları sayfasındaki komut dosyası kimliğini verin.

En iyi uygulamalar

Kitaplık yazarken uymanız gereken bazı kurallar şunlardır:

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ız tarafından görülmüyor (veya kullanılamıyor) 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şlev dışında oluşturulan değişkenler ve genel nesne üzerinde açıkça ayarlanan özellikler dahildir. Örneğin, enumerable öğesinin false olarak ayarlandığı Object.defineProperty(), kitaplığınızda kullanabileceğiniz bir simge oluşturur ancak kullanıcılarınız bu simgeye erişemez.

4. Kitaplık kullanıcılarınızın komut dosyası düzenleyicinin otomatik tamamlama özelliğinden ve otomatik olarak oluşturulan dokümanlardan yararlanmasını istiyorsanız tüm işlevleriniz için JSDoc stili 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 vardır: paylaşılan ve paylaşılmayan. Paylaşılan kaynak, hem kitaplığın hem de dahil komut dosyasının aynı kaynak örneğine yerleşik erişime sahip olduğu 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 komut dosyasının yalnızca kendi kaynak örneğine yerleşik erişime sahip olduğu anlamına gelir. Ancak kitaplık, paylaşılmayan kaynaklarına, üzerinde çalışan açık işlevler ekleyerek erişim sağlayabilir. Komut Dosyası Özelliklerini görüntülemek için kitaplığınıza ekleyebileceğiniz bir işlev örneğini burada bulabilirsiniz:

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

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

Referans olması amacıyla, paylaşılan ve paylaşılmayan kaynaklar aşağıdaki tabloda listelenmiştir:

Kaynak	Paylaşıldı*	Paylaşılmayan**	Notlar
Kilitle			Aynı örneği, kitaplıkta oluşturulan komut dosyaları dahil herkes görebilir.
Komut Dosyası Özellikleri			Aynı örneği, kitaplıkta oluşturulan komut dosyaları dahil herkes görebilir.
Önbellek			Aynı örneği, kitaplıkta oluşturulan komut dosyaları dahil herkes görebilir.
Tetikleyiciler			Kitaplıkta oluşturulan basit tetikleyiciler, dahil etme komut dosyası tarafından tetiklenmez.
ScriptApp
UiApp
Kullanıcı Özellikleri
Günlük kaydedici 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 durum, kitaplığın kendi özellik/kaynak örneğinin olmadığı, bunun yerine onu çağıran komut dosyası tarafından oluşturulan örneği kullandığı anlamına gelir. ** Bu, kitaplığın kendi kaynak/özellik örneğinin bulunduğu ve kitaplığı kullanan tüm komut dosyalarının aynı örneği paylaştığı ve bu örneğe erişimi olduğu anlamına gelir.

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 "head" dağıtımını kullanabilir.

Yine de kitaplığın en az bir sürümünün kayıtlı olması gerekir.

Kitaplıkta hata ayıklama

Hata ayıklayıcıyı kitaplık içeren bir projede kullandığınızda, dahil edilen kitaplıktaki bir işleve geçebilirsiniz. Bu kod, hata ayıklayıcıda salt görüntüleme modunda ve doğru sürümde görünür.