گسترش Google Docs

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

اصول اولیه

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

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

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

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

ساختار یک سند

از دیدگاه Apps Script، یک Google Doc بسیار شبیه به یک سند HTML ساختار یافته است - یعنی یک Google Doc از عناصری (مانند یک Paragraph یا Table ) تشکیل شده است که اغلب حاوی عناصر دیگری است. اکثر اسکریپت هایی که Google Doc را تغییر می دهند با فراخوانی getBody() شروع می شوند، زیرا Body یک عنصر اصلی است که شامل تمام عناصر دیگر به جز HeaderSection ، FooterSection و هر Footnotes است.

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

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

• سند
• بدن
• List Item
• معادله
• EquationFunction
• تابع معادله ...
• EquationFunctionArgumentSeparator
• نماد معادله
• متن

جایگزین کردن متن

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

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

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

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

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

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

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

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

افزونه‌ها برای Google Docs

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

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

محرک ها

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

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