# @ai-matrx/media 中文文档

规范地址：https://npmcn.com/package/%40ai-matrx/media/

版本：0\.15\.189
npm 元数据更新时间：2026-10-30T16:01:34.715Z
中文译文更新时间：2026-11-05T18:18:03.154Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ai-matrx/media
原文对照：https://npmcn.com/package/%40ai-matrx/media/?lang=original
项目主页：https://github.com/AI-Matrix-Engine/aidream/tree/main/apps/shared/media#readme
源码仓库：https://github.com/AI-Matrix-Engine/aidream

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

- 包体积（解压后）：13.9 MB，449 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：20 个
- peer 依赖：next \>=14\.0\.0，react \>=18\.0\.0，react-dom \>=18\.0\.0，react-pdf \>=11\.0\.0，react-redux \>=9\.0\.0，@reduxjs/toolkit \>=2\.0\.0
- 首次发布：2026-08-29T17:50:28.555Z
- 最新版本发布：2026-10-30T16:01:34.503Z
- 近 30 天下载量：86975（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：315（近 12 个月 315 个）

## 中文简介

AI Matrx媒体组件工具包:仅用于图像,视频,音频和文件缩略图的可持久反光渲染器外加仅与Matrx文件系统相通的活的TTS回放——无头核心钩子外加DOM捆绑,被接入被注入的MediaClient. 签名

## 安装

```sh
npm install @ai-matrx/media
```

也可以使用：`pnpm add @ai-matrx/media`、`yarn add @ai-matrx/media`、`bun add @ai-matrx/media`

## README

# @ai-matrx/ 媒体

媒体组成部分 **只是工作时** 具有持久文件系统。 制作人 图像、视频、音频和文件缩略图,这些缩略图需要持久的参考——a `file_id` 或永久的公共 URL ——并拥有整个 URL 生命周期 : 解析, 认证运输, 负载错误回收, 键入不可用状态, 上传进度,并共享/下载/副本/打开动作.

货船 **零运输**所有数据形状都通过 一个注入端口 `MediaClient`。这就是重点:每一次媒体中断 我们曾经运送的代码 是手建的URL或 `<img>`这里 正确路径是类型允许的唯一路径.

```
@ai-matrx/media          types only — MediaRef, DurableSrc, MediaClient, host ports
@ai-matrx/media/core     headless React hooks (platform-free state machines)
@ai-matrx/media/react    DOM components (Tailwind classes, inlined SVG icons)
@ai-matrx/media/share    the complete share popover body (optional peer: @ai-matrx/associations)
```

## 执行的规则类型

1.  **软件包从不获取媒体 URL 本身 .** 字节仅通过 `MediaClient.getBlob`。 。 。 .
2.  **每一个部件都有一个参考,从来没有 `src`。 。 。 .** 甚至一个呼叫器提供的 URL 字符串按 `resolve()`从不相信.
3.  **签名的 URL 是交接, 从来不是身份 .** 媒体唯一的字符串 元素绑定是标记 `DurableSrc`,仅此 `MediaClient` 执行可以薄荷。 未到期的 URL 无法通过类型 不安全的铸造.
4.  **股价未结清.** `shareableUrl` 返回时 `null` 相当 发布一个签名的 URL; 未连接的动作会禁用 .
5.  **一次复试政策.** 装入错误路径通过 `MediaClient.recoverLoadError` (会场刷新) – 同- URL 重试 – (原始内容存档于2018-10-21). terminal. 套件本身没有重试逻辑.

## 快开始

```tsx
import { MediaProvider } from "@ai-matrx/media/core";
import { InlineMediaRef, MediaThumbnail, MediaLightbox } from "@ai-matrx/media/react";

// `client` implements the MediaClient interface from "@ai-matrx/media".
// Matrx apps wire the canonical implementation from @ai-matrx/files/client;
// any structural implementation works.
<MediaProvider client={client} ports={{ ImageComponent, actions, playbackSession }}>
  <InlineMediaRef ref={{ file_id }} size="md" fit="cover" />
  <MediaThumbnail mediaRef={{ file_id }} fileName="report.pdf" />
</MediaProvider>
```

`InlineMediaRef` 接受一个 `MediaRef` (单位:千美元)`{ file_id, url?, mime_type? }`页:1 赤裸的文件ID字符串,或外部的公开 URL 字符串——并制作一个 正确大小 `<img>` 编号 : `<video>` 编号 : `<audio>` 背负并提供信息 错误状态 . `ref` 是内容道具( 反应19); 使用 `mediaElementRef` 页:1 DOM进入.

## 无头钩( C)`/core`(中文(简体) )

| 钩子 | 它拥有的 |
| --- | --- |
| `useMediaResolution(ref)` | 参考 `MediaResolution` 作为状态( e)`empty` 编号 : `ready` 编号 : `unavailable` 带有输入原因) |
| `useMediaLoadRecovery(src)` | 重试键/误差机,以覆盖客户端的 ONE 回收政策 |
| `useMediaBlob(ref)` | 有生命周期+释放的对象- URL 字节 |
| `useMediaUpload()` | 单倍分批上传、进度和每个文件托盘(`entries`(中文(简体) ) |
| `useThumbnailSource(ref, opts)` | 4级缩略图决定( 交接拇指 变体 活源 图标) |
| `useMediaActions(ref)` | 共享/下载/复制/开放可用性+在注入动作端口执行 |
| `getFileKindDetails(name, mime)` | 文件名/MIME = 类别、图标名称、颜色 |

## 构成部分(`/react`(中文(简体) )

`InlineMediaRef` • 妇女 `MediaThumbnail` • 妇女 `FileIcon` • 妇女 `FileUploadDropzone` (+ 数) `UploadProgressList`, (中文(简体) ), `useMediaDropzone`· `MediaActionToolbar` • 妇女 `MediaLightbox` ——外加软件包自带的SVG图标集(无图标) 图书馆依赖).

### 动作和共享

主机注入 a `MediaActionsPort` (单位:千美元)`share`, (中文(简体) ), `download`, (中文(简体) ), `copy`, (中文(简体) ), `open` 管理人员和/或富人 `SharePopover` 页:1 工具栏和灯盒 使任何有线设备都无法工作 不碰这个包裹.

```tsx
<MediaProvider client={client} ports={{ actions: { download, share, SharePopover } }}>
  <MediaActionToolbar mediaRef={{ file_id }} fileName="photo.png" />
</MediaProvider>
```

### 完整的分享机构(`/share`(中文(简体) )

`/share` 船舱预留了船位 Matrx 分享经验 :

-   **复制公共链接** ——一击问 `MediaClient.shareableUrl(ref)` 页:1 真实永久的 URL( 主机执行重用或薄荷 a) 无过期共享链接, 或返回公共文件的永久 CDN URL) 并复制它. `null` 失败已关闭 .
-   **外部参考** 获得简化表面:安全的外部 URL 或 a 已禁用行.
-   **管理所有链接** 编号 : **谁能看到这个** 属于主机槽 (单位:千美元)`manageLinks` 召回电话, `AccessSummary` ——将库存与 可达性与宿主的iam表面相活.
-   **链接到/ 附加到..** - 协会负担,骑马 `@ai-matrx/associations` 通过其公用钩. 他们点亮 当一个 `AssociationsProvider` 被挂在上方,在没有时被降解为缺席.

```tsx
import { createMediaSharePopover } from "@ai-matrx/media/share";

const SharePopover = createMediaSharePopover({
  manageLinks: (ctx) => openShareLinkDialog(ctx),   // optional
  AccessSummary,                                    // optional host panel
  notify: { success: toast.success, error: toast.error }, // optional
});

<MediaProvider client={client} ports={{ actions: { SharePopover, download, copy } }}>
  {/* every toolbar/lightbox now opens the full share experience */}
</MediaProvider>
```

仅 `/share` 进口 `@ai-matrx/associations` 实际依赖,已安装 自动( 它带来 `@ai-matrx/design-system` 与它一样。 没有额外的 解析; 关联负担仍会降低到在运行时缺席, 如果没有 `AssociationsProvider` 包起树来. 其他的条目从来不碰它.

### 诊断——终极失败从不沉默

每死一死 `resolve()`,失败的私有像素字节,一个负载 错误 ONE 恢复重试无法修复, 失败的会话薄荷会释放 完全是一个严格型号 `MediaFailureInfo` —— 说 `phase`,持久 `mediaRef` 身份(从未签名的URL), `status?`, (中文(简体) ), `retryOutcome?`, (中文(简体) ), `terminal`, (中文(简体) ), `message` - 每一个媒体身份都被绑住 所以重新投手永远不要垃圾邮件 捆绑 沉入错误系统 :

只有在React重新装入重试键后才能重新加价; 复制浏览器 `error` 来自会话中原元素的事件 刷新在飞行中被忽略 永远不要消耗真正的重试.

```tsx
<MediaProvider
  client={client}
  ports={{ diagnostics: { capture: (info) => myErrorCapture(info) } }}
>
```

没有绑定的下沉软件包 `console.error`相同的有效载荷——通过 默认,绝不沉默。 狦 `MediaClient.recoverLoadError` 返回 a `MediaRecoveryReport` 携带会话薄荷 `secret_source: "ephemeral"`,软件包立即抓取全应用程序 警告私有制将突破服务器重启/启动.

## 文件查看器( E)`/viewers`(中文(简体) )

Full-pane 渲染 ONE 文件——预览面板,文件标签,代码编辑器 二进制文件倒置. `MediaFileViewer` 文件类型和船舶上的发送 文本、代码、SVG、HTML和未知文件的工作机构.

```tsx
import { MediaFileViewer } from "@ai-matrx/media/viewers";

<MediaFileViewer
  source={{ kind: "ref", ref: { file_id } }}
  fileName={file.name}
  fileSize={file.size}
  generic={{ onDownload }}
/>;
```

Kinds的渲染是只使用重浏览器的引擎——PDF,Markdown, 电子表格, 办公室文件 - 是你的注册, 所以一个消费者只 显示从未带 PDF 引擎的文本文件 :

```tsx
import { registerMediaViewer, registerMediaCodeHighlighter } from "@ai-matrx/media/viewers";

registerMediaViewer("pdf", MyPdfViewer);          // gets MediaViewerProps
registerMediaCodeHighlighter(MyPrismHighlighter); // optional: color for code
```

在你注册之前,这种人会 **宣布默认**: 它的名称 缺少的引擎和补救, 仍然提供下载/ 视图- 文本。 这个 从来不是空白的窗帘。 (代码不同:没有显示器注册) 使完整——单空,行号,可复制——只是没有颜色, 所以它宣布什么也没有

正在注册软件包中已经使该软件包替换内置的 如何插入您自己的特定域查看器 .

这个 `blob` 源道( r)`{ kind: "blob", blob, url }`)使您成为字节 已经没有触摸过 `MediaClient` 一点也不.

## 下册.js`/next`(中文(简体) )

这个 `ImageComponent` 端口,已执行 `next/image` 所以你从不写 又是那个包裹. `next` 是一个可选的对等点——没有为您安装它, 并且没有其他条目进口.

```tsx
import { NextMediaImage } from "@ai-matrx/media/next";

const ports: MediaHostPorts = { ImageComponent: NextMediaImage };
// or: createNextMediaImageComponent({ unoptimized: false, quality: 90 })
```

默认为 `unoptimized`,这对 Matrx 媒体是正确的: 耐用文件 URL为会话- cookie 认证, Next 的优化器从中获取 没有用户会话的服务器.

## 样式

`/react` 使用带有语义符号的 Tailwind 工具类(`bg-muted`, (中文(简体) ), `text-destructive`(中文(简体) ). Tailwind v4 主机将软件包注册为源 :

```css
@source "../node_modules/@ai-matrx/media";
```

## 安保部门/区域服务中心

根条目为服务器安全(类型+一纯函数). `/core`, (中文(简体) ), `/react`, (中文(简体) ), `/share`, (中文(简体) ), `/viewers` 财务报告和审定财务报表 `/next` 是客户模块( e)`"use client"` 已盖章 每个条目). 没有触摸 `window` 在导入时间.

## 许可证

麻省理工学院. 复制自的内嵌图标路径 [卢西德](https://lucide.dev/) (印度语).

## 常见问题

### @ai-matrx/media 是什么？

AI Matrx媒体组件工具包:仅用于图像,视频,音频和文件缩略图的可持久反光渲染器外加仅与Matrx文件系统相通的活的TTS回放——无头核心钩子外加DOM捆绑,被接入被注入的MediaClient\. 签名

### 如何安装 @ai-matrx/media？

在项目目录运行 npm install @ai-matrx/media，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ai-matrx/media 支持 TypeScript 吗？

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

### @ai-matrx/media 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ai-matrx/media 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ai-matrx/media 可以商用吗？

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

### @ai-matrx/media 的下载量有多少？

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

### @ai-matrx/media 还在维护吗？

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