Thư viện

Thư viện là một dự án tập lệnh có các hàm có thể được sử dụng lại trong các tập lệnh khác.

Nhận quyền truy cập vào thư viện

Để đưa thư viện vào dự án, tối thiểu bạn phải có cấp độ xem quyền truy cập vào nội dung đó. Nếu bạn không phải là tác giả của thư viện mà bạn muốn bao gồm, liên hệ với tác giả và yêu cầu quyền truy cập.

Bạn cần có mã tập lệnh của thư viện mà bạn muốn đưa vào. Khi bạn có quyền truy cập vào thư viện, bạn có thể tìm thấy ID tập lệnh trong phần Cài đặt dự án .

Thêm thư viện vào dự án tập lệnh của bạn

  1. Ở bên trái trình chỉnh sửa Apps Script, bên cạnh phần "Thư viện", hãy nhấp vào Thêm thư viện .
  2. Trong "Script ID" hãy dán mã tập lệnh của thư viện.
  3. Nhấp vào Tra cứu.
  4. Nhấp vào trình đơn thả xuống Phiên bản rồi chọn phiên bản thư viện để sử dụng.
  5. Kiểm tra xem "Giá trị nhận dạng" mặc định có phải là là tên mà bạn muốn sử dụng với thư viện này. Đây là tên mà tập lệnh của bạn dùng để tham chiếu đến thư viện. Ví dụ: nếu đặt thành Test thì bạn có thể gọi một phương thức của thư viện đó như sau: Test.libraryMethod().
  6. Nhấp vào Thêm.

Sử dụng thư viện

Sử dụng thư viện đi kèm giống như khi bạn sử dụng dịch vụ mặc định. Cho ví dụ: nếu Test là giá trị nhận dạng cho thư viện của bạn, hãy nhập Test theo sau là một dấu chấm để xem danh sách các phương thức trong thư viện.

Bạn có thể mở tài liệu tham khảo cho thư viện đi kèm bằng cách làm theo các bước sau:

Ở bên trái trình chỉnh sửa tập lệnh, bên cạnh tên thư viện, hãy nhấp vào biểu tượng Thêm > Mở trong một thẻ mới.

Xoá thư viện

Ở bên trái trình chỉnh sửa tập lệnh, bên cạnh tên thư viện, hãy nhấp vào biểu tượng Thêm > Xoá > Xoá thư viện.

Cập nhật thư viện

Bạn có thể thay đổi phiên bản của thư viện hoặc cập nhật giá trị nhận dạng của thư viện.

  1. Ở bên trái trình chỉnh sửa, trong phần "Thư viện" hãy nhấp vào tên thư viện.
  2. Chỉnh sửa rồi nhấp vào Lưu.

Tạo và chia sẻ thư viện

Để sử dụng và chia sẻ dự án tập lệnh của bạn dưới dạng thư viện, hãy làm theo các bước dưới đây.

  1. Tạo quy trình triển khai theo phiên bản của tập lệnh.
  2. Ít nhất phải có quyền truy cập ở cấp độ xem với tất cả người dùng tiềm năng của thư viện.
  3. Cung cấp cho những người dùng đó mã nhận dạng tập lệnh. Bạn có thể tìm thấy mã này trên trang Dự án cài đặt .

Các phương pháp hay nhất

Dưới đây là một số nguyên tắc cần tuân thủ khi viết thư viện:

  1. Chọn một tên có ý nghĩa cho dự án của bạn vì tên này được dùng làm giá trị nhận dạng mặc định khi thư viện của bạn có trong thư viện.
  2. Nếu bạn muốn một hoặc nhiều phương thức của tập lệnh không hiển thị (hoặc sử dụng được) cho người dùng thư viện, bạn có thể kết thúc tên phương thức bằng dấu gạch dưới. Ví dụ: myPrivateMethod_().
  3. Người dùng thư viện chỉ nhìn thấy các thuộc tính chung có thể liệt kê. Bao gồm cả hàm nội dung khai báo, các biến được tạo bên ngoài hàm có var và các thuộc tính được đặt rõ ràng trên đối tượng toàn cục. Ví dụ: Object.defineProperty() với enumerable được đặt thành false tạo một biểu tượng mà bạn có thể sử dụng trong thư viện của mình nhưng người dùng của bạn không thể truy cập vào biểu tượng này.

  4. Nếu bạn muốn người dùng thư viện của mình sử dụng tính năng tự động hoàn thành của trình chỉnh sửa tập lệnh và tài liệu được tạo tự động, bạn phải có kiểu JSDoc cho tất cả các chức năng của bạn. Ví dụ:

    /**
 * Raises a number to the given power, and returns the result.
 *
 * @param {number} base the number we're raising to a power
 * @param {number} exp the exponent we're raising the base to
 * @return {number} the result of the exponential calculation
 */
function power(base, exp) { ... }

Phạm vi tài nguyên

Có hai loại tài nguyên khi bạn làm việc với thư viện: dùng chung và không được chia sẻ. Tài nguyên dùng chung nghĩa là cả thư viện và phần tử bao gồm tập lệnh có quyền truy cập tích hợp vào cùng một phiên bản của tài nguyên. Chiến lược phát hành đĩa đơn sơ đồ dưới đây minh hoạ một tài nguyên dùng chung Thuộc tính người dùng:

Tài nguyên được chia sẻ

Tài nguyên không được chia sẻ có nghĩa là cả thư viện và tập lệnh bao gồm đều có quyền truy cập tích hợp sẵn vào bản sao tài nguyên của chúng. Tuy nhiên, thư viện có thể cung cấp quyền truy cập vào các tài nguyên không được chia sẻ của nó bằng cách có các hàm tường minh thao tác trên chúng. Dưới đây là ví dụ về một hàm mà bạn sẽ đưa vào thư viện của bạn để hiển thị các Thuộc tính của tập lệnh:

  function getLibraryProperty(key) {
    return ScriptProperties.getProperty(key);
  }

Sơ đồ dưới đây minh hoạ một tài nguyên không được chia sẻ bằng cách sử dụng ví dụ về Thuộc tính của tập lệnh:

Tài nguyên không được chia sẻ

Bảng này liệt kê các tài nguyên được chia sẻ và không được chia sẻ để bạn tham khảo:

Tài nguyên Đã chia sẻ* Không được chia sẻ** Ghi chú
Khoá Cùng một phiên bản hiển thị cho tất cả tập lệnh khi được tạo trong thư viện.
Thuộc tính của tập lệnh Cùng một phiên bản hiển thị cho tất cả tập lệnh khi được tạo trong thư viện.
Bộ nhớ đệm Cùng một phiên bản hiển thị cho tất cả tập lệnh khi được tạo trong thư viện.
Điều kiện kích hoạt Các trình kích hoạt đơn giản được tạo trong thư viện không được kích hoạt bởi các thuộc tính bao gồm tập lệnh.
ScriptApp
UiApp
Thuộc tính người dùng
Trình ghi nhật ký và bản chép lời thực thi
Sites, Trang tính và vùng chứa khác Lệnh gọi đến getActive() sẽ trả về vùng chứa của bao gồm cả tập lệnh.
MailApp và GmailApp
* Điều này có nghĩa là thư viện không có phiên bản riêng của tính năng/tài nguyên và thay vào đó là sử dụng tính năng/tài nguyên do tập lệnh tạo đã gọi ra nó.
** Điều này có nghĩa là thư viện có một thực thể riêng của tài nguyên/tính năng và tất cả tập lệnh sử dụng thư viện đều dùng chung và có quyền truy cập vào thư viện đó cùng một trường hợp.

Kiểm thử thư viện

Để kiểm thử thư viện, hãy sử dụng tính năng triển khai đầu. Bất kỳ ai có cấp người chỉnh sửa quyền truy cập vào tập lệnh có thể sử dụng triển khai đầu.

Gỡ lỗi thư viện

Khi bạn sử dụng trình gỡ lỗi trong một dự án có chứa một thư viện có thể truy cập vào một chức năng của thư viện đi kèm. Mã này sẽ xuất hiện trong trình gỡ lỗi ở chế độ chỉ có thể xem và hiển thị đúng phiên bản.