# @datafe-open/markdown-chart-echarts 中文文档

规范地址：https://npmcn.com/package/%40datafe-open/markdown-chart-echarts/

版本：0\.4\.1
npm 元数据更新时间：2026-10-31T14:54:38.835Z
中文译文更新时间：2026-11-11T13:34:48.339Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40datafe-open/markdown-chart-echarts
原文对照：https://npmcn.com/package/%40datafe-open/markdown-chart-echarts/?lang=original
项目主页：https://github.com/datafe/markdown-chart#readme
源码仓库：https://github.com/datafe/markdown-chart

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

- 包体积（解压后）：204 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：echarts \>=5\.5 \<7
- 首次发布：2026-07-17T03:17:02.066Z
- 最新版本发布：2026-10-31T14:54:38.524Z
- 近 30 天下载量：36412（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 28 个）

## 中文简介

Markdown图的安全犬类ECharts渲染器

## 安装

```sh
npm install @datafe-open/markdown-chart-echarts
```

也可以使用：`pnpm add @datafe-open/markdown-chart-echarts`、`yarn add @datafe-open/markdown-chart-echarts`、`bun add @datafe-open/markdown-chart-echarts`

## README

# @ datafe- open/ markdown- 图表- echarts

严格 JSON 仅限 Cononial 的 ECharts 渲染器 `markdown-chart` 协议. ECharts运行时间和任何引用的数据集解析器由 主机; Canonical 路径从不获取数据或评价JavaScript.

`createEChartsRenderer()` 装入已安装的主机 `echarts` 对等者依赖 首先挂载。 过 `loadECharts` 只有在提供定制的 ECharts 构建时.

默认情况下, 渲染器会应用从 [Quen 代码 WebShell ECharts 组件](https://github.com/QwenLM/qwen-code/blob/89ab15d2f1bc253d4375e508130462ad5df3c56f/packages/web-shell/client/components/messages/EchartsFullDataBlock.tsx)数字 : 轻/暗调色板、打字、网格间隔、轴、工具提示、传奇和 栏/行/皮条系列细节。 准确的12相光/暗色调色板和主题 共享图表设计系统的颜色在公众中保持 渲染器,所以主机共享一个运行的真相源. 表中的明确值 已验证的 ECharts 选项覆盖这些默认值 . 过 `defaultStyle: false` 只禁用这些演示文稿默认值 :

```ts
createEChartsRenderer({ defaultStyle: false });
```

验证,犬类数据注入,和数据检索分辨率仍然适用. 见包裹 [第三方通知](https://npmcn.com/package/%40datafe-open/markdown-chart-echarts/THIRD_PARTY_NOTICES.md) 页:1 归属和许可细节.

当共享图/数据卡可用时,其标题来自第一个 非空的电荷 `option.title.text` 数值。 若为 `title.text` 缺席或空白, 卡片省略了标题,而不是显示倒置。 同样的规则是 在临时遗产表实现后适用。 当牌 显示标题,渲染器将匹配的主标题从它的 克隆渲染选项, 因此标题只出现一次 。 其他标题组合条目 和匹配条目 `subtext` 保留字幕。 正在挂载 直接或没有内含数据卡的渲染器离开 原生ECharts产权不变.

在峡谷里 `markdown-chart` 信封, 渲染器中性 `data` 是个兄弟 联 合 国 `spec`,以及 `spec` 是 ECharts 选项。 这样可以检查主机 在不理解ECharts的情况下插入数据.

渲染器由 `"renderer": "echarts"` 在峡谷中 `markdown-chart` 信封上写着 渲染器光谱从未定义它自己的 `version`· ; 协议版本属于 `markdown-chart`。 。 。 .

准确 `echarts-fulldata` 别名接受 `dataworks-chart` 紧凑 JSON 信封 `{ version: 1, data, option }`它与同样的ECharts 正常化 解析数据和选项为条形 `{ renderer: "echarts", data, spec }`这样 标题、 安全字符串用于物质模板、 数据参考和图表/数据行为 共享。 紧凑信封拒绝未知字段, 需要稳定的 ASCII 维度和等宽数组行, 并且从不评价 JavaScript 。 这个 单数 `echart-fulldata` 故意不登记别名.

何时 `resolveDataRef` 实现引用数据集, 渲染器注入 输入已验证行 `option.dataset` ,然后通过 图表/数据视图的核心物质化流程.

条形结构数据不包含 `option.dataset`数字 :

-   `shape: "graph"` 支持一个 Sankey 或 图表序列。 节点标识, 不显示 名称,确定数字链接的终点; 图表分类首先使用.
-   `shape: "hierarchy"` 支持一棵树、树图或太阳爆发系列。 家长 总数是在克隆选项上得到的,从不变异犬科源.

结构化系列不能包含 `data`, (中文(简体) ), `nodes`, (中文(简体) ), `links`,或 `edges`。桑基语 循环和缺失的流量值、树根不匹配和缺失的区域叶 值作为图表约束出错返回,这样共享的数据视图仍然保留 可检查.

## 临时遗留适配器

需要临时查询的主机和沙盒文件栅栏可以共享文件 发现状态机器同时保留认证和 HTTP 本地细节 :

```ts
import {
  createEChartsRenderer,
  createLegacySandboxErrorClassifier,
  createLegacySandboxHostAdapter,
  waitForLegacySandboxAbortable,
  type LegacySandboxFile,
  type LegacySandboxTransport,
} from '@datafe-open/markdown-chart-echarts';

interface HostFile extends LegacySandboxFile {
  readonly downloadId: string;
}

const classifyError = createLegacySandboxErrorClassifier({
  getStatus(error) {
    return isHostHttpError(error) ? error.statusCode : undefined;
  },
});

const transport: LegacySandboxTransport<HostFile> = {
  async listFiles({ sessionId, requestId, signal }) {
    const request = listAuthorizedFiles({ sessionId, requestId });
    return waitForLegacySandboxAbortable(request, signal);
  },
  async readFile({ sessionId, file, signal }) {
    const request = downloadAuthorizedCsv({ sessionId, id: file.downloadId });
    return waitForLegacySandboxAbortable(request, signal);
  },
  classifyError,
};

const adapter = createLegacySandboxHostAdapter({ transport });
const context = {
  sessionId,
  requestId,
  phase: turnPhase,
  cacheScopeKey: `${tenantId}:${userId}`,
} as const;
const legacySandbox = adapter.bind(context);
if (!legacySandbox) throw new Error('Legacy sandbox context is incomplete');
const renderer = createEChartsRenderer({ legacySandbox });
const rendererIdentity = adapter.identity(context);
```

`cacheScopeKey` 必须是稳定、非秘密的主要身份; 永远不要使用无记名标志,饼干,或者他们的散文。 装订有固定的 请求到会话重试时间表, 唯一 CSV 匹配, 私人 30秒 / 64 输入成功缓存,以及 `shouldDefer(language)` 对于尚未生效的围栏 请出示身份证明 一个没有请求的最后约束 ID 故意跳过两者 成功cache读写. 运输拥有授权和反应 映射、文件下载和分类 `not-found`, (中文(简体) ), `retryable`,或 `fatal`,必须尊重所提供的 `AbortSignal`。 。 。 .

可选的主机帮助器在此包中保留了剩余的主机中性胶: `waitForLegacySandboxAbortable` 连接可中止的类似承诺的请求到 `AbortSignal`, (中文(简体) ), `createLegacySandboxErrorClassifier` 处理结构 HTTP 和 未检查错误消息的网络故障,以及 `createLegacySandboxHostAdapter` 规范背景,私人拥有 活动客户端/缓存生成。 一个主机仍然拥有其认证的API呼叫, 响应及文件描述符映射,下载 URL 处理,主源, 和任何特定主机状态的延长。 使用 `adapter.identity(context)` 作为 主机组件/控制器身份,从而替换主机或转弯更改 处理旧控制器 。 当孤立时创建新的适配器实例 需要客户/缓存寿命;公共适配器故意没有 `reset()` 方法。 直接 `createLegacySandboxClient({ transport })` 剩余用途 支持现有消费者. `turnPhase` 必须来自主机的实际 使用寿命周期;不要从制造器的占位器或栅栏中推断出来 状态.

直接绑定失败使用导出 `LegacySandboxError` 密码 一个渲染器 配置为 `legacySandbox` 保持这些公共失败. `legacySandbox` 是临时 ChatBI 查询的唯一公共渲染器配置,并且 沙盒文件围栏。 内容 `resolveLegacyArtifactContent` 财务报告和审定财务报表 `resolveLegacySandboxFileContent` 方法是内部有约束力的执行 由共享客户创建的合同,而不是独立的渲染器选项或 框架组件道具。 匹配函数类型仍为导出 自定义 `LegacySandboxBinding` 执行可以满足该合同.

绑定返回授权的原始 CSV 内容到渲染器 。 这个包 应用字节/行/列/单元格限制,保留对大小写敏感的沙盒路径, 剖析 CSV, 将临时源进行消毒, 并在一个 专职工人,拥有独有的靴子框,逐一拒绝 CSP. (中文(简体) ). JSON 唯一的结果通过同样的 ECharts 选项验证 以夸夸其谈的方式.

所有移民代码都生活在 `src/legacy`. 具有约束力的方法请求/功能 类型和遗产限额 `@deprecated`; 仅保留为 内部执行签名 `LegacySandboxBinding`客户, 约束、运输、描述和出错出口也是暂时的遗产 迁移表面,但没有单独说明 `@deprecated` 在此 因此,ChatBI和ADA可以聚合到一个执行上. 不要用他们 用于划线图或紧凑图.

清除要求每个主机停止生产和解决临时的 查询和沙盒文件围栏,至少发布一个折旧通知 发布周期,以及已知的零存储器、外部消费者和运行时间使用. 删除将删除 `legacySandbox` 渲染器选项, 临时 出口类型,以及 `src/legacy` 一并执行,同时保留 解析和验证。 参见 ChatBI OpenAPI 主机侧列表/ Get 示例 迁移期间代理融合.

### 标准瀑布

使用 [犬形瀑布模板](https://npmcn.com/package/skills/markdown-chart/references/waterfall.md) 和四个本土酒吧系列. `stackStrategy: "all"` 财务报告和审定财务报表 零占位符通过负平衡和零交叉来保存几何. 总数是零的快照,而不是额外的三角洲。 绑定签名的标签/工具提示 语义数据列;保持帮助者隐形并禁止图例选择. 红色/绿色系列颜色 [输出语言会议](https://npmcn.com/package/skills/markdown-chart/references/semantic-colors.md)。 。 。 . 适配器拒绝不存在 `series.type: "waterfall"` 并指导使用本地的栏杆.

## 常见问题

### @datafe-open/markdown-chart-echarts 是什么？

Markdown图的安全犬类ECharts渲染器

### 如何安装 @datafe-open/markdown-chart-echarts？

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

### @datafe-open/markdown-chart-echarts 支持 TypeScript 吗？

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

### @datafe-open/markdown-chart-echarts 支持 ESM 还是 CommonJS？

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

### @datafe-open/markdown-chart-echarts 可以商用吗？

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

### @datafe-open/markdown-chart-echarts 的下载量有多少？

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

### @datafe-open/markdown-chart-echarts 还在维护吗？

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