87
Element definitionis a process of adding acustom element definitionp652
to theCustomElementsRegistryp653
. This is accomplished by the
define()p654
method. When invoked, thedefine(name, constructor, options)method must run these steps:
1. IfIsConstructor
(constructor) is false, then throw aTypeError
and abort these steps.
2. Ifnameis not avalid custom element namep652
, then throw a"SyntaxError"
DOMException
and abort these steps.
3. If thisCustomElementsRegistryp653
contains an entry withnamep652
name, then throw a"NotSupportedError"
DOMException
and abort these steps.
4. If thisCustomElementsRegistryp653
contains an entry withconstructorp652
constructor, then throw a"NotSupportedError"
DOMException
and abort these steps.
5. LetlocalNamebename.
6. Letextendsbe the value of theextendsmember ofoptions, or null if no such member exists.
7. Ifextendsis not null, then:
1. Ifextendsis avalid custom element namep652
, then throw a"NotSupportedError"
DOMException
.
2. If theelement interface
forextendsand theHTML namespacep97
isHTMLUnknownElementp113
(e.g., ifextendsdoes not
indicate an element definition in this specification), then throw a"NotSupportedError"
DOMException
.
3. SetlocalNametoextends.
8. LetobservedAttributesIterablebeGet
(constructor, "observedAttributes"). Rethrow any exceptions.
9. IfobservedAttributesIterableis undefined, then letobservedAttributesbe an emptysequence<DOMString>. Otherwise, let
observedAttributesbe the result ofconverting
observedAttributesIterableto asequence<DOMString>. Rethrow any exceptions.
10. LetprototypebeGet
(constructor, "prototype"). Rethrow any exceptions.
11. IfType
(prototype) is not Object, then throw aTypeError
exception.
12. LetconnectedCallbackbeGet
(prototype, "connectedCallback"). Rethrow any exceptions.
13. IfconnectedCallbackis not undefined, andIsCallable
(connectedCallback) is false, then throw aTypeError
exception.
14. LetdisconnectedCallbackbeGet
(prototype, "disconnectedCallback"). Rethrow any exceptions.
15. IfdisconnectedCallbackis not undefined, andIsCallable
(disconnectedCallback) is false, then throw aTypeError
exception.
16. LetattributeChangedCallbackbeGet
(prototype, "attributeChangedCallback"). Rethrow any exceptions.
17. IfattributeChangedCallbackis not undefined, andIsCallable
(attributeChangedCallback) is false, then throw aTypeError
exception.
window.customElementsp653 .definep654(name,constructor, { extends:baseLocalName})
Defines a newcustom elementp651
, mapping the given name to the given constructor as acustomized built-in elementp651
for theelement
typep43
identified by the suppliedbaseLocalName. A"NotSupportedError"
DOMException
will be thrown upon trying to extend a
custom elementp651
or an unknown element.
window.customElementsp653 .getp655(name)
Retrieves thecustom element constructorp651
defined for the givennamep652
. Returns undefined if there is nocustom element
definitionp652
with the givennamep652
.
window.customElementsp653 .whenDefinedp655(name)
Returns a promise that will be fulfilled when acustom elementp651
becomes defined with the given name. (If such acustom elementp651
is already defined, the returned promise will be immediately fulfilled.) Returns a promise rejected with a"SyntaxError"
DOMException
if not given avalid custom element namep652
.
654
C# Image: Save or Print Document and Image in Web Viewer or image, you can easily save the changes to DLL Library, including documents TIFF, PDF, Excel, Word string fileName = Request.Form["saveFileName"]; string fid
extract data from pdf to excel online; export excel to pdf form
78
18. Letdefinitionbe a newcustom element definitionp652
withnamep652
name,local namep652
localName,constructorp652
constructor,
prototypep652
prototype,observed attributesp652
observedAttributes, andlifecycle callbacksp653
connectedCallback,
disconnectedCallback, andattributeChangedCallback(stored by their corresponding name).
19. Adddefinitionto thisCustomElementsRegistryp653
.
20. Letdocumentbe thisCustomElementsRegistryp653
'srelevant global objectp837
'sDocumentobjectp748
.
21. Letupgrade candidatesbe all elements that areshadow-including descendants
ofdocument, whose namespace is theHTML
namespacep97
and whose local name islocalName, inshadow-including tree order
. Additionally, ifextendsis non-null, only include
elements that have an attribute namedisp651
whose value isname.
22. For each elementelementinupgrade candidates,enqueue a custom element upgrade reactionp658
givenelementanddefinition.
23. If thisCustomElementsRegistryp653
'swhen-defined promise mapp653
contains an entry with keyname:
1. Letpromisebe the value of that entry.
2. Resolvepromisewith undefined.
3. Delete the entry with keynamefrom thisCustomElementsRegistryp653
'swhen-defined promise mapp653
.
When invoked, theget(name)method must run these steps:
1. If thisCustomElementsRegistryp653
contains an entry withnamep652
name, then return that entry'sconstructorp652
.
2. Otherwise, return undefined.
When invoked, thewhenDefined(name)method must run these steps:
1. Ifnameis not avalid custom element namep652
, then return a new promise rejected with a"SyntaxError"
DOMException
and abort
these steps.
2. If thisCustomElementsRegistryp653
contains an entry withnamep652
name, then return a new promise resolved with undefined and
abort these steps.
3. Letmapbe thisCustomElementsRegistryp653
'swhen-defined promise mapp653
.
4. Ifmapdoes not contain an entry with keyname, create an entry inmapwith keynameand whose value is a new promise.
5. Letpromisebe the value of the entry inmapwith keyname.
6. Returnpromise.
ThewhenDefined()p655
method can be used to avoid performing an action until all appropriatecustom elementsp651
aredefined
. In
this example, we combine it with the:definedp667
pseudo-class to hide a dynamically-loaded article's contents until we're sure that all
of theautonomous custom elementsp651
it uses are defined.
articleContainer.hidden = true;
fetch(articleURL)
.then(response => response.text())
.then(text => {
articleContainer.innerHTML = text;
return Promise.all(
[...articleContainer.querySelectorAll(":not(:defined)")]
.map(el => customElements.whenDefined(el.localName))
);
})
.then(() => {
articleContainer.hidden = false;
});
Example
655
76
Toupgrade an element, given as input acustom element definitionp652
definitionand an elementelement, run the following steps:
1. Addelementto the end ofdefinition'sconstruction stackp653
.
2. LetCbedefinition'sconstructorp652
.
3. LetconstructResultbeConstruct
(C).
4. Removeelementfrom the end ofdefinition'sconstruction stackp653
.
5. IfconstructResultis an abrupt completion, then returnconstructResult(i.e., rethrow the exception).
6. IfSameValue
(constructResult.[[value]],element) is false, then throw an"InvalidStateError"
DOMException
and terminate these
steps.
7. Setelement'scustom element state
to "customized".
8. For eachattributeinelement'sattribute list
, in order,enqueue a custom element callback reactionp657
withelement, callback name
"attributeChangedCallback", and an argument list containingattribute's local name, null,attribute's value, andattribute's
namespace.
9. Ifelementis currentlyin a shadow-including document
, thenenqueue a custom element callback reactionp657
withelement, callback
name "connectedCallback", and an empty argument list.
Totry to upgrade an element, given as input an elementelement, run the following steps:
1. Letdocumentbeelement'snode document
.
2. Letisbe the value of the attribute inelement'sattribute list
whose qualified name is "isp651
", if any such attribute exists, or null
otherwise.
3. Letdefinitionbe the result oflooking up a custom element definitionp653
givendocument,element's namespace,element's local name,
andis.
4. Ifdefinitionis not null, thenenqueue a custom element upgrade reactionp658
givenelementanddefinition.
Acustom elementp651
possesses the ability to respond to certain occurrences by running author code:
• Whenupgradedp656
, itsconstructorp651
is run.
• When it isinserted
in a shadow-including document
, itsconnectedCallbackis run.
• When it isin a shadow-including document
andremoved
, itsdisconnectedCallbackis run.
• When any of its attributes arechanged
,appended
,removed
, orreplaced
, itsattributeChangedCallbackis run.
We call these reactions collectivelycustom element reactions.
The way in whichcustom element reactionsp656
are invoked is done with special care, to avoid running author code during the middle of delicate
operations. Effectively, they are delayed until "just before returning to user script". This means that for most purposes they appear to execute
synchronously, but in the case of complicated composite operations (likecloning
, orrange
manipulation), they will instead be delayed until after all
the relevant user agent processing steps have completed, and then run together as a batch.
Additionally, the precise ordering of these reactions is managed via a somewhat-complicated stack-of-queues system, described below. The
intention behind this system is to guarantee thatcustom element reactionsp656
always are invoked in the same order as their triggering actions, at
least within the local context of a singlecustom elementp651
. (Becausecustom element reactionp656
code can perform its own mutations, it is not
possible to give a global ordering guarantee across multiple elements.)
This can occur ifCconstructs another instance of the same custom element before callingsuper(), or ifCuses JavaScript's
return-override feature to return an arbitrary object from the constructor.
Note
4.13.5Upgrades
4.13.6 Custom element reactions
656
57
Eachunit of related similar-origin browsing contextsp752
has acustom element reactions stack, which is initially empty. Each item in the stack is
anelement queue, which is initially empty as well; theelement queuep657
at the top of the stack is called thecurrent element queue. Each item in
anelement queuep657
is an element. (The elements are not necessarilycustomyet, since this queue is used forupgradesp656
as well.)
All elements have an associatedcustom element reaction queue, initially empty. Each item in thecustom element reaction queuep657
is of one of
two types:
• Anupgrade reaction, which willupgradep656
the custom element and contains acustom element definitionp652
; or
• Acallback reaction, which will call a lifecycle callback, and contains a callback function as well as a list of arguments.
This is all summarised in the following schematic diagram:
custom element
reactions stack
⋯
element queue
<x-a>
<x-b>
<x-c>
⋯
custom element reaction queue
Upgrade
Attribute
changed
Attribute
changed
Connected
Toenqueue a custom element callback reaction, given acustom elementp651
element, a callback namecallbackName, and a list of arguments
args, run the following steps:
1. Letdocumentbeelement'snode document
.
2. Ifdocumentdoes not have abrowsing contextp748
, then abort these steps.
3. Letregistrybedocument'sassociatedWindowp748
'sCustomElementsRegistryp653
object.
4. Letdefinitionbe the entry inregistrywithnamep652
equal toelement's local name.
5. Letcallbackbe the value of the entry indefinition'slifecycle callbacksp653
with keycallbackName.
6. Ifcallbackis undefined, then abort these steps.
7. IfcallbackNameis "attributeChangedCallback", then:
1. LetattributeNamebe the first element ofargs.
2. Ifdefinition'sobserved attributesp652
does not containattributeName, then abort these steps.
8. Add a newcallback reactionp657
toelement'scustom element reaction queuep657
, with callback functioncallbackand argumentsargs.
9. Addelementto thecurrent element queuep657
.
This algorithm can only be called when such a definition exists.
Note
657
70
Toenqueue a custom element upgrade reaction, given an elementelementandcustom element definitionp652
definition, run the following steps:
1. Add a newupgrade reactionp657
toelement'scustom element reaction queuep657
, withcustom element definitionp652
definition.
2. Addelementto thecurrent element queuep657
.
Toinvoke custom element reactionsin anelement queuep657
queue, run the following steps:
1. For eachcustom elementp651
elementinqueue:
1. Letreactionsbeelement'scustom element reaction queuep657
.
2. Repeat untilreactionsis empty:
1. Remove the first element ofreactions, and letreactionbe that element. Switch onreaction's type:
↪
upgrade reactionp657
Upgradep656
elementusingreaction'scustom element definitionp652
.
↪
callback reactionp657
Invoke
reaction's callback function withreaction's arguments, and withelementas thecallback this
value
.
If this throws any exception, thenreport the exceptionp840
.
To ensurecustom element reactionsp656
are triggered appropriately, we introduce the[CEReactions]IDLextended attribute. It indicates that the
relevant algorithm is to be supplemented with additional steps in order to appropriately track and invokecustom element reactionsp656
.
The[CEReactions]p658
extended attribute must take no arguments, and must not appear on anything other than an operation, attribute, setter, or
deleter. Additionally, it must not appear on readonly attributes, unless the readonly attribute is also annotated with[PutForwards].
Operations, attributes, setters, or deleters annotated with the[CEReactions]p658
extended attribute must run the following steps surrounding the
main algorithm specified for the operation, setter, deleter, or for the attribute's setter:
Before executing the algorithm's steps
Push a newelement queuep657
onto thecustom element reactions stackp657
.
After executing the algorithm's steps
Pop theelement queuep657
from thecustom element reactions stackp657
, andinvoke custom element reactionsp658
in that queue.
4.14 Common idioms without dedicated elements
The main content of a page — not including headers and footers, navigation links, sidebars, advertisements, and so forth — can be marked up in a
variety of ways, depending on the needs of the author.
The simplest solution is to not mark up the main content at all, and just leave it as implicit. Another way to think of this is that thebodyp156
elements
marks up the main content of the page, and the bits that aren't main content are excluded through the use of more appropriate elements like
asidep165
andnavp162
.
The intent behind this extended attribute is somewhat subtle. One way of accomplishing its goals would be to say that every operation,
attribute, setter, and deleter on the platform should have these steps inserted, and to allow implementers to optimize away unnecessary
cases (where no DOM mutation is possible that could causecustom element reactionsp656
to occur).
However, in practice this imprecision could lead to non-interoperable implementations ofcustom element reactionsp656
, as some
implementations might forget to invoke these steps in some cases. Instead, we settled on the approach of explicitly annotating all relevant
IDL constructs, as a way of ensuring interoperable behavior and helping implementations easily pinpoint all cases where these steps are
necessary.
Note
Example
4.14.1 The main part of the content
658
61
If the main content is an independent unit of content that one could imagine syndicating independently, then thearticlep157
element would be
appropriate to mark up the main content of the document.
Here is a short Web page marked up along this minimalistic school of thought. The main content is highlighted. Notice how all theother
content in thebodyp156
is marked up with elements to indicate that it's not part of the main content, in this caseheaderp170
,navp162
,
andfooterp171
.
<!DOCTYPE HTML>
<html lang="en">
<head>
<title> My Toys </title>
</head>
<body>
<header>
<h1>My toys</h1>
</header>
<nav>
<p><a href="/">Home</a></p>
<p><a href="/contact">Contact</a></p>
</nav>
<p>I really like my chained book and my telephone. I'm not such a
fan of my big ball.</p>
<p>Another toy I like is my mirror.</p>
<footer>
<p>© copyright 2010 by the boy</p>
</footer>
</body>
</html>
The document in the previous example is here recast as a blog post:
<!DOCTYPE HTML>
<html lang="en">
<head>
<title> The Boy Blog: My Toys </title>
</head>
<body>
<header>
<h1>The Boy Blog</h1>
</header>
<nav>
<p><a href="/">Home</a></p>
<p><a href="/contact">Contact</a></p>
</nav>
<article>
<header>
<h1>My toys</h1>
<p>Published August 4th</p>
</header>
<p>I really like my chained book and my telephone. I'm not such a
fan of my big ball.</p>
<p>Another toy I like is my mirror.</p>
</article>
<footer>
<p>© copyright 2010 by the boy</p>
</footer>
</body>
</html>
Example
659
61
If the main content is not an independent unit of content so much as a section of a larger work, for instance a chapter, then thesectionp159
element would be appropriate to mark up the main content of the document.
If neitherarticlep157
norsectionp159
would be appropriate, but the main content still needs an explicit element, for example for styling purposes,
then themainp204
element can be used.
Here is the same document, but as a chapter in an online book:
<!DOCTYPE HTML>
<html lang="en">
<head>
<title> Chapter 2: My Toys — The Book of the Boy </title>
</head>
<body>
<header>
<hgroup>
<h1>The Book of the Boy</h1>
<h2>A book about boy stuff</h2>
</hgroup>
</header>
<nav>
<p><a href="/">Front Page</a></p>
<p><a href="/toc">Table of Contents</a></p>
<p><a href="/c1">Chapter 1</a> — <a href="/c3">Chapter 3</a></p>
</nav>
<section>
<h1>Chapter 2: My Toys</h1>
<p>I really like my chained book and my telephone. I'm not such a
fan of my big ball.</p>
<p>Another toy I like is my mirror.</p>
</section>
</body>
</html>
Example
This is the same as the original example, but usingmainp204
for the main content instead of leaving it implied:
<!DOCTYPE HTML>
<html lang="en">
<head>
<title> My Toys </title>
<style>
body > main { background: navy; color: yellow; }
</style>
</head>
<body>
<header>
<h1>My toys</h1>
</header>
<nav>
<p><a href="/">Home</a></p>
<p><a href="/contact">Contact</a></p>
</nav>
<main>
<p>I really like my chained book and my telephone. I'm not such a
fan of my big ball.</p>
<p>Another toy I like is my mirror.</p>
</main>
<footer>
<p>© copyright 2010 by the boy</p>
Example
660
Documents you may be interested
Documents you may be interested
