# @cmtx/core - 图片模块

Markdown 图片处理核心库的图片模块，提供纯文本层的图片筛选、解析、替换、格式化和尺寸调整功能。

# 1. 安装

pnpm add @cmtx/core

# 2. 快速开始

import {
  filterImages,
  parseImages,
  updateImageRefs,
  formatMarkdownImage,
} from '@cmtx/core'

// 1. 从 Markdown 中筛选本地图片
const markdown = '![alt](../assets/examples/local.png) ![](https://example.com/img.png)'
const localImages = filterImages(markdown, {
  mode: 'sourceType',
  value: 'local',
})

// 2. 解析所有图片
const allImages = parseImages(markdown)

// 3. 替换图片路径和属性（多字段模式：通过 src 匹配，同时替换多个字段）
const result = updateImageRefs(markdown, [
  {
    field: 'src',
    pattern: '../assets/examples/local.png',
    newSrc: './uploaded/local.png',
    newAlt: '上传后的图片',
    newTitle: '点击查看大图',
  },
])

// 4. 格式化图片
const mdImage = formatMarkdownImage({ src: '../assets/examples/image.png', alt: '描述' })

# 3. 图片筛选

# 3.1. filterImages

从 Markdown 文本中筛选图片，支持多种过滤模式。

function filterImages(
  markdown: string,
  options?: ImageFilterOptions,
): ImageMatch[]

ImageFilterOptions：

属性	类型	默认值	说明
mode	ImageFilterMode	—	筛选模式
value	ImageFilterValue	—	筛选值，含义取决于 mode
logger?	Logger	—	可选的日志记录器

ImageFilterMode：'sourceType' | 'hostname' | 'absolutePath' | 'regex'

ImageFilterValue：string | RegExp

• sourceType — 按图片来源筛选（'web' / 'local'）
• hostname — 按 Web 图片的主机名筛选
• absolutePath — 按本地图片的路径筛选
• regex — 按正则表达式匹配 src 字段

# 返回值

ImageMatch[] — 匹配到的图片数组，每个结果包含解析后的图片信息。

interface ImageMatch {
  // 继承自 FileRef
  type: 'local' | 'web'
  src: string
  raw: string
  syntax: 'md' | 'html'
  refType: 'image' | 'link' | 'media' | 'other'
  text?: string
  title?: string
  // ImageMatch 自有字段
  alt: string
  width?: string
  height?: string
}

# 4. 图片解析

# 4.1. parseImages

解析 Markdown 文本中的所有图片引用（同时支持 Markdown 内联语法和 HTML img 标签）。

function parseImages(text: string): ParsedImage[]

ParsedImage：

属性	类型	说明
src	string	图片 URL 或路径
alt?	string	替代文本
title?	string	标题文本
raw	string	原始匹配文本
syntax	'md' | 'html'	图片语法类型
width?	string	宽度（仅 HTML 图片）
height?	string	高度（仅 HTML 图片）

# 5. 图片替换

# 5.1. updateImageRefs

使用正则表达式批量替换图片的 src、alt、title 属性。支持多字段模式：通过 src 或 raw 识别图片，同时替换多个字段。

function updateImageRefs(text: string, options: ReplaceOptions[]): ReplaceResult

ReplaceOptions：

属性	类型	说明
field	'src' | 'raw'	用于识别图片的字段（通过 src 或 raw 匹配）
pattern	string | RegExp	匹配模式（字符串或正则表达式）
newSrc?	string	替换后的 src 值
newAlt?	string	替换后的 alt 值
newTitle?	string	替换后的 title 值

// 通过 src 匹配，同时替换多个字段
const result = updateImageRefs(markdown, [
  {
    field: 'src',
    pattern: './old.png',
    newSrc: './new.png',
    newAlt: '新描述',
  },
])

# 5.2. applyReplacementOps

按偏移量批量替换文档内容。纯函数，按 offset 降序排序后从后向前替换，避免偏移量错位。

function applyReplacementOps(documentText: string, options: ReplacementOp[]): string

参数	类型	说明
documentText	string	原始文档文本
options	ReplacementOp[]	替换操作数组

ReplacementOp：

属性	类型	说明
offset	number	替换在原文本中的起始位置
length	number	被替换文本的长度
newText	string	替换后的文本

import { applyReplacementOps, type ReplacementOp } from '@cmtx/core'

const result = applyReplacementOps("Hello World!", [
  { offset: 6, length: 5, newText: "TypeScript" }
])
// => "Hello TypeScript!"

# 6. 图片格式化

# 6.1. formatMarkdownImage

生成 Markdown 图片语法。

function formatMarkdownImage(options: FormatMarkdownImageOptions): string

FormatMarkdownImageOptions：

属性	类型	说明
src	string	图片 URL
alt?	string	替代文本
title?	string	标题（显示在悬停时）

# 6.2. formatHtmlImage

生成 HTML img 标签。

function formatHtmlImage(options: FormatHtmlImageOptions): string

FormatHtmlImageOptions：

属性	类型	说明
src	string	图片 URL
alt?	string	替代文本
attributes?	HtmlImageAttributes	标准 HTML img 属性（width/height/loading/decoding/crossorigin/referrerpolicy）
extraAttributes?	Record<string, string>	额外属性（class, id, style, data-*, title 等）

# 7. 图片尺寸调整

图片尺寸调整模块提供纯文本层的 HTML 属性设置和 Markdown 转 HTML 功能。

# 7.1. setImageDimensions

设置 HTML img 标签的 width / height 属性，属性存在时替换，不存在时添加。

function setImageDimensions(html: string, attrs?: { width?: string; height?: string }): string

参数	类型	说明
html	string	包含 img 标签的 HTML 字符串
attrs	{ width?: string; height?: string }	要设置的尺寸属性

// 替换现有 width
setImageDimensions('<img src="../assets/examples/test.png" width="300">', { width: '500' })
// => '<img src="../assets/examples/test.png" width="500">'

// 添加 height
setImageDimensions('<img src="../assets/examples/test.png" width="300">', { width: '500', height: '400' })
// => '<img src="../assets/examples/test.png" width="500" height="400">'

# 7.2. toHtmlImage

将 Markdown 图片语法转换为 HTML img 标签，支持自定义 HTML 属性。

function toHtmlImage(
  markdown: string,
  attributes?: Record<string, string>,
): string

参数	类型	说明
markdown	string	Markdown 图片语法
attributes	Record<string, string>	可选的自定义属性

toHtmlImage('![alt text](image.png)')
// '<img src="image.png" alt="alt text">'

toHtmlImage('![alt](image.png "title")')
// '<img src="image.png" alt="alt" title="title">'

toHtmlImage('![alt](img.png)', { width: '800', loading: 'lazy' })
// '<img src="img.png" alt="alt" width="800" loading="lazy">'

# 8. 文件引用 API

通用文件引用解析、筛选和替换。与图片 API 的区别：文件引用覆盖所有 Markdown/HTML 中的外部资源引用（图片、链接、媒体等），不限于图片。

# 8.1. parseFileRefs

解析 Markdown/HTML 文本中的所有文件引用。

function parseFileRefs(text: string, options?: { refTypes?: FileRefType[] }): FileRef[]

参数	类型	说明
text	string	Markdown/HTML 文本
options?	{ refTypes?: FileRefType[] }	按引用类型过滤

FileRef：

属性	类型	说明
type	'local' | 'web'	来源类型
src	string	URL 或路径
raw	string	原始匹配文本
syntax	'md' | 'html'	语法类型
refType	FileRefType	引用类型
text?	string	链接文本/alt 文本
title?	string	标题

FileRefType：'image' | 'link' | 'media' | 'other'

# 8.2. filterFileRefs

解析并按条件筛选文件引用。

function filterFileRefs(markdown: string, options?: FileRefFilterOptions): FileRef[]

FileRefFilterOptions：

属性	类型	说明
mode	FileRefFilterMode	筛选模式
value	FileRefFilterValue	筛选值

FileRefFilterMode：'sourceType' | 'hostname' | 'absolutePath' | 'regex' | 'refType'

FileRefFilterValue：string | RegExp | FileRefType | FileRefType[]

# 8.3. replaceFileRefs

按操作列表批量替换文件引用。

function replaceFileRefs(text: string, operations: FileRefReplaceOp[]): ReplaceResult

FileRefReplaceOp：

属性	类型	说明
field	'src' | 'raw'	匹配字段
pattern	string | RegExp	匹配模式
targetRefType	FileRefType	目标引用类型
newSrc?	string	新 src
newText?	string	新文本（alt/text）
newTitle?	string	新 title

# 8.4. isWebSource

判断 URL 是否为远程 Web 来源。

function isWebSource(src: string): boolean

# 8.5. FILE_REF_REGEX

预定义的文件引用正则常量，用于匹配 Markdown/HTML 中的文件引用。

const FILE_REF_REGEX: Record<string, RegExp>

# 9. 参考

• 源码：GitHub - packages/core