# @navelcloud/nuxt-core 中文文档

规范地址：https://npmcn.com/package/%40navelcloud/nuxt-core/

版本：0\.0\.28
npm 元数据更新时间：2026-11-01T22:15:56.776Z
中文译文更新时间：2026-11-01T23:38:22.514Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40navelcloud/nuxt-core
原文对照：https://npmcn.com/package/%40navelcloud/nuxt-core/?lang=original

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

- 包体积（解压后）：102 kB，39 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：nuxt ^4\.5\.2，@nuxtjs/i18n ^10\.6\.0
- 首次发布：2026-09-19T21:38:54.571Z
- 最新版本发布：2026-11-01T22:15:56.595Z
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

应用程序级别的下一层，用于Navel Cloud站点和应用程序。

## 安装

```sh
npm install @navelcloud/nuxt-core
```

也可以使用：`pnpm add @navelcloud/nuxt-core`、`yarn add @navelcloud/nuxt-core`、`bun add @navelcloud/nuxt-core`

## README

# Nuxt核心

应用程序级别的下一层，用于Navel Cloud站点和应用程序。

## 安装

```sh
npm install @navelcloud/nuxt-core
```

从消费next应用程序扩展包：

```js
export default defineNuxtConfig({
  extends: ['@navelcloud/nuxt-core'],
})
```

`@navelcloud/nuxt-core` 扩展 `@navelcloud/api-client` 并拥有共享的应用程序运行时行为，包括API/auth状态、模块访问、租户引导、i18n、运行时主题值和可视化站点编辑器桥。

## 本地翻译退路

模板可以保留自己的默认副本，而无需重新引入i18n配置。将JSON文件放在消费应用程序的根目录中 `i18n/locales` 目录:

```text
i18n/locales/en.json
i18n/locales/nl.json
i18n/locales/de.json
```

解析顺序是包默认值，然后是本地模板文件，然后是API返回的运行时翻译字典。后面的层覆盖前面的层，同时保留不相关的嵌套键。

## 运行时主题值

`useTheme()` 使用当前站点主机名从API加载特定于站点的值。值位于部署之外，因此更改它们不需要构建或重新部署。

```vue
<script setup>
const theme = useTheme()
const heroImage = computed(() => theme.image('home.hero.image', '/images/default-hero.jpg'))
</script>

<template>
  <img
    :src="heroImage"
    alt=""
    v-site-editor="{
      source: 'theme',
      type: 'image',
      key: 'home.hero.image',
      label: 'Hero image',
      original: '/images/default-hero.jpg',
    }"
  >
</template>
```

扩展该层但不是租户站点模板的管理应用程序可以禁用运行时主题请求 `runtimeConfig.public.siteThemeEnabled = false`.

### 主题拥有的外观控件

站点主题可以声明由管理主题编辑器公开的外观控件 `runtimeConfig.public.siteThemeEditor`． 管理应用程序一般呈现此元数据；色键、可用方案、选择选项和调色板仍然属于主题。

```js
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      siteThemeEnabled: true,
      siteThemeEditor: {
        scheme: {
          key: 'colors.scheme',
          label: 'Color scheme',
          default: 'light',
          options: [
            { value: 'light', label: 'Light' },
            { value: 'dark', label: 'Dark' },
          ],
        },
        colors: [
          { key: 'colors.background', label: 'Background', default: '#ffffff' },
          {
            key: 'theme.primary',
            label: 'Primary',
            type: 'select',
            default: 'blue',
            options: [
              { value: 'blue', label: 'Blue' },
              { value: 'violet', label: 'Violet' },
            ],
          },
        ],
        palettes: [
          {
            id: 'clean',
            name: 'Clean',
            scheme: 'light',
            swatches: ['#ffffff', '#2563eb', '#171717'],
            values: {
              'colors.background': '#ffffff',
              'theme.primary': 'blue',
            },
          },
        ],
      },
    },
  },
})
```

`scheme` 是可选的。 `colors` 字段默认为本机颜色输入，可以使用 `type: 'select'` 与theme-owned `options`． 调色板 `scheme` 值可选地将调色板限定为一个配色方案。 `swatches` 是调色板的可选显示颜色，其实际值是语义名而不是CSS颜色。

所有声明的值都使用标准 `useTheme().value(key, fallback)` 运行时的路径。编辑器预览桥暂时覆盖值 `setPreviewValues()` 和持久化值继续使用现有的站点主题API。

## 网站编辑器

翻译通过 `$t()` 在使用？打开站点时自动公开的 `?site_editor=1`． 包保留现有的 `navel:site-editor:translation` 消息，并发出泛型的 `navel:site-editor:select` 消息。

`v-site-editor` 和 `useSiteEditor().attributes()` 只携带字段元数据(`source`， `type`， `key`， `label`， `original`）. 管理应用程序决定哪个编辑器UI属于某个字段类型。主题图像更新可以通过张贴立即应用 `navel:site-editor:refresh-theme` 回到预览iframe。

### 资源支持主题字段

主题组件可以通过相同的站点编辑器契约公开资源选择。主题只声明资源类型和主题键；管理应用程序拥有选择器UI和资源查找。键是特定于主题的，但编辑器类型在每个主题之间共享。

目前支持的管理编辑器资源类型包括 `calendar`， `collection`, `form`.

```vue
<script setup>
const theme = useTheme()
const calendarId = computed(() => theme.value('booking.calendar_id', ''))
const collection = computed(() => theme.value('journal.collection', 'news'))
const form = computed(() => theme.value('contact.form', 'contact'))
</script>

<template>
  <BookingCalendar
    v-site-editor="{
      source: 'theme',
      type: 'calendar',
      key: 'booking.calendar_id',
      label: 'Booking calendar',
      original: '',
    }"
    :calendar-id="calendarId"
  />

  <Journal
    v-site-editor="{
      source: 'theme',
      type: 'collection',
      key: 'journal.collection',
      label: 'Journal collection',
      original: 'news',
    }"
    :collection="collection"
  />

  <ContactForm
    v-site-editor="{
      source: 'theme',
      type: 'form',
      key: 'contact.form',
      label: 'Contact form',
      original: 'contact',
    }"
    :form="form"
  />
</template>
```

当组件需要转发属性时，同样的元数据也可以不用指令来应用：

```js
const siteEditor = useSiteEditor()

const editorAttributes = siteEditor.resourceAttributes(
  'collection',
  'journal.collection',
  'news',
  'Journal collection',
)
```

`app.navel.cloud` 将资源类型解析为租户API并呈现一个选择列表。主题不包含资源列表或管理编辑器逻辑。

## 可视化页面布局

站点构建器通过next层共享两个UI组件： `SitePageLayout` （在SSR期间呈现注册的Vue块）和 `SiteLayoutEditor` （在管理仪表板中编辑JSON页面布局）。各个主题注册它们构建的Vue组件，并公开一个可序列化的 `siteBuilderBlocks` 列表中 `runtimeConfig.public` 给编辑的。iframe预览将此列表发送给管理编辑器 `navel:site-layout:config`． 只有注册的组件类型才能呈现。

页面布局使用 `{ "schemaVersion": 1, "sections": [{ "id": "hero-1", "type": "hero", "props": { "title": "Welcome" } }] }`． Laravel Workers API包含单独的草稿和已发布的布局。 `useSiteContent().fetchPage(path)` 获取已发布的内容(包括 `path = ''` 对于主页)，而 `fetchPreview(pageId, token)` 获取授权的短期汇票。如果不存在已发布的布局，则模板实现应该呈现其原始页面，并且应该只使用控件中的预览端点 `noindex` 编辑路线。

### 本地主题部分

`SitePageLayout` 可以通过命名槽呈现原始主题自己的标记，而无需从页面中提取API工作流或替换视觉设计：

```vue
<SitePageLayout :layout="layout" :registry="{}">
  <template #hero>
    <section class="theme-hero">Original hero</section>
  </template>
  <template #services>
    <ModuleView module="appointments">
      <section class="theme-services">Original booking services</section>
    </ModuleView>
  </template>
</SitePageLayout>
```

主题通过声明其现有的节类型 `runtimeConfig.public.siteBuilderBlocks`，以及其当前的顺序 `siteBuilderDefaultLayout` （与发布页面相同的JSON版本布局模式）。iframe `navel:site-layout:config` 消息可以包括 `defaultLayout` 所以 `SiteLayoutEditor` 何时可以初始化新的未保存的草稿 `initializeFromTheme` 是真的。现有的、有意保存的草稿永远不会被该初始化覆盖。普通公共页面在出现时使用已发布的布局，否则呈现主题的默认值。

插槽保存所有现有的页作用域变量、事件绑定、翻译和模块条件。无法识别的块类型不会呈现。现有的组件注册表块将继续工作。不要直接通过 `postMessage`;编辑器在发送之前序列化布局。

## 常见问题

### @navelcloud/nuxt-core 是什么？

应用程序级别的下一层，用于Navel Cloud站点和应用程序。

### 如何安装 @navelcloud/nuxt-core？

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

### @navelcloud/nuxt-core 支持 TypeScript 吗？

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

### @navelcloud/nuxt-core 支持 ESM 还是 CommonJS？

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

### @navelcloud/nuxt-core 可以商用吗？

@navelcloud/nuxt-core 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @navelcloud/nuxt-core 还在维护吗？

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