Hướng dẫn về kiểu giao diện người dùng cho Tiện ích bổ sung dành cho trình chỉnh sửa

Tiện ích bổ sung trình chỉnh sửa tạo giao diện người dùng (trình đơn, thanh bên và hộp thoại) bằng dịch vụ HTML của Apps Script. Vì các giao diện được phát triển bằng HTML và CSS, nên chúng có khả năng tuỳ chỉnh cao. Tuy nhiên, khi xây dựng giao diện tiện ích bổ sung, bạn nên thiết kế giao diện đó để mang lại trải nghiệm người dùng tuyệt vời.

Các tiện ích bổ sung tốt nhất mở rộng từng trình chỉnh sửa một cách tự nhiên bằng cách sử dụng các chế độ điều khiển và hành vi quen thuộc. Khi xây dựng tiện ích bổ sung mới:

Văn bản

Tên tiện ích bổ sung

Bạn phải đặt tên cho tiện ích bổ sung khi phát hành tiện ích bổ sung đó. Tên xuất hiện ở nhiều nơi, chẳng hạn như cửa hàng tiện ích bổ sung và trong các trình đơn.

  • Sử dụng viết hoa chữ cái đầu tiên.
  • Tránh dùng dấu câu, đặc biệt là dấu ngoặc đơn, trừ phi tên đó là một phần của thương hiệu.
  • Hãy tạo tên ngắn gọn — tốt nhất là tối đa 30 ký tự. Tên dài có thể tự động bị cắt bớt.
  • Đừng thêm tên của sản phẩm của Google làm tiện ích bổ sung (hoặc sử dụng từ Google).
  • Bỏ thông tin phiên bản.
  • Hãy đảm bảo tên đã phát hành của tiện ích bổ sung giống với tên tệp của dự án tập lệnh. Tên dự án xuất hiện trong hộp thoại uỷ quyền.
Việc không nên làm Việc nên làm
Tên tiện ích bổ sung không hợp lệ Tên tiện ích bổ sung hay

Phong cách viết

Bạn không cần phải viết nhiều. Bạn phải thể hiện rõ ràng hầu hết các thao tác thông qua biểu tượng, bố cục và nhãn ngắn. Nếu bạn thấy một phần tiện ích bổ sung của mình cần giải thích rộng hơn so với các nhãn ngắn, tốt nhất bạn nên tạo một trang web riêng mô tả tiện ích bổ sung của mình và liên kết đến tiện ích đó.

Khi viết văn bản giao diện người dùng:

  • Sử dụng viết hoa đầu câu (đặc biệt đối với các nút, nhãn và các mục trong trình đơn).
  • Ưu tiên văn bản ngắn, đơn giản không có biệt ngữ hoặc từ viết tắt.
Việc không nên làm Việc nên làm

Mẹo sau khi cài đặt

Mẹo sau khi cài đặt sẽ bật lên ngay sau khi ai đó cài đặt tiện ích bổ sung của bạn và cũng xuất hiện trong phần Trợ giúp. Bạn có một vài câu để giúp người dùng bắt đầu nhanh chóng.

  • Bắt đầu bằng một từ hành động.
  • Mô tả bước đầu tiên khi sử dụng tiện ích bổ sung.
  • Nếu bạn có giao diện người dùng chính, chẳng hạn như thanh bên, hãy giải thích cách mở thanh bên.
  • Không quảng cáo tiện ích bổ sung của bạn tại đây vì tiện ích bổ sung đó đã được cài đặt.
Việc không nên làm Việc nên làm
Mẹo sau khi cài đặt không hợp lệ Mẹo hay sau khi cài đặt

Không giống như các dự án Apps Script thông thường, tiện ích bổ sung không xuất hiện trong trình chỉnh sửa tập lệnh hoặc trình quản lý tập lệnh; người dùng không thể trực tiếp chạy tập lệnh tiện ích bổ sung. Thay vào đó, mỗi tiện ích bổ sung sẽ có một vị trí trong trình đơn tiện ích bổ sung. Trình đơn (và có thể là hộp thoại hoặc thanh bên) cho phép người dùng tương tác với tiện ích bổ sung.

  • Trình đơn là một phần quan trọng trong cách người dùng kiểm soát tiện ích bổ sung của bạn, vì vậy, hãy thiết kế cấu trúc và từ ngữ cẩn thận cho tiện ích bổ sung.
  • Tránh các mục trong trình đơn chỉ lặp lại tên của tiện ích bổ sung. Thay vào đó, hãy bắt đầu bằng một từ hành động.
  • Nếu mục trong trình đơn chính bắt đầu quy trình công việc và không có một động từ nào mô tả chức năng đó, hãy gọi là "Bắt đầu". Mẫu này được dùng trong phần Bắt đầu nhanh của tiện ích bổ sung Tài liệu.
  • Nếu trình đơn của bạn có nhiều hơn 6 mục, hãy cố gắng không sử dụng trình đơn phụ. Những trò chơi này có thể phức tạp và khó chọn.
  • Mô tả việc cần làm, chứ không phải thành phần giao diện người dùng mà mục trong trình đơn hiển thị.
Việc không nên làm Việc nên làm
Nhãn mục trong trình đơn không hợp lệ Nhãn mục trong thực đơn hợp lệ

Thông báo lỗi

Khi gặp sự cố, cần sử dụng ngôn từ thuần tuý. Giải thích vấn đề từ quan điểm của người dùng và đề xuất cách khắc phục.

  • Không cho phép người dùng xem bất kỳ ngoại lệ nào mà mã của bạn gửi. Thay vào đó, hãy sử dụng câu lệnh try...catch để chặn các trường hợp ngoại lệ, sau đó hiển thị thông báo lỗi do người dùng tải lên với văn bản cùng dòng được tạo kiểu trong lớp error từ gói CSS bổ sung tiện ích bổ sung hoặc hộp thoại cảnh báo.
  • Trước khi phát hành, hãy kiểm tra để đảm bảo tiện ích bổ sung của bạn không ghi lại thông tin gỡ lỗi vào bảng điều khiển JavaScript; thay vào đó, hãy sử dụng tính năng ghi nhật ký Stackdriver.
Việc không nên làm Việc nên làm
Thông báo lỗi không hợp lệ Thông báo lỗi hợp lệ

Nội dung trợ giúp

Trình đơn của mọi tiện ích bổ sung đều có một hộp thoại Trợ giúp tự động. Nếu bạn cung cấp URL trợ giúp khi xuất bản, nút "Tìm hiểu thêm" sẽ liên kết đến trang đó. Vui lòng cung cấp một trang giải thích cách sử dụng tiện ích bổ sung của bạn, trừ phi tiện ích bổ sung của bạn là tiện ích tự giải thích.

  • Khi có thể, hãy hiển thị hướng dẫn dưới dạng danh sách có dấu đầu dòng hoặc được đánh số. Hướng dẫn người dùng đến kết quả cuối cùng, với thông tin tham chiếu rõ ràng đến các thành phần trên giao diện người dùng được đặt tên.
  • Hãy đảm bảo hướng dẫn của bạn giải thích rõ mọi yêu cầu, chẳng hạn như thiết lập bảng tính theo một cách nhất định.
  • Bạn cũng có thể liên kết đến nội dung trợ giúp từ giao diện người dùng chính. Nếu tiện ích bổ sung của bạn tạo một tài liệu mới, bạn cũng có thể hiển thị hướng dẫn trong phần nội dung của tài liệu.

Giao diện người dùng tuỳ chỉnh

Bạn có thể kiểm soát hoàn toàn một số Tiện ích bổ sung trình chỉnh sửa đơn giản bằng trình đơn, nhưng hầu hết sẽ hiển thị thanh bên hoặc hộp thoại có nội dung tuỳ chỉnh.

  • Thanh bên phù hợp nhất với các công cụ liên tục mà mọi người có thể sử dụng nhiều lần khi tham chiếu đến nội dung tài liệu hoặc bảng tính của họ.
  • Hộp thoại phù hợp nhất với các công cụ sử dụng một lần, trang cài đặt và các thư quan trọng.

Văn bản giao diện người dùng

Trong bất kỳ hộp thoại hoặc thanh bên nào, hãy giả định rằng mọi người chỉ đọc tiêu đề và nhãn nút. Họ có thể vẫn tìm ra giao diện của bạn để đưa ra lựa chọn phù hợp không?

  • Sử dụng tiêu đề và nhãn nút độc lập.
  • Tránh dùng các đoạn văn bản mô tả dài.

Hộp thoại

Hộp thoại rất phù hợp với những công cụ mà mọi người chỉ dùng một lần, sau đó tiếp tục. Ví dụ: nếu tiện ích bổ sung của bạn cho phép mọi người chèn đồ hoạ, bạn có thể hiển thị hộp thoại với các lựa chọn chèn Hộp thoại cũng hữu ích khi hiển thị các chế độ cài đặt của tiện ích bổ sung hoặc để truyền đạt một thông điệp quan trọng.

  • Không mở hộp thoại (bao gồm cả cảnh báo hoặc lời nhắc) từ một hộp thoại khác mà chỉ hiển thị lần lượt từng hộp thoại.
  • Đối với tiêu đề hộp thoại, hãy sử dụng một từ hoặc cụm từ ngắn, ở đầu bằng từ quan trọng nhất.
  • Nhãn nút phải liên quan đến tiêu đề hộp thoại.
  • Ưu tiên hai nút, thường là thao tác chính và nút "Huỷ". Đối với các trường hợp đặc biệt yêu cầu nút thứ ba, hãy cân nhắc góc dưới cùng bên phải.
  • Đặt các nút ở góc dưới cùng bên trái của hộp thoại. Nút chính màu xanh dương phải ở bên trái, với mọi nút phụ màu xám ở bên phải.
Việc không nên làm Việc nên làm
Tiêu đề hộp thoại không hợp lệ Tiêu đề hộp thoại hợp lệ

Thanh bên cho phép mọi người xem lại tài liệu, bảng tính, bản trình bày hoặc biểu mẫu của họ trong khi đưa ra lựa chọn. Họ cũng cho phép mọi người sử dụng tiện ích bổ sung của bạn nhiều lần. Bất cứ khi nào một thanh bên mới được mở, bất kỳ thanh bên nào trước đó sẽ tự động đóng. Chúng phù hợp nhất cho các chế độ tạm thời mà người dùng thoát khi hoàn tất.

  • Người dùng có thể có các tiện ích bổ sung khác có thanh bên của riêng họ. Nếu 2 tiện ích bổ sung cố gắng mở đồng thời thanh bên, thì chỉ có một tiện ích được hiển thị.
  • Không hiển thị thanh bên hoặc hộp thoại khi tài liệu mở lần đầu.
  • Chỉ những tiện ích bổ sung hoạt động trong AuthMode.FULL mới có thể mở thanh bên hoặc hộp thoại. Bạn có thể sử dụng mục trong trình đơn để mở thanh bên vì thao tác này sẽ nhắc người dùng cấp toàn quyền uỷ quyền.

Các chế độ kiểm soát

Các giao diện người dùng tiện ích bổ sung tuyệt vời sẽ rời khỏi bộ điều khiển của họ. Việc có đủ lề và khoảng đệm sẽ phát huy hiệu quả, trong khi các tuỳ chọn kiểm soát dày đặc có thể gây quá tải. Nếu không chắc chắn, hãy mượn bố cục từ chính trình chỉnh sửa. Ví dụ: xem lại các hộp thoại hiện có trong Google Tài liệu, chẳng hạn như Tệp > Thiết lập trang khi tạo các hộp thoại của riêng bạn.

Tài liệu về gói CSS tiện ích bổ sung cung cấp mã đánh dấu mẫu cho từng loại chế độ kiểm soát dưới đây.

Nút

Hãy sử dụng các nút để điều khiển các thao tác chính trên giao diện người dùng thay vì các đường liên kết thuần tuý hoặc các thành phần khác.

  • Tránh hiển thị nhiều nút màu xanh dương, đỏ hoặc xanh lục cùng một lúc. Các nút màu xám có thể xuất hiện liên tục.
  • Hầu hết các nhãn của nút phải viết hoa đầu câu và bắt đầu bằng một động từ. Các nút màu đỏ (thường dùng để tạo thao tác) phải viết hoa toàn bộ.
Việc không nên làm Việc nên làm

Hộp kiểm và nút chọn

Sử dụng hộp đánh dấu khi mọi người có thể chọn nhiều tuỳ chọn hoặc hoàn toàn không chọn tuỳ chọn nào. Sử dụng nút chọn (hoặc trình đơn chọn) khi phải chọn đúng một tuỳ chọn.

  • Không thay đổi hành vi của hộp đánh dấu để bắt chước các nút chọn.
  • Không làm bất cứ điều gì ngay lập tức khi chúng được kiểm tra. Mọi người có thể phạm lỗi. Chờ cho đến khi người dùng nhấp vào một nút để xác nhận lựa chọn của họ.

Chọn trình đơn

Chọn lọc là một cách tuyệt vời để cung cấp danh sách ngắn các lựa chọn thay thế.

  • Sắp xếp các tuỳ chọn theo thứ tự bảng chữ cái hoặc theo lược đồ logic mà tất cả người dùng đều hiểu được (như ngày trong tuần, bắt đầu từ Chủ Nhật).
  • Nếu danh sách tăng quá dài, hãy cân nhắc sử dụng một chế độ kiểm soát khác. Ví dụ: bạn có thể hiển thị một danh sách có thể cuộn để trình đơn có thêm không gian và giúp thao tác dễ dàng hơn.

Vùng văn bản

Nếu mọi người cần nhập nhiều từ, hãy sử dụng một vùng văn bản.

  • Tạo vùng văn bản cao ít nhất 2 dòng để dễ sử dụng hơn và không giống như trường văn bản.
  • Đặt nhãn ở trên cùng.

Trường văn bản

Sử dụng các trường văn bản nếu mọi người chỉ cần nhập một hoặc hai từ.

  • Chiều rộng của trường văn bản phải đề xuất nội dung mà bạn muốn mọi người nhập vào đó.
  • Tránh sử dụng văn bản giữ chỗ làm nhãn, vì văn bản này sẽ biến mất khi được đặt tiêu điểm. Văn bản của phần giữ chỗ rất hữu ích trong việc cung cấp các ví dụ hoặc thông tin chi tiết bổ sung.
  • Đặt nhãn lên trên, nhưng đừng ngại sắp xếp các trường văn bản ngắn cạnh nhau.

Xây dựng thương hiệu

Trong tiện ích bổ sung của bạn

Nếu bạn muốn đưa thương hiệu vào nội dung, hãy viết ngắn gọn và súc tích. Điều này giúp mọi người tập trung vào giao diện người dùng của bạn và khiến tiện ích bổ sung của bạn giống như một phần của trình chỉnh sửa.

  • Mọi khía cạnh của tiện ích bổ sung của bạn phải tuân thủ nguyên tắc sử dụng thương hiệu.
  • Đừng thêm từ "Google" hoặc sử dụng biểu tượng sản phẩm của Google.
  • Văn bản không được dài quá vài từ và được tạo kiểu trong lớp gray từ gói CSS của tiện ích bổ sung.
  • Đồ hoạ phải trên nền trắng và có kích thước không quá 200px x 60px.
  • Đối với hộp thoại, thương hiệu nên nằm ở góc dưới cùng bên phải.
  • Đối với thanh bên, thương hiệu có thể nằm ở trên cùng hoặc dưới cùng.

Trong cửa hàng

Để phát hành một Tiện ích bổ sung dành cho trình chỉnh sửa, bạn cần có số thành phần hình ảnh. Những thành phần này được dùng để tạo trang thông tin của tiện ích bổ sung trên Cửa hàng Play.

Hỗ trợ tiếp cận

Mọi người đều có thể sử dụng tiện ích bổ sung của bạn, cho dù họ thấy màu sắc khác nhau, sử dụng trình đọc màn hình hay có nhu cầu khác. Khả năng hỗ trợ tiếp cận là một chủ đề rộng mà không thể đề cập đầy đủ trong hướng dẫn quy tắc này. Một tài nguyên hữu ích là trang web Google Hỗ trợ tiếp cận. Nhưng sau đây là một vài mẹo giúp bạn bắt đầu:

  • Đảm bảo bạn có thể dùng bàn phím để di chuyển đến tất cả các nút điều khiển trên giao diện người dùng. Thêm tabindex=0 vào các chế độ điều khiển tuỳ chỉnh (chẳng hạn như các chế độ được tạo bằng <div>) để mọi người có thể thêm vào các chế độ đó. Hãy cân nhắc xem các khoá khác có được hỗ trợ hay không, chẳng hạn như các mũi tên cho danh sách.
  • Một số người có thể sử dụng trình đọc màn hình cùng với tiện ích bổ sung của bạn. Do đó, hình ảnh phải có thuộc tính alt và các thành phần điều khiển tuỳ chỉnh phải có thuộc tính ARIA để mô tả cách sử dụng.
  • Đừng chỉ dựa vào màu sắc để truyền đạt trạng thái. Sử dụng cả biểu tượng và văn bản.

Nếu bạn sử dụng các thành phần điều khiển tiêu chuẩn trên web, như các thành phần được mô tả ở phần trước trong hướng dẫn này, thì việc làm cho tiện ích bổ sung của bạn có thể truy cập được sẽ dễ dàng hơn.