Google Dokümanlar'ın kapsamını genişletme

Google Apps Komut Dosyası, Google Dokümanlar'ı programlı olarak oluşturup değiştirmenize ve kullanıcı arayüzünü yeni menüler, iletişim kutuları ve kenar çubuklarıyla özelleştirmenize olanak tanır.

Temel bilgiler

Apps Komut Dosyası, Google Dokümanlar ile iki farklı şekilde etkileşim kurabilir: Herhangi bir komut dosyası, kullanıcısı ilgili doküman için uygun izinlere sahipse doküman oluşturabilir veya dokümanı değiştirebilir. Ayrıca, bir komut dosyası bir dokümana bağlı olabilir. Bu durumda komut dosyası, kullanıcı arayüzünü değiştirme veya doküman açıldığında yanıt verme gibi özel özelliklere sahip olur. Google Dokümanlar'dan kapsayıcıya bağlı bir komut dosyası oluşturmak için Uzantılar > Apps Komut Dosyası'nı tıklayın.

Her iki durumda da, aşağıdaki örnekte gösterildiği gibi Apps Script'in Doküman Hizmeti aracılığıyla bir Google Dokümanlar dokümanıyla etkileşimde bulunmak kolaydır.

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var documentTab = doc.getTab('t.0').asDocumentTab();
  var body = documentTab.getBody();
  var rowsData = [['Plants', 'Animals'], ['Ficus', 'Goat'], ['Basil', 'Cat'], ['Moss', 'Frog']];
  body.insertParagraph(0, doc.getName())
      .setHeading(DocumentApp.ParagraphHeading.HEADING1);
  table = body.appendTable(rowsData);
  table.getRow(0).editAsText().setBold(true);
}

Yukarıdaki komut dosyası, kullanıcının Google Drive'ında yeni bir doküman oluşturur, ardından t.0 kimlikli sekmeyi (varsayılan ilk sekme) alır, dokümanın adıyla aynı metni içeren bir paragraf ekler, bu paragrafı başlık olarak biçimlendirir ve iki boyutlu bir dizideki değerlere göre bir tablo ekler. Komut dosyası, DocumentApp.create() çağrısını DocumentApp.openById() veya openByUrl() ile değiştirerek mevcut bir dokümanda bu değişiklikleri kolayca yapabilir. Bir doküman içinde oluşturulan komut dosyaları (kapsayıcıya bağlı) için DocumentApp.getActiveDocument() ve Document.getActiveTab() öğelerini kullanın.

Doküman yapısı

Apps Script'in bakış açısına göre, bir Google Dokümanlar belgesi HTML belgesine çok benzer şekilde yapılandırılmıştır. Yani bir belge, her biri genellikle başka öğeler içeren öğeler (ör. Paragraph veya Table) içeren bir veya daha fazla Tab nesnesinden oluşur. Bir Google Dokümanlar dokümanını değiştiren komut dosyalarının çoğu, Body bir sekmedeki HeaderSection, FooterSection ve Footnotes dışındaki tüm öğeleri içeren temel bir öğe olduğundan getTab() ve asDocumentTab() çağrısıyla başlar ve ardından getBody() çağrısı gelir.

Ancak hangi öğe türlerinin diğer türleri içerebileceğiyle ilgili kurallar vardır. Ayrıca, Apps Komut Dosyası'ndaki Doküman Hizmeti, diğer öğelere yalnızca belirli öğe türlerini ekleyebilir. Aşağıdaki ağaçta, belirli bir öğe türüne hangi öğelerin dahil edilebileceği gösterilmektedir.

Kalın olarak gösterilen öğeler eklenebilir; kalın olmayan öğeler yalnızca yerinde değiştirilebilir.

Metni değiştirme

Apps Script, genellikle Google Dokümanlar'daki metinleri değiştirmek için kullanılır. Müşteri bilgileriyle dolu bir e-tablonuz olduğunu ve her müşteri için kişiselleştirilmiş bir Google Dokümanları belgesi oluşturmak istediğinizi varsayalım. (Bu tür işlemlere genellikle posta birleştirme denir.)

Metni değiştirmenin birçok yolu vardır ancak en basiti aşağıdaki örnekte gösterilen replaceText() yöntemidir. replaceText, JavaScript'in normal ifade özelliklerinin çoğunu destekler. Aşağıdaki ilk işlev, bir Google Dokümanlar dosyasına birkaç satır yer tutucu metin ekler. Gerçek hayatta, yer tutucuları dokümana kendiniz yazma olasılığınız daha yüksektir. İkinci işlev, yer tutucuları client nesnesinde tanımlanan özelliklerle değiştirir.

Bu işlevlerin her ikisinin de getActiveDocument() ve getActiveTab() yöntemlerini kullandığını unutmayın. Bu yöntemler yalnızca Google Dokümanlar belgesi içinde oluşturulan komut dosyaları için geçerlidir. Bağımsız bir komut dosyasında Document.getTab() ile birlikte DocumentApp.create(), openById() veya openByUrl() yöntemini kullanın.

Yer tutucu ekleme

function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  body.appendParagraph('{name}');
  body.appendParagraph('{address}');
  body.appendParagraph('{city} {state} {zip}');
}

Yer tutucuları değiştirme

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().getBody();
  var client = {
    name: 'Joe Script-Guru',
    address: '100 Script Rd',
    city: 'Scriptville',
    state: 'GA',
    zip: 94043
  };

  body.replaceText('{name}', client.name);
  body.replaceText('{address}', client.address);
  body.replaceText('{city}', client.city);
  body.replaceText('{state}', client.state);
  body.replaceText('{zip}', client.zip);
}

Özel menüler ve kullanıcı arayüzleri

Menüler, iletişim kutuları ve kenar çubukları ekleyerek Google Dokümanlar'ı özelleştirebilirsiniz. Ancak bir komut dosyasının yalnızca açık dokümanın mevcut örneğinin kullanıcı arayüzüyle etkileşime geçebileceğini ve bunun da yalnızca komut dosyasının dokümana bağlı olması durumunda geçerli olduğunu unutmayın.

Google Dokümanlar dosyalarınıza özel menüler ve iletişim kutuları nasıl ekleyeceğinizi öğrenin. İletişim kutusu veya kenar çubuğu için özel arayüz oluşturma hakkında daha fazla bilgi edinmek için HTML Hizmeti kılavuzuna bakın. Özel arayüzünüzü bir eklenti kapsamında yayınlamayı planlıyorsanız Google Dokümanlar düzenleyicisinin stili ve düzeniyle tutarlı olması için stil kılavuzundaki talimatları uygulayın.

Google Dokümanlar için eklentiler

Eklentiler, Google Dokümanlar'da çalışır ve Google Dokümanlar eklenti mağazasından yüklenebilir. Google Dokümanlar için bir komut dosyası geliştirdiyseniz ve bunu dünyayla paylaşmak istiyorsanız Apps Komut Dosyası, komut dosyanızı eklenti olarak yayınlamanıza olanak tanır. Böylece diğer kullanıcılar eklenti mağazasından komut dosyanızı yükleyebilir.

Google Dokümanlar için nasıl eklenti oluşturabileceğinizi öğrenmek isterseniz Dokümanlar eklentisi oluşturmaya yönelik hızlı başlangıç kılavuzuna göz atın.

Tetikleyiciler

Bir Google Dokümanına bağlı komut dosyaları, dokümanın onOpen etkinliğine yanıt vermek için basit bir tetikleyici kullanabilir. Bu etkinlik, dokümana düzenleme erişimi olan bir kullanıcı dokümanı Google Dokümanlar'da her açtığında gerçekleşir.

Tetikleyiciyi ayarlamak için onOpen() adlı bir işlev yazmanız yeterlidir. Bu tetikleyicinin örneği için Google Workspace'te özel menüler başlıklı makaleyi inceleyin. Basit tetikleyici, menü eklemek için kullanışlı olsa da yetkilendirme gerektiren hiçbir Apps Komut Dosyaları hizmetini kullanamaz.