Framework

Safari Extensions JS

Extend the browsing experience with injected scripts and style sheets for web content, custom buttons in the Safari toolbar, and contextual menu items.

Overview

Safari extensions provide a way for you to add features to the Safari browser and extend the browsing experience. Extensions can add custom buttons to the Safari toolbar, create additional bars, add contextual menu items, display content, and inject scripts and style sheets into webpages.

Topics

Classes

SafariActivateEvent

Instances of the SafariActivateEvent class are used to notify listeners when a tab or window is activated.

SafariAppExtension

The SafariAppExtension class is used by a content script to represent your extension; an instance of the class is accessible as safari.extension.

SafariAppExtensionPage

The SafariAppExtensionPage class represents a web content area; an instance of the class is accessible as safari.self. Your extension can listen for events, such as SafariExtensionMessageEvent, using safari.self.addEventListener. See “Registering Event Listeners” in SafariEventTarget.

SafariApplication

The SafariApplication class allows a Safari extension to interact with the application's SafariBrowserWindow and SafariBrowserTab objects.

SafariAvailableEvent

Instances of the SafariAvailableEvent class are used to notify listeners when Reader is available.

SafariBeforeNavigateEvent

Instances of the SafariBeforeNavigateEvent class are used to notify listeners when the user navigates to a new page, before the page is loaded. You can use the preventDefault method to prevent the new page from loading.

SafariBeforeSearchEvent

The SafariBeforeSearchEvent event fires before the Smart Search Field performs a search, allowing you to intercept the query and execute an alternate task. SafariBeforeSearchEvent can be used with SafariBeforeNavigateEvent to determine what the user intends to do in the Smart Search Field.

SafariBrowserTab

Instances of the SafariBrowserTab class represent tabs in the user’s browser window.

SafariBrowserWindow

Instances of the SafariBrowserWindow class represent browser windows. Each window contains one or more tabs, which display web content.

SafariCloseEvent

Instances of the SafariCloseEvent class are used to notify listeners when a tab or window is closed.

SafariCommandEvent

Instances of the SafariCommandEvent class represent events being used to send a command.

SafariContentBrowserTabProxy

Instances of the SafariContentBrowserTabProxy class serve as proxy objects, allowing scripts injected in the web content to communicate with SafariBrowserTab objects and the rest of the extension.

SafariContentExtension

The SafariContentExtension class represents your extension to scripts running inside the web content; an instance of the class is accessible as safari.extension. Its counterpart class outside of the web content is SafariExtension.

SafariContentNamespace

The SafariContentNamespace class is a namespace that provides access to the Safari Extensions functionality inside of a web content area.

SafariContentReader

The SafariContentReader class allows you to inject content into the Reader view.

SafariContentWebPage

Instances of the SafariContentWebPage class represent a web content area.

SafariDeactivateEvent

Instances of the SafariDeactivateEvent class are used to notify listeners when a browser tab or a browser window is deactivated.

SafariEvent

The SafariEvent class is a base class used to encapsulate events. Developers who are familiar with DOM events will notice many similarities in design and behavior.

SafariEventTarget

The SafariEventTarget class serves as a base class for all objects that participate in the event-dispatch hierarchy.

SafariExtension

A SafariExtension instance represents your extension outside of the web content; an instance of the class is accessible as safari.extension. The counterpart class to SafariExtension for scripts running within the web content is SafariContentExtension.

SafariExtensionBar

Instances of the SafariExtensionBar class represent a bar that your extension provides. An extension can add any number of bars to Safari. Adding bars is optional.

SafariExtensionCompanion

A SafariExtensionCompanion object is an app extension for your macOS app that receives and responds to secure messages from your Safari extension. Sending a message to a Safari extension companion is similar to sending a message to an injected script; simply call the dispatchMessage method on the extension companion object. See Communicating with your OS X App for more information on extension companions.

SafariExtensionContextMenu

Instances of the SafariExtensionContextMenu class represent a contextual menu that is populated by the extension. Safari displays the contents of this menu as part of its contextual menu.

SafariExtensionContextMenuEvent

Instances of the SafariExtensionContextMenuEvent class are used to notify listeners when a context menu is about to be displayed.

SafariExtensionContextMenuItem

Instances of the SafariExtensionContextMenuItem class represent individual menu items within an extension’s context menu.

SafariExtensionContextMenuItemCommandEvent

Instances of the SafariExtensionContextMenuItemCommandEvent class are used to send command events from a context menu item.

SafariExtensionContextMenuItemValidateEvent

Instances of the SafariExtensionContextMenuItemValidateEvent class are used to notify listeners when a context menu is about to be displayed.

SafariExtensionGlobalPage

Safari extensions have a global page, represented by the SafariExtensionGlobalPage class. The global page is loaded once when the extension is loaded, but it is never displayed to the user. It can contain resources such as scripts, images, and HTML content.

SafariExtensionMenu

The SafariExtensionMenu class represents menus.

SafariExtensionMenuItem

The SafariExtensionMenuItem class represents items in a menu.

SafariExtensionMessageEvent

Instances of the SafariExtensionMessageEvent encapsulate a message being passed. Message passing is the only way to communicate information from inside the web content area to scripts running outside of it, and vice versa.

SafariExtensionPopover

The SafariExtensionPopover class represents popovers. You use popovers to present information temporarily. The popover content is layered on top of the existing web content in a special type of window.

SafariExtensionPopoverEvent

Instances of the SafariExtensionPopoverEvent class are used to notify listeners when a popover is about to be displayed.

SafariExtensionSecureSettings

The SafariExtensionSecureSettings class provides a place for your extension to securely store settings that should persist between sessions. You interact with it in exactly the same way as you interact with the SafariExtensionSettings class.

SafariExtensionSettings

The SafariExtensionsSettings class provides a place for your extension to store settings that should persist between sessions.

SafariExtensionSettingsChangeEvent

Instances of the SafariExtensionsSettingsChangeEvent class are used to provide a description of a change made to the extension’s settings. A settings change event is sent when your extension changes a setting as well as when a setting is changed outside your extension (for example, a setting changed in the Safari preferences).

SafariExtensionToolbarItem

Instances of the SafariExtensionToolbarItem represent items that your extension adds to the Safari toolbar. Users can select which toolbar items are shown by selecting Customize Toolbar in the same way that they can add and remove toolbar items provided by Safari.

SafariNamespace

The SafariNamespace class is a namespace that provides access to the Safari Extensions functionality outside of the web content area.

SafariNavigateEvent

Instances of the SafariNavigateEventClassRef class are used to notify listeners when the user navigates to a new webpage.

SafariOpenEvent

Instances of the SafariOpenEvent class are used to notify listeners when a tab or window is opened.

SafariPrivateBrowsing

The SafariPrivateBrowsing class allows you to determine whether Safari currently has Private Browsing enabled. Private Browsing mode disables the ability for Safari to store cookies, browsing history, search history, caches, and Autofill information. If Private Browsing is enabled, you should make efforts not to track the user’s browsing behavior and respect their decision to browse privately.

SafariReader

Reader is a Safari feature that allows users to read online articles in a continuous, clutter-free view, with no ads or visual distractions. Reader concatenates multipage articles into a single scrolling pane.

SafariValidateEvent

Instances of the SafariValidateEvent class encapsulate a validate event. User interface elements such as contextual menu items and toolbar buttons send a validate event when they are about to display. You can prevent the element from displaying by listening for validate events and marking the element as disabled.

SafariWebPageProxy

Instances of the SafariWebPageProxy class serve as a proxy objects, allowing objects outside of the web content to communicate with the SafariContentWebPage object.