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

Google Apps Komut Dosyası, Google Dokümanlar'ı programatik 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 şekilde etkileşime geçebilir: Komut dosyasının kullanıcısı doküman için uygun izinlere sahipse herhangi bir komut dosyası doküman oluşturabilir veya değiştirebilir. Ayrıca, komut dosyası bir dokümana bağlanabilir. Bu durumda komut dosyası, kullanıcı arayüzünü değiştirme veya doküman açıldığında yanıt verme gibi özel yetkilere sahip olur. Google Dokümanlar'da 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 Document Service'i aracılığıyla Google Dokümanlar dokümanıyla etkileşim kurmak 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 dayalı bir tablo ekler. Komut dosyası, DocumentApp.create() çağrısını DocumentApp.openById() veya openByUrl() ile değiştirerek bu değişiklikleri mevcut bir dokümanda da aynı kolaylıkla yapabilir. Bir dokümanın içinde oluşturulan komut dosyaları (kapsayıcıya bağlı) için DocumentApp.getActiveDocument() ve Document.getActiveTab() kullanın.

Doküman yapısı

Apps Komut Dosyası açısından bir Google Dokümanı, HTML dokümanına çok benzer bir şekilde yapılandırılır. Yani bir doküman, her biri genellikle başka öğeler içeren öğeler (ör. Paragraph veya Table) içeren bir veya daha fazla Tab nesneden oluşur. Google Dokümanlar belgesini değiştiren çoğu komut dosyası getTab() ve asDocumentTab() çağrısıyla başlar, ardından getBody() gelir. Bunun nedeni, Body'in HeaderSection, FooterSection ve Footnotes dışındaki bir sekmedeki tüm diğer öğeleri içeren temel bir öğe olmasıdır.

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 yalnızca belirli öğe türlerini diğer öğelere ekleyebilir. Aşağıdaki ağaçta, belirli bir öğe türünün hangi öğeleri içerebileceğ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 Komut Dosyası, Google Dokümanlar'da metin değiştirmek için sıklıkla kullanılır. Müşteri bilgileriyle dolu bir elektronik tablonuz olduğunu ve her müşteri için kişiselleştirilmiş bir Google Dokümanı 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ümanı'na birkaç satır yer tutucu metin ekler. Gerçek hayatta, yer tutucuları dokümana kendiniz yazmanız daha olasıdır. İkinci işlev, yer tutucuları client nesnesinde tanımlanan özelliklerle değiştirir.

Bu iki işlevin de yalnızca Google Dokümanlar belgesinde oluşturulan komut dosyaları için geçerli olan getActiveDocument() ve getActiveTab() yöntemlerini kullandığını unutmayın. Bağımsız bir komut dosyasında bunun yerine Document.getTab() ile birlikte DocumentApp.create(), openById() veya openByUrl() yöntemlerini kullanın.

Birkaç yer tutucu ekleyin

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

Yer tutucuları değiştirin

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 bir dokümanın mevcut örneğinin kullanıcı arayüzüyle etkileşimde bulunabileceğini ve yalnızca komut dosyası dokümana bağlıysa etkileşimde bulunabileceğini unutmayın.

Google Dokümanlarınıza nasıl özel menü ve iletişim kutusu ekleyeceğinizi öğrenin. Bir iletişim kutusu veya kenar çubuğu için özel arayüzler oluşturma hakkında daha fazla bilgi edinmek için HTML Hizmeti Kılavuzu'na bakın. Özel arayüzünüzü bir eklenti olarak yayınlamayı planlıyorsanız Google Dokümanlar düzenleyicisinin stili ve düzeniyle tutarlılık için stil kılavuzuna uyun.

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 tüm dünyayla paylaşmak istiyorsanız Apps Komut Dosyası, komut dosyanızı eklenti mağazasından diğer kullanıcılar tarafından yüklenebilecek bir eklenti olarak yayınlamanıza olanak tanır.

Google Dokümanlar için nasıl eklenti oluşturabileceğinizi öğrenmek istiyorsanız Dokümanlar eklentileri oluşturmayla ilgili hızlı başlangıç başlıklı makaleyi inceleyin.

Tetikleyiciler

Google Doküman'a bağlı olan komut dosyaları, dokümanın onOpen etkinliğine yanıt vermek için basit 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 tetikleyiciyle ilgili bir örnek 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 Dosyası hizmetini kullanamaz.