Thư viện

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

Một tập lệnh sử dụng thư viện sẽ không chạy nhanh bằng khi tất cả mã đều nằm trong một dự án tập lệnh. Mặc dù thư viện có thể giúp việc phát triển và bảo trì trở nên thuận tiện hơn, nhưng bạn nên sử dụng thư viện một cách tiết kiệm trong các dự án mà tốc độ là yếu tố quan trọng. Do vấn đề này, bạn nên hạn chế sử dụng thư viện trong các tiện ích bổ sung của Google Workspace.

Truy cập vào thư viện

Để đưa thư viện vào dự án, bạn phải có ít nhất quyền truy cập ở cấp độ xem. 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, hãy tìm 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

1. Ở bên trái trình chỉnh sửa tập lệnh Apps Script, bên cạnh "Thư viện", hãy nhấp vào biểu tượng 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 Tìm.
   Nếu bạn gặp lỗi, hãy đảm bảo rằng bạn có ít nhất quyền truy cập ở cấp độ xem vào dự án mà bạn đang cố gắng đưa vào.
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 cần sử dụng.
5. Kiểm tra để xem tên "Mã 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 bạn đặt tên này thành Test, thì hãy gọi một phương thức của thư viện đó như sau: Test.libraryMethod.
   Nếu bạn sử dụng tên mã nhận dạng trùng với tên của một dịch vụ đã tồn tại (chẳng hạn như MailApp) hoặc một thư viện đã thêm trước đó, thì thư viện mà bạn đã thêm gần đây nhất sẽ ghi đè dịch vụ hoặc thư viện hiện có.
6. Nhấp vào Thêm.

Sử dụng thư viện

Sử dụng thư viện đã đưa vào như cách bạn sử dụng dịch vụ mặc định. Ví dụ: nếu Test là mã nhận dạng cho thư viện của bạn, hãy nhập Test ngay sau đó là dấu chấm để xem danh sách các phương thức trong thư viện.

Mở tài liệu tham khảo cho thư viện đã đưa vào 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 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.

Nếu tác giả xoá một thư viện, bạn vẫn cần xoá thư viện đó khỏi danh sách thư viện đã đưa vào.

Cập nhật thư viện

Thay đổi phiên bản của thư viện hoặc cập nhật mã 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 sau:

1. Tạo bản triển khai có phiên bản cho tập lệnh.
2. Chia sẻ ít nhất 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ã tập lệnh mà bạn có thể tìm thấ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 bạn 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 mã nhận dạng mặc định khi người khác đưa thư viện của bạn vào.
2. Để một hoặc nhiều phương thức của tập lệnh không hiển thị (cũng như không sử dụng được) cho người dùng thư viện, hãy kết thúc tên của phương thức bằng dấu gạch dưới. Ví dụ: myPrivateMethod_.
3. Chỉ những thuộc tính toàn cục có thể liệt kê mới hiển thị cho người dùng thư viện. Điều này bao gồm các khai báo hàm, biến được tạo bên ngoài một 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() với enumerable được đặt thành false sẽ 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 không thể truy cập vào biểu tượng này.

4. Để đảm bảo người dùng thư viện có thể 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, hãy đưa tài liệu theo kiểu JSDoc vào tất cả cá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 thư viện: tài nguyên dùng chung và tài nguyên không dùng chung. Tài nguyên dùng chung có nghĩa là cả thư viện và tập lệnh đưa vào đều có quyền truy cập tích hợp vào cùng một thực thể của tài nguyên. Sơ đồ sau đây minh hoạ một tài nguyên dùng chung bằng ví dụ về Thuộc tính người dùng:

Tài nguyên không dùng chung có nghĩa là cả thư viện và tập lệnh đưa vào chỉ có quyền truy cập tích hợp vào thực thể tài nguyên của riêng 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 dùng chung bằng cách có các hàm rõ ràng hoạt động trên các 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ị Thuộc tính của tập lệnh:

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

Sơ đồ sau đây minh hoạ một tài nguyên không dùng chung bằng ví dụ về Thuộc tính của tập lệnh:

Bảng này liệt kê các tài nguyên dùng chung và không dùng chung để bạn tham khảo:

Tài nguyên	Được chia sẻ*	Không dùng chung**	Ghi chú
Khoá			Tất cả các tập lệnh đưa vào đều có thể nhìn thấy cùng một thực thể khi được tạo trong thư viện.
Thuộc tính của tập lệnh			Tất cả các tập lệnh đưa vào đều có thể nhìn thấy cùng một thực thể khi được tạo trong thư viện.
Bộ nhớ đệm			Tất cả các tập lệnh đưa vào đều có thể nhìn thấy cùng một thực thể khi được tạo trong thư viện.
Đ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 sẽ không được kích hoạt bởi tập lệnh đưa vào.
ScriptApp
UiApp
Thuộc tính người dùng
Trình ghi nhật ký và nhật ký thực hiện lệnh
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 đưa vào.
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 và thay vào đó, đang sử dụng thực thể do tập lệnh đã gọi thư viện đó tạo. ** Điều này có nghĩa là thư viện có thực thể riêng của tài nguyên/tính năng và tất cả cá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 bản triển khai chính. Bất kỳ ai có quyền truy cập ở cấp độ trình chỉnh sửa vào tập lệnh đều có thể sử dụng bản triển khai chính.

Bạn vẫn cần lưu ít nhất một phiên bản của thư viện.

Gỡ lỗi thư viện

Khi gỡ lỗi một tập lệnh có chứa thư viện, bạn không thể đi vào mã thư viện hoặc đặt điểm ngắt trong đó. Nếu bạn cố gắng đi vào một hàm thư viện ở chế độ gỡ lỗi, trình gỡ lỗi sẽ bỏ qua hàm đó và chuyển đến dòng tiếp theo trong tập lệnh gọi.

Việc sử dụng HEAD (Chế độ phát triển) cho phiên bản thư viện không cho phép đi vào thư viện hoặc đạt đến các điểm dừng trong đó.

Để gỡ lỗi mã thư viện, hãy sử dụng một trong các phương thức sau:

• Gỡ lỗi từ dự án thư viện: Mở dự án tập lệnh thư viện trong trình chỉnh sửa Apps Script. Để kiểm thử các hàm thư viện bằng các đối số cụ thể, hãy tạo một hàm "kiểm thử" tạm thời trong dự án thư viện gọi các hàm thư viện của bạn, sau đó chạy hàm kiểm thử đó ở chế độ gỡ lỗi.
• Ghi nhật ký: Sử dụng console.log() trong các hàm thư viện để xuất thông tin vào nhật ký thực thi. Khi thư viện được một tập lệnh khác gọi, các nhật ký này sẽ xuất hiện trong nhật ký thực thi của tập lệnh gọi.