JavaScript HTMLSlotElement.assignedElements 怎样读取插槽分配的元素

我在给 Web Components 做“可插拔内容区”时，最容易写错的地方不是 slot 标签，而是把“插槽里显示出来的内容”误认为“插槽对象自己的子节点”。真正需要读取分配结果时，应先拿到 HTMLSlotElement，再调用 slot.assignedElements()。

assignedElements() 返回的是元素数组，只包含当前分配到这个 slot 的元素，不包含文本节点。默认模式只看直接分配；传入 { flatten: true } 时，才会继续展开后代 slot 的分配元素。如果没有任何分配元素，方法会返回 slot 的 fallback 内容。官方资料：https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedElements

记住三件事：先查询真正的 slot 对象，再读取 assignedElements()；默认不展开后代 slot；结果会随着 slotchange 改变，不要长期缓存旧数组。

先创建一个能观察分配结果的 slot

为了让读取过程容易理解，下面定义一个很小的自定义元素。它的 Shadow DOM 中有一个名为 content 的插槽，外部元素通过同名 slot 属性进入这个出口。这里读取的是组件内部的 slot 元素，而不是外部的 宿主元素。

// 自定义元素内部只放一个命名 slot，外部内容通过 slot 属性分配进来。
class ArticleCard extends HTMLElement {
  constructor() {
    super();

    // 使用 open 便于示例通过 shadowRoot 查询 slot；生产代码也可以封装读取方法。
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = `
      
默认标题
        
暂无内容
      
    `;
  }
}

customElements.define('article-card', ArticleCard);

// 外部节点用 slot 属性声明自己要进入哪个命名插槽。
document.body.insertAdjacentHTML('beforeend', `
  插槽标题
    
第一段内容
    
第二段内容
  
`);

这个例子里，两个 p 元素都被分配给 content 插槽。它们在 light DOM 中仍然属于 article-card 的子节点；slot 只是 Shadow DOM 中接收这些节点的出口。下一步要在自定义元素内部取得这个出口。

调用 assignedElements() 读取直接分配的元素

拿到命名 slot 后，直接调用无参数版本即可读取当前分配的元素。返回值是一个数组，每次调用都会给出当下的分配结果；它不是“slot 的 DOM 子节点列表”，也不会把文本节点混进来。

// 取得组件实例和它内部的命名 slot。
const card = document.querySelector('article-card');
const contentSlot = card.shadowRoot.querySelector('slot[name="content"]');

// 默认 flatten=false，只读取直接分配到 content slot 的元素。
const assigned = contentSlot.assignedElements();

// 返回值是 Element 数组，因此可以安全地读取标签名和属性。
for (const element of assigned) {
  console.log(element.tagName, element.getAttribute('slot'));
}

对于上面的标记，assigned 会包含两个 p 元素。它不会包含换行产生的文本节点，也不会包含 shadowRoot 里的 section 或 div。如果你需要同时处理文本节点，应该改用 assignedNodes()，不要强行把它们当成元素处理。

flatten 参数决定是否展开后代 slot

默认的 assignedElements() 只读取直接分配给当前 slot 的元素。插槽内容本身如果还包含一个后代 slot，默认结果不会继续向下展开。需要递归得到可见插槽链上的元素时，传入 flatten: true。

// 默认模式：后代 slot 仍作为插槽边界，不继续展开。
const directElements = contentSlot.assignedElements();

// 展开模式：把后代 slot 中可继续取得的分配元素纳入结果。
const flattenedElements = contentSlot.assignedElements({ flatten: true });

// 根据业务需要读取结果，不要假设两种数组长度永远相同。
console.log({
  directCount: directElements.length,
  flattenedCount: flattenedElements.length,
});

flatten 的默认值是 false。这意味着简单组件可以使用无参数调用，只有组件内部存在嵌套 slot 或需要观察完整插槽链时才显式传 true。展开并不是“把所有 Shadow DOM 节点都查出来”，它关注的仍然是插槽分配关系。

没有分配元素时要理解 fallback

如果当前 slot 没有分配任何元素，assignedElements() 会返回这个 slot 的 fallback 内容。fallback 是 slot 标签内部写下的备用内容，例如 暂无内容 中的文字或元素。

// 取得一个可能没有外部分配内容的 slot。
const titleSlot = card.shadowRoot.querySelector('slot[name="title"]');
const titleElements = titleSlot.assignedElements();

if (titleElements.length === 0) {
  // 没有分配元素时，业务上可以显示空状态或读取 fallback 节点。
  const fallbackText = titleSlot.textContent.trim();
  console.log('当前使用 fallback：', fallbackText);
} else {
  // 有分配元素时只处理实际进入 slot 的元素。
  console.log('当前标题元素：', titleElements[0].textContent.trim());
}

判断时要看返回数组的长度，而不是把 assignedElements() 的结果和 slot.childNodes 直接比较。fallback 的存在是 slot 的默认展示策略；一旦外部有元素分配进来，读取结果就会转向分配元素。

slotchange 后重新读取，不要复用旧数组

当外部内容被添加、删除或更换 slot 属性时，slot 的分配关系会发生变化。组件如果需要同步目录、统计数量或刷新摘要，可以监听 slotchange，在事件回调中再次调用 assignedElements()。不要把初始化时得到的数组当成永久状态。

// 统一从当前 slot 读取最新的元素数组，避免使用过期引用。
function readContentElements(slot) {
  return slot.assignedElements({ flatten: true });
}

// slotchange 表示分配关系可能变化，回调里重新获取结果。
contentSlot.addEventListener('slotchange', () => {
  const currentElements = readContentElements(contentSlot);

  // 用最新数量更新组件内部状态或摘要，不修改 slot 的分配关系。
  console.log('内容元素数量：', currentElements.length);
});

这个监听器只负责重新读取，不会自动改变外部节点的 slot 属性。若业务代码还要调整分配关系，应单独修改 DOM，并让下一次 slotchange 触发新的读取流程。

assignedElements 和 assignedNodes 怎么选

两者都用于读取 slot 的分配结果，但返回对象的粒度不同。只处理按钮、段落、图片等元素时选 assignedElements()；需要保留文本节点、注释节点或完整节点顺序时选 assignedNodes()。

如果你的逻辑要调用 getAttribute()、classList 或 matches()，元素数组更直接；如果要实现文本拼接、节点级序列化或保留空白节点，则应明确选择节点数组。

最后用一条工作流排查读取结果

1. 确认拿到的是 Shadow DOM 内真正的 元素，而不是宿主自定义元素。
2. 确认外部节点的 slot 属性和 slot 的 name 完全对应，未命名 slot 则对应没有 slot 属性的节点。
3. 先调用无参数版本观察直接分配结果，再根据嵌套 slot 需求决定是否使用 { flatten: true }。
4. 返回空数组时，检查是否正在使用 fallback，而不是马上判断为 API 失效。
5. 动态变化场景监听 slotchange，在事件中重新调用方法，不缓存旧数组。

我实际使用时会把 assignedElements() 当作“插槽分配关系的读取口”，而不是普通的后代选择器。这样一来，直接分配、嵌套 slot 和 fallback 就各自有清晰边界，组件内部也不需要猜测外部节点当前到底显示在哪个出口。

常见追问

assignedElements() 返回的是 slot 的子元素吗？

不是。它返回分配给这个 slot 的元素，默认只包含直接分配的元素；slot 标签内部的 fallback 内容只在没有分配元素时作为结果出现。

什么时候必须传 flatten: true？

当你的组件允许后代 slot 继续承接内容，并且业务需要读取展开后的元素集合时，传入 { flatten: true }。没有嵌套 slot 时，无参数调用通常足够。

为什么要用 assignedElements() 而不是 assignedNodes()？

如果只处理元素节点，assignedElements() 可以避免文本节点判断；需要保留文本、注释等 Node 类型时，才使用 assignedNodes()。

slotchange 发生后原来的数组会自动更新吗？

不要依赖旧数组自动更新。更稳妥的做法是在 slotchange 回调中重新调用 assignedElements()，再用新数组刷新组件状态。