Hướng dẫn viết Userscript

Hướng dẫn viết Userscript 

Userscript luôn chứa một Metadata Block, được đặt ở phần đầu script. Đây là nơi khai báo các thông tin như tên, phiên bản, giới hạn sử dụng…

Định dạng chuẩn của một Metadata Block.

// ==UserScript==
// @key1 value1
// @key2 value2
// @keyX valueX
// ==/UserScript==

Việc hỗ trợ khóa (key) Metadata cũng khác nhau tùy tiện ích quản lý, nên mình chỉ giới thiệu các khóa phổ biến, dựa trên Greasemonkey, và một số khóa quan trọng trong các tiện ích quản lý thông dụng.

Các khóa Metadata

@name

Tên của Userscript, bạn nên sử dụng tiếng Anh hoặc viết không dấu, và không ký tự đặc biệt, vì nó cũng được dùng làm tên tệp.

Ví dụ:

// @name  JS CSS beautify
@namespace

Tên bổ sung, nó được kết hợp với @name để tạo thành cặp khóa định danh cho Userscript đó, nếu bạn tạo ra một Userscript mới mà cặp khóa này trùng nhau, tiện ích quản lý sẽ xem nó như một bản cập nhật và thay thế nó. Vì @namespace không có nghĩa nên tác giả thường dùng để đăng URL website, một số tiện ích quản lý cũng dùng khóa này để xác định Trang chủ của script.

Ví dụ:

// @namespace  http://baivong.github.io/
@description

Giới thiệu thông tin sơ lược.

Ví dụ:

// @description  Beautify and syntax highlighting for source code javascript, json, css.
@version

Phiên bản hiện tại. Giá trị này được tiện ích quản lý sử dụng để cập nhật Userscript. Xem thêm quy chuẩn Semantic Versioning để hiểu cách viết phiên bản.

Ví dụ:

// @version  2.3.2
@icon

URL icon, ảnh đại diện cho Userscript.

Ví dụ:

// @icon  http://i39.servimg.com/u/f39/18/83/32/63/usersc10.png
@author

Tên tác giả.

Ví dụ:

// @author  Zzbaivong
@license

Tên hoặc URL đến giấy phép sử dụng script. Truy cập Choose a License để biết thêm thông tin và cách lựa chọn.

Ví dụ:

// @license  MIT
@include

Giới hạn địa chỉ trang web mà script sẽ chạy, có thể dùng biểu thức chính quy (Regular Expressions). Có thể dùng nhiều lần.

Ví dụ:

// @include  /^https?://*/*.js$/
// @include  /^https?://*/*.css$/
@match

Chức năng tương tự @include nhưng được đặt quy tắc nghiêm ngặt hơn trong cách sử dụng dấu *, không được dùng biểu thức chính quy. Xem chi tiết về Match Patterns.

Ví dụ:

// @match  http://*/*.js
// @match  https://*/*.js
// @match  http://*/*.css
// @match  https://*/*.css
@exclude

Cách dùng tương tự @include nhưng có vai trò ngược lại, nó loại trừ địa chỉ trang web mà script sẽ chạy.

Ví dụ:

// @exclude  /^https?://*/*.json$/
// @exclude  /^https?://*/*.less$/
@downloadURL

URL để cập nhật Userscript. Nếu không đặt giá trị cho khóa này, tiện ích quản lý sẽ dùng URL lúc bạn tải về để làm URL cập nhật.

Ví dụ:

// @downloadURL  https://greasyfork.org/scripts/16111-javascript-css-beautify/code/Javascript-css%20beautify.user.js
@updateURL

URL để kiểm tra thông tin cập nhật, có đuôi .meta.js, thông thường chỉ chứa Metadata Block. Nếu thông tin @version trong này mới hơn thì tiện ích quản lý sẽ tiến hành cập nhật Userscript.

Ví dụ:

// @updateURL  https://greasyfork.org/scripts/16111-javascript-css-beautify/code/Javascript-css%20beautify.meta.js
@supportURL

URL dẫn đến trang hỗ trợ, báo lỗi.

Ví dụ:

// @supportURL  https://github.com/baivong/Userscript/issues
@require

URL của thư viện javascript cần sử dụng, có thể dùng nhiều lần.

Ví dụ:

// @require  https://openuserjs.org/src/libs/baivong/beautify-js.min.js
// @require  https://openuserjs.org/src/libs/baivong/beautify-css.min.js
// @require  https://openuserjs.org/src/libs/baivong/highlight-css-js.min.js
@resource

Bổ sung thêm tài nguyên để sử dụng, có thể dùng nhiều lần. Bạn có thể truy cập thông qua API GM_getResourceText hoặc GM_getResourceURL.

Ví dụ:

// @resource  devsLogo http://i56.servimg.com/u/f56/18/59/49/93/lg110.png
@run-at

Thời điểm chạy Userscript so với trang web. Bao gồm 3 giá trị document-start, document-end và document-idle.

Ví dụ:

// @run-at  document-idle
@noframes

Ngăn không cho Userscript chạy trong thẻ nhúng như iframe. Nó không có đối số, chỉ là dùng hoặc không dùng. Nên sử dụng khóa này để tránh lỗi hiệu suất, nhất là với các trang có quảng cáo nhúng.

Ví dụ:

// @noframes
@grant

Yêu cầu cấp quyền sử dụng API đặc biệt với tiện ích quản lý, không có nó, tiện ích quản lý có thể đưa ra thông tin sai, gây lỗi. Nếu bạn không yêu cầu quyền API đặc biệt hãy đặt giá trị none. Ví dụ:

// @grant  GM_addStyle
// @grant  GM_getResourceText
@connect

Đây là khóa bổ sung khi yêu cầu API GM_xmlhttpRequest, nó xác định tên miền chứa dữ liệu cần lấy, có thể dùng nhiều lần. Bao gồm các giá trị: domain (cũng sẽ bao gồm toàn bộ sub-domain), sub-domain, IP address, localhost, self (trang mà script đang chạy), * (tất cả). Ví dụ:

// @connect  baivong.github.io
// @connect  localhost

Chú ý

Một Metadata Block tối thiểu phải có 3 khóa @name, @namespace, @grant (có tiện ích quản lý yêu cầu thêm @match, @id).
Tài nguyên từ @require và @resource chỉ được tải về một lần vào máy người dùng và sử dụng, đến khi có bản cập nhật thì nó mới tải lại.

Sau khi tạo Metadata Block, bạn đã có thể bắt đầu viết code cho nó bằng javascript ở bên dưới, sử dụng thêm API nếu cần thiết. Tuy nhiên, mức độ hỗ trợ API của mỗi tiện ích quản lý đều có vài điểm khác biệt, trong bài này mình chỉ hướng dẫn cách tạo Userscript cơ bản với javascript. Nếu bạn muốn viết nâng cao hơn thì nên tìm xem các tài liệu API của tiện ích quản lý mà bạn sử dụng.

Ví dụ:

// ==UserScript==
// @name reverse
// @namespace Zzbaivong
// @grant none
// ==/UserScript==
document.body.style.transform = "rotate(180deg)";

Bạn có thể cài trực tiếp Userscript vào trình duyệt nhân Chromium, tuy nhiên nó chỉ cho phép các khóa @name, @namespace, @description, @version, @match, @include, @exclude và một số API (không bắt buộc dùng @grant) GM_log, GM_openInTab, GM_addStyle, GM_xmlhttpRequest (chỉ trong cùng nguồn, tương đương @connect self).

Ví dụ:

// ==UserScript==
// @match http://github.com/*
// ==/UserScript==
GM_openInTab("https://github.com/baivong/Userscript");

Nguồn bài viết : https://baivong.github.io/huong-dan-viet-userscript/

Rated 4.6/5 based on 28 votes