# 前言

该 single-spa-layout NPM包是一个可选的附加单温泉。布局引擎提供了一个路由API，用于控制您的顶级路由，应用程序和dom元素。使用单spa布局可以更轻松地完成以下任务：

DOM放置和应用程序排序。
下载应用程序时加载UI。
未找到/ 404页的默认路由。
路线之间的转换（执行中）。

布局引擎执行两项主要任务：

从HTML元素和/或JSON对象生成单温泉注册配置。
侦听路由事件，以确保在安装单spa应用程序之前正确布置所有DOM元素。

single-spa-layout 被压缩为3.2kb（未压缩为9kb）。

# 安装

您只需要将布局引擎安装到您的根配置中即可（无需在任何其他应用程序中安装）。

npm install --save single-spa-layout@beta
# or
yarn add single-spa-layout@beta

@前端进阶之旅: 代码已经复制到剪贴板

# 项目状态

single-spa-layout 是新的，当前 beta 在npm的dist标签下发布。我们正在收集反馈并改进布局引擎，以准备发布稳定版本。尽管我们不希望版图引擎发生巨大变化，但是我们建议您在正式发布之前不要在生产环境中使用它。

# 浏览器支持

single-spa-layout 在 single-spa 支持的所有浏览器（包括IE11）中均可使用。

# 要求

您必须使用 single-spa @> == 5.4.0才能使布局引擎正常工作。此外，您可能不 domElementGetter 为任何 single-spa 应用程序提供自定义功能，因为这些功能会覆盖 single-spa 布局中的配置。

# 基本用法

在根html文件中，将 <template> 元素添加到头部。它应具有 <single-spa-router> 包含 <route> 元素，<application> 元素和任何其他dom元素的元素：

<html>
  <head>
    <template id="single-spa-layout">
      <single-spa-router>
        <nav class="topnav">
          <application name="@organization/nav"></application>
        </nav>
        <div class="main-content">
          <route path="settings">
            <application name="@organization/settings"></application>
          </route>
          <route path="clients">
            <application name="@organization/clients"></application>
          </route>
        </div>
        <footer>
          <application name="@organization/footer"></application>
        </footer>
      </single-spa-router>
    </template>
  </head>
</html>

@前端进阶之旅: 代码已经复制到剪贴板

然后在您的root-config的JavaScript代码中，添加以下内容：

import { registerApplication, start } from 'single-spa';
import {
  constructApplications,
  constructRoutes,
  constructLayoutEngine,
} from 'single-spa-layout';
const routes = constructRoutes(document.querySelector('#single-spa-layout'));
const applications = constructApplications({
  routes,
  loadApp({ name }) {
    return System.import(name);
  },
});
const layoutEngine = constructLayoutEngine({ routes, applications });
applications.forEach(registerApplication);
start();

@前端进阶之旅: 代码已经复制到剪贴板

# 布局定义

布局是 HTMLElement ，路由和 single-spa 应用程序的组合。在根配置中静态定义了布局，以处理顶级路由和dom元素。单个 single-spa 布局不应在根配置之外使用；相反，UI框架（React，Angular，Vue）应处理应用程序中的布局。

您可以将布局定义为HTML模板或JSON对象。对于喜欢将布局定义存储在数据库中而不是代码中的组织，支持JSON定义。HTML和JSON布局具有相同的功能集。但是，通常首选在代码中存储布局，并且默认情况下鼓励使用。如果您刚开始使用 single-spa 布局，我们建议您使用HTML模板。

一旦你定义布局，你应该 constructRoutes，constructApplications 和 constructLayoutEngine

# HTML布局

您可以在根配置的 index.html 文件中或在被解析为HTML的javascript字符串中定义HTML布局。我们通常鼓励在根配置的 index.html 文件中定义布局。

要在 index.html 文件中定义布局，请创建一个 <template id="single-spa-layout"> 包含布局的元素。在模板内，添加一个 <single-spa-router> 元素以及所有路由，应用程序和dom元素。

请注意，在布局中定义的HTMLElement是静态的-无法强制重新呈现或更改它们。

<!-- index.ejs -->
<html>
  <head>
    <template>
      <single-spa-router>
        <div class="main-content">
          <route path="settings">
            <application name="settings"></application>
          </route>
        </div>
      </single-spa-router>
    </template>
  </head>
</html>
// 不推荐使用，但是也可以用HTMLElements进行javascript构造
const doc = new DOMParser().parseFromString(`
<single-spa-router>
  <div class="main-content">
    <route path="settings">
      <application name="settings"></application>
    </route>
  </div>
</single-spa-router>
`, "text/html").documentElement

@前端进阶之旅: 代码已经复制到剪贴板

# JSON布局

您可以将布局定义为JSON，包括路由，应用程序和任意dom元素。

const layout = {
  "routes": [
    { "type": "route", "path": "settings", "routes": [
      { "type": "application", "name": "settings" }
    ]}
  ]
};

@前端进阶之旅: 代码已经复制到剪贴板

# 布局元素

布局元素是HTMLElement或JSON对象，代表dom节点，路由或应用程序。

# template

仅当将布局定义为HTML时才使用该 template 元素。它的目的是防止其内容被浏览器显示，因为布局定义对用户不可见。

<template>
  <!-- 在这里定义您的布局 -->
  <single-spa-router></single-spa-router>
</template>

@前端进阶之旅: 代码已经复制到剪贴板

请注意，<template> IE11中不完全支持元素。但是，您无需为了在 single-spa 布局中使用模板元素而对其进行填充。相反，只需添加 style="display: none;" 到模板即可防止其内容显示在IE11中。

<template style="display: none;">
  <!-- 在这里定义您的布局 -->
  <single-spa-router></single-spa-router>
</template>

@前端进阶之旅: 代码已经复制到剪贴板

# `<single-spa-router>`

该 single-spa-router 元素是必需的布局的顶层容器。所有属性都是可选的。

<single-spa-router mode="hash|history" base="/" disableWarnings></single-spa-router>
{
  "mode": "hash|history",
  "base": "/",
  "disableWarnings": false,
  "containerEl": "#container",
  "routes": []
}

@前端进阶之旅: 代码已经复制到剪贴板

属性:

mode（可选）：必须为hash或history默认为的字符串history。这指示路由是否应与Location路径名或hash匹配。
base （可选）：匹配路由路径时将考虑的字符串URL前缀。
disableWarnings （可选）：一个布尔值，当提供的元素不正确时，该布尔值将打开单个spa布局的控制台警告。
containerEl（可选）：字符串CSS选择器或HTMLElement，用作所有单spa dom元素的容器。默认为body。

该route元素用于控制为顶级URL路由显示哪些应用程序和dom元素。它可能包含 HTMLElement，应用程序或其他路由。

<route path="clients">
  <application name="clients"></application>
</route>
<route default>
  <application name="clients"></application>
</route>

@前端进阶之旅: 代码已经复制到剪贴板

{
  "type": "route",
  "path": "clients",
  "routes": [
    { "type": "application", "name": "clients" }
  ],
  "default": false
}

@前端进阶之旅: 代码已经复制到剪贴板

属性:

路由必须具有路径或为默认路由。

routes （必填）：激活路线时将显示的子元素数组
path（可选）：将与浏览器的URL匹配的字符串路径。路径是相对于其父路径（或基本URL）的。开头和结尾/字符是不必要的，并且会自动应用。通过使用:字符（“clients/:id/reports”），路径可能包含“动态段” 。单spa布局使用单spa的pathToActiveWhen功能将路径字符串转换为活动功能。
default（可选）：一个布尔值，确定此路由是否将与同级路由未定义的所有其余URL匹配。这对于“ 404找不到页面”很有用。同级路由定义为具有相同最近父路由的任何路由。
props：单spa自定义道具的对象，在安装时将提供给应用程序。请注意，对于不同路径上的同一应用程序，可以对它们进行不同的定义。您可以在下面的文档中阅读有关在HTML中定义道具的更多信息。

# application

同一应用程序可能会在布局中以不同的路线出现多次。但是，每个应用程序只能为每个路由定义一次。

属性:

# DOM元素

single-spa-layout 仅在路由转换期间支持更新DOM元素。不支持任意重新渲染和更新。

# 前言

# 安装

# 项目状态

# 浏览器支持

# 要求

# 基本用法

# 布局定义

# HTML布局

# JSON布局

# 布局元素

# template

# <single-spa-router>

# application

# DOM元素

# 属性

# `<single-spa-router>`

布局引擎Layout Engine|微前端专题

布局引擎Layout Engine|微前端专题