浏览器扩展

用户脚本

用户脚本（我们也称之为「扩展」）实质上是用 JavaScript 编写的小程序。用户脚本修改或扩展一个或多个网站的功能。许多 AdGuard 用户已经熟悉 AdGuard 助手、弹窗拦截器和 AdGuard Extra 等用户脚本。

支持的应用

AdGuard 可作为用户脚本管理器以显著扩展网站功能。您可以在我们的三款产品中添加自定义脚本或管理现有脚本：AdGuard Windows 版、AdGuard Android 版和 AdGuard Mac 版。

AdGuard 以外的最佳脚本选择

这些用户脚本并非由 AdGuard 开发，因此我们无法百分之百保证它们的安全性或始终正常运作。然而，根据我们的经验，它们值得被推荐，因为它们都已经赢得了良好的声誉。

Don't track me Google

该脚本移除 Google 搜索结果中链接的 Google 跟踪功能。它加快搜索结果的加载速度，允许用户右键单击或点击复制链接 URL。

其源代码可在 GitHub 上获取。这个用户脚本可以从 GreasyFork 下载，并安装在任何基于 AdGuard CoreLibs 的应用程序中。

tinyShield

一个适用于访问韩国网站和一些国际网站的用户脚本。 tinyShield 用户脚本可以屏蔽 Ad-Shield 广告和反广告拦截功能。这个用户脚本可以安装在基于 AdGuard CoreLibs 的应用程序、Violentmonkey、Tampermonkey 以及 quoid/userscripts 中。了解更多关于 tinyShield 的信息以及如何在 GitHub 上安装它。

在哪里查看更多自定义脚本

由于用户脚本主要由爱好者创建，因此在安装时应保持谨慎。任何来源不明的脚本都有潜在风险。不过，也有大量有用的脚本。如果认真负责地选择，确实可以使网页更易于浏览。

下面我们将介绍一些最常用的用户脚本。

Userscript.Zone

Userscript.Zone 是一个网站，它允许通过输入匹配的 URL 或域名来搜索用户脚本。该网站使用方便，可信度高，因为它只显示经过审核的网页脚本。

Greasy Fork

Greasy Fork 是一个由 Stylish 创作者提供的用户脚本目录。该目录中的脚本经过审核，因此其可信度大大提高。

OpenUserJS.org

OpenUserJS.org 是一个用 nodeJS 编写的开源用户脚本目录。它没有经过审核，因此请注意可疑的脚本。

社区

如您想在用户脚本的帮助下自定义您的浏览器并有任何问题，可以在以下网站进行询问：

开发

申请许可证

如果您开发自己的用户脚本并希望测试它与 AdGuard 的工作方式，可以通过填写表单请求许可证。

兼容性

元数据块

支持的属性

不支持的属性

AdGuard 将忽略这些属性。

@unwrap

支持的 GM 函数

AdGuard 同时支持旧的 GM_ 函数和使用 GM 对象的新 GM4 API。

注意

所有列出的旧 Greasemonkey 函数都已过时，但仍受支持。

您可以在手册中找到有关 Greasemonkey API 的更多信息。

示例

// ==UserScript==
// @name            Name as shown to the user when locale is english or unknown
// @name:ru         Name as shown to the user when locale is russian
// @description     Description as shown to the user when locale is english or unknown
// @description:ru  Description as shown to the user when locale is russian
// @icon            https://myhomepage.com/myuserscript.png
// @version         1.0.0.0
// @downloadURL     https://dl.myhomepage.org/myuserscript.user.js
// @updateURL       https://dl.myhomepage.org/myuserscript.meta.js
// @homepageURL     https://myhomepage.com/myuserscript
// @include         *
// @exclude         *://website.com/*
// @resource        https://myhomepage.com/myuserscript.css
// @require         https://myhomepage.com/mylibrary.js
// @grant           property:settings
// @grant           GM_getValue
// @grant           GM_setValue
// @grant           GM_deleteValue
// @grant           GM_listValues
// @grant           GM_getResourceText
// @grant           GM_getResourceURL
// @grant           GM_addStyle
// @grant           GM_log
// @grant           GM_setClipboard
// @grant           GM_xmlhttpRequest
// @grant           unsafeWindow
// @grant           GM_info
// @grant           GM_openInTab
// @grant           GM_registerMenuCommand
// @grant           GM_addElement
// @grant           window.onurlchange
// @run-at          document-start
// ==/UserScript==
!function(){(
    console.log("I am loaded!");
)}();

Trusted Types API

AdGuard 提供一个 PolicyApi 类的实例，允许用户管理用户脚本中的 Trusted Types。

您可以使用用户脚本中的 ADG_policyApi 变量访问此类的实例。

属性

name: string —— 政策的名称（默认是 "AGPolicy"）。
isSupported: boolean —— 一个标志，指示当前浏览器是否支持 Trusted Types API。

多填充方法

ADG_policyApi.createHTML。如果不支持，请返回 input: string。
ADG_policyApi.createScript。如果不支持，请返回 input: string。
ADG_policyApi.createScriptURL。如果不支持，请返回 input: string。
ADG_policyApi.getAttributeType。如果不支持，请返回 null。
ADG_policyApi.getPropertyType。如果不支持，请返回 null。
ADG_policyApi.isHTML。如果不支持，请返回 false。
ADG_policyApi.isScript。如果不支持，请返回 false。
ADG_policyApi.isScriptURL。如果不支持，请返回 false。

其他类型

/**
 * Enum representation of the return values of the `getAttributeType` and
 * `getPropertyType` methods of the native Trusted Types API.
 *
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/getAttributeType}
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory/getPropertyType}
 */
enum TrustedType {
    HTML = 'TrustedHTML',
    Script = 'TrustedScript',
    ScriptURL = 'TrustedScriptURL',
}

// You can access it like that inside of userscript
ADG_TrustedType.HTML // "TrustedHTML"

/**
 * Isomorphic trusted value type. If a browser supports the Trusted Types API, it will be one of the enum Trusted Types
 * (`TrustedHTML`, `TrustedScript` or `TrustedScriptURL`); otherwise, it will be regular `string`.
 *
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedHTML}
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedScript}
 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/TrustedScriptURL}
 */
type TrustedValue = string | TrustedHTML | TrustedScript | TrustedScriptURL;

其他操作

/**
 * Creates a Trusted Type depending on `type`:
 * - `TrustedHTML`
 * - `TrustedScript`
 * - `TrustedScriptURL`
 * - or returns `value` if none of them is applicable.
 *
 * @param type          Trusted Type.
 * @param value         Value from which a Trusted Type is created.
 * @param createArgs    Additional arguments to be passed to the function represented by `TrustedTypePolicy`.
 * @returns             Created value.
 */
function create(
    type: TrustedType,
    value: string,
    ...createArgs: unknown[]
): TrustedValue


// Example: Creates TrustedHTML
const trustedHTML = ADG_policyApi.create(ADG_TrustedType.HTML, '<div></div>');

/**
 * Converts `value` of `attribute` into one of the Trusted Types:
 * - `TrustedHTML`
 * - `TrustedScript`
 * - `TrustedScriptURL`
 * - or returns `value` if none of them is applicable.
 *
 * @param tagName       Name of an HTML tag.
 * @param attribute     Attribute.
 * @param value         Value of an attribute to be converted.
 * @param elementNS     Element namespace. If empty, defaults to the HTML namespace.
 * @param attrNS        Attribute namespace. If empty, defaults to null.
 * @param createArgs    Additional arguments to be passed to the function represented by `TrustedTypePolicy`.
 * @returns             Converted value.
 */
function convertAttributeToTrusted(
    tagName: string,
    attribute: string,
    value: string,
    elementNS?: string,
    attrNS?: string,
    ...createArgs: unknown[]
): TrustedValue

// Example: Converts to TrustedScriptURL
const trustedScriptURL = ADG_policyApi.convertAttributeToTrusted("script", "src", 'SOME_URL');
scriptElement.setAttribute("src", trustedScriptURL);

/**
 * Converts `value` of `property` into one of the Trusted Types:
 * - `TrustedHTML`
 * - `TrustedScript`
 * - `TrustedScriptURL`
 * - or returns `value` if none of them is applicable.
 *
 * @param tagName       Name of an HTML tag.
 * @param property      Property.
 * @param value         Value of a property to be converted.
 * @param elementNS     Element namespace. If empty, defaults to the HTML namespace.
 * @param createArgs    Additional arguments to be passed to the function represented by `TrustedTypePolicy`.
 * @returns             Converted value.
 */
function convertPropertyToTrusted(
    tagName: string,
    property: string,
    value: string,
    elementNS?: string,
    ...createArgs: unknown[]
): TrustedValue

// Example: Converts to TrustedHTML
divElement.innerHTML = ADG_policyApi.convertPropertyToTrusted("div", "innerHTML", "<div></div>");

Matching SPA sites

兼容性

This section only applies to AdGuard for Windows, AdGuard for Mac, AdGuard for Android, and AdGuard for Linux with CoreLibs v1.19 or later.

Many modern websites, such as YouTube, utilize Single Page Application (SPA) capabilities. Unlike traditional web applications, the page does not reload when navigating between pages. Instead, the content is updated dynamically using JavaScript, allowing for a smoother user experience.

On such websites, a userscript is invoked only once when the @match or @include directives are matched (unless @exclude is matched). Due to the nature of SPAs, the userscript cannot be re-invoked on subsequent page changes because the global JavaScript context remains the same. To address this issue, userscripts can use the @grant window.onurlchange directive.

// ==UserScript==
// @name SPA
// @namespace spa
// @version 1.0.0
// @match https://*/*
// @grant window.onurlchange
// @run-at document-start
// ==/UserScript==

// via window.onurlchange
window.onurlchange = (event) => {
    console.log('URL changed to:', event.url);
};

// via window.addEventListener('urlchange')
window.addEventListener('urlchange', (event) => {
    console.log('URL changed to:', event.url);
});

This will allow userscripts to listen for URL changes and handle them accordingly.

注意

The urlchange event is only triggered for full URL changes, such as a change in the path or query, but not for fragment (hash) changes. Examples:

Navigation from https://example.com/page1 to https://example.com/page2 will trigger the event.
Navigation from https://example.com/page1?query=1 to https://example.com/page1?query=2 will trigger the event.
Navigation from https://example.com/page1#section1 to https://example.com/page1#section2 will NOT trigger the event.

注意

The window.onurlchange and window.addEventListener('urlchange', ...) APIs are non-standard. To use them, you must explicitly grant them in your userscript with @grant window.onurlchange.

If a website uses hash routing, userscripts can use the native DOM hashchange event:

// ==UserScript==
// @name SPA
// @namespace spa
// @version 1.0.0
// @match https://*/*
// @run-at document-start
// ==/UserScript==

// via window.onhashchange
window.onhashchange = (event) => {
    console.log(`Hash changed from "${event.oldURL}" to "${event.newURL}"`);
};

// via window.addEventListener('hashchange')
window.addEventListener('hashchange', (event) => {
    console.log(`Hash changed from "${event.oldURL}" to "${event.newURL}"`);
});

Userstyles

Userstyles allow users to change the appearance of popular websites.

AdGuard has the option to upload or create your own userstyles. This is an advanced feature, so you will need some knowledge of HTML and CSS.

支持的应用

Currently, two AdGuard apps allow you to create and manage userstyles: AdGuard for Windows (v7.19 or later) and AdGuard for Mac (v2.16 or later). We also plan to implement this new feature in AdGuard for Android v4.8 in the nearest future.

This is an experimental feature, so if you encounter any problems while adding or creating a userstyle, please contact our support team at support@adguard.com.

How to set up a userstyle in AdGuard

You can download userstyles from various websites. One of the most popular userstyle websites is https://userstyles.world/, which we will use as an example for the following instructions on how to set up the userstyle in AdGuard.

Follow the link above and choose the userstyle you like
Click Copy next to the userstyle address
Open AdGuard settings → Extensions
Press the [+] button and paste the userstyle link
完成！

If you’re familiar with CSS rules, you can also create userstyles yourself.

注意

We don’t support userstyles that contain @var or @advanced in the metadata. AdGuard also doesn’t support @preprocessor without the default value.

Open AdGuard settings → Extensions
Press the [+] button and choose the Create userstyle option. A new window will appear on your screen
To create a userstyle, first write the title with metadata, for example
```
/* ==UserStyle==
@name New userstyle
@version 1.0
==/UserStyle== */
```

Write the CSS part after the meta data. AdGuard supports website domain names matching (@-moz-document domain(…), …). 例如：

body {
  background: gray;
  }

Or:

@-moz-document domain('example.org'),
domain('example.net'),
domain('example.com') body {
  background: gray;
  }

Once you’re finished, press Save and Close. Your new userstyle has been successfully added to AdGuard

示例

/* ==UserStyle==
@name         Example userstyle
@namespace    https://example.org/userstyle
@homepageURL  https://example.org/userstyle
@version      1.0.0
@license      Other
@description  This is an example
@author       example
@preprocessor default
==/UserStyle== */
@-moz-document regexp("https?\:\/\/(www\.)?example\.(org|com).*") {
    body {
        background-color: #000000 !important;
    }
}

浏览器扩展

用户脚本

推荐的 AdGuard 脚本

AdGuard Extra

AdGuard 弹窗拦截器

AdGuard 助手（旧版）

Disable AMP

AdGuard 以外的最佳脚本选择

Don't track me Google

tinyShield

在哪里查看更多自定义脚本

Userscript.Zone

Greasy Fork

OpenUserJS.org

社区

开发

申请许可证

兼容性

元数据块

支持的属性

不支持的属性

支持的 GM 函数

示例

Trusted Types API

属性

多填充方法

其他类型

其他操作

Matching SPA sites

Userstyles

How to set up a userstyle in AdGuard

示例

用户脚本​

推荐的 AdGuard 脚本​

AdGuard Extra​

AdGuard 弹窗拦截器​

AdGuard 助手（旧版）​

Disable AMP​

AdGuard 以外的最佳脚本选择​

Don't track me Google​

tinyShield​

在哪里查看更多自定义脚本​

Userscript.Zone​

Greasy Fork​

OpenUserJS.org​

社区​

开发​

申请许可证​

兼容性​

元数据块​

支持的属性​

不支持的属性​

支持的 GM 函数​

示例​

Trusted Types API​

属性​

多填充方法​

其他类型​

其他操作​

Matching SPA sites​

Userstyles​

How to set up a userstyle in AdGuard​

示例​

用户脚本

推荐的 AdGuard 脚本

AdGuard Extra

AdGuard 弹窗拦截器

AdGuard 助手（旧版）

Disable AMP

AdGuard 以外的最佳脚本选择

Don't track me Google

tinyShield

在哪里查看更多自定义脚本

Userscript.Zone

Greasy Fork

OpenUserJS.org

社区

开发

申请许可证

兼容性

元数据块

支持的属性

不支持的属性

支持的 GM 函数

示例

Trusted Types API

属性

多填充方法

其他类型

其他操作

Matching SPA sites

Userstyles

How to set up a userstyle in AdGuard

示例