Usage

The Declarative Content API allows you to show your extension's
page action depending on the URL of a web page and
the CSS selectors its content matches, without needing to take a host permission or
inject a content script. Use the
activeTab permission in order to be able
to interact with a page after the user clicks on your page action.

If you need more precise control over when your page action appears or
you need to change its appearance to match the current tab before the
user clicks on it, you'll have to keep using the pageAction API.

The PageStateMatcher matches web pages if and only
if all listed criteria are met. The following rule would show a page
action for pages on https://www.google.com/ when a
password field is present on it:

Note: You should always register or unregister rules in bulk
rather than individually because each of these operations recreates internal
data structures. This re-creation is computationally expensive but facilitates
a faster matching algorithm.

Combine the above rule with the activeTab
permission to create an extension that doesn't need any install-time
permissions but can invite the user to click its page action on
relevant pages and can run on those pages when the user clicks the
page action.

CSS conditions only match displayed elements: if an element that matches your
selector is display:none or one of its parent elements
is display:none, it doesn't cause the condition to match. Elements
styled with visibility:hidden, positioned off-screen, or hidden by
other elements can still make your condition match.

RequestContentScriptInstanceType

PageStateMatcher

Matches if the condition of the UrlFilter are fulfilled for the top-level URL of the page.

string

(optional)
hostContains

Matches if the host name of the URL contains a specified string. To test whether a host name component has a prefix 'foo', use hostContains: '.foo'. This matches 'www.foobar.com' and 'foo.com', because an implicit dot is added at the beginning of the host name. Similarly, hostContains can be used to match against component suffix ('foo.') and to exactly match against components ('.foo.'). Suffix- and exact-matching for the last components need to be done separately using hostSuffix, because no implicit dot is added at the end of the host name.

string

(optional)
hostEquals

Matches if the host name of the URL is equal to a specified string.

string

(optional)
hostPrefix

Matches if the host name of the URL starts with a specified string.

string

(optional)
hostSuffix

Matches if the host name of the URL ends with a specified string.

string

(optional)
pathContains

Matches if the path segment of the URL contains a specified string.

string

(optional)
pathEquals

Matches if the path segment of the URL is equal to a specified string.

string

(optional)
pathPrefix

Matches if the path segment of the URL starts with a specified string.

string

(optional)
pathSuffix

Matches if the path segment of the URL ends with a specified string.

string

(optional)
queryContains

Matches if the query segment of the URL contains a specified string.

string

(optional)
queryEquals

Matches if the query segment of the URL is equal to a specified string.

string

(optional)
queryPrefix

Matches if the query segment of the URL starts with a specified string.

string

(optional)
querySuffix

Matches if the query segment of the URL ends with a specified string.

string

(optional)
urlContains

Matches if the URL (without fragment identifier) contains a specified string. Port numbers are stripped from the URL if they match the default port number.

string

(optional)
urlEquals

Matches if the URL (without fragment identifier) is equal to a specified string. Port numbers are stripped from the URL if they match the default port number.

string

(optional)
urlMatches

Matches if the URL (without fragment identifier) matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string

(optional)
originAndPathMatches

Matches if the URL without query segment and fragment identifier matches a specified regular expression. Port numbers are stripped from the URL if they match the default port number. The regular expressions use the RE2 syntax.

string

(optional)
urlPrefix

Matches if the URL (without fragment identifier) starts with a specified string. Port numbers are stripped from the URL if they match the default port number.

string

(optional)
urlSuffix

Matches if the URL (without fragment identifier) ends with a specified string. Port numbers are stripped from the URL if they match the default port number.

array of string

(optional)
schemes

Matches if the scheme of the URL is equal to any of the schemes specified in the array.

array of integer or array of integer

(optional)
ports

Matches if the port of the URL is contained in any of the specified port lists. For example [80, 443, [1000, 1200]] matches all requests on port 80, 443 and in the range 1000-1200.

array of string

(optional)
css

Matches if all of the CSS selectors in the array match displayed elements in a frame with the same origin as the page's main frame. All selectors in this array must be compound selectors to speed up matching. Note that listing hundreds of CSS selectors or CSS selectors that match hundreds of times per page can still slow down web sites.

boolean

(optional)
isBookmarked

Since Chrome 45.

Matches if the bookmarked state of the page is equal to the specified value. Requres the bookmarks permission.

ShowPageAction

Declarative event action that shows the extension's page action while the corresponding conditions are met. This action can be used without host permissions, but the extension must have a page action. If the extension takes the activeTab permission, a click on the page action will grant access to the active tab.

SetIcon

Since Chrome 39.

Declarative event action that sets the n-dip square icon for the extension's page action or browser action while the corresponding conditions are met. This action can be used without host permissions, but the extension must have page or browser action.

Exactly one of imageData or path must be specified. Both are dictionaries mapping a number of pixels to an image representation. The image representation in imageData is anImageData object, for example from a <canvas> element, while the image representation in path is the path to an image file relative to the extension's manifest. If scale screen pixels fit into a device-independent pixel, the scale * n icon will be used. If that scale is missing, another image will be resized to the needed size.

properties

ImageData or object

(optional)
imageData

Either an ImageData object or a dictionary {size -> ImageData} representing icon to be set. If the icon is specified as a dictionary, the actual image to be used is chosen depending on screen's pixel density. If the number of image pixels that fit into one screen space unit equals scale, then image with size scale * n will be selected, where n is the size of the icon in the UI. At least one image must be specified. Note that 'details.imageData = foo' is equivalent to 'details.imageData = {'16': foo}'

RequestContentScript

Since Chrome 38.

Declarative event action that injects a content script.

WARNING: This action is still experimental and is not supported on stable builds of Chrome.

properties

array of string

(optional)
css

Names of CSS files to be injected as a part of the content script.

array of string

(optional)
js

Names of Javascript files to be injected as a part of the content script.

boolean

(optional)
allFrames

Whether the content script runs in all frames of the matching page, or only the top frame. Default is false.

boolean

(optional)
matchAboutBlank

Whether to insert the content script on about:blank and about:srcdoc. Default is false.