اصول اسکریپت برنامه‌ها با کاربرگ‌نگار شماره ۲ Google: صفحات گسترده، برگه‌ها و محدوده‌ها

اصول اسکریپت برنامه‌ها با کاربرگ‌نگار شماره ۲ Google:

صفحات گسترده، برگه‌ها و محدوده‌ها

درباره این codelab

آخرین به‌روزرسانی: آوریل ۴, ۲۰۲۲

نویسنده: Google Workspace Developer Relations

1. مقدمه

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

چیزی که یاد خواهید گرفت

• نحوه نمایش صفحات گسترده، صفحات و محدوده ها در Apps Script.
• نحوه دسترسی، ایجاد و تغییر نام صفحه گسترده فعال (باز) با کلاس SpreadsheetApp و Spreadsheet .
• نحوه تغییر نام برگه و جهت ستون/ردیف محدوده با استفاده از کلاس Sheet .
• نحوه تعیین، فعال کردن، جابجایی و مرتب‌سازی گروهی از سلول‌ها یا محدوده‌ای از داده‌ها با استفاده از کلاس Range .

قبل از اینکه شروع کنی

این دومین لبه کد در فهرست پخش Fundamentals of Apps Script with Google Sheets است. قبل از شروع، حتماً اولین لبه کد را تکمیل کنید: ماکروها و توابع سفارشی .

آنچه شما نیاز دارید

• درکی از موضوعات اساسی Apps Script که در کدهای قبلی این لیست پخش بررسی شده است.
• آشنایی اولیه با ویرایشگر Apps Script
• آشنایی اولیه با Google Sheets
• قابلیت خواندن Sheets A1 Notation
• آشنایی اولیه با جاوا اسکریپت و کلاس String آن

بخش بعدی کلاس های اصلی سرویس Spreadsheet را معرفی می کند.

2. معرفی سرویس صفحه گسترده

چهار کلاس اساس سرویس صفحه گسترده را در بر می گیرد: SpreadsheetApp ، Spreadsheet ، Sheet و Range . این بخش این کلاس‌ها و کاربرد آنها را توضیح می‌دهد.

کلاس SpreadsheetApp

قبل از جستجو در صفحات گسترده، صفحات و محدوده‌ها، باید کلاس والد آنها را مرور کنید: SpreadsheetApp . بسیاری از اسکریپت ها با فراخوانی روش های SpreadsheetApp شروع می شوند، زیرا می توانند نقطه اولیه دسترسی به فایل های Google Sheets شما را فراهم کنند. می توانید SpreadsheetApp را به عنوان کلاس اصلی سرویس Spreadsheet در نظر بگیرید. کلاس SpreadsheetApp در اینجا به طور عمیق کاوش نشده است. با این حال، بعداً در این Codelab می توانید هم مثال ها و هم تمرین هایی را بیابید که به شما در درک این کلاس کمک کند.

صفحات گسترده، برگه ها و کلاس های آنها

به عنوان یک اصطلاح Sheets، صفحه گسترده یک فایل Google Sheets (ذخیره شده در Google Drive) است که حاوی داده هایی است که بر اساس ردیف ها و ستون ها سازماندهی شده اند. یک صفحه‌گسترده گاهی اوقات به‌عنوان «Google Sheet» نامیده می‌شود، به همان شیوه‌ای که یک سند به عنوان «Google Doc» نامیده می‌شود.

می‌توانید از کلاس Spreadsheet برای دسترسی و اصلاح داده‌های فایل کاربرگ‌نگار Google استفاده کنید. همچنین می‌توانید از این کلاس برای سایر عملیات‌های سطح فایل مانند افزودن همکاران استفاده کنید.

یک برگه** نمایانگر صفحه مجزای یک صفحه گسترده است که گاهی اوقات به عنوان "برگه" نامیده می شود. هر صفحه گسترده می تواند شامل یک یا چند صفحه باشد. می توانید از Sheet استفاده کنید ** کلاس برای دسترسی و اصلاح داده‌ها و تنظیمات سطح برگ، مانند جابجایی ردیف‌ها یا ستون‌های داده.

نکته کلیدی : صفحات گسترده علاوه بر نام، یک رشته شناسه منحصر به فرد برای آن صفحه نیز دارند. شناسه در URL صفحه گسترده به شکل زیر موجود است:

https://docs.google.com/spreadsheets/d/ spreadsheetID /edit#gid=0

هر صفحه در یک صفحه گسترده همچنین دارای یک شماره شناسه منحصر به فرد برای آن صفحه گسترده است. این شماره شناسه تصادفی است، اما می‌توانید آن را در URL صفحه‌گسترده در قالب زیر نیز ببینید:

https://docs.google.com/spreadsheets/d/ spreadsheetID /edit#gid= sheetID

شما می توانید هر دو شناسه را در این URL مثال ببینید:

از آنجایی که شناسه‌های صفحه‌گسترده و برگه‌ها منحصربه‌فرد هستند (و نام‌های صفحه‌گسترده منحصربه‌فرد هستند)، بهتر است از شناسه‌ها برای تعیین صفحه‌گسترده‌ها و برگه‌ها در صورت امکان استفاده کنید. به عنوان مثال، می توانید چندین صفحه گسترده با یک نام در Google Drive خود داشته باشید. با استفاده از روش های اسکریپت مانند SpreadsheetApp.openById(id) برای باز کردن صفحات گسترده خود، می توانید از ویرایش تصادفی فایل اشتباه جلوگیری کنید.

با مراجعه به مقدمه Google Sheets درباره شناسه‌ها در Google Sheets بیشتر بیاموزید.

به طور خلاصه، کلاس Spreadsheet روی مجموعه برگه ها عمل می کند و یک فایل Google Sheets را در Google Drive تعریف می کند. کلاس Sheet بر روی صفحات جداگانه در یک صفحه گسترده عمل می کند.

کلاس Range

اکثر عملیات دستکاری داده ها (به عنوان مثال، خواندن، نوشتن، یا قالب بندی داده های سلولی) از شما نیاز دارند که مشخص کنید این عملیات روی چه سلول هایی اعمال می شود. می توانید از کلاس Range برای انتخاب مجموعه خاصی از سلول ها در یک صفحه استفاده کنید. نمونه‌های این کلاس یک محدوده را نشان می‌دهند - گروهی از یک یا چند سلول مجاور در یک صفحه. می توانید محدوده ها را با شماره ردیف و ستون آنها یا با استفاده از نماد A1 مشخص کنید.

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

بسیاری از متدهای کلاس، شیء فعال کلاس درخواستی را برمی گرداند. برای مثال، اجرای SpreadsheetApp.getActiveSpreadsheet() فعال یا فعلی کاربر را برمی گرداند. با دریافت صفحه گسترده فعال، می توانید عملیات را روی آن صفحه گسترده اعمال کنید. به طور مشابه، متدهایی مانند متد Sheet.activate() می توانند شی فعال را تغییر دهند.

فعال کردن یک صفحه، محدوده یا سلول معادل کلیک روی آن صفحه، محدوده یا سلول در رابط کاربرگ‌نگار Google است، بنابراین تمرکز مکان‌نما را به آن مکان منتقل می‌کند.

بقیه کدها نمونه هایی از اسکریپت هایی را نشان می دهد که با این کلاس ها کار می کنند و متدهای آنها.

3. برپایی

قبل از ادامه، به یک صفحه گسترده با مقداری داده نیاز دارید. ما یکی را برای شما فراهم کرده‌ایم: روی این پیوند کلیک کنید تا برگه داده را کپی کنید و سپس روی ایجاد یک کپی کلیک کنید.

یک کپی از صفحه گسترده نمونه برای استفاده در پوشه Google Drive شما قرار می گیرد و نام آن "کپی از صفحه گسترده بدون عنوان" است. از این صفحه گسترده برای تکمیل تمرینات این کد لبه استفاده کنید.

به عنوان یادآوری، می‌توانید ویرایشگر اسکریپت را از کاربرگ‌نگار Google با کلیک کردن بر روی برنامه‌های افزودنی > اسکریپت برنامه‌ها باز کنید.

وقتی برای اولین بار یک پروژه Apps Script را در ویرایشگر اسکریپت باز می کنید، ویرایشگر اسکریپت هم یک پروژه اسکریپت و هم یک فایل اسکریپت را برای شما ایجاد می کند.

بخش بعدی نحوه استفاده از کلاس Spreadsheet را برای بهبود این صفحه گسترده به شما نشان می دهد.

4. به صفحات گسترده دسترسی داشته باشید و آنها را اصلاح کنید

در این بخش می توانید نحوه استفاده از کلاس های SpreadsheetApp و Spreadsheet برای دسترسی و اصلاح صفحات گسترده را بیاموزید. به طور خاص، تمرین‌ها به شما یاد می‌دهند که چگونه یک صفحه‌گسترده را تغییر نام دهید و برگه‌ها را در یک صفحه‌گسترده کپی کنید.

اینها عملیات ساده هستند، اما اغلب بخشی از یک گردش کار بزرگتر و پیچیده تر هستند. هنگامی که بتوانید نحوه خودکارسازی این وظایف با کد اسکریپت را درک کنید، یادگیری نحوه خودکارسازی عملیات دقیق تر آسان تر خواهد بود.

صفحه گسترده فعال را تغییر نام دهید

فرض کنید می‌خواهید نام پیش‌فرض «کپی از صفحه‌گسترده بدون عنوان» را به عنوانی تغییر دهید که هدف صفحه‌گسترده شما را بهتر نشان دهد. می توانید این کار را با کلاس های SpreadsheetApp و Spreadsheet انجام دهید.

1. در ویرایشگر اسکریپت، بلوک کد پیش‌فرض myFunction() را با کد زیر جایگزین کنید:

function renameSpreadsheet() {
  var mySS = SpreadsheetApp.getActiveSpreadsheet();
  mySS.rename("2017 Avocado Prices in Portland, Seattle");
}

2. برای ذخیره اسکریپت خود، روی ذخیره کلیک کنید .
3. برای تغییر نام پروژه Apps Script خود، روی پروژه Untitled کلیک کنید، "Avocado Prices" را به عنوان نام پروژه جدید وارد کنید و روی تغییر نام کلیک کنید.
4. برای اجرای اسکریپت خود، renameSpreadsheet را از لیست توابع انتخاب کنید و روی Run کلیک کنید.
5. با دنبال کردن دستورالعمل‌های روی صفحه، ماکرو را مجاز کنید. اگر پیام «این برنامه تأیید نشده است» دریافت کردید، روی « پیشرفته » کلیک کنید، سپس روی «رفتن به قیمت‌های آووکادو» (ناامن) کلیک کنید. در صفحه بعدی، روی Allow کلیک کنید.

توجه: اگر از یک حساب gmail.com استفاده می‌کنید، ممکن است در اولین استفاده از اسکریپت خود یک گفتگوی برنامه تأیید نشده دریافت کنید. Google از این برای هشدار به کاربرانی که ممکن است از کدهای نویسندگان ناشناس یا نامعتبر استفاده می کنند، استفاده می کند. اگر این گفتگو را مشاهده کردید، مشکلی نیست که ادامه دهید زیرا شما نویسنده اسکریپت هستید. برای ادامه دادن مجوز به اسکریپت، فرمان های روی صفحه را دنبال کنید.

پس از اجرای تابع، نام فایل صفحه گسترده شما باید تغییر کند:

بیایید به کدی که وارد کردید نگاه کنیم. متد getActiveSpreadsheet() یک شی را برمی گرداند که صفحه گسترده فعال را نشان می دهد. یعنی کپی صفحه گسترده تمرینی که ساخته اید. این شی صفحه گسترده در متغیر mySS ذخیره می شود. با فراخوانی rename(newName) در mySS ، نام فایل صفحه‌گسترده در Google Drive به «قیمت‌های آووکادو 2017 در پورتلند، سیاتل» تغییر می‌کند.

از آنجایی که متغیر mySS مرجعی به صفحه گسترده است، می‌توانید کد خود را با فراخوانی متدهای Spreadsheet در mySS به جای فراخوانی مکرر getActiveSpreadsheet() پاک‌تر و کارآمدتر کنید.

برگه فعال را کپی کنید

در صفحه گسترده فعلی خود، فقط یک صفحه دارید. می‌توانید متد Spreadsheet.duplicateActiveSheet() را فراخوانی کنید تا یک کپی از برگه ایجاد کنید:

1. تابع جدید زیر را در زیر تابع renameSpreadsheet() در پروژه اسکریپت خود اضافه کنید:

function duplicateAndOrganizeActiveSheet() {
  var mySS = SpreadsheetApp.getActiveSpreadsheet();
  var duplicateSheet = mySS.duplicateActiveSheet();
}

2. پروژه اسکریپت خود را ذخیره کنید
3. برای اجرای اسکریپت خود، duplicateAndOrganizeActiveSheet را از لیست توابع انتخاب کنید و روی Run کلیک کنید.

به برگه‌ها بازگردید تا ببینید برگه برگه «کپی از Sheet_Original» جدید به صفحه‌گسترده شما اضافه شده است.

در این تابع جدید، متد duplicateActiveSheet() duplicateActiveSheet صفحه تکراری را در صفحه گسترده شما ایجاد، فعال و برمی گرداند. این برگه در duplicateSheet ذخیره می‌شود، اما کد هنوز با آن متغیر کاری انجام نمی‌دهد.

در بخش بعدی، از کلاس Sheet برای تغییر نام و قالب بندی برگه تکراری استفاده می کنید.

5. برگه خود را با کلاس Sheet قالب بندی کنید

کلاس Sheet متدهایی را ارائه می دهد که به اسکریپت ها اجازه می دهد برگه ها را بخوانند و به روز کنند. در این بخش می توانید نحوه تغییر نام برگه و عرض ستون را با متدهایی از کلاس Sheet یاد بگیرید.

توجه **: Spreadsheet ** و کلاس‌های Sheet چندین روش متداول مخصوص برگه را به اشتراک می‌گذارند، مانند Spreadsheet.deleteColumn(columnPosition) و Sheet.deleteColumn(columnPosition) .

هنگامی که Spreadsheet.deleteColumn(columnPosition) را فراخوانی می کنید، این روش ستون ها را از صفحه فعال (باز) موجود در صفحه گسترده حذف می کند. می‌توانید با فراخوانی getActiveSheet() و سپس Sheet.deleteColumn(columnPosition) همان نتیجه را دریافت کنید. نسخه Spreadsheet به سادگی در زمان شما صرفه جویی می کند.

نام برگه را تغییر دهید

تغییر نام برگه ها به همان سادگی است که تغییر نام صفحه گسترده در renameSpreadsheet() بود. فقط یک فراخوانی روش مورد نیاز است.

1. در Google Sheets، روی صفحه Sheet_Original کلیک کنید تا فعال شود.
2. در Apps Script، تابع duplicateAndOrganizeActiveSheet() خود را برای مطابقت با موارد زیر تغییر دهید:

function duplicateAndOrganizeActiveSheet() {
  var mySS = SpreadsheetApp.getActiveSpreadsheet();
  var duplicateSheet = mySS.duplicateActiveSheet();

  // Change the name of the new sheet.
  duplicateSheet.setName("Sheet_" + duplicateSheet.getSheetId());
}

3. تابع را ذخیره و اجرا کنید.

در Google Sheets، یک برگه تکراری ایجاد شده و با اجرای تابع تغییر نام می‌دهد:

در کد اضافه شده، setName(name) نام duplicateSheet را تغییر می‌دهد و با استفاده از getSheetID() شماره شناسه منحصربه‌فرد برگه را دریافت می‌کند. عملگر + شناسه برگه را به انتهای رشته "Sheet_" می کند.

ستون ها و ردیف های یک برگه را تغییر دهید

همچنین می توانید از کلاس Sheet برای قالب بندی برگه خود استفاده کنید. برای مثال، می‌توانیم تابع duplicateAndOrganizeActiveSheet() شما را به‌روزرسانی کنیم تا اندازه ستون‌های صفحه تکراری را نیز تغییر دهیم و ردیف‌های ثابت اضافه کنیم:

1. در Google Sheets، روی صفحه Sheet_Original کلیک کنید تا فعال شود.
2. در Apps Script، تابع duplicateAndOrganizeActiveSheet() خود را برای مطابقت با موارد زیر تغییر دهید:

function duplicateAndOrganizeActiveSheet() {
  var mySS = SpreadsheetApp.getActiveSpreadsheet();
  var duplicateSheet = mySS.duplicateActiveSheet();

  // Change the name of the new sheet.
  duplicateSheet.setName("Sheet_" + duplicateSheet.getSheetId());

  // Format the new sheet.
  duplicateSheet.autoResizeColumns(1, 5);
  duplicateSheet.setFrozenRows(2);
}

3. تابع را ذخیره و اجرا کنید.

در Google Sheets، یک برگه تکراری ایجاد، تغییر نام، فعال و قالب‌بندی می‌شود:

کدی که اضافه کردید از autoResizeColumns(startColumn, numColumns) برای تغییر اندازه ستون‌های صفحه برای خوانایی استفاده می‌کند. setFrozenRows(rows) تعداد ردیف‌های داده شده (در این مورد دو تا) را ثابت می‌کند که ردیف‌های سرصفحه را در حین حرکت خواننده به پایین صفحه‌گسترده قابل مشاهده نگه می‌دارد.

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

هنگام استفاده از روش‌های مربوط به ستون‌ها و ردیف‌ها مانند autoResizeColumns(startColumn, numColumns) به این نکته توجه داشته باشید. در تمرین فعلی ما، 1 (نه 0) را به عنوان پارامتر به ستون A مرجع duplicateSheet وارد می‌کنید.

در بخش بعدی، با محدوده ها و دستکاری اولیه داده ها آشنا خواهید شد.

6. مرتب سازی مجدد داده ها با کلاس Range

کلاس Range و روش های آن بیشتر گزینه های دستکاری و قالب بندی داده ها را در سرویس صفحه گسترده ارائه می کنند.

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

حرکت محدوده ها

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

بیایید متد duplicateAndOrganizeActiveSheet() شما را به‌روزرسانی کنیم تا برخی از داده‌ها را نیز جابه‌جا کنیم:

1. در Google Sheets، روی صفحه Sheet_Original کلیک کنید تا فعال شود.
2. در Apps Script، تابع duplicateAndOrganizeActiveSheet() خود را برای مطابقت با موارد زیر تغییر دهید:

function duplicateAndOrganizeActiveSheet() {
  var mySS = SpreadsheetApp.getActiveSpreadsheet();
  var duplicateSheet = mySS.duplicateActiveSheet();

  // Change the name of the new sheet.
  duplicateSheet.setName("Sheet_" + duplicateSheet.getSheetId());

  // Format the new sheet.
  duplicateSheet.autoResizeColumns(1, 5);
  duplicateSheet.setFrozenRows(2);

  // Move column F to column C.
  var myRange = duplicateSheet.getRange("F2:F");
  myRange.moveTo(duplicateSheet.getRange("C2"));
}

3. تابع را ذخیره و اجرا کنید.

هنگامی که این تابع را اجرا می کنید، یک برگه تکراری ایجاد، فعال و فرمت می شود. و محتویات ستون F به ستون C منتقل می شود:

کد جدید از روش getRange(a1Notation) برای شناسایی محدوده داده ای که باید جابجا شود استفاده می کند. با وارد کردن نماد A1 "F2:F" به عنوان پارامتر روش، ستون F را مشخص می کنید (به استثنای F1). اگر محدوده مشخص شده وجود داشته باشد، getRange(a1Notation) نمونه Range خود را برمی گرداند. کد برای سهولت استفاده، نمونه را در متغیر myRange می کند.

پس از شناسایی محدوده، moveTo(target) محتویات myRange (هم مقادیر و هم قالب بندی) را می گیرد و آنها را جابجا می کند. مقصد (ستون C) با استفاده از علامت A1 "C2" مشخص می شود. این یک سلول است نه یک ستون. هنگام انتقال داده ها، نیازی نیست اندازه ها را با محدوده هدف و مقصد مطابقت دهید. Apps Script به سادگی اولین سلول هر کدام را تراز می کند.

توجه: هنگامی که اسکریپت های خود را می نویسید، حتما آنها را به طور کامل آزمایش کنید تا مطمئن شوید که داده های شما به جایی می رسد که در نظر داشتید. Apps Script مقادیر داده های موجود را هنگام تغییر مقادیر سلول بازنویسی می کند. اگر مراقب نباشید، می‌توانید داده‌هایی را که می‌خواهید حفظ کنید، بازنویسی کنید. در این مثال، ستون C خالی بود، اما اگر داده‌ای وجود داشت، moveTo(target) آن را حذف می‌کرد.

مرتب سازی محدوده ها

کلاس Range به شما اجازه می دهد تا گروه هایی از سلول ها را بخوانید، به روز کنید و سازماندهی کنید. به عنوان مثال، می توانید با استفاده از روش Range.sort(sortSpecObj) یک محدوده داده را مرتب کنید:

1. در Google Sheets، روی صفحه Sheet_Original کلیک کنید تا فعال شود.
2. در Apps Script، تابع duplicateAndOrganizeActiveSheet() خود را برای مطابقت با موارد زیر تغییر دهید:

function duplicateAndOrganizeActiveSheet() {
  var mySS = SpreadsheetApp.getActiveSpreadsheet();
  var duplicateSheet = mySS.duplicateActiveSheet();

  // Change the name of the new sheet.
  duplicateSheet.setName("Sheet_" + duplicateSheet.getSheetId());

  // Format the new sheet.
  duplicateSheet.autoResizeColumns(1, 5);
  duplicateSheet.setFrozenRows(2);

  // Move column F to column C.
  var myRange = duplicateSheet.getRange("F2:F");
  myRange.moveTo(duplicateSheet.getRange("C2"));

  // Sort all the data using column C (Price information).
  myRange = duplicateSheet.getRange("A3:D55");
  myRange.sort(3);
}

3. تابع را ذخیره و اجرا کنید.

اکنون تابع، علاوه بر قالب بندی قبلی، تمام داده های جدول را با استفاده از اطلاعات قیمت در ستون C مرتب می کند:

کد جدید از getRange(a1Notation) برای تعیین محدوده جدیدی که A3:D55 را پوشش می دهد (کل جدول به استثنای سرفصل های ستون) استفاده می کند. سپس کد متد sort(sortSpecObj) را برای مرتب‌سازی جدول فراخوانی می‌کند. در اینجا، پارامتر sortSpecObj شماره ستونی است که باید بر اساس آن مرتب شود. این روش محدوده را مرتب می کند تا مقادیر ستون نشان داده شده از پایین ترین به بالاترین (مقادیر صعودی) بروند. روش sort(sortSpecObj) می‌تواند الزامات مرتب‌سازی پیچیده‌تری را انجام دهد، اما در اینجا به آنها نیاز ندارید. می‌توانید تمام روش‌های مختلف فراخوانی محدوده‌های مرتب‌سازی را در مستندات مرجع روش مشاهده کنید.

تبریک می‌گوییم، شما تمام تمرین‌های موجود در Codelab را با موفقیت به پایان رساندید. بخش بعدی به بررسی نکات کلیدی این کد لبه و پیش نمایش کدهای بعدی در این لیست پخش می پردازد.

7. نتیجه

شما به پایان این آزمایشگاه کد رسیده اید. اکنون می توانید از کلاس ها و شرایط ضروری سرویس Spreadsheet در Apps Script استفاده و تعریف کنید.

برای رفتن به کدهای بعدی آماده هستید.

آیا این کد لبه را مفید یافتید؟

آره خیر

آنچه را پوشش داده ایم

• نحوه نمایش صفحات گسترده، صفحات و محدوده ها در Apps Script.
• برخی از کاربردهای اساسی کلاس های SpreadsheetApp ، Spreadsheet ، Sheet و Range .

مفاهیم کلیدی :

1. در Apps Script، همه آرایه‌ها از این قرارداد پیروی می‌کنند که فهرست با شاخص 0 شروع می‌شود. با این حال، سطرها و ستون‌ها از 1 ایندکس می‌شوند.
2. در Apps Script، صفحه باز، سلول، محدوده برجسته شده در حال حاضر فعال در نظر گرفته می شود. بسیاری از روش‌های Apps Script به عنصر فعال دسترسی دارند یا آن را تغییر می‌دهند.
3. کلاس های Spreadsheet و Sheet چندین روش مخصوص برگه را به اشتراک می گذارند. متدهای تکراری در کلاس Spreadsheet فقط برای راحتی کاربر هستند زیرا معمولاً هنگام فراخوانی صفحه فعال را هدف قرار می دهند.
4. هر صفحه گسترده و صفحه یک شناسه منحصر به فرد دارد که می توانید آن را در URL مرورگر بیابید. متدهای صفحه گسترده و کلاس شیت از شناسه ها استفاده می کنند. می‌توانید در معرفی کاربرگ‌نگار Google درباره شناسه‌ها و نشانی‌های وب اطلاعات بیشتری کسب کنید.

شرایط کلیدی :

• فعال (وضعیت) : نشان می‌دهد صفحه‌گسترده، صفحه، محدوده، یا سلولی که کاربر صفحه‌گسترده در حال حاضر در حال مشاهده یا برجسته کردن آن است.
• سلول فعال: تنها سلول برجسته شده در صفحه فعال با فوکوس مکان نما.
• محدوده فعال : گروهی از یک یا چند سلول که در حال حاضر در صفحه فعال برجسته شده است.
• مجوز : فرآیندی که کاربر اجازه می دهد تا به Apps Script اجازه دهد به داده های کاربر در سرویس های مربوطه Google دسترسی داشته باشد یا اقدامات دیگری از طرف کاربر انجام دهد.
• اسکریپت محدود به کانتینر : هر اسکریپتی که به یک سند Google Workspace متصل شده و از آن ایجاد می‌شود، مانند Google Sheet یا Google Doc.
• محدوده:** گروهی از یک یا چند سلول مجاور در یک صفحه. محدوده Range class به شما امکان خواندن و به روز رسانی محدوده ها را در یک برگه می دهد.
• ویرایشگر اسکریپت : ویرایشگر کد درون مرورگر برای Apps Script.
• Sheet**: یک صفحه از یک صفحه گسترده (شبیه به کتابهای کاری Microsoft Excel). گاهی اوقات برای ارجاع به فایل Google Sheets در Google Drive استفاده می شود. ورق Sheet class به شما امکان می دهد به برگه ها دسترسی داشته باشید و آنها را تغییر دهید.
• SpreadsheetApp : این کلاس به عنوان کلاس والد برای سرویس Spreadsheet عمل می کند و نقطه شروعی برای کدهایی است که داده های Google Sheets را می خواند یا دستکاری می کند.
• صفحه گسترده**: یک فایل Google Sheets که در Google Drive قرار دارد. صفحه Spreadsheet ** class به شما امکان می دهد به صفحات گسترده دسترسی داشته باشید و آنها را تغییر دهید.
• سرویس صفحه‌گسترده : یک سرویس Apps Script که به اسکریپت‌ها اجازه ایجاد، دسترسی و اصلاح فایل‌های Google Sheets را می‌دهد.

بعدش چیه

کد بعدی در این لیست پخش به نحوه خواندن، نوشتن و اصلاح داده ها در یک صفحه گسترده می پردازد.

آزمایشگاه کد بعدی را در Working with data پیدا کنید.