Shoelace组件库安装指南：从CDN到npm全方位解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00319/article/details/148392019

Shoelace组件库安装指南：从CDN到npm全方位解析

shoelace A collection of professionally designed, every day UI components built on Web standards. Works with all frameworks as well as regular HTML/CSS/JS. 🥾 项目地址: https://gitcode.com/gh_mirrors/sh/shoelace

前言

Shoelace是一套基于Web Components的现代化UI组件库，它采用纯原生Web技术构建，不依赖任何框架，却能完美兼容React、Vue、Angular等主流前端框架。本文将全面介绍Shoelace的多种安装方式，帮助开发者根据项目需求选择最适合的集成方案。

一、CDN安装（最简单方式）

对于快速原型开发或简单项目，CDN是最便捷的安装方式。Shoelace提供了两种CDN加载方案：

1. 自动加载器（推荐）

自动加载器是最高效的使用方式，它通过轻量级脚本监听DOM变化，按需懒加载未注册的Shoelace组件，包括动态添加的元素。

<!-- 引入默认浅色主题 -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/themes/light.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/shoelace-autoloader.js"></script>

注意：自动加载可能导致短暂的自定义元素未定义闪烁现象(FOUCE)，可通过CSS预定义样式或加载动画缓解。

2. 传统加载器

传统方式会一次性注册所有组件，适合需要立即使用多个组件的场景。但相比自动加载器，这种方式会加载更多不必要的代码。

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/themes/light.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/shoelace.js"></script>

二、主题配置

Shoelace提供灵活的主题配置方案：

1. 深色主题

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/themes/dark.css" />
<html class="sl-theme-dark">

2. 自动适应主题

根据用户系统偏好自动切换深浅主题：

<link
  rel="stylesheet"
  media="(prefers-color-scheme:light)"
  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/themes/light.css"
/>
<link
  rel="stylesheet"
  media="(prefers-color-scheme:dark)"
  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@%VERSION%/%CDNDIR%/themes/dark.css"
  onload="document.documentElement.classList.add('sl-theme-dark');"
/>

三、npm安装（推荐生产环境使用）

对于正式项目，建议通过npm安装以获得更好的版本控制和构建优化：

npm install @shoelace-style/shoelace

安装后，需要配置静态资源服务。常见做法是在项目中创建专门路由指向node_modules中的Shoelace资源：

<link rel="stylesheet" href="/shoelace/%NPMDIR%/themes/light.css" />
<script type="module" src="/shoelace/%NPMDIR%/shoelace.js"></script>

四、按需加载（Cherry Picking）

为优化性能，可以只导入需要的组件：

<link rel="stylesheet" href="/path/to/shoelace/%NPMDIR%/themes/light.css" />

<script type="module" data-shoelace="/path/to/shoelace/%NPMDIR%">
  import '@shoelace-style/shoelace/%NPMDIR%/components/button/button.js';
  // 现在可以使用<sl-button>组件了
</script>

重要提示：

组件文档的"Importing"部分提供了具体导入路径
某些组件有依赖关系，会在文档中"Dependencies"部分列出
切勿直接从shoelace.js中按需导入，这会导致加载整个库

五、构建工具集成

现代前端项目通常使用构建工具，以下是配置要点：

1. 基本配置

// 示例：webpack配置
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/i,
        use: ['style-loader', 'css-loader']
      }
    ]
  }
}

2. 组件导入示例

import '@shoelace-style/shoelace/%NPMDIR%/themes/light.css';
import '@shoelace-style/shoelace/%NPMDIR%/components/button/button.js';
import { setBasePath } from '@shoelace-style/shoelace/%NPMDIR%/utilities/base-path.js';

setBasePath('/path/to/shoelace/%NPMDIR%');

3. 避免自动注册

如需手动控制组件注册：

import SlButton from '@shoelace-style/shoelace/%NPMDIR%/components/button/button.component.js';

六、资源路径配置

组件依赖的图标等资源需要正确配置基础路径：

1. 设置方式

<!-- 方式1：通过data属性 -->
<script src="bundle.js" data-shoelace="/path/to/shoelace/%NPMDIR%"></script>

<!-- 方式2：通过API设置 -->
<script type="module">
  import { setBasePath } from '@shoelace-style/shoelace/%NPMDIR%/utilities/base-path.js';
  setBasePath('/path/to/shoelace/%NPMDIR%');
</script>

2. 获取资源路径

import { getBasePath } from '@shoelace-style/shoelace/%NPMDIR%/utilities/base-path.js';

// 获取基础路径
const basePath = getBasePath();

// 获取完整资源路径
const assetPath = getBasePath('icon.png');