Thư viện

Thư viện là một dự án tập lệnh 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 một thư viện vào dự án, tối thiểu bạn phải có quyền truy cập ở cấp độ xem đối với thư viện đó. Nếu bạn không phải là tác giả của thư viện mà bạn muốn đưa vào, hãy 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 có quyền truy cập vào thư viện, bạn có thể tìm thấy mã tập lệnh trên trang 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 "Libraries" (Thư viện), hãy nhấp vào Add a library (Thêm thư viện).
  2. Trong trường "Mã tập lệnh", 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 Version (Phiên bản) rồi chọn phiên bản thư viện bạn muốn sử dụng.
  5. Hãy kiểm tra xem tên "Giá trị nhận dạng" mặc định có phải là tên mà bạn muốn sử dụng với thư viện này hay không. Đâ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 giá trị này 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ư cách bạn sử dụng dịch vụ mặc định. 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 ngay trước 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 một 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 Tuỳ chọn khác > Mở trong 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 Xem thêm > Xoá > Xoá thư viện.

Cập nhật thư viện

Bạn có thể thay đổi phiên bản 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 của 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 bên dưới.

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

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

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

  1. Hãy chọn một tên có ý nghĩa cho dự án của bạn vì tên đó sẽ được dùng làm giá trị nhận dạng mặc định khi những người khác thêm thư viện của bạn vào.
  2. Nếu không muốn người dùng thư viện nhìn thấy (hoặc sử dụng được) một hoặc nhiều phương thức trong tập lệnh của mình, 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. Chỉ người dùng thư viện mới có thể nhìn thấy các thuộc tính chung có thể đếm được. Trong đó bao gồm nội dung khai báo hàm, các biến được tạo bên ngoài hàm bằng 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()enumerable được đặt thành false sẽ tạo ra một biểu tượng mà bạn có thể sử dụng trong thư viện, nhưng người dùng của bạn không truy cập được biểu tượng này.
  4. Nếu muốn người dùng thư viện 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ó tài liệu kiểu JSDoc cho tất cả hàm. 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ó 2 loại tài nguyên khi bạn làm việc với các thư viện: được chia sẻ và không được chia sẻ. Tài nguyên dùng chung 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 vào cùng một bản sao của tài nguyên. Sơ đồ sau minh hoạ một tài nguyên dùng chung trong ví dụ về 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 chỉ có quyền truy cập tích hợp vào thực thể tài nguyên của chúng. Tuy nhiên, thư viện có thể cấp quyền truy cập vào các tài nguyên không được chia sẻ của thư viện đó bằng cách có các hàm rõ ràng hoạt động trên những tài nguyên đó. Dưới đây là ví dụ về một hàm mà bạn sẽ đưa vào thư việ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 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á Khi được tạo trong thư viện, tất cả tập lệnh (bao gồm cả tập lệnh) đều sẽ thấy cùng một thực thể.
Thuộc tính của tập lệnh Khi được tạo trong thư viện, tất cả tập lệnh (bao gồm cả tập lệnh) đều sẽ thấy cùng một thực thể.
Bộ nhớ đệm Khi được tạo trong thư viện, tất cả tập lệnh (bao gồm cả tập lệnh) đều sẽ thấy cùng một thực thể.
Điều kiện kích hoạt Các điều kiện kích hoạt đơn giản được tạo trong thư viện không được tập lệnh bao gồm cả tập lệnh kích hoạt.
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à các vùng chứa khác Lệnh gọi đến getActive() sẽ trả về vùng chứa của tập lệnh bao gồm.
MailApp và GmailApp
* Điều này có nghĩa là thư viện không có thực thể riêng của tính năng/tài nguyên mà sử dụng thực thể do tập lệnh đã gọi nó tạo.
** Tức là thư viện có bản sao tài nguyên/tính năng riêng và tất cả tập lệnh sử dụng thư viện đều chia sẻ và có quyền truy cập vào cùng một thực thể đó.

Kiểm thử thư viện

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

Gỡ lỗi thư viện

Khi sử dụng trình gỡ lỗi trong một dự án có chứa thư viện, bạn có thể chuyển sang một hàm 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à ở đúng phiên bản.