Nuxt 内容资产

在 Nuxt Content 中启用本地资产

Nuxt Content Assets logo

概述

Nuxt 内容资产可在 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 和前置 matter 中使用
文件监视和资产实时重新加载
图像大小注入
零配置

游乐场

在安装模块之前，您可以尝试使用 Nuxt 内容资产游乐场。

克隆并本地运行

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" />

相对路径可以在前置 matter 中定义 - 只要它们是唯一的 value

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

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

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

查看游乐场以获取标记和组件示例。

实时重新加载

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

如果删除了资产，它将在浏览器中显示为灰色，直到替换文件或修改指向它的路径。

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

！注意实时重新加载目前不适用于 Nuxt Image（请参阅问题 #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 模块正确提供图像，从而导致静态站点生成失败

散文组件

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

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

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

前置 matter

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

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

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

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

请参阅游乐场组件此处。

Nuxt Image

通过将 Nuxt 内容资产的缓存文件夹添加为 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=...`（仅限前置 matter）

注意：如果仅添加 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)，并检查元素属性和前置 matter 属性以查看它们是否解析为先前索引的资产路径。

如果解析成功，则 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。