# Somnia 组件编写指南
> 提醒：本文档为 AI 生成，如需使用请自行验证其内容。
Somnia 使用 Swup.js 实现无刷新页面切换。Swup 通过 AJAX 加载新页面的 HTML 片段并替换 DOM，
但由于浏览器安全策略，**innerHTML 插入的 `
```
## 根因说明
Swup.js 的工作原理是拦截链接点击 → 通过 `fetch()` 获取新页面 HTML → 提取 `#content-wrapper` 内的 HTML 字符串 → 通过 `innerHTML` 替换当前内容。**浏览器规范规定 `innerHTML` 赋值时，其中的 `
```
在 `assets/js/custom.js` 的 `Somnia.prototype.swupPageInitCustom` 中添加：
```javascript
document.querySelectorAll('#content-wrapper script').forEach(script => {
const newScript = document.createElement('script');
newScript.innerHTML = script.innerHTML;
document.head.appendChild(newScript);
});
document.dispatchEvent(new CustomEvent('somnia:moved', { bubbles: true }));
```
**优点：** shortcode 自包含，无需额外文件。
**缺点：** 页面切换会堆积重复的 `
```
在 `custom.js` 的 `Somnia.prototype.swupPageInitCustom` 中添加：
```javascript
document.querySelectorAll('div[x-ignore]').forEach(div => {
const nextEl = div.nextElementSibling;
if (nextEl && nextEl.tagName.toLowerCase() === 'script') {
div.setAttribute('x-data', nextEl.innerText);
nextEl.remove();
div.removeAttribute('x-ignore');
div.parentNode.replaceChild(div, div); // 触发 Alpine 重新解析
}
});
```
`replaceChild(div, div)` 用自身替换自身，不改变 DOM 结构，但会触发 Alpine 的 MutationObserver 回调，重新解析该元素上的 `x-data` 指令。
**优点：** shortcode 基本自包含；脚本可以是函数也可以是纯对象；无重复堆积。
**缺点：** 需要注入一次脚本处理逻辑。
**适合场景：** shortcode 自包含且使用频繁。
---
## 方法 5：Async Alpine 异步加载
将组件函数迁移到独立 `.mjs` 文件，通过 Async Alpine 按需加载。
1. 创建独立文件，如 `static/js/comment.mjs`：
```javascript
export default function() {
return {
count: 0,
increment() { this.count++ }
}
}
```
2. 在 shortcode 中使用 `x-load` 指定加载来源：
```html
```
**优点：** 真正的代码分割，按需加载，性能最佳。
**缺点：** 需要了解 Async Alpine 的加载协议。
> 文档：https://async-alpine.dev/docs/
**适合场景：** 大型独立组件（评论系统、图库）。
---
## 方法 6：Alpine.initTree() 官方 API
Alpine.js v3 提供了 `Alpine.initTree(el)`，可手动初始化指定 DOM 子树。
在 Swup 切换完成后调用，新内容中的 `x-data` 自动生效。
**只需在 `custom.js` 添加一次代码，无需修改任何 shortcode：**
```javascript
document.addEventListener('swup:contentReplaced', () => {
Alpine.initTree(document.getElementById('content-wrapper'));
});
```
`initTree` 遍历 DOM 树，找到含 `x-data` 的未初始化元素并初始化。Alpine 内部维护初始化标记，已初始化的元素不会重复处理。
**优点：** 零侵入，Alpine 官方 API，无兼容性风险。
**缺点：** 函数仍需全局定义，局部变量 `