Nuxt 内容资产

在 Nuxt Content 中启用本地资源

Nuxt Content Assets logo

概述

Nuxt Content Assets 允许在 Nuxt Content 中使用本地资源

+- content
    +- posts
        +- 2023-01-01
            +- index.md
            +- media
                +- featured.png
                +- mountains.jpg
                +- seaside.mp4

在您的文档中，使用相对路径引用资源

---
title: Summer Holiday
featured: media/featured.png
---

I loved being in the mountains.

![mountains](media/mountains.png)

Almost as much as being in the sea!

:video{src="media/seaside.mp4"}

在构建时，该模块会整理并提供资源和内容。

特性

基于 Nuxt Content 构建，并与任何 Nuxt Content 项目或主题兼容，包括 Docus。

用户体验

将资源与内容文件共同放置
使用相对路径引用资源
支持任何格式（图像、视频、文档）

开发者体验

适用于标签和自定义组件
适用于 Markdown 和 Frontmatter
文件监视和资源实时重载
图像大小注入
零配置

演示

要在安装之前测试该模块，您可以试用 Nuxt Content Assets 演示。

要在本地克隆和运行

git clone https://github.com/davestewart/nuxt-content-assets.git
cd nuxt-content-assets
npm install && npm install --prefix ./playground
npm run dev

然后在浏览器中打开演示，地址为 localhost:3000。

要在网上运行演示，请访问

https://stackblitz.com/github/davestewart/nuxt-content-assets?file=playground%2Fapp.vue

要浏览演示文件夹

https://github.com/davestewart/nuxt-content-assets/tree/main/playground

安装

安装依赖

npm install nuxt-content-assets

配置 nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-content-assets', // make sure to add before content!
    '@nuxt/content',
  ]
})

运行开发服务器或构建，本地资源现在应该与 Markdown 内容一起提供。

用法

概述

在文档中的任何位置使用相对路径

Images
![image](image.jpg)

Links
[link](docs/article.txt)

Elements / components
:video{src="media/video.mp4"}

HTML
<iframe src="media/example.html" />

相对路径可以在 Frontmatter 中定义 – 只要它们是唯一的值

---
title: Portfolio
images:
  - assets/image-1.jpg
  - assets/image-2.jpg
  - assets/image-3.jpg
---

然后可以将这些值传递给组件

:image-gallery{:data="images"}

有关示例，请参阅演示中的标记和组件。

实时重载

在开发中，该模块会监视资源的添加、移动和删除，并实时更新浏览器。

如果您删除某个资源，它将在浏览器中显示为灰色，直到您替换该文件或修改其路径为止。

如果您编辑图像、视频、嵌入或 iframe 源，内容将立即更新，如果您希望获得正确的设计，这将非常有用！

!注意实时重载目前不适用于 Nuxt Image（请参阅 Issue #77）。
如果您需要在图像设计上进行迭代，请考虑在开发中禁用 Nuxt Image。

图像大小

HTML

该模块可以将图像大小提示传递给生成的 <img> 标签

<!-- imageSize: 'style' -->
<img src="/image.jpg" style="aspect-ratio:640/480">

<!-- imageSize: 'attrs' -->
<img src="/image.jpg" width="640" height="480">

启用此功能可以防止页面加载时内容跳动。

!警告请勿将 imageSize: 'src' 与 Nuxt Image 结合使用，因为它会阻止 IPX 模块正确提供图像，从而导致静态站点生成失败

Prose 组件

如果您使用 ProseImg 组件，您可以通过 $attrs 属性挂钩图像大小提示

<template>
  <span class="image">
    <img :src="$attrs.src" :width="$attrs.width" :height="$attrs.height" />
  </span>
</template>

<script>
export default {
  inheritAttrs: false
}
</script>

Frontmatter

如果您将 Frontmatter 传递给自定义组件，请将 imageSize 设置为 'src'，以在 src 中编码值

:image-content{:src="image"}

组件将接收大小信息作为查询字符串，您可以提取并应用它

<img class="image-content" src="/image.jpg?width=640&height=480">

请参阅此处的演示组件：here。

Nuxt Image

通过将 Nuxt Content Asset 的缓存文件夹添加为 Nuxt 图层，即可支持 Nuxt Image

// nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    'node_modules/nuxt-content-assets/cache',
  ],
}

要将所有图像作为 Nuxt Image 图像提供，请创建一个如下所示的 ProseImg 组件

<!-- components/content/ProseImg.vue -->
<template>
  <nuxt-img />
</template>

请参阅演示文件夹，以获取全局解决方案和每个图像解决方案。

配置

该模块具有以下选项

// nuxt.config.ts
export default defineNuxtConfig({
  contentAssets: {    
    // inject image size hints into the rendered html
    imageSize: 'style',
    
    // treat these extensions as content
    contentExtensions: 'mdx? csv ya?ml json',
    
    // output debug messages
    debug: false,
  }
})

图像大小

!注意
自 v1.4.1 起，图像大小提示现在是可选的。这样做是为了最大限度地提高与 Nuxt Image 的兼容性。

您可以向生成的图像添加一个或多个图像大小提示

{
  imageSize: 'style attrs src'
}

从以下开关中选择

开关	功能
`'style'`	向任何 `<img>` 标签添加 `style="aspect-ratio:..."`
`'attrs'`	向任何 `<img>` 标签添加 `width` 和 `height` 属性
`'src'`	向 `src` 属性添加 `?width=...&height=...` （仅限 Frontmatter）

注意：如果您仅添加 attrs，请在您的应用程序中包含以下 CSS

img {
  max-width: 100%;
  height: auto;
}

内容扩展

!注意通常，您不需要更改此设置

此设置告诉 Nuxt Content 忽略不是受支持内容类型之一的任何内容

mdx? csv ya?ml json

这样，您可以使用任何其他文件类型作为资源，而无需显式配置 Nuxt Content 的忽略列表。

如果没有此设置，Nuxt Content 将警告不支持的文件类型

警告不支持 .jpg 文件，“content:path:to:some-asset.jpg” 回退到原始内容

调试

如果您想查看该模块在运行时所做的事情，请将 debug 设置为 true

{
  debug: true
}

工作原理

当 Nuxt 构建时，该模块会扫描所有内容源以查找资源，将其复制到临时图层文件夹 (nuxt_modules/nuxt-content-assets/cache) 并索引路径和图像元数据。

在 Nuxt Content 运行后，将遍历解析的内容 (.nuxt/content-cache)，并检查元素属性和 Frontmatter 属性，以查看它们是否解析为先前索引的资源路径。

如果它们确实解析为，则使用绝对路径重写 Nuxt Content 缓存中的属性。如果资源是图像，则可以选择使用大小属性或查询字符串更新元素或元数据。

最后，Nitro 提供站点，并且对转换后的资源路径所做的任何请求都应该被获取，并且由浏览器提供复制的资源。

在开发中，监视进程会将资源更改传播到缓存，更新资源索引，并通过 Web 套接字通知浏览器刷新任何已加载的图像。

如果使用 Nuxt Image，则 _ipx/ 端点直接从缓存的公共文件夹提供图像。

开发

如果您希望开发该项目，您将使用以下实体

src
模块代码本身
playground
一个独立的 Nuxt 应用程序，读取实时模块代码
scripts
一组用于开发和发布模块的脚本

安装

要设置项目，请运行以下每个脚本一次

# install dependencies
npm install

# copy the cache folder to the playground's node_modules (workaround required in development)
npm run dev:setup

# generate types for the module and playground (re-run if you install new packages)
npm run dev:prepare

开发

要开发模块，请使用提供的演示应用程序

# compile the module, run and serve the playground
npm run dev

# generate the playground
npm run dev:generate

# build the playground
npm run dev:build

# serve the generated/built playground
npm run dev:preview

使用以下工具检查您的代码质量

# lint your code with eslint
npm run lint

# runs tests with vitest
npm run test
npm run test:watch

发布

!重要在发布之前，请务必更新版本和更新日志！

要构建和发布，请根据需要运行以下脚本

# lint, test, build, and dry-run publish
npm run release:dry

# lint, test, build and publish
npm run release

维护

此模块是使用 Nuxt 模块构建器命令创建的

npx nuxi init -t module nuxt-content-assets

这从此处找到的入门模板创建了模块代码

https://github.com/nuxt/starter/tree/module

Nuxi 和模块的依赖项和脚本都会定期更新，因此有时可能需要更新此模块以保持同步。到目前为止，这仅意味着更新依赖项和脚本，这些依赖项和脚本位于上面提到的入门模板代码中。

请注意，构建/发布脚本与原始脚本略有修改；现在将构建分离，并且发布不再使用 changelogen，或者自动添加标签并推送到 GitHub。