Google Apps Script به شما این امکان را می دهد که به صورت برنامه نویسی Google Docs را ایجاد و تغییر دهید، و همچنین رابط کاربری را با منوها، کادرهای گفتگو و نوارهای جانبی جدید سفارشی کنید.
اصول اولیه
Apps Script می تواند به دو روش کلی با 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);
} اسکریپت بالا یک سند جدید در Google Drive کاربر ایجاد می کند، سپس برگه را با شناسه t.0 بازیابی می کند (برگه اول پیش فرض)، یک پاراگراف را وارد می کند که حاوی متنی مشابه با نام سند است، سبک آن پاراگراف را به عنوان عنوان، و جدولی را بر اساس مقادیر موجود در یک آرایه دو بعدی اضافه می کند. این اسکریپت می تواند به همین راحتی این تغییرات را در یک سند موجود با جایگزین کردن فراخوانی DocumentApp.create() با DocumentApp.openById() یا openByUrl() انجام دهد. برای اسکریپت‌های ایجاد شده در داخل یک سند (محدود به کانتینر)، از DocumentApp.getActiveDocument() و Document.getActiveTab() استفاده کنید.
ساختار یک سند
از دیدگاه Apps Script، یک سند Google Docs بسیار شبیه به یک سند HTML ساختار یافته است - یعنی یک سند از یک یا چند شی Tab تشکیل شده است، که هر کدام شامل عناصری (مانند یک Paragraph یا Table ) است که اغلب حاوی عناصر دیگری است. اکثر اسکریپت هایی که سند Google Docs را تغییر می دهند با فراخوانی به getTab() و asDocumentTab() و سپس getBody() شروع می شوند، زیرا Body یک عنصر اصلی است که شامل تمام عناصر دیگر در یک برگه به جز HeaderSection ، FooterSection و هر کدام است. Footnotes .
با این حال، قوانینی در مورد اینکه کدام نوع از عناصر می توانند شامل انواع دیگری باشند وجود دارد. علاوه بر این، Document Service در Apps Script فقط می تواند انواع خاصی از عناصر را در عناصر دیگر وارد کند. درخت زیر نشان می دهد که کدام عناصر را می توان توسط یک نوع خاص از عنصر در بر داشت.
عناصر نشان داده شده به صورت پررنگ را می توان درج کرد. عناصر غیر پررنگ فقط در جای خود قابل دستکاری هستند.
- سند
- Tab
- DocumentTab
- بدن
- List Item
- معادله
- EquationFunction
- تابع معادله ...
- EquationFunctionArgumentSeparator
- نماد معادله
- متن
جایگزین کردن متن
Apps Script اغلب برای جایگزینی متن در Google Docs استفاده می شود. فرض کنید صفحه گسترده ای پر از اطلاعات مشتری دارید و می خواهید برای هر مشتری یک Google Docs شخصی سازی کنید. (این نوع عملیات اغلب ادغام نامه نامیده می شود.)
روش‌های زیادی برای جایگزینی متن وجود دارد، اما ساده‌ترین روش، متد replaceText() است که در مثال زیر نشان داده شده است. replaceText از اکثر ویژگی های عبارت معمولی جاوا اسکریپت پشتیبانی می کند. اولین تابع زیر چندین خط متن مکان‌دار را به Google Docs اضافه می‌کند. در دنیای واقعی، احتمال بیشتری وجود دارد که متغیرهایی را خودتان در سند تایپ کنید. تابع دوم مکان‌ها را با ویژگی‌های تعریف شده در شی 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 را با افزودن منوها، کادرهای محاوره‌ای و نوارهای کناری سفارشی کنید. با این حال، به خاطر داشته باشید که یک اسکریپت فقط می تواند با 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 که نیاز به مجوز دارند استفاده کند.