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

Google Apps Komut Dosyası, Google Dokümanlar'ı programatik olarak oluşturmanıza ve değiştirmenize, ayrıca 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 kapsamlı etkileşim gerçekleştirebilir: Komut dosyası kullanıcısı doküman için uygun izinlere sahipse herhangi bir komut dosyası doküman oluşturabilir veya dokümanı değiştirebilir. Ayrıca komut dosyası bir dokümana bağlanabilir. Bu da komut dosyasına, kullanıcı arayüzünü değiştirme veya doküman açıldığında yanıt verme gibi özel olanaklar sunar. Google Dokümanlar'ın içinden 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 Komut Dosyası'nın Doküman Hizmeti üzerinden bir Google Dokümanı ile etkileşimde bulunmak kolaydır.

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var body = doc.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 dokümanın adıyla aynı metni içeren bir paragrafı ve bu paragrafı başlık olarak ekler 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 mevcut bir dokümanda bu değişiklikleri kolayca yapabilir. Bir dokümanın içinde oluşturulan komut dosyaları (kapsayıcıya bağlı) için DocumentApp.getActiveDocument() değerini kullanın.

Bir belgenin yapısı

Apps Komut Dosyası açısından bakıldığında, bir Google Dokümanı HTML dokümanına benzer şekilde yapılandırılır. Yani bir Google Dokümanı, genellikle başka öğeler içeren öğelerden (Paragraph veya Table gibi) oluşur. Body; HeaderSection, FooterSection ve Footnotes haricindeki tüm diğer öğeleri içeren bir ana öğe olduğundan, bir Google Dokümanını değiştiren çoğu komut dosyası getBody() çağrısıyla başlar.

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

Kalın karakterlerle gösterilen öğeler eklenebilir; kalın olmayan öğeler ise yalnızca yerlerinde düzenlenebilir.

Metin değiştiriliyor

Google Dokümanlar'da metin değiştirmek için genellikle Apps Komut Dosyası kullanılır. Müşteri bilgilerini içeren bir e-tablonuz olduğunu ve her müşteri için kişiselleştirilmiş bir Google Dokümanlar dosyası oluşturmak istediğinizi varsayalım. (Bu tür işlemlere genellikle posta birleştirme denir.)

Metinleri 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'a birkaç satır yer tutucu metin ekler. Gerçek dünyada, yer tutucuları dokümana kendiniz girmeniz gerekir. İkinci işlev, yer tutucuları client nesnesinde tanımlanan özelliklerle değiştirir.

Bu işlevlerin ikisinin de yalnızca Google Dokümanı içinde oluşturulan komut dosyaları için geçerli olan getActiveDocument() yöntemini kullandığını unutmayın. Bağımsız bir komut dosyası ise bunun yerine DocumentApp.create(), openById() veya openByUrl() yöntemini kullanın.

Yer tutucu ekleyin

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

Yer tutucuları değiştirme

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument()
      .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. Bununla birlikte, bir komut dosyasının yalnızca açık bir dokümanın geçerli örneği için kullanıcı arayüzüyle ve yalnızca komut dosyası dokümana bağlıysa etkileşim kurabileceğ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ılavuzuna bakın. Özel arayüzünüzü bir eklentinin parçası olarak yayınlamayı planlıyorsanız, Google Dokümanlar düzenleyicisinin stili ve düzeniyle tutarlılık sağlamak için stil kılavuzundaki adımları uygulayın.

Google Dokümanlar eklentileri

Eklentiler, Google Dokümanlar'ın içinde ç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ı, diğer kullanıcıların eklenti mağazasından yükleyebileceği bir eklenti olarak komut dosyanızı publish olanak tanır.

Google Dokümanlar için eklenti oluşturma hakkında bilgi edinmek üzere Dokümanlar eklentileri oluşturma hızlı başlangıç kılavuzunu inceleyin.

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 işlem, 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 bir örneğini Google Workspace'te özel menüler bölümünde bulabilirsiniz. Basit tetikleyici, menü eklemek için kullanışlı olsa da yetkilendirme gerektiren herhangi bir Apps Komut Dosyası hizmetini kullanamaz.