JSDoc trong Apps Script

tài liệu trong giao diện người dùng của Google Trang tính và chú giải ở cấp tập lệnh.

Google Apps Script sử dụng JSDoc để tạo tài liệu và tính năng tự động hoàn thành cho các tập lệnh của bạn. JSDoc là một tiêu chuẩn để ghi lại mã JavaScript bằng cách sử dụng chú thích.

Trong Apps Script, JSDoc có những mục đích chính sau:

Tự động hoàn thành trong trình chỉnh sửa: Cung cấp gợi ý về tham số và nội dung mô tả hàm khi bạn nhập.
Hàm tuỳ chỉnh trong Google Trang tính: Ghi lại hàm tuỳ chỉnh để hàm đó xuất hiện trong trình trợ giúp công thức của Trang tính.
Chú thích ở cấp tập lệnh: Sử dụng các thẻ đặc biệt để kiểm soát hành vi trên toàn tập lệnh, chẳng hạn như uỷ quyền.

Các hàm liên quan đến chứng từ

Để ghi lại một hàm, hãy đặt một khối nhận xét JSDoc ngay phía trên khai báo hàm. Một nhận xét JSDoc bắt đầu bằng /** và kết thúc bằng */.

/**
 * 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;
}

Khi bạn ghi lại một hàm theo cách này, trình chỉnh sửa Apps Script sẽ hiện một chú thích tài liệu khi bạn tham chiếu đến hàm đó. Ví dụ: khi bạn nhập double( trong trình chỉnh sửa, bạn sẽ thấy:

double(input)

Nhân giá trị đầu vào với 2.

đầu_vào: số – Giá trị cần nhân.

Thẻ phổ biến

Thẻ	Mô tả
`@param {type} name description`	Tài liệu hoá một tham số hàm. `{type}` và `description` được môi trường phát triển dùng cho tính năng tự động hoàn thành.
`@return {type} description`	Tài liệu hoá giá trị trả về của hàm.
`@example`	Cung cấp ví dụ về cách sử dụng hàm.

Quá tải và nhiều loại

Mặc dù JavaScript không hỗ trợ việc nạp chồng hàm cổ điển (xác định nhiều hàm có cùng tên), nhưng bạn có thể viết một hàm duy nhất xử lý nhiều loại dữ liệu đầu vào. Bạn có thể ghi lại những hành vi "quá tải" này trong JSDoc.

Loại hợp nhất

Nếu một tham số hoặc giá trị trả về có thể là một trong nhiều loại, hãy sử dụng dấu gạch dọc (|) để tạo một loại hợp nhất. Điều này thường xảy ra trong Apps Script đối với các hàm có thể chấp nhận một giá trị duy nhất hoặc một dải giá trị (được biểu thị dưới dạng một mảng 2 chiều).

/**
 * 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;
}

Nhiều chữ ký bằng `@overload`

Đối với các hàm có chữ ký phức tạp mà các tham số được phép phụ thuộc vào nhau, bạn có thể dùng thẻ @overload để xác định từng chữ ký riêng biệt. Trình chỉnh sửa Apps Script sử dụng các thông tin này để đưa ra những gợi ý cụ thể dựa trên phiên bản hàm mà bạn đang gọi.

/**
 * @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
}

Hàm tuỳ chỉnh trong Google Trang tính

Khi viết một hàm tuỳ chỉnh cho Google Trang tính, bạn phải sử dụng thẻ @customfunction để hàm đó xuất hiện trong tính năng tự động hoàn thành và trợ lý công thức của bảng tính.

JSDoc là nguồn cho văn bản trợ giúp mà người dùng nhìn thấy khi họ sử dụng hàm tuỳ chỉnh của bạn trong Google Trang tính. Nếu không có JSDoc, người dùng sẽ chỉ thấy tên hàm, khiến họ khó biết được hàm này làm gì hoặc cần những tham số nào.

Các thẻ được hỗ trợ và hạn chế về giao diện người dùng

Mặc dù Apps Script phân tích cú pháp hầu hết các thẻ JSDoc tiêu chuẩn, nhưng giao diện người dùng Google Trang tính cho các hàm tuỳ chỉnh có một số hành vi và hạn chế cụ thể:

@customfunction: Bắt buộc để hàm xuất hiện trong danh sách công thức của Trang tính.
@param: Tên và nội dung mô tả sẽ xuất hiện trong trình trợ giúp công thức của Trang tính.
@return: Nội dung mô tả được cung cấp trong thẻ @return không xuất hiện trong trình trợ giúp công thức của Trang tính.
Tham số không bắt buộc: Giao diện người dùng của Trang tính không nhận dạng cú pháp JSDoc chuẩn cho các tham số không bắt buộc (ví dụ: [name] hoặc name=). Tất cả các tham số sẽ xuất hiện dưới dạng bắt buộc trong trình trợ giúp công thức.
Giá trị mặc định: Giá trị tham số mặc định (ví dụ: [name=Value]) không được hỗ trợ trong giao diện người dùng của Trang tính.
Định dạng: Chúng tôi không hỗ trợ thẻ HTML và dấu ngắt dòng văn bản thuần tuý trong nội dung mô tả. Giao diện người dùng của Trang tính hiển thị nội dung mô tả dưới dạng một khối văn bản duy nhất và loại bỏ hầu hết HTML.

Ví dụ về Google Trang tính

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

Nội dung người dùng nhìn thấy trong Google Trang tính

Khi người dùng nhập =CALCULATEDISCOUNT( vào một ô, Google Trang tính sẽ hiển thị hộp trợ giúp sau:

CALCULATEDISCOUNT

Tính chiết khấu.

price: Giá gốc.

percent: Tỷ lệ phần trăm chiết khấu (ví dụ: 0,1 cho 10%).

Lưu ý rằng nội dung mô tả cho các tham số đến trực tiếp từ các thẻ JSDoc @param.

Chú giải cấp tập lệnh

Apps Script sử dụng các thẻ JSDoc duy nhất để kiểm soát các chế độ cài đặt trên toàn tập lệnh. Các hàm này thường được đặt ở đầu tệp kịch bản.

Thẻ uỷ quyền

Thẻ	Mô tả
`@OnlyCurrentDoc`	Yêu cầu Apps Script chỉ yêu cầu uỷ quyền cho tài liệu hiện tại thay vì tất cả các tệp thuộc loại đó. Hãy xem [Hướng dẫn uỷ quyền](/apps-script/guides/services/authorization) để biết thêm thông tin.
`@NotOnlyCurrentDoc`	Được dùng trong các thư viện để ghi đè chú thích `@OnlyCurrentDoc` được kế thừa.

JSDoc trong Apps Script Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.