Custom Elements 中文规范

动机

概念

自定义元素是一个 平台对象其接口由开发者定义。自定元素的接口的接口原型对象被称为 自定义元素原型。

自定义元素类型 标识一个自定义元素接口 必须和NCName 产生方式相匹配的字符串，必须包含一个U+002D连字符号字符, 且不能包含任何ASCII大写字母. 自定义元素类型禁止是下面的任何一种:

• annotation-xml
• color-profile
• font-face
• font-face-src
• font-face-uri
• font-face-format
• font-face-name
• missing-glyph

元素定义描述了一个自定义元素，包括:

• 元素类型,
• 本地名,
• 命名空间,
• 自定义元素原型, 和
• 生命周期回调函数。

在创建时， 文档可以和一个注册表关联。注册表是元素定义的集合。

元素注册是一个添加元素定义到一个注册表的过程。 一个元素定义只能被注册到一个注册表.

如果一个文档 有一个与之关联的 注册 ， 那么这个 文档 和在这个 注册表特定的 元素定义 , 自定义元素的接口 必须是 元素接口 ，分别为 自定义元素类型的 本地命名 和 命名空间值，和元素定义的命名空间。

如果一个文档 没有一个 注册表与它关联, 所有元素注册 的尝试就会失败。

确切建立注册,与文档关联, 元素注册在这个规范被进一步定义 。

自定义元素生命周期

一个 自定义元素 可以在它的生命周期贯穿这些改变:

• 自定义元素 被创建早于它的定义被注册
• 自定义元素 的定义被注册
• 自定义元素 实例被创建后于定义的注册
• 自定义元素被 插入到当前文档
• 自定义元素从当前文档被移除
• 自定义元素的 属性 被创建, 移除, 或修改。

各种回调函数被调用当一个自定义元素 贯穿这些变化。这些回调函数在内部以建-值对的集合存储，被称为生命周期回调函数。

把一个被称作 name 的回调函数从一个被称作property的对象属性转移到 生命周期回调,用户代理 必须 执行以下步骤：

入栈和调用回调函数

为了方便调用回调函数， 相关的类似浏览上下文的每个单元 有一个处理堆栈, 最初是空的。堆栈的每一项是一个元素队列,最初也是空的。元素队列的每一项是一个 自定义元素。

每个 自定义元素有一个相关的回调队列和一个元素被创建成为 标志。标志最初设置为 false 以及 回调队列 最初是空的。在队列中的每项包含回调本身和零个或多个被用作回调参数的字符串值。

在一个 元素队列调用回调函数, 用户代理必须 执行这些步骤或类似:

任何时候，一个脚本调用一个方法，读取或设置属性由用户代理执行，下面的操作必须出现：

• 当脚本转换成用户代理代码，压入一个新的 元素队列 到 处理栈
• 当用户代理代码转换成脚本，从处理栈弹出元素队列 并 调用回调函数在队列里.

除了一个元素队列, 也有一个排队的元素队列。 自定义元素被保存在增加 自定义元素顺序的顺序中。

自定义元素顺序 是文档自定义元素顺序和 输入树顺序的总和, 其中 输入树顺序 被控制以使它的最低值总是比文档自定义元素顺序的最高可能值要大。

文档自定义元素顺序是一个数值，与每一个自定义元素相关。 这个值是 自定义元素的文档 保持一个递增的数值并分配到 自定义元素 作为它的 自定义元素顺序 每当发生以下情况的结果:

• 一个自定义元素 从 开放元素堆栈中弹出
• 一个 自定义元素被创建用其他解析方法

输入树的特定自定义元素 的输入树顺序 由被压入每个输入链路 用输入文档的内容来替换的输入树的树顺序决定。

最稳定的顺序 是紧接着前面的一个元素在第一个入口的 自定义元素顺序的值，在树顺序， 其 准备好的标志 尚未设定。 如果不存在这样的元素, 最高的稳定顺序在扁平的输入树里 是最高的自定义元素。

index.html:
<link rel="import" href="import.html">
...
<me-second></me-second>
...

import.html:
<me-first></me-first>

每一个 与浏览器上下文相关的单元有一个最初为空的存储元素队列, 被成为 基本元素队列.

作为microtask checkpoint的一部分, 用户代理 必须 处理基础元素队列与浏览器上下文相关的单元到 脚本浏览上下文。

为了阻止重写，当 处理基础元素队列时，每一个 与浏览器上下文相关的单元有一个处理基础元素队列 标志, 必须 初始化为false.

为了处理基本元素队列, 用户代理必须 执行以下步骤或 同等：

在属于脚本浏览上下文 与浏览器上下文相关的单元 , 当前元素队列是 处理堆栈 的顶部的元素队列，或是基本元素队列 如果 处理堆栈 为空。

回调函数类型

下面的回调确认：

createdCallback

这个回调被调用在自定义元素 实例被创建之后，并且 定义被注册。这个回调的确实时间在本规范中会进一步定义。

定义元素原型 必须 被设置 在调用回调函数之前。

回到函数调用期间，被创建的元素 标志 必须 设置为 true。 在所有情况下，标志 必须 被设为 false。

如果被 创建 的回调存在于一个元素，所有回调 不能被排队直到 被创建 回调的调用开始。

attachedCallback

除非另有规定，回调 必须被 入队 当 自定义元素 被 插入一个文档 且 这个 文档有一个浏览上下文。

detachedCallback

除非另有规定， 回调 必须被 入队 当 自定义元素 被 从文档移除 且 这个 文档 有一个 浏览上下文。

attributeChangedCallback

除非另有规定， 回调 必须被 入队当 自定义元素的属性 被 添加, 修改 或是 移除。根据 属性 修改类型， 下列额外的字符串被添加到队列项中：

属性被设置

属性名, null, 新 属性值, 和 属性命名空间。

属性被改变

属性名, 旧 属性值, 新 属性值, 和 属性命名空间。

属性被移除

属性名, 旧 属性值, null, 和 属性命名空间。

要在自定义元素上 设置自定义元素的原型， 用户代理 必须 执行以下步骤或 同等：

创建和传递注册

当一个 HTML Document 被加载 进一个 浏览上下文，一个新的 注册 必须 被创建且关联到这个document。

一个新 document 实例 必须 被关联到一个现有 注册 在这些例子里:

• 当 DOMImplementation的 createDocument 方法被调用命名空间 设置为 HTML Namespace 或者当 createHTMLDocument 方法被调用, 使用与实例关联的document的注册
• 当创建一个输入， 使用 主文档的 注册。
• 当创建一个模板内容所有者的文档, 使用一个新的空的 注册。

在所有情况下， 新的 documents 不能 有一个 注册。

注册自定义元素

因为 元素注册 可在任何时间发生， 一个自定义元素在它的 定义 被 注册之前可能被创建。 这样的 自定义元素 实例被称为 unresolved elements。当一个unresolved element 被创建， 且 如果它的元素实例 没有被 HTML 或者 其他适用的规范定义。 unresolved element的元素实例 必须 是：

• HTMLElement, 如果 命名空间是HTML 命名空间；
• SVGElement, 如果 命名空间 是 SVG 命名空间；或者
• 未知的，相反的

每个 注册 有一个相关联的给出一对自定义元素类型 和 命名空间的所有unresolved elements 实例的表。这些数据结构被称为 升级的候选表 且初始化是空 。在表里的每项值是一个存储元素队列。

无论何时一个unresolved element被创建，必须 被添加到相应的 存储元素队列 在升级的候选表里。

注册 一个 元素定义是元素配准算法的职责， 必须 是等于 执行这些步骤：

定义构造算法创建一个 元素定义 ， 必须 等同于 运行这些步骤：

元素升级算法 升级 unresolved elements，它的定义现在被 注册 且 必须 等同于 运行这些步骤：

扩展文档接口

文档 接口的 注册元素 方法提供了一种 注册 和 返回它的 自定义元素构造函数的方法。

partial interface Document {
    Function registerElement(DOMString type, optional ElementRegistrationOptions options);
};

dictionary ElementRegistrationOptions {
     object? prototype = null;
     DOMString? extends = null;
};

调用时， 注册元素 方法 必须 执行这些步骤：

document.registerElement('x-foo', {
    prototype: Object.create(HTMLParagraphElement.prototype, {
        firstMember: {
            get: function() { return "foo"; },
            enumerable: true,
            configurable: true
        },
        // specify more members for your prototype.
        // ...
    }),
    extends: 'p'
});

<p is="x-foo">Paragraph of amazement</p>

var foo = document.createElement('p', 'x-foo');

用SVGElement 原型的元素值得一提的是： 使用 自定义标签方法 的结果是在SVG忽略元素。 因此, 基于SVG的自定义元素可能几乎始终是 类型扩展名。

Unresolved伪类元素

:unresolved 伪类 必须 匹配所有被创建的回调还没有被调用的 自定义元素。

实例化自定义元素

自定义元素类型 被给到一个自定义元素在它的实例的两种方式中的一种：

1. 由于自定义元素 的本地命名。这些自定义元素类型的类型被称为 自定义标签。
2. 由于 自定义元素的attribute值。 自定义元素类型 被给定的方法叫做 类型扩展。

自定义元素 被实例化之后，改变它的属性 值不能影响该元素的自定义元素类型。

如果两种自定义元素类型在元素实例化的时候被提供， 自定义标签 必须 胜过 类型扩展。

所有 自定义元素 必须 可用 函数对象构建，被称为 自定义元素构建函数。该构造函数 必须 用自定义元素构造函数生成算法生成， 可以 等于 执行这些步骤：

扩展 文档 接口

要允许同时创建 自定义标签 和 类型扩展式 自定义元素， 在createElement 或 createElementNS 方法有 重载一个 typeExtension 参数:

partial interface Document {
    Element createElement(DOMString localName, DOMString typeExtension);
    Element createElementNS(DOMString? namespace, DOMString qualifiedName, DOMString typeExtension);
};

解析自定义元素

在树构造函数期间启用实例化 自定义元素 , 一个符合标准的 UA 必须 执行 排队 created 回调函数无论何时 创建 一个自定义元素。

同样,自定义元素的构造函数生成算法将发生如下改变：

附录A：在一个图中的所有算法