public final class Prefixer extends Object implements DependentPlugin
Which vendor prefixes are actually used depends of the browser versions that you want to support. You can manually specify
specific browser versions, last N versions, or just the latest browser version by utilizing the SupportMatrix
returned
by the support()
method. In most cases however the default set of browser versions to support is adequate, as achieved
by using the defaultBrowserSupport()
constructor method.
Browser and prefix data is seamlessly handled via updates from the caniuse.com data. To update to the latest data, see the section named "Scripts" in the main readme file.
This plugin integrates well with existing CSS. If all required prefixes are already present then nothing will be changed by
default. You can optionally have unnecessary prefixes removed via the prune(boolean)
method. You can also optionally
have all existing vendor-prefixed declarations rearranged to be before the unprefixed version via the rearrange(boolean)
method.
This doesn't automatically refine declarations or other refinables to check if they might need prefixes. This will only handle
prefixes if declarations, at-rules, and selectors have already been refined. If you want to ensure that every thing gets
checked then register AutoRefine#everything()
or StandardValidation
. Either must be registered before
this plugin. See the main readme doc for more information on refinement.
Important: Check the list of what's actually supported in the readme or prefix-info.yaml
file.
Even if a prefix is supported, there may still be a few edge cases where a particular prefixable value is not automatically handled. If you are using bleeding-edge syntax or prefixable features in a non-typical way then please double check the CSS output for the proper behavior.
Also note that some very old browser versions utilizing non-standard syntax may not currently be handled. For example, the legacy linear-gradient syntax is not currently handled because many browser versions have passed since it was last used.
Example usage:
Prefixer prefixing = Prefixer.customBrowserSupport();
prefixing.support().last(Browser.FIREFOX, 3);
prefixing.support().last(Browser.CHROME, 2);
prefixing.support().latest(Browser.SAFARI);
prefixing.support().browser(Browser.IE, 9);
prefixing.support().browser(Browser.IE, 10);
prefixing.prune(true);
prefixing.rearrange(true);
AutoRefine refinement = AutoRefine.everything();
Omakase.source(cssSource).use(refinement).use(prefixing).process();
In some cases at-rules scoped by a prefixed name may have non-applicable prefixes added. For example:
@keyframes animation {
from { transform: rotate(0deg) }
from { transform: rotate(360deg) }
}
after prefixing could result in
@-webkit-keyframes animation {
from { -webkit-transform: rotate(0deg); -ms-transform: rotate(0deg); transform: rotate(0deg) }
from { -webkit-transform: rotate(360deg); -ms-transform: rotate(360deg); transform: rotate(360deg) }
}
Notice the -ms-transform
is most likely unnecessary as it is within a -webkit-
prefixed at-rule. The PrefixCleaner
plugin can be utilized to remove such prefixed declarations inside of prefixed at-rules. The plugin must be
registered after this one:
Omakase.source(input)
.add(Prefixer.defaultBrowserSupport())
.add(PrefixPruner.prunePrefixedAtRules())
.process()
Modifier and Type | Method and Description |
---|---|
void |
atRule(AtRule atRule)
Subscription method - do not invoke directly.
|
static Prefixer |
customBrowserSupport()
Creates a new instance of the
Prefixer plugin with no default browser version support. |
static Prefixer |
customBrowserSupport(SupportMatrix support)
Creates a new instance of the
Prefixer plugin using the given SupportMatrix . |
void |
declaration(Declaration declaration)
Subscription method - do not invoke directly.
|
static Prefixer |
defaultBrowserSupport()
Creates a new instance of the
Prefixer plugin with default browser version support levels: IE10+, latest
versions of Safari and IE Mobile, last 3 versions of Firefox, Chrome, Edge and Android and last 6 versions of IOS Safari. |
void |
dependencies(PluginRegistry registry)
Registers plugin dependencies.
|
void |
function(FunctionValue function)
Subscription method - do not invoke directly.
|
void |
keyword(KeywordValue keyword)
Subscription method - do not invoke directly.
|
boolean |
prune()
Gets whether unnecessary prefixed declarations can be pruned.
|
Prefixer |
prune(boolean prune)
Whether we should remove prefixed declarations/at-rules if they are not required for the supported browser versions.
|
void |
pseudoElementSelector(PseudoElementSelector selector)
Subscription method - do not invoke directly.
|
boolean |
rearrange()
Gets whether prefixed declarations can be rearranged.
|
Prefixer |
rearrange(boolean rearrange)
Whether this plugin should rearranged the declarations/at-rules so that the unprefixed version always comes last.
|
SupportMatrix |
support()
Gets the
SupportMatrix instance which can be used to indicate which browser versions are supported. |
public SupportMatrix support()
SupportMatrix
instance which can be used to indicate which browser versions are supported.SupportMatrix
instance.public Prefixer rearrange(boolean rearrange)
This only works for at-rules if the at-rules are contiguous.
rearrange
- Whether we should moved the unprefixed version last.public boolean rearrange()
public Prefixer prune(boolean prune)
This only works for at-rules if the at-rules are contiguous.
prune
- Whether we should remove unnecessary prefixed declarations.public boolean prune()
public void dependencies(PluginRegistry registry)
DependentPlugin
Any plugins you add to the registry in this method will be ordered before this plugin itself.
Keep in mind that only one instance of a plugin can be added in a single parsing operation. You can use PluginRegistry.require(Class)
, PluginRegistry.require(Class, Supplier)
and PluginRegistry.retrieve(Class)
to assist in scenarios where a plugin instance may have already been added.
Dependencies to include can range from refinement dependencies such as SelectorPlugin
and MediaPlugin
to
other custom plugins.
dependencies
in interface DependentPlugin
registry
- The PluginRegistry
instance.PluginRegistry.require(Class)
,
PluginRegistry.require(Class, Supplier)
,
PluginRegistry.retrieve(Class)
public void declaration(Declaration declaration)
declaration
- The declaration instance.public void function(FunctionValue function)
function
- The function instance.public void keyword(KeywordValue keyword)
keyword
- The keyword instance.public void atRule(AtRule atRule)
atRule
- The atRule instance.public void pseudoElementSelector(PseudoElementSelector selector)
selector
- The selector instance.public static Prefixer defaultBrowserSupport()
Prefixer
plugin with default browser version support levels: IE10+, latest
versions of Safari and IE Mobile, last 3 versions of Firefox, Chrome, Edge and Android and last 6 versions of IOS Safari.Prefixer
instance.rearrange(boolean)
,
prune(boolean)
public static Prefixer customBrowserSupport()
Prefixer
plugin with no default browser version support. Specify which versions to
support via the support()
method.Prefixer
instance.rearrange(boolean)
,
prune(boolean)
public static Prefixer customBrowserSupport(SupportMatrix support)
Prefixer
plugin using the given SupportMatrix
.support
- Use this SupportMatrix
instance.Prefixer
instance.rearrange(boolean)
,
prune(boolean)
Copyright (c) 2019, Salesforce.com, Inc. All rights reserved. Licensed under the BSD 3-Clause license. For full license text, see the LICENSE file in the repository.