# @gluhar/app 中文文档

规范地址：https://npmcn.com/package/%40gluhar/app/

版本：6\.4\.1
npm 元数据更新时间：2026-11-16T12:46:08.887Z
中文译文更新时间：2026-11-16T16:56:22.492Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gluhar/app
原文对照：https://npmcn.com/package/%40gluhar/app/?lang=original
项目主页：https://github.com/gluharco/gluhar#readme
源码仓库：https://github.com/gluharco/gluhar

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：70.2 kB，41 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：13 个
- peer 依赖：nuxt ^4\.6\.2
- 首次发布：2025-01-22T11:47:27.160Z
- 最新版本发布：2026-11-16T12:46:08.655Z
- 近 30 天下载量：2933（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：81（近 12 个月 34 个）

## 中文简介

格卢哈尔主包. 将@gluhar/them,@gluhar/i18n,@gluhar/sanity和@gluhar/core组合成一个主包. 提供众多的组件,可堆肥,利用和类型.

## 安装

```sh
npm install @gluhar/app
```

也可以使用：`pnpm add @gluhar/app`、`yarn add @gluhar/app`、`bun add @gluhar/app`

## README

# `@gluhar/app`

[![npm version](https://img.shields.io/npm/v/my-module/latest.svg?style=flat&colorA=020420&colorB=00DC82)](https://npmjs.com/package/my-module) [![npm downloads](https://img.shields.io/npm/dm/my-module.svg?style=flat&colorA=020420&colorB=00DC82)](https://npmjs.com/package/my-module) [![License](https://img.shields.io/npm/l/my-module.svg?style=flat&colorA=020420&colorB=00DC82)](https://npmjs.com/package/my-module) [![Nuxt](https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js)](https://nuxt.com/)

格卢哈尔主包. 将@gluhar/them,@gluhar/i18n,@gluhar/sanity和@gluhar/core组合成一个主包. 提供众多的组件,可堆肥,利用和类型.

[QQ 发布注释](https://npmcn.com/CHANGELOG.md)

## 安装

用一个命令将模块安装到您的 Nuxt 应用程序 :

```bash
npx nuxi module add @gluhar/app
```

## 使用量

### 页面转换( E)`usePageTransition`(中文(简体) )

路由器驱动的页面转换. 航行前请假,一直到 时间线完成; 输入等待到进入的页面 **已执行** (纽斯特的) `page:finish`,所以一个页面等待 `useFetch` 编号 : `useSinglePage` 在屏幕上先,盖上 以 `readyTimeout`。用它来包装页面,从不每页:

```vue
<!-- components/layout/PageTransition.vue -->
<script setup lang="ts">
const wrapper = ref<HTMLElement>();
const overlay = ref<HTMLElement>();

usePageTransition({
  // Forward = leave (visible → hidden), reversed = enter. The project owns the look.
  timeline: (gsap) =>
    gsap
      .timeline()
      .fromTo(wrapper.value!, { opacity: 1 }, { opacity: 0, duration: 0.5 })
      .fromTo(overlay.value!, { autoAlpha: 0 }, { autoAlpha: 1, duration: 0.5 }, 0),
});
</script>

<template>
  <div ref="wrapper"><slot /></div>
  <div ref="overlay" class="pointer-events-none fixed inset-0 invisible bg-white" />
</template>
```

这里滚动不需要什么: Nuxt 的路由器将窗口滚动到顶端( 或散列) 一旦新的页面被打开 列尼斯被暂停休假 并恢复进入, 重新同步到那个位置 .

```vue
<!-- layouts/default.vue: no :key on the wrapper, it must not remount per route -->
<PageTransition><main><slot /></main><Footer /></PageTransition>
```

| 选项 | 默认 |  |
| --- | --- | --- |
| `timeline(gsap)` | 所需经费 | 内建 `onMounted` (意见已设定). 别设了 `paused` 编号 : `onComplete` 编号 : `onReverseComplete`: 可调和的暂停 `kill()`打开它 |
| `onEnter(to)` | —— 说 | 运行在所提供新页面和路由器滚动后, 在输入播放之前 |
| `skip(to, from)` | —— 说 | 航行让无动于衷。 同路径( 仅用hash/ 查询) 导航从不过渡 |
| `firstEnter` | `"none"` | `"none"`: 服务器发送的页面显示为原样( 无闪光, LCP 中无保留) . `"manual"`: 开始隐藏直到 `usePageTransitionStore().allowFirstEnter()`,例如从装载器中 |
| `readyTimeout` | `3000` | 在输入前最长时间等待到的页面 |

在休假开始后中止或丢弃的导航带入当前页面 回来. `usePageTransitionStore()` 曝光情况 `phase` (单位:千美元)`idle` 编号 : `leaving` 编号 : `entering` 编号 : `entered`, (中文(简体) ), `entered`, (中文(简体) ), `transitioning`, (中文(简体) ), `enterCycle` 编号 : `leaveCycle` (每个完成的跳出) 输入/ 离开, 以重放一节的入声)和 `setDelay(ms)` (保持下一个输入).

### 平滑滚动( E)`gluhar.lenis`(中文(简体) )

[列尼斯语Name](https://github.com/darkroomengineering/lenis) 编辑 **窗口**,默认情况下:

```ts
// nuxt.config.ts
gluhar: {
  lenis: { lerp: 0.1, wheelMultiplier: 1 }, // or true (defaults) / false (native scrolling)
}
```

-   由GSAP的计时器驱动 `ScrollTrigger.update` 每个卷轴上,都有钉住的 被擦拭的相片与卷轴保持同一框.
-   列尼斯荣誉 `prefers-reduced-motion` 本身,然后在本地滚动.
-   选项被序列化为运行时配置, 因此函数( S) :`easing`, (中文(简体) ), `prevent`, (中文(简体) ), `virtualScroll`),元素不能在此设置. 配置实例.
-   `useLenis()` 返回时 `{ lenis }`,一个计算的例子。 没错 `null` 编辑 服务器,使用 `lenis: false`,或者在客户端插件运行之前,所以总是选择链 内容: `lenis.value?.scrollTo("#faq", { offset: -80 })`。 。 。 .
-   在页面中滚动 `lenis.value.scrollTo` 当它运行时,从没有GSAP的twen 窗口:两个争夺位置.
-   要让列尼斯远离一个本土可滚动元素(地图,代码块),请添加 `data-lenis-prevent`。 。 。 .

页面本身总是在窗口上滚动. 没有页面级滚动容器 (单位:千美元)`useLenis("#scroller")`:一个断了本地锚,路由器的卷轴还原, `position: sticky` 和每个不命名为 联合国 `scroller`。 。 。 .

### 薄膜平滑滚动( N)`<GLenisScroller>`(中文(简体) )

对于在页面内自行滚动的区域(模式正文、侧面板、 水平条),带有自己的列尼斯:

```vue
<GLenisScroller class="h-[60svh]" content-class="p-6" :options="{ lerp: 0.12 }">
  …
</GLenisScroller>
```

-   该元素需要一个有限度的大小(高度,或弹性/网格大小)来滚动.
-   它携带 `data-lenis-prevent`,所以窗口 Lenis 忽略了轮子和触摸事件 里面还有两个从不同时滚动的 和我们一起工作 `gluhar.lenis: false` 我也一样.
-   展览 `lenis`, (中文(简体) ), `scrollerRef` 财务报告和审定财务报表 `contentRef`。其内部的 ScrollTrigger 必须命名 元素: `scroller: scroller.value.scrollerRef`。 。 。 .
-   事实并非如此 `useLenis()` 返回,且页面转换不会暂停.

### 卫生图像( N)`<SanityImg>`(中文(简体) )

过 `sizes` 用于响应服务器的图像 : `srcset` 结束 `widths` (从来没有过去) 原始的宽度, `auto=format`质量75, `loading="lazy"` (与 `loading="eager"` + 键 `fetchpriority="high"` 第一个图像)和 `object-position` 从 热点. `placeholder` 添加 lqip 作为模糊的背景, 直到图像装入( 那么它就是) 被删除,所以它从来没有显示 `object-contain` )),字母收发. 查找资产 维度和方位: `photo{ ..., asset->{ _id, metadata { lqip, dimensions } } }`。 。 。 .

```vue
<SanityImg class="absolute inset-0 size-full" :image="photo" sizes="(min-width: 48rem) 33vw, 100vw" />
```

无 `sizes` 它保持了旧的行为: 上载后 URL 大小为元素 (无) `src` 在服务器上,所以更喜欢 `sizes` 上面的列表和任何东西.

### SEO 和链接预览`useSeo`(中文(简体) )

`useSeo(seo?)` 设置标题、描述和 OG / Twitter 集、 服务器已交付并保存在内 在客户端上同步,返回默认的 SEO 文档字段。 传个接通 对于依赖于状态(被过滤的视图)、平方字符串或本地字段的值,a `ogImage` 卫生图像(其热点上1200×630个作物由资产建造;a `asset.url` 绝对 `url` 页:1 `og:url`数字 :

```ts
useSeo(() => ({ title: viewTitle.value, ogImage: first.value?.photos?.[0], url: absoluteUrl.value }));
```

### 目标

`gsap` 属于 `@gluhar/app`。滚动拖取器和滚动拖取器已注册 在客户端。 导入( E)`import { gsap } from "gsap"`)或使用自动进口 `useGSAP()` 财务报告和审定财务报表 `useScrollTrigger()`,返回相同的对象。 增加的项目 `gsap` 本身应该保持相同的范围,所以 npm 安装一个副本:两个副本意味着 两下,莱尼斯会更新一个ScrollTrigger 没有人听.

v- gsap- nuxt 未安装( 因为 `6.0.0-next.10`) (中文(简体) ).

## 配置

## 捐款

地方发展

```bash
# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release
```

## 常见问题

### @gluhar/app 是什么？

格卢哈尔主包\. 将@gluhar/them,@gluhar/i18n,@gluhar/sanity和@gluhar/core组合成一个主包\. 提供众多的组件,可堆肥,利用和类型\.

### 如何安装 @gluhar/app？

在项目目录运行 npm install @gluhar/app，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：nuxt（^4\.6\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gluhar/app 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @gluhar/app 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @gluhar/app 可以商用吗？

@gluhar/app 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gluhar/app 的下载量有多少？

根据 npm 官方下载统计，@gluhar/app 在 2026/10/17 – 2026/11/15 这 30 天内被下载 2,933 次，日均约 98 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gluhar/app 还在维护吗？

最新版本 6\.4\.1 发布于 2026/11/16（今天）；至今共发布 81 个版本，其中过去 12 个月发布了 34 个；首次发布于 2025/01/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

