گسترش Google Docs

اسکریپت Google Apps به شما امکان می‌دهد تا اسناد گوگل را به صورت برنامه‌نویسی شده ایجاد و تغییر دهید، و همچنین رابط کاربری را با منوها، کادرهای محاوره‌ای و نوارهای کناری جدید سفارشی کنید.

اصول اولیه

اسکریپت برنامه‌ها می‌تواند به دو روش کلی با Google Docs تعامل داشته باشد: هر اسکریپتی می‌تواند یک سند را ایجاد یا تغییر دهد، در صورتی که کاربر اسکریپت مجوزهای لازم برای سند را داشته باشد، و همچنین یک اسکریپت می‌تواند به یک سند متصل شود، که به اسکریپت قابلیت‌های ویژه‌ای برای تغییر رابط کاربری یا پاسخ دادن هنگام باز شدن سند می‌دهد. برای ایجاد یک اسکریپت متصل به کانتینر از درون Google Docs، روی Extensions > Apps Script کلیک کنید.

در هر صورت، همانطور که مثال زیر نشان می‌دهد، تعامل با یک سند Google Docs از طریق سرویس سند Apps Script ساده است.

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);
}

اسکریپت بالا یک سند جدید در گوگل درایو کاربر ایجاد می‌کند، سپس تب با شناسه t.0 (تب اول پیش‌فرض) را بازیابی می‌کند، پاراگرافی را که حاوی همان متن نام سند است وارد می‌کند، آن پاراگراف را به عنوان سرتیتر استایل‌بندی می‌کند و یک جدول بر اساس مقادیر موجود در یک آرایه دوبعدی اضافه می‌کند. این اسکریپت می‌تواند به راحتی با جایگزینی فراخوانی DocumentApp.create() با DocumentApp.openById() یا openByUrl() این تغییرات را در یک سند موجود ایجاد کند. برای اسکریپت‌هایی که درون یک سند (container-bound) ایجاد می‌شوند، DocumentApp.getActiveDocument() و Document.getActiveTab() استفاده کنید.

ساختار یک سند

از دیدگاه Apps Script، یک سند Google Docs ساختار بسیار شبیه به یک سند HTML دارد - یعنی یک سند از یک یا چند شیء Tab تشکیل شده است که هر کدام شامل عناصری (مانند یک Paragraph یا Table ) هستند که اغلب شامل عناصر دیگری نیز می‌شوند. اکثر اسکریپت‌هایی که یک سند Google Docs را تغییر می‌دهند، با فراخوانی getTab() و asDocumentTab() و به دنبال آن getBody() شروع می‌شوند، زیرا Body یک عنصر اصلی است که شامل تمام عناصر دیگر در یک tab به جز HeaderSection ، FooterSection و هرگونه Footnotes می‌شود.

با این حال، قوانینی در مورد اینکه کدام نوع عناصر می‌توانند شامل انواع دیگر باشند، وجود دارد. علاوه بر این، سرویس سند در Apps Script فقط می‌تواند انواع خاصی از عناصر را در عناصر دیگر وارد کند. درخت زیر نشان می‌دهد که کدام عناصر می‌توانند توسط یک نوع خاص از عنصر در بر گرفته شوند.

عناصری که با حروف پررنگ نشان داده شده‌اند را می‌توان وارد کرد؛ عناصر غیر پررنگ را فقط می‌توان در جای خود دستکاری کرد.

• سند
• تب
• برگه سند
• بدن
• آیتم لیست
• معادله
• تابع معادله
• تابع معادله ...
• تابع معادلهجداکننده آرگومان
• نماد معادله
• متن

جایگزینی متن

اسکریپت برنامه‌ها اغلب برای جایگزینی متن در Google Docs استفاده می‌شود. فرض کنید یک صفحه گسترده پر از اطلاعات مشتری دارید و می‌خواهید برای هر مشتری یک Google Docs شخصی‌سازی‌شده ایجاد کنید. (این نوع عملیات اغلب ادغام پستی نامیده می‌شود.)

روش‌های زیادی برای جایگزینی متن وجود دارد، اما ساده‌ترین آنها متد replaceText() است که در مثال زیر نشان داده شده است. replaceText از اکثر ویژگی‌های عبارات منظم جاوا اسکریپت پشتیبانی می‌کند. اولین تابع زیر چندین خط متن جایگزین را به یک سند گوگل اضافه می‌کند؛ در دنیای واقعی، احتمال بیشتری وجود دارد که خودتان جایگزین‌ها را در سند تایپ کنید. تابع دوم جایگزین‌ها را با ویژگی‌های تعریف شده در شیء client جایگزین می‌کند.

توجه داشته باشید که هر دوی این توابع از متدهای getActiveDocument() و getActiveTab() استفاده می‌کنند که فقط برای اسکریپت‌هایی که درون یک سند Google Docs ایجاد شده‌اند، اعمال می‌شوند؛ در یک اسکریپت مستقل، به جای آن از DocumentApp.create() ، openById() یا openByUrl() در ترکیب با Document.getTab() استفاده کنید.

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

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);
}

منوها و رابط‌های کاربری سفارشی

شما می‌توانید با اضافه کردن منوها، کادرهای محاوره‌ای و نوارهای کناری، Google Docs را سفارشی کنید. با این حال، به خاطر داشته باشید که یک اسکریپت فقط می‌تواند با رابط کاربری برای نمونه فعلی یک سند باز تعامل داشته باشد و تنها در صورتی که اسکریپت به سند متصل باشد.

نحوه اضافه کردن منوها و پنجره‌های محاوره‌ای سفارشی به Google Docs خود را ببینید. برای کسب اطلاعات بیشتر در مورد ایجاد رابط‌های کاربری سفارشی برای یک پنجره محاوره‌ای یا نوار کناری، به راهنمای سرویس HTML مراجعه کنید. اگر قصد دارید رابط کاربری سفارشی خود را به عنوان بخشی از یک افزونه منتشر کنید، برای هماهنگی با سبک و طرح‌بندی ویرایشگر Google Docs، راهنمای سبک را دنبال کنید.

افزونه‌های گوگل داکز

افزونه‌ها درون گوگل داکس اجرا می‌شوند و می‌توانند از فروشگاه افزونه‌های گوگل داکس نصب شوند. اگر اسکریپتی برای گوگل داکس توسعه داده‌اید و می‌خواهید آن را با جهان به اشتراک بگذارید، Apps Script به شما امکان می‌دهد اسکریپت خود را به عنوان یک افزونه منتشر کنید تا سایر کاربران بتوانند آن را از فروشگاه افزونه‌ها نصب کنند.

برای دیدن نحوه ایجاد افزونه برای Google Docs، به راهنمای سریع ساخت افزونه‌های Docs مراجعه کنید.

محرک‌ها

اسکریپت‌هایی که به یک سند گوگل (Google Doc) متصل هستند می‌توانند از یک تریگر ساده برای پاسخ به رویداد onOpen سند استفاده کنند، که هر زمان که کاربری که دسترسی ویرایش به سند دارد، آن را در سند گوگل باز کند، رخ می‌دهد.

برای تنظیم تریگر، کافیست تابعی به نام onOpen() بنویسید. برای مثالی از این تریگر، به منوی سفارشی در Google Workspace مراجعه کنید. اگرچه تریگر ساده برای اضافه کردن منوها مفید است، اما نمی‌تواند از هیچ سرویس اسکریپت برنامه‌ها که نیاز به مجوز دارد استفاده کند.