安装

设置

添加到你的项目

1. 安装 unplugin-gueleton 包

   npm

   npm install unplugin-gueleton@latest

   pnpm

   pnpm add unplugin-gueleton@latest

   yarn

   yarn add unplugin-gueleton@latest

2. 将 unplugin-gueleton 作为插件添加到你的构建工具配置中

   vite.config.ts

   import { defineConfig } from 'vite'
   import Gueleton from 'unplugin-gueleton/vite'
   
   // https://vite.dev/config/
   export default defineConfig({
     plugins: [Gueleton()],
   })

   vite-plugin-html 注意事项

   与 vite-plugin-html 插件一起使用时，你需要将 unplugin-gueleton 插件添加在 vite-plugin-html 之前，以确保正确处理 HTML 文件。

   webpack.config.js

   const { Gueleton } = require('unplugin-gueleton/webpack')
   
   module.exports = {
     /* ... */
     plugins: [
       Gueleton(),
     ],
   }

   nuxt.config.ts

   // https://nuxt.com/docs/api/configuration/nuxt-config
   export default defineNuxtConfig({
     // ...
     modules: ['unplugin-gueleton/nuxt'],
     // ...
   })

   vue.config.js

   const { defineConfig } = require('@vue/cli-service')
   const { Gueleton } = require('unplugin-gueleton/webpack')
   
   module.exports = defineConfig({
     configureWebpack: {
       plugins: [
         Gueleton()
       ]
     }
   })

3. 将 Gueleton 组件注册到应用中

   main.ts

   import { createApp } from 'vue'
   import App from './App.vue'
   
   import GueletonPlugin from 'unplugin-gueleton/vue'
   
   createApp(App)
     .use(GueletonPlugin)
     .mount('#app')

   main.js

   import { createApp } from 'vue'
   import App from './App.vue'
   
   import GueletonPlugin from 'unplugin-gueleton/vue'
   
   createApp(App)
     .use(GueletonPlugin)
     .mount('#app')

   提示

   得益于 Nuxt 的自动导入功能，你无需手动注册组件。只需确保在 nuxt.config.ts 中正确配置了插件即可。

   main.js

   import { createApp } from 'vue'
   import App from './App.vue'
   
   import GueletonPlugin from 'unplugin-gueleton/vue'
   
   createApp(App)
     .use(GueletonPlugin)
     .mount('#app')

4. 启动开发服务器

   Gueleton 会向 Nuxt 开发服务器添加一个新的路由 /__gueleton/，用于访问 Gueleton 的管理面板。

   成功启动后，Gueleton 会在控制台打印一条消息，提示你可以访问的 URL。

   Nuxt 4.0.3 with Nitro 2.12.4                                                                                                     nuxi 16:22:59
                                                                                                                                         16:22:59
     ➜ Local:    http://localhost:3000/
     ➜ Network:  use --host to expose
   
     ➜ DevTools: press Shift + Option + D in the browser (v2.6.3)                                                                        16:23:00
   
   ℹ ➜  Gueleton: http://localhost:3000/__gueleton/                                                                       nuxt-gueleton 16:23:02

   Gueleton 会 启动一个服务器，用于访问 Gueleton 的管理面板。

   成功启动 webpack 开发服务器后，Gueleton 会在控制台打印一条消息，提示你可以访问的 URL。

     - Local:   http://localhost:8080/
     - Network: http://192.168.224.65:8080/
   
   ➜  Gueleton: http://localhost:5679/__gueleton/

   Gueleton 会向 Vite 开发服务器添加一个新的路由 /__gueleton/，用于访问 Gueleton 的管理面板。

   成功启动后，Gueleton 会在控制台打印一条消息，提示你可以访问的 URL。

     VITE v7.1.3  ready in 666 ms
   
     ➜  Local:   http://localhost:5173/
     ➜  Network: use --host to expose
     ➜  press h + enter to show help
     ➜  Gueleton: http://localhost:5173/__gueleton/

   Gueleton 会 启动一个服务器，用于访问 Gueleton 的管理面板。

   成功启动开发服务器后，Gueleton 会在控制台打印一条消息，提示你可以访问的 URL。

     - Local:   http://localhost:8080/
     - Network: http://192.168.224.65:8080/
   
   ➜  Gueleton: http://localhost:5679/__gueleton/

   

5. 最后，你还需要了解一些特定于 Gueleton 的内容。

   占位骨架一般由一个浅色底加上一个或多个深色块组成。

   container

   bone

   bone

   bone

   Gueleton 将浅色底称为 container，而深色块则称为 bone。

   当自定义的占位骨架的样式时，你会用它们分别定义占位骨架的背景和骨架块的样式。

   就这些！现在你已经成功安装了 Gueleton，并可以开始使用它来为你的应用添加占位骨架屏了。

选项

你可以通过向插件传递选项来自定义全局的 Gueleton 行为。

limit

使用 limit 选项来设置预存数据的裁剪规则。它可以是一个数字或一个对象。

• 当 limit 为数字时, 表示取前 limit 项, 仅对数组有效.

• 当 limit 为对象时, length 表示取前 length 项, properties 表示裁剪对象的属性, 仅对对象有效.

• 默认值: 3

main.ts

import { createApp } from 'vue'
import App from './App.vue'

import { GueletonPlugin, GueletonProvider } from 'unplugin-gueleton/vue'

GueletonProvider.updateOptions({
  // limit: 3,
  limit: { length: 3, properties: ['id', 'name'] },
})

createApp(App)
  .use(GueletonPlugin)
  .mount('#app')

main.js

import { createApp } from 'vue'
import App from './App.vue'

import { GueletonPlugin, GueletonProvider } from 'unplugin-gueleton/vue'

GueletonProvider.updateOptions({
  // limit: 3,
  limit: { length: 3, properties: ['id', 'name'] },
})

createApp(App)
  .use(GueletonPlugin)
  .mount('#app')

app.config.ts

export default defineAppConfig({
  gueleton: {
    // limit: 3,
    limit: { length: 3, properties: ['id', 'name'] },
  }
})

main.js

import { createApp } from 'vue'
import App from './App.vue'

import { GueletonPlugin, GueletonProvider } from 'unplugin-gueleton/vue'

GueletonProvider.updateOptions({
  // limit: 3,
  limit: { length: 3, properties: ['id', 'name'] },
})

createApp(App)
  .use(GueletonPlugin)
  .mount('#app')

fuzzy

使用 fuzzy 选项可以调整 Gueleton 如何确定哪些 DOM 元素被识别为 bone。

较低的 fuzzy 会生成更多、更细粒度的骨架块，而较高的值则会生成更少、更大块的骨架。这也是 Gueleton 能够自动适应不同 UI 组件库的关键。

• 默认值: 1
• 示例：

  1. 当 fuzzy 设置为 1 时，p1 和 span1 分别被识别为 bone。

     <div class="div1">
       <p class="p1">这是一个段落。</p>
       <p class="p2">
         <span class="span1">内联元素</span>
       </p>
     </div>

  2. 当 fuzzy 设置为 2 时，整个 div1 将被识别为一个 bone。

     <div class="div1">
       <p class="p1">这是一个段落。</p>
       <p class="p2">
         <span class="span1">内联元素</span>
       </p>
     </div>

提示

查看 fuzzy 示例 以更好的了解 fuzzy 机制。

type

使用 type 选项可以设置骨架的渲染方式。

• 可选值:
  • overlay (默认): 整个占位骨架会覆盖在实际内容上。
  • inPlace: bone 会覆盖在它的父元素上。

bone 和 container

使用 bone 和 container 选项分别可以自定义 bone 和 container 的样式。

它们都可以接受一个 style 对象和 className 字符串。

bone

• 默认值:

  {
    style: {
      backgroundColor: 'rgba(240, 240, 240, 1)',
    },
    className: '',
  }

container

• 默认值:

  {
    style: {
      cursor: 'wait',
      backgroundColor: 'rgba(255, 255, 255, 1)',
    },
    className: '',
    leave: {}
  }

container.leave

当数据加载完成后，Gueleton 会移除占位骨架并显示实际内容。container.leave 选项允许你为 container 元素定义离开时的样式。 配合 transition 属性使用，可以实现更平滑的过渡效果。

过渡动画示例 展示了通过修改 leave 样式来实现骨架淡出效果。

• 默认值:

  {
    style: {},
    className: '',
  }