# @dotcms/vue 中文文档

规范地址：https://npmcn.com/package/%40dotcms/vue/

版本：26\.11\.2-3
npm 元数据更新时间：2026-11-11T19:25:07.287Z
中文译文更新时间：2026-11-12T21:33:52.334Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40dotcms/vue
原文对照：https://npmcn.com/package/%40dotcms/vue/?lang=original
项目主页：https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/vue/README.md
源码仓库：https://github.com/dotCMS/core#main

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

- 包体积（解压后）：103 kB，48 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：vue \>=3\.4，@dotcms/uve 26\.11\.2-3，@dotcms/types 26\.11\.2-3，@dotcms/client 26\.11\.2-3
- 首次发布：2026-07-08T22:43:26.092Z
- 最新版本发布：2026-11-11T19:25:07.037Z
- 近 30 天下载量：4848（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：94（近 12 个月 94 个）

## 中文简介

官方 Vue 组件库来渲染一个 DotCMS 页面 .

## 安装

```sh
npm install @dotcms/vue
```

也可以使用：`pnpm add @dotcms/vue`、`yarn add @dotcms/vue`、`bun add @dotcms/vue`

## README

# 点CMS Vue SDK

这个 `@dotcms/vue` SDK是"点"CMS官方Vue 3库. 它赋予了Vue开发者在不时建立强大,可编辑的网站和应用程序的能力,同时全力支持通用视觉编辑器(UVE).

## 目录

-   [先决条件设置( S)](https://npmcn.com/package/%40dotcms/vue/#readme-prerequisites--setup)
    -   [获取点CMS 环境](https://npmcn.com/package/%40dotcms/vue/#readme-get-a-dotcms-environment)
    -   [配置通用视觉编辑器 App](https://npmcn.com/package/%40dotcms/vue/#readme-configure-the-universal-visual-editor-app)
    -   [创建点CMS API 密钥](https://npmcn.com/package/%40dotcms/vue/#readme-create-a-dotcms-api-key)
    -   [安装](https://npmcn.com/package/%40dotcms/vue/#readme-installation)
    -   [dotCMS 客户端配置](https://npmcn.com/package/%40dotcms/vue/#readme-dotcms-client-configuration)
    -   [静态资产的代理配置](https://npmcn.com/package/%40dotcms/vue/#readme-proxy-configuration-for-static-assets)
-   [快速启动: 将一个页面渲染为 dotCMS](https://npmcn.com/package/%40dotcms/vue/#readme-quickstart-render-a-page-with-dotcms)
    -   [示例项目](https://npmcn.com/package/%40dotcms/vue/#readme-example-project-)
-   [SDK 参考](https://npmcn.com/package/%40dotcms/vue/#readme-sdk-reference)
    -   [创建 DotCMSVue / 使用 DotCMS 客户端](https://npmcn.com/package/%40dotcms/vue/#readme-createdotcmsvue--usedotcmsclient)
    -   [点数CMSLayoutBody](https://npmcn.com/package/%40dotcms/vue/#readme-dotcmslayoutbody)
    -   [DotCMSE可变文本](https://npmcn.com/package/%40dotcms/vue/#readme-dotcmseditabletext)
    -   [DotCMSBlock 编辑器](https://npmcn.com/package/%40dotcms/vue/#readme-dotcmsblockeditorrenderer)
    -   [DotCMSShow 游戏](https://npmcn.com/package/%40dotcms/vue/#readme-dotcmsshow)
    -   [使用 EdiableDotCMSPage 软件](https://npmcn.com/package/%40dotcms/vue/#readme-useeditabledotcmspage)
    -   [何时使用 DotCMSSshow](https://npmcn.com/package/%40dotcms/vue/#readme-usedotcmsshowwhen)
    -   [创建 DotCMSimage 记录器](https://npmcn.com/package/%40dotcms/vue/#readme-createdotcmsimageloader)
    -   [已删除](https://npmcn.com/package/%40dotcms/vue/#readme-toplain)
-   [解决问题](https://npmcn.com/package/%40dotcms/vue/#readme-troubleshooting)
    -   [共同问题和解决方案](https://npmcn.com/package/%40dotcms/vue/#readme-common-issues--solutions)
    -   [调试提示](https://npmcn.com/package/%40dotcms/vue/#readme-debugging-tips)
    -   [还有什么问题吗?](https://npmcn.com/package/%40dotcms/vue/#readme-still-having-issues)
-   [支助](https://npmcn.com/package/%40dotcms/vue/#readme-support)
-   [捐款](https://npmcn.com/package/%40dotcms/vue/#readme-contributing)
-   [许可证发放](https://npmcn.com/package/%40dotcms/vue/#readme-licensing)

## 先决条件设置( S)

### 获取点CMS 环境

#### 我该用哪个SDK版本?

dotCMS SDKs 发布在锁定步骤中,同时发布 dotCMS 本身: 每 `@dotcms/*` 货包船 地点 **完全相同的版本编号** 作为点CMS的发布,它是为(例如:点CMS)而建的 `26.7.14-1` → `@dotcms/client@26.7.14-1`, (中文(简体) ), `@dotcms/react@26.7.14-1`,等等).

**简单的拇指规则:使用匹配您点CMS实例版本的 SDK 版本.**

每次dotCMS发布新版本(反之亦然)时,你不必升级SDK. 大部分的发布都不会改变SDK所依赖的东西,所以一个更老的SDK通常会继续工作 对一个新的点CMS案例,罚款。 但偶尔,释放确实包括一个真正的 打破更改——如果您的 SDK 年龄超过此点, 它会停止正确工作 .

你不需要自己去跟踪它: 你的点CMS实例总是知道最古老的SDK 版本它仍然支持,SDK自动对照它检查自己. 狦琌 使用SDK这个太老了,你会看到一个清晰的警告 在你的控制台上告诉你 升级.

**建议:** 将您的 SDK 与您的点CMS 实例相同的版本连接, 并且只接通 当您升级了点CMS, 或者当控制台告诉你.

> **在LTS发布?** LTS发行版目前没有获得自己匹配的SDK版本. 在解决之前,请使用所出版的SDK版本,以便最接近定期发布 或者在你的LTS版本之前.
> 
> 想要更多关于dotCMS发布和支持窗口如何工作的背景吗? 见 [发布和支持生命周期( S)](https://dev.dotcms.com/docs/release-support-lifecycle)。 。 。 .

#### 环境设置

**用于生产:**

-   ☁️ [云托管选项](https://www.dotcms.com/pricing) - 与苏丹解放军管理解决方案
-   🛠️ [自备选项](https://dev.dotcms.com/docs/current-releases) - 在你的基础设施上部署

**测试和开发:**

-   🧑🏻‍💻 [dotCMS 演示站点](https://demo.dotcms.com/dotAdmin/#/public/login) - 适合试出SDK
-   📘 [学习如何使用演示网站](https://dev.dotcms.com/docs/demo-site)
-   \* 只读访问,理想的概念证明

**促进地方发展:**

-   🐳 [Docker 设置指南](https://github.com/dotCMS/core/tree/main/docker/docker-compose-examples/single-node-demo-site)
-   💻 [本地安装指南](https://dev.dotcms.com/docs/quick-start-guide)

### 配置通用视觉编辑器 App

关于设置世界视觉编辑器的分步指南 请检查我们 [容易遵循的指令](https://dev.dotcms.com/docs/uve-headless-config) 马上就开始!

当配置UVE应用时,将其指向您Vue应用的URL(例如. `http://localhost:5173`:

```json
{ "config": [{ "pattern": "(.*)", "url": "http://localhost:5173" }] }
```

### 创建点CMS API 密钥

> \[TIP\] 请确定您的 API Token 对页面、 文件夹、 资产和内容有只读权限 。 使用最少许可的密钥遵循安全最佳做法.

这种集成需要包含只读权限的 API 密钥用于安全最佳做法 :

1.  转到 **dotCMS 管理员面板**。 。 。 .
2.  点击 **系统** > 翻译: **用户**。 。 。 .
3.  选择要创建 API 密钥的用户.
4.  转到 **API 访问密钥** 生成新密钥.

关于详细说明,请参见: [dotCMS API 文档 - 只读符号](https://dev.dotcms.com/docs/rest-api-authentication#ReadOnlyToken)。 。 。 .

### 安装

```bash
npm install @dotcms/vue@latest
```

要求数 **第3.4条+** (被宣布为同伴依赖). 安装也带来 `@tinymce/tinymce-vue` (授权内置文本编辑于 [`DotCMSEditableText`](https://npmcn.com/package/%40dotcms/vue/#readme-dotcmseditabletext), (中文(简体) ), 但你需要自己安装这些软件包:

-   `@dotcms/uve`: 启用与该对话框的互动 [通用视觉编辑器](https://dev.dotcms.com/docs/uve-headless-config) 用于实时内容编辑
-   `@dotcms/client`: 提供获取和管理dotCMS数据的核心客户端功能
-   `@dotcms/types`: 整个API中所使用的类型脚本定义

```bash
npm install @dotcms/uve @dotcms/client @dotcms/types
```

> npm 7+ 和 pnpm 将这些自动安装为对等依赖性 `@dotcms/vue`。 。 。 . **Yarn Classic (1. x) 和 npm under v7 下没有** 他们只印一个警告 如果缺少一个, 因此,对于这些软件包管理器,您必须如上所示明确添加.

### dotCMS 客户端配置

启动时安装一次点CMS Vue插件 。 它构建客户端并提供 整个应用,所以组件取回它 `useDotCMSClient()` 换成 输入模块级单子的相模 `provideDotCMSClient`。 。 。 .

```ts
// main.ts
import { createApp } from 'vue';
import { createDotCMSVue } from '@dotcms/vue';

import App from './App.vue';

const app = createApp(App);

app.use(
    createDotCMSVue({
        dotcmsUrl: import.meta.env.VITE_DOTCMS_HOST,
        authToken: import.meta.env.VITE_DOTCMS_AUTH_TOKEN, // Optional for public content
        siteId: import.meta.env.VITE_DOTCMS_SITE_ID, // Optional site identifier/name
        requestOptions: {
            // The UVE needs fresh data so in-context edits are reflected immediately.
            cache: 'no-cache'
        }
    })
);

app.mount('#app');
```

然后,在任何组件中:

```vue
<script setup lang="ts">
import { useDotCMSClient } from '@dotcms/vue';

const client = useDotCMSClient();
const { pageAsset } = await client.page.get('/');
</script>
```

> **在组件之外使用客户端?** 代码在 a 之前/ 之外运行 组件 `setup` ——例如Vue路由器的页面加载器——不能调用 `useDotCMSClient()`并读取插件 `.client`数字 :
> 
> ```ts
> export const dotCMSVue = createDotCMSVue({ ...config });
> export const dotCMSClient = dotCMSVue.client; // same instance the plugin provides
> ```

如果你喜欢自己管理客户, `createDotCMSClient` 从 `@dotcms/client` 仍然可用,并且与SDK的所有组件一起工作 和可堆积物——插件是一种方便,而不是要求.

```typescript
import { createDotCMSClient } from '@dotcms/client';

export const dotCMSClient = createDotCMSClient({
    dotcmsUrl: import.meta.env.VITE_DOTCMS_HOST,
    authToken: import.meta.env.VITE_DOTCMS_AUTH_TOKEN,
    siteId: import.meta.env.VITE_DOTCMS_SITE_ID,
    requestOptions: { cache: 'no-cache' }
});
```

### 静态资产的代理配置

配置一个代理以杠杆作用强大的点CMS图像 API,允许您调整大小并高效服务优化的图像. 这提高了应用性能并改进了用户体验.

#### 1\. 配置维特

```ts
// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
    server: {
        proxy: {
            '/dA': {
                target: 'https://your-dotcms-instance.com',
                changeOrigin: true
            }
        }
    }
});
```

更多地了解 Vite 配置 [这里](https://vitejs.dev/config/)。 。 。 .

#### 2\. 组件的使用

一旦配置, 您组件中的图像 URL 将自动被代理到您的点CMS 实例 :

> 更多关于 [在 dotCMS 中的图像调整大小和处理](https://www.dotcms.com/blog/image-resizing-and-processing-in-dotcms-with-angular-and-nextjs)。 。 。 .

```vue
<script setup lang="ts">
import type { DotCMSBasicContentlet } from '@dotcms/types';

defineProps<{ contentlet: DotCMSBasicContentlet }>();
</script>

<template>
    <img :src="`/dA/${contentlet.inode}`" :alt="contentlet.title" />
</template>
```

## 快速启动: 将一个页面渲染为 dotCMS

以下示例显示如何在您 Vue 应用程序中快速设置一个基本的 dotCMS 页面渲染器 。 它表明如何:

-   获取一个 DotCMS 页面并将其渲染为 `DotCMSLayoutBody`
-   将内容类型映射到自己的 Vue 组件
-   将页面保留在通用视觉编辑器内可编辑和实时更新

因为一个 Vue 相容性必须被称为同步 `setup`从渲染中获取的推荐模式分割:a **获取器** 装入页面,然后挂载 **渲染器** 接收已解析页面和呼叫的孩子 `useEditableDotCMSPage`。 。 。 .

```vue
<!-- PageView.vue — fetches the page, then mounts the renderer -->
<script setup lang="ts">
import { shallowRef, onMounted } from 'vue';

import PageRenderer from './PageRenderer.vue';
import { dotCMSClient } from './dotCMSClient';

// shallowRef keeps the response a plain object (see toPlain / reactivity note below).
const pageResponse = shallowRef<Awaited<ReturnType<typeof dotCMSClient.page.get>> | null>(null);

onMounted(async () => {
    pageResponse.value = await dotCMSClient.page.get('/');
});
</script>

<template>
    <PageRenderer v-if="pageResponse" :page-response="pageResponse" />
</template>
```

```vue
<!-- PageRenderer.vue — renders the resolved page -->
<script setup lang="ts">
import { DotCMSLayoutBody, useEditableDotCMSPage } from '@dotcms/vue';
import { computed } from 'vue';

import Blog from './content-types/Blog.vue';
import Product from './content-types/Product.vue';

const props = defineProps<{ pageResponse: unknown }>();

const pageComponents = {
    Blog,
    Product
};

// Returns a reactive ref that live-updates while editing in the UVE.
const page = useEditableDotCMSPage(props.pageResponse as never);
const pageAsset = computed(() => page.value?.pageAsset);
</script>

<template>
    <DotCMSLayoutBody v-if="pageAsset" :page="pageAsset" :components="pageComponents" />
</template>
```

### 示例项目

想快点开始吗? 我们 [Vue.js 启动项目](https://github.com/dotCMS/core/tree/main/examples/vuejs) 是完美的发射板。 此 Vite + TypeScript + Tailwind 模板显示您需要的一切 :

QQ 获取和渲染带有最佳做法的 DotCMS 页面 将组件映射到不同内容类型 列出有搜索功能的页面 与块编辑器的详细页面 \* 图像和资产优化,以提高业绩 通过通用视觉编辑器(UVE)进行无缝编辑 Vue Constitution API + 反应活性更新

## SDK 参考

所有部件、可堆肥和公用事业均从下列来源进口: `@dotcms/vue`。 。 。 .

### 创建 DotCMSVue / 使用 DotCMS 客户端

`createDotCMSVue(config)` 返回用于构建点CMS客户端的 Vue 插件 提供全应用. `useDotCMSClient()` 从任何 组件。 见 [dotCMS 客户端配置](https://npmcn.com/package/%40dotcms/vue/#readme-dotcms-client-configuration) 页:1 全部设置.

```ts
import { createDotCMSVue } from '@dotcms/vue';

const plugin = createDotCMSVue({ dotcmsUrl, authToken /* …DotCMSClientConfig */ });
app.use(plugin);
```

| 导出 | 签署 | 说明 |
| --- | --- | --- |
| `createDotCMSVue(config)` | `(config: DotCMSClientConfig) => DotCMSVuePlugin` | Vue 插件用于 `app.use()`。 。 。 . `config` 被 `createDotCMSClient`。 。 。 . |
| `useDotCMSClient()` | `() => DotCMSClient` | 返回所提供的客户端 。 如果插件没有安装则丢出 。 进去吧 `setup`。 。 。 . |
| `DotCMSVuePlugin.client` | `DotCMSClient` | 创建的客户端实例,用于外部组件(如路由器加载器). |

### 点数CMSLayoutBody

`DotCMSLayoutBody` 使一个dotCMS页面的布局(行) ~列 ~ 容器 → 内容片,将每个内容片发送到映射的组件. 它支持生产和发展模式.

| Prop | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `page` | `DotCMSPageAsset` | ✅ | \- 说吧 | 包含要渲染的布局的页面资产 |
| `components` | `Record<string, Component>` | ✅ | `{}` | [内容类型- Vue 组件地图](https://npmcn.com/package/%40dotcms/vue/#readme-component-mapping) |
| `mode` | `DotCMSPageRendererMode` | ❌ | `'production'` | [渲染模式(“生产”或“开发”)](https://npmcn.com/package/%40dotcms/vue/#readme-layout-body-modes) |

#### 使用量

```vue
<script setup lang="ts">
import { DotCMSLayoutBody } from '@dotcms/vue';
import type { DotCMSPageAsset } from '@dotcms/types';

import Blog from './content-types/Blog.vue';
import Product from './content-types/Product.vue';

defineProps<{ page: DotCMSPageAsset }>();

const components = {
    Blog,
    Product
};
</script>

<template>
    <DotCMSLayoutBody :page="page" :components="components" />
</template>
```

#### 布局正文模式

-   `production`: 性能优化模式,只使内容带有明确映射的组件,使未映射的内容空出.
-   `development`: 调试方便模式,使未映射的内容类型倒置,并显示空容器和缺失映射的可视化指标. **UVE 内部自动检测到编辑模式** - 编辑 `data-dot-*` 元数据总是不计其数 `mode` 道具 (英语).

#### 构成部分绘图

这个 `components` prop将内容类型可变名称映射到Vue组件. 每个内容的字段被传递到匹配的组件作为道具.

```typescript
const components = {
    Blog: MyBlogCard,
    Product: MyProductCard,
    CustomNoComponent: MyFallback // optional: rendered for unmapped types in dev mode
};
```

-   键( 如 . `Blog`, (中文(简体) ), `Product`: 必须符合您的 [内容类型可变名称](https://dev.dotcms.com/docs/content-types#VariableNames) 在点数据管理系统中(它们具有大小写敏感性——例如). `webPageContent`, (中文(简体) ), `calendarEvent`) (中文(简体) ).
-   值:使该内容类型具有Vue组件。 声明您使用的字段的打入道具界面 – do **没有** 散开全部 `DotCMSBasicContentlet` 键入组件,因为 Vue 运行时验证每个已声明的道具和点CMS 船载一些字段(例如. `language`, (中文(简体) ), `modDate`),类型与defs类型不同.
-   特别节目 `CustomNoComponent` 键是当不存在映射时产生的倒计时.

> \[TIP\] 总是使用从 dotCMS 得到的确切内容类型可变名称作为密钥. 您可以在您 dotCMS 管理面板的内容类型部分找到它.

#### 每个内容槽

除了按内容类型映射外,您还可以覆盖一个 **具体** 内容由 联合国 `identifier` 使用命名槽 : `#contentlet-<identifier>`。当存在时, 时空档代替映射的组件——反应的Vue模拟 SDK的车 `slots` 道具,用于一次性自定义标记或预发节点.

内容被曝光为插槽范围道具.

```vue
<template>
    <DotCMSLayoutBody :page="page" :components="components">
        <!-- Renders instead of the Blog component for this one contentlet -->
        <template #contentlet-a1b2c3d4="{ contentlet }">
            <FeaturedBlog :blog="contentlet" />
        </template>
    </DotCMSLayoutBody>
</template>
```

没有相配槽的内容返回到 `components` 照常绘制地图.

### DotCMSE可变文本

`DotCMSEditableText` 允许对 dotCMS 中的单个文本字段进行内置编辑。 在编辑模式下的 UVE 中, 它会挂载一个 TinyMCE 编辑器; 在其它任何地方它都会使字段的当前值 .

| Prop | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `contentlet` | `T extends DotCMSBasicContentlet` | ✅ | \- 说吧 | 包含可编辑字段的内容夹 |
| `fieldName` | `keyof T` | ✅ | \- 说吧 | 要编辑的字段名称( 必须是内容段的有效密钥) |
| `mode` | `'plain' | 'minimal' | 'full'` | ❌ | `'plain'` | TinyMCE 工具栏预设 . `full` 启用完整风格的泡泡菜单. |
| `format` | `'text' | 'html'` | ❌ | `'text'` | `text` 使 HTML 成为纯文本; `html` 解析 HTML 标记 |

#### 使用量

```vue
<script setup lang="ts">
import { DotCMSEditableText } from '@dotcms/vue';
import type { DotCMSBasicContentlet } from '@dotcms/types';

const props = defineProps<{ contentlet: DotCMSBasicContentlet }>();
</script>

<template>
    <div class="banner">
        <img :src="`/dA/${contentlet.inode}`" :alt="contentlet.title" />
        <h2>
            <DotCMSEditableText :contentlet="contentlet" field-name="title" />
        </h2>
    </div>
</template>
```

#### 编辑器集成

-   检测 UVE 编辑模式并允许内置 TinyMCE 编辑 .
-   将编辑的内容以模糊的方式发送回编辑器,而不打开全部内容对话框 .
-   TinyMCE 脚本是从您的 DotCMS 实例中装入的(`dotCMSHost`因此不需要额外的TinyMCE安装.

### DotCMSBlock 编辑器

`DotCMSBlockEditorRenderer` 调制 [块编辑器](https://dev.dotcms.com/docs/block-editor) 内容来自dotCMS,支持自定义块渲染器.

| Prop | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `blocks` | `BlockEditorNode` | ✅ | \- 说吧 | 要渲染的块编辑器字段值 |
| `customRenderers` | `CustomRenderer` | ❌ | \- 说吧 | 自定义 特定块类型/内容类型的 Vue 组件 |
| `className` | `string` | ❌ | \- 说吧 | 适用于集装箱的CSS类别 |
| `style` | `CSSProperties` | ❌ | \- 说吧 | 容器的内嵌样式 |
| `isDevMode` | `boolean` | ❌ | `false` | 何时 `true`,显示无效/未知块的可见消息 |

> **`className`编号 :`style` 对本地 `class`编号 :`style`数字 :** 页:1 `className` 财务报告和审定财务报表 `style` 道具反射回放SDK,所以相同的代码形状可以跨出框架. 这个 组件使两个根元素之一(错误框或内容) 因此 Vue 的自动属性掉入 **没有** 适用——a 本地语言 `class="prose"` 在标签上无法到达容器。 使用 `className` 财务报告和审定财务报表 `style` 样式容器的道具 :
> 
> ```vue
> <DotCMSBlockEditorRenderer
>     :blocks="contentlet.body"
>     class-name="prose max-w-none"
>     :style="{ marginTop: '1rem' }" />
> ```

#### 使用量

自定义渲染器是接收块的Vue组件 `node` prop和违约时提供的儿童 `<slot />`。 。 。 .

```vue
<!-- CustomHeading.vue -->
<script setup lang="ts">
import type { CustomRendererProps } from '@dotcms/vue';

defineProps<CustomRendererProps>();
</script>

<template>
    <h1 class="my-heading"><slot /></h1>
</template>
```

```vue
<!-- DetailPage.vue -->
<script setup lang="ts">
import { DotCMSBlockEditorRenderer, type CustomRenderer } from '@dotcms/vue';
import type { DotCMSBasicContentlet } from '@dotcms/types';

import CustomHeading from './CustomHeading.vue';

const props = defineProps<{ contentlet: DotCMSBasicContentlet }>();

const customRenderers: CustomRenderer = {
    heading: CustomHeading
};
</script>

<template>
    <DotCMSBlockEditorRenderer
        :blocks="contentlet.myBlockEditorField"
        :custom-renderers="customRenderers" />
</template>
```

#### 建议

-   不应与 [`DotCMSEditableText`](https://npmcn.com/package/%40dotcms/vue/#readme-dotcmseditabletext) 在同一个领域.
-   注意CSS级联会影响你区块的外观和感觉.
-   仅与 [块编辑器字段](https://dev.dotcms.com/docs/block-editor)。用于其他文本字段,使用 [`DotCMSEditableText`](https://npmcn.com/package/%40dotcms/vue/#readme-dotcmseditabletext)。 。 。 .

### DotCMSShow 游戏

`DotCMSShow` 有条件地使其基于当前UVE模式的槽内容——对编辑或重排按钮等仅供编辑者使用.

| Prop | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `when` | `UVE_MODE` | ❌ | `UVE_MODE.EDIT` | 显示槽内容的 UVE 模式 |

#### 使用量

```vue
<script setup lang="ts">
import { DotCMSShow } from '@dotcms/vue';
import { UVE_MODE } from '@dotcms/types';
</script>

<template>
    <DotCMSShow :when="UVE_MODE.EDIT">
        <button>Edit</button>
    </DotCMSShow>
</template>
```

了解更多关于 `UVE_MODE` 语句 [dotCMS UVE 文档](https://dev.dotcms.com/docs/universal-visual-editor)。 。 。 .

### 使用 EdiableDotCMSPage 软件

`useEditableDotCMSPage` 将一页线接入通用视觉编辑器,并返回一个作为编辑器进行修改的活化回放. 在UVE之外,这是一个通过——返回的裁判只是持有最初的反应.

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `pageResponse` | `DotCMSComposedPageResponse` | ✅ | 页面响应来自 `client.page.get()` |

**回返** (单位:千美元) `Ref<DotCMSComposedPageResponse>` ——准入 `.value.pageAsset` 财务报告和审定财务报表 `.value.content`。 。 。 .

当你使用可堆肥时,它:

1.  以您的页面数据初始化 UVE
2.  保持编辑器同步导航
3.  在编辑内容、块被添加/删除、布局变化或组件被移动时,订阅新页面的内容更改和互换
4.  清理所有卸载的听众

#### 使用量

```vue
<script setup lang="ts">
import { DotCMSLayoutBody, useEditableDotCMSPage } from '@dotcms/vue';
import { computed } from 'vue';

const props = defineProps<{ pageResponse: unknown }>();

const page = useEditableDotCMSPage(props.pageResponse as never);
const pageAsset = computed(() => page.value?.pageAsset);

const components = {
    /* content-type → component map */
};
</script>

<template>
    <DotCMSLayoutBody v-if="pageAsset" :page="pageAsset" :components="components" />
</template>
```

> \[大 将页面响应存储在 `shallowRef` (不是深处) `ref`) (中文(简体) ). 一个深 `ref` 将整个页面以被动代理方式包裹, UVE 无法做到 `postMessage` 给编辑( e)`DataCloneError`) (中文(简体) ). 见 [`toPlain`](https://npmcn.com/package/%40dotcms/vue/#readme-toplain)。 。 。 .

### 何时使用 DotCMSSshow

`useDotCMSShowWhen` 返回当前 UVE 模式是否匹配的反应布尔 -- -- 用于模板外基于模式的逻辑.

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `when` | `UVE_MODE` | ✅ | UVE 模式以查看 |

#### 使用量

```vue
<script setup lang="ts">
import { useDotCMSShowWhen } from '@dotcms/vue';
import { UVE_MODE } from '@dotcms/types';

const isEditMode = useDotCMSShowWhen(UVE_MODE.EDIT); // Readonly<Ref<boolean>>
</script>

<template>
    <button v-if="isEditMode">Edit</button>
</template>
```

### 创建 DotCMSimage 记录器

`createDotCMSImageLoader(dotcmsUrl?)` 返回通过 dotCMS 图像 API(即 `/dA/` 路由,它处理调整大小和优化。 这是Angular的Vue模拟 `provideDotCMSImageLoader` -Vue没有 `IMAGE_LOADER` 符号,所以您直接调用返回的函数.

绝对 `http(s)://…` URL的返回没有改变,因此将dotCMS资产与外部/库存图像相混合只是起作用了.

| 参数 | 类型 | 需求 | 默认 | 说明 |
| --- | --- | --- | --- | --- |
| `dotcmsUrl` | `string` | ❌ | `''` | 您的点CMS 实例的基础 URL 。 站点关系 Omit (空) `/dA/…` 在代理服务器后面. |

返回的装载器是 `(src: string, options?) => string`时 `options` 实值 `{ width?, quality?, languageId? }` (单位:千美元)`quality` 默认为 `50`, (中文(简体) ), `languageId` 改为 `'1'`) (中文(简体) ).

```ts
import { createDotCMSImageLoader } from '@dotcms/vue';

// Absolute (production)
const image = createDotCMSImageLoader(import.meta.env.VITE_DOTCMS_HOST);
image(contentlet.inode, { width: 800 });
// → https://demo.dotcms.com/dA/<inode>/800w/50q?language_id=1

// Site-relative (dev proxy) — omit the host so the Vite /dA proxy handles it
const proxied = createDotCMSImageLoader();
proxied(contentlet.inode, { width: 800 }); // → /dA/<inode>/800w/50q?language_id=1
```

```vue
<script setup lang="ts">
import { createDotCMSImageLoader } from '@dotcms/vue';
import type { DotCMSBasicContentlet } from '@dotcms/types';

const props = defineProps<{ contentlet: DotCMSBasicContentlet }>();

const image = createDotCMSImageLoader(import.meta.env.VITE_DOTCMS_HOST);
</script>

<template>
    <img :src="image(contentlet.inode, { width: 800 })" :alt="contentlet.title" />
</template>
```

### 已删除

`toPlain` 深解将一个Vue反应值(refs /活性代词)包裹入一个平坦的,结构化的-clone-安全对象. 在将被动数据传递给 UVE 编辑器动作之前使用它( Name`editContentlet`, (中文(简体) ), `enableBlockEditorInline`从 `@dotcms/uve`,通过 `postMessage`。 。 。 .

```vue
<script setup lang="ts">
import { toPlain } from '@dotcms/vue';
import { editContentlet } from '@dotcms/uve';
import type { DotCMSBasicContentlet } from '@dotcms/types';

const props = defineProps<{ contentlet: DotCMSBasicContentlet }>();

const onEdit = () => editContentlet(toPlain(props.contentlet));
</script>
```

## 解决问题

### 共同问题和解决方案

#### 通用视觉编辑器( UVE)

1.  **UVE 不装入**:页面使编辑器工具/覆盖不出现.
    
    -   **可能的原因**: 不正确的 UVE 应用程序配置; 缺失 `useEditableDotCMSPage`;该应用程序不在UVE iframe内部运行.
    -   **解决方案**: 校验您的 Vue dev 服务器的 UVE 应用程序 URL; 确保页面树被包裹 `useEditableDotCMSPage`; 确认 `data-dot-object="contentlet"` 属性存在于制成的内容中(它们只在编辑模式中出现).
2.  **`DataCloneError: could not be cloned`** 当装入编辑器时.
    
    -   **原因**: Vue 反应式代理服务器通过 `postMessage`。 。 。 .
    -   **解决方案**: 将页面响应存储在 `shallowRef`没有深处 `ref`; 使用 [`toPlain`](https://npmcn.com/package/%40dotcms/vue/#readme-toplain) 在使用被动数据调用 UVE 编辑器动作之前.
3.  **内容编辑不更新页面直播.**
    
    -   **原因**: 通常重复 Vue 实例——如果 `vue` sDK的活性与你的应用不同 确保单一 `vue` 已安装.

#### 缺少内容

1.  **不渲染的组件**: 显示内容的空格.
    
    -   **解决方案**:检查 `components` 地图注册; 校验内容类型变量名称精确匹配( 区分大小写); 使用 `mode="development"` 详细记录.
2.  **推荐验证警告** (例如:. _无效道具: Prop "modDate" 类型检查失败_) (中文(简体) ).
    
    -   **原因**:一个内容类型的组件通过扩展完整内容类型来宣告道具;dotCMS将一些系统字段与def不同类型.
    -   **解决方案**: 只声明您组件读取的特定字段.

#### 开发设置

1.  **`npm install` 失败**:清除 npm 缓存(`npm cache clean --force`),删除 `node_modules`,然后重新安装;验证您的节点.js版本.
    
2.  **丢失导入的运行时间错误**:检查所有 SDK 进口来自 `@dotcms/vue`,以及同伴的依赖关系(`vue`, (中文(简体) ), `@dotcms/client`, (中文(简体) ), `@dotcms/uve`, (中文(简体) ), `@dotcms/types`已安装.
    

### 调试提示

1.  **启用开发模式**
    
    ```vue
    <DotCMSLayoutBody :page="pageAsset" :components="components" mode="development" />
    ```
    
    这显示了详细的信息, 使未映射组件背出, 并突出显示空容器 .
    
2.  **检查浏览器控制台和网络标签** 对于错误,请注意401/403(自动)答复.
    
3.  **检查DOM** 在UVE iframe内——内容应携带 `data-dot-object="contentlet"` 集装箱 `data-dot-object="container"` 在编辑模式中.
    

### 还有什么问题吗?

如果你在尝试这些解决方案后还遇到问题:

1.  搜索已存在 [GitHub 问题](https://github.com/dotCMS/core/issues)
2.  问问题 [社区论坛](https://community.dotcms.com/)
3.  创建一个包含详细复制步骤、环境信息、错误消息和代码样本的新问题

## 支助

我们提供多个渠道来寻求帮助 与点CMS Vue SDK:

-   **GitHub 问题**: 对于错误报告和特性请求,请 [打开一个问题](https://github.com/dotCMS/core/issues/new/choose)。 。 。 .
-   **社区论坛**: 加入我们 [社区讨论](https://community.dotcms.com/)。 。 。 .
-   **企业支助**:企业客户可通过 [dotCMS 支持门户](https://www.dotcms.com/support)。 。 。 .

在报告问题时,请包括:

-   您使用的 SDK 版本
-   Vue 版本
-   最小复制步骤
-   预期与实际行为

## 捐款

GitHub 拖取请求是向dotCMS提供代码的首选方法. 欢迎大家为"DotCMS Vue SDK"捐款! 如果你愿意,请:

1.  叉子存储器 [点/核心](https://github.com/dotCMS/core)
2.  创建特性分支( E)`git checkout -b feature/amazing-feature`(中文(简体) )
3.  提交更改( E)`git commit -m 'Add some amazing feature'`(中文(简体) )
4.  推向分行(`git push origin feature/amazing-feature`(中文(简体) )
5.  打开拉请求

请确保您的代码遵循现有的样式并包含适当的测试 .

## 许可证发放

点CMS 可在 [业务来源许可证1.1(BSL)](https://www.dotcms.com/bsl) 或商业执照.

在BSL下,DotCMS可以免费由个人开发商,小企业或机构在总资金中低于5M美元,也可以由非生产环境下的更大型组织使用. BSL每次发布都会在其发布后四年自动转换为GPL v3. 全文和问题,访问 [dotcms.com/bsl (英语)](https://www.dotcms.com/bsl) 财务报告和审定财务报表 [dotcms.com/bsl-faq (英语)](https://www.dotcms.com/bsl-faq)。 。 。 .

大型组织的生产用途,以及管理下的云、服务级协议、支助和企业能力,均根据点集管理系统的商业许可证提供。 关于商业计划、特点和支助选项的详情,见 [dotcms.com/定价](https://www.dotcms.com/pricing)。 。 。 .

## 常见问题

### @dotcms/vue 是什么？

官方 Vue 组件库来渲染一个 DotCMS 页面 \.

### 如何安装 @dotcms/vue？

在项目目录运行 npm install @dotcms/vue，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（\>=3\.4）、@dotcms/uve（26\.11\.2-3）、@dotcms/types（26\.11\.2-3）、@dotcms/client（26\.11\.2-3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @dotcms/vue 支持 TypeScript 吗？

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

### @dotcms/vue 支持 ESM 还是 CommonJS？

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

### @dotcms/vue 可以商用吗？

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

### @dotcms/vue 的下载量有多少？

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

### @dotcms/vue 还在维护吗？

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