مستندات در رابط کاربری گوگل شیت و حاشیهنویسیهای سطح اسکریپت.
اسکریپت برنامههای گوگل از JSDoc برای تولید مستندات و تکمیل خودکار اسکریپتهای شما استفاده میکند. JSDoc استانداردی برای مستندسازی کد جاوا اسکریپت با استفاده از کامنتها است.
در Apps Script، JSDoc این اهداف اصلی را دنبال میکند:
- تکمیل خودکار در ویرایشگر : ارائه نکات مربوط به پارامترها و توضیحات تابع هنگام تایپ.
- توابع سفارشی در گوگل شیت : مستندسازی توابع سفارشی شما به گونهای که در فرمولیاب گوگل شیت نمایش داده شوند.
- حاشیهنویسیهای سطح اسکریپت : استفاده از تگهای ویژه برای کنترل رفتار در سطح اسکریپت، مانند مجوزدهی.
توابع سند
برای مستندسازی یک تابع، یک بلوک توضیح JSDoc را مستقیماً بالای اعلان تابع قرار دهید. یک توضیح JSDoc با /** شروع میشود و با */ پایان مییابد.
/**
* Multiplies an input value by 2.
*
* @param {number} input The value to multiply.
* @return {number} The input multiplied by 2.
*/
function double(input) {
return input * 2;
}
وقتی یک تابع را به این روش مستند میکنید، ویرایشگر Apps Script هنگام ارجاع به تابع، یک راهنمای ابزار مستندسازی نشان میدهد. برای مثال، وقتی در ویرایشگر double( را تایپ میکنید، موارد زیر را میبینید:
دو برابر (ورودی)
مقدار ورودی را در ۲ ضرب میکند.
ورودی : عدد — مقداری که قرار است در هم ضرب شود.
برچسبهای رایج
| برچسب | توضیحات |
|---|---|
@param {type} name description | یک پارامتر تابع را مستند میکند. {type} و description توسط محیط توسعه برای تکمیل خودکار استفاده میشوند. |
@return {type} description | مقدار برگشتی تابع را مستند میکند. |
@example | مثالی از نحوه استفاده از تابع ارائه میدهد. |
اضافه بارها و انواع مختلف آنها
اگرچه جاوا اسکریپت از سربارگذاری کلاسیک توابع (تعریف چندین تابع با نام یکسان) پشتیبانی نمیکند، اما میتوانید یک تابع واحد بنویسید که انواع مختلف ورودی را مدیریت کند. میتوانید این رفتارهای «سربارگذاریشده» را در JSDoc مستند کنید.
انواع اتحادیه
اگر یک پارامتر یا مقدار برگشتی میتواند یکی از چندین نوع باشد، از یک پایپ ( | ) برای ایجاد یک نوع یونیون استفاده کنید. این کار در Apps Script برای توابعی که میتوانند یک مقدار واحد یا طیفی از مقادیر (که به صورت یک آرایه دوبعدی نمایش داده میشوند) را بپذیرند، رایج است.
/**
* Multiplies an input value (or a range of values) by 2.
*
* @param {number|number[][]} input The value or 2D array to multiply.
* @return {number|number[][]} The result.
*/
function double(input) {
return Array.isArray(input) ?
input.map(row => row.map(cell => cell * 2)) :
input * 2;
}
چندین امضا با @overload
برای توابعی با امضاهای پیچیده که پارامترهای مجاز آنها به یکدیگر وابسته هستند، میتوانید از تگ @overload برای تعریف هر امضا مجزا استفاده کنید. ویرایشگر Apps Script از این موارد برای ارائه نکات خاص بر اساس نسخهای از تابع که فراخوانی میکنید، استفاده میکند.
/**
* @overload
* @param {string} name The name of the property to get.
* @return {string} The property value.
*/
/**
* @overload
* @param {number} index The index of the item to get.
* @return {object} The item object.
*/
function get(arg) {
// Implementation that handles both cases
}
توابع سفارشی در گوگل شیت
وقتی یک تابع سفارشی برای گوگل شیت مینویسید، باید از تگ @customfunction برای نمایش آن در تکمیل خودکار و کمککننده فرمول صفحه گسترده استفاده کنید.
JSDoc منبع متن کمکی است که کاربران هنگام استفاده از تابع سفارشی شما در Google Sheets میبینند. بدون JSDoc، کاربران فقط نام تابع را میبینند و فهمیدن اینکه تابع چه کاری انجام میدهد یا به چه پارامترهایی نیاز دارد، دشوار میشود.
برچسبهای پشتیبانیشده و محدودیتهای رابط کاربری
در حالی که Apps Script اکثر تگهای استاندارد JSDoc را تجزیه میکند، رابط کاربری Google Sheets برای توابع سفارشی دارای رفتارها و محدودیتهای خاصی است:
-
@customfunction: برای نمایش تابع در لیست فرمولهای Sheets مورد نیاز است. -
@param: نام و توضیحات در تابع کمکی فرمول Sheets نمایش داده میشوند. -
@return: توضیحات ارائه شده در تگ@returnدر تابع کمکی فرمول Sheets نمایش داده نمیشود . - پارامترهای اختیاری : سینتکس استاندارد JSDoc برای پارامترهای اختیاری (مثلاً
[name]یاname=) توسط رابط کاربری Sheets شناخته نمیشود. همه پارامترها طبق الزامات در تابع کمکی فرمول ظاهر میشوند. - مقادیر پیشفرض : مقادیر پیشفرض پارامترها (مثلاً
[name=Value]) در رابط کاربری Sheets پشتیبانی نمیشوند. - قالببندی : تگهای HTML و متن ساده برای ایجاد خط جدید در توضیحات شما پشتیبانی نمیشوند. رابط کاربری Sheets توضیحات را به صورت یک بلوک متنی واحد نمایش میدهد و بیشتر HTML را حذف میکند.
مثال برای گوگل شیت
/**
* Calculates a discount.
*
* @param {number} price The original price.
* @param {number} percent The discount percentage (e.g., 0.1 for 10%).
* @return {number} The price after discount.
* @customfunction
*/
function calculateDiscount(price, percent) {
return price * (1 - percent);
}
آنچه کاربران در Google Sheets میبینند
وقتی کاربر عبارت =CALCULATEDISCOUNT( در یک سلول تایپ میکند، گوگل شیت کادر کمکی زیر را نمایش میدهد:
تخفیف محاسبهشده
تخفیف محاسبه میکند.
قیمت : قیمت اصلی.
درصد : درصد تخفیف (مثلاً 0.1 برای 10٪).
توجه داشته باشید که توضیحات مربوط به پارامترها مستقیماً از تگهای JSDoc @param شما میآیند.
حاشیهنویسیهای سطح اسکریپت
Apps Script از تگهای منحصر به فرد JSDoc برای کنترل تنظیمات اسکریپت استفاده میکند. این تگها معمولاً در بالای فایل اسکریپت قرار میگیرند.
برچسبهای مجوز
| برچسب | توضیحات |
|---|---|
@OnlyCurrentDoc | به Apps Script میگوید که فقط برای سند فعلی درخواست مجوز کند، نه برای همه فایلهای از آن نوع. برای جزئیات بیشتر به [راهنمای مجوز](/apps-script/guides/services/authorization) مراجعه کنید. |
@NotOnlyCurrentDoc | در کتابخانهها برای لغو حاشیهنویسی ارثبریشدهی @OnlyCurrentDoc استفاده میشود. |