اسکریپت Google Apps به شما امکان میدهد اسناد را به صورت برنامهنویسی ایجاد و تغییر دهید، و همچنین رابط کاربری را با منوها، کادرهای محاورهای و نوارهای کناری جدید سفارشی کنید.
اصول اولیه
اسکریپت برنامهها میتواند به دو روش کلی با Docs تعامل داشته باشد: هر اسکریپتی میتواند یک سند را ایجاد یا تغییر دهد، در صورتی که کاربر اسکریپت مجوزهای لازم برای سند را داشته باشد، و یک اسکریپت همچنین میتواند به یک سند متصل شود، که به اسکریپت قابلیتهای ویژهای برای تغییر رابط کاربری یا پاسخ دادن هنگام باز شدن سند میدهد. برای ایجاد یک اسکریپت متصل به کانتینر از درون Docs، روی Extensions > Apps Script کلیک کنید.
در هر صورت، میتوانید با استفاده از سرویس سند Apps Script با یک سند Docs تعامل داشته باشید، همانطور که مثال زیر نشان میدهد.
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، یک سند Docs ساختار بسیار شبیه به یک سند HTML دارد - یعنی یک سند از یک یا چند شیء Tab تشکیل شده است که هر کدام شامل عناصری (مانند یک Paragraph یا Table ) هستند که اغلب شامل عناصر دیگری نیز میشوند. اکثر اسکریپتهایی که یک سند Docs را تغییر میدهند، با فراخوانی getTab و asDocumentTab و به دنبال آن getBody شروع میشوند، زیرا Body یک عنصر اصلی است که شامل تمام عناصر دیگر در یک tab به جز HeaderSection ، FooterSection و هرگونه Footnotes میشود.
با این حال، قوانینی در مورد اینکه کدام نوع عناصر میتوانند شامل انواع دیگر باشند، وجود دارد. علاوه بر این، سرویس سند در Apps Script فقط میتواند انواع خاصی از عناصر را در عناصر دیگر وارد کند. درخت زیر نشان میدهد که کدام عناصر میتوانند توسط یک نوع خاص از عنصر در بر گرفته شوند.
عناصری که با حروف پررنگ نشان داده شدهاند را میتوان وارد کرد؛ عناصر غیر پررنگ را فقط میتوان در جای خود دستکاری کرد.
- ردیف جدول
- سلول جدولی
- پاراگراف ...
- مورد لیست ...
- میز ...
متن را جایگزین کنید
اسکریپت Apps اغلب برای جایگزینی متن در Docs استفاده میشود. فرض کنید یک صفحه گسترده پر از اطلاعات مشتری دارید و میخواهید برای هر مشتری یک Docs شخصیسازیشده ایجاد کنید. (این نوع عملیات اغلب ادغام پستی نامیده میشود.)
شما میتوانید متن را با استفاده از متد replaceText جایگزین کنید، که از اکثر ویژگیهای عبارات منظم جاوا اسکریپت پشتیبانی میکند. در مثال زیر، تابع اول متن جایگزین را به سند اضافه میکند و تابع دوم آن متن را با ویژگیهایی از یک شیء client جایگزین میکند.
هر دوی این توابع از متدهای getActiveDocument و getActiveTab استفاده میکنند که فقط برای اسکریپتهایی که درون یک سند 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);
}
منوها و رابطهای کاربری سفارشی
شما میتوانید با اضافه کردن منوها، کادرهای محاورهای و نوارهای کناری سفارشی ، Docs را سفارشی کنید. به خاطر داشته باشید که یک اسکریپت فقط میتواند با رابط کاربری سندی که به آن متصل است، تعامل داشته باشد.
برای کسب اطلاعات بیشتر در مورد ایجاد رابطهای سفارشی با HTML و CSS، به راهنمای سرویس HTML مراجعه کنید. اگر قصد دارید رابط خود را به عنوان یک افزونه منتشر کنید، از راهنمای سبک پیروی کنید تا مطمئن شوید که ظاهر آن با ویرایشگر Docs سازگار است.
افزونههای اسناد
افزونهها درون Docs اجرا میشوند و میتوانند از فروشگاه افزونههای Docs نصب شوند. اگر اسکریپتی برای Docs توسعه دادهاید و میخواهید آن را با جهان به اشتراک بگذارید، Apps Script به شما امکان میدهد اسکریپت خود را به عنوان یک افزونه منتشر کنید تا سایر کاربران بتوانند آن را از فروشگاه افزونهها نصب کنند.
برای ایجاد افزونه برای Docs، به راهنمای سریع ساخت افزونههای Docs مراجعه کنید.
محرکها
اسکریپتهایی که به یک سند گوگل (Google Doc) متصل هستند میتوانند از یک تریگر ساده برای پاسخ به رویداد onOpen سند استفاده کنند، که هر زمان که کاربری که دسترسی ویرایش به سند دارد، آن را در Docs باز کند، رخ میدهد.
برای تنظیم تریگر، تابعی به نام onOpen بنویسید. برای مثالی از این تریگر، به منوی سفارشی در Google Workspace مراجعه کنید. اگرچه تریگر برای اضافه کردن منوها مفید است، اما نمیتواند از هیچ سرویس اسکریپت برنامهها که نیاز به مجوز دارد استفاده کند.