# @barmark/render 中文文档

规范地址：https://npmcn.com/package/%40barmark/render/

版本：0\.16\.2
npm 元数据更新时间：2026-11-07T17:38:33.956Z
中文译文更新时间：2026-11-07T17:08:07.562Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40barmark/render
原文对照：https://npmcn.com/package/%40barmark/render/?lang=original
项目主页：https://github.com/kevinpeckham/barmark/tree/main/packages/render#readme
源码仓库：https://github.com/kevinpeckham/barmark

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

- 包体积（解压后）：260 kB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-10-31T17:49:42.883Z
- 最新版本发布：2026-11-07T17:38:33.601Z
- 近 30 天下载量：4803（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

Render Barmark 和弦图作为干净,可访问的条形网格: HTML 有声明阴影 DOM,或者网页组件.

## 安装

```sh
npm install @barmark/render
```

也可以使用：`pnpm add @barmark/render`、`yarn add @barmark/render`、`bun add @barmark/render`

## README

# @ barmark/ 放弃

渲染器 [标记](https://github.com/kevinpeckham/barmark) 和弦图为 任何页面上看起来相同的干净、平平的条形网格如下: 光和暗模式,带有读者文本大小的缩放,读取到 屏幕阅读器作为音乐.

```
npm install @barmark/render
```

## 作为 HTML( 不需要浏览器 JavaScript)

```js
import { renderChart } from "@barmark/render";

const html = renderChart(chartText, { fontUrl: "/fonts/Edwin-Roman.otf" });
```

`renderChart` 返回 a `<barmark-chart>` 含有声明的元素 阴影根:将其放入任意一页,服务器或静态,并显示 没有脚本的图表。 阴影根使页面的 CSS 关闭,所以 博客的重排和字体无法重新安排栏目 。 浏览器附加 a 仅在解析 HTML 时声明阴影根 : 要从 脚本, 使用 `setHTMLUnsafe` (或以下要素),不 `innerHTML`。 。 。 .

`renderChartUnwrapped(text, options)` 返回相同的标记,不包含 阴影根( 前缀类) `bm-`),用于包括以下内容的页面: `stylesheet` 他们自己.

## 作为网络组成部分

```html
<script type="module">import "@barmark/render/element";</script>

<barmark-chart src="/charts/peaceful-dreams.chart.md"></barmark-chart>

<barmark-chart theme="dark" rehearsal-letters>
    <script type="text/barmark">
        ## Verse
        | D | A | Bm | G |
    </script>
</barmark-chart>
```

本要件源于 `text` 财产,其 `src` URL 或一个孩子 `<script type="text/barmark">` (缩进被去掉),再次 当一个变化时; 它获取一个 `src` 一次, 并做一次 许多属性和属性一起改变。 上映的图表 服务器 `renderChart` 保持它的音乐,直到它有自己的来源, 仍然跟着 `theme`, (中文(简体) ), `bar-numbers` 财务报告和审定财务报表 `wrap`; 更改为 `numerals`, (中文(简体) ), `rehearsal-letters` 或者说 `show-part` 需要图表的文本,所以 它等待一个来源.

对于一个活编辑器,设置 `text`数字 :

```js
const chart = document.querySelector("barmark-chart");
editor.addEventListener("input", () => { chart.text = editor.value; });
```

虽然 `text` 是它赢得的字符串 `src` 和剧本孩子,没有 获取发生; 设定为 `null` 回到他们身边 任何字符串都是安全的 : 问题表现为诊断 绝对不会出错. 没有 `text` 属性:图表文本属于属性或属性 脚本孩子.

元素从 `fonts/` 文件夹旁边 拥有模块。 如果您的捆绑者移动文件, 请在文件之前亲自登记 元素负载,以 `<style data-barmark-font>` 持有 `fontFaceCss(yourUrl)`;然后元素离开它.

## 选项和属性

| `renderChart` 选项 | 元素属性( 财产) | 默认 |  |
| --- | --- | --- | --- |
| `theme` | `theme` (单位:千美元)`theme`(中文(简体) ) | `"auto"` | `"auto"` 遵循系统; `"light"` 或者说 `"dark"` 部队一 |
| `barNumbers` | `bar-numbers="off"` (单位:千美元)`barNumbers`(中文(简体) ) | `true` | 每行开头的栏号 |
| `rehearsalLetters` | `rehearsal-letters` (单位:千美元)`rehearsalLetters`(中文(简体) ) | `false` | 在播放的每节中 |
| `numerals` | `numerals` (单位:千美元)`numerals`(中文(简体) ) | 无 | `"nashville"` (6平方米)或 `"roman"` (vi7):每个和弦作为其酒吧钥匙的学位 |
| `wrap` | `wrap="off"` (单位:千美元)`wrap`(中文(简体) ) | `true` | 当区域宽于图表框时, 将区域行包起来; 关闭时, 各行保持其列和图表外溢, 以便其页面滚动 |
| `part` | `show-part` (单位:千美元)`showPart`(中文(简体) ) | 无 | 仅用这个标签画出部分,如一名玩家所读:tutti栏杆,自有栏杆,而"tacet"则放在那里. 属性不是 `part`, HTML 保留用于 `::part()` 样式 |
| `diagnostics` |  | `false` | 列出图表下方的错误和警告 |
| `fontUrl` |  | 无 | 释放爱德温 `@font-face` 图表前的规则 |
| (单位:千美元) `text` 参数) | (单位:千美元)`text`(中文(简体) ) | `null` | 要绘制的图表; 胜过 `src` 和脚本孩子 |

### 数值

与 `numerals`,每个和弦在键上显示其程度 因此,一个调值 重新编号 从它的下行。 度数 从键的通尼克对主尺度, 在每一种模式: `key: Am`,Am是1m,C是♭3. Nashville保持了和弦的质量 数字后上标(D中Bm7为6m7;D/F♯为1/3;Roman) (二、七、七)。 两个都加一个 动力和弦为5入上标(D的D5为15和I5为从15). 一个没有钥匙的酒吧,注解集,N.C, `?` 财务报告和审定财务报表 `--` 看着像往常一样 做,一个屏幕阅读器听到两个: "栏5:5,A 7". 编号 带弦 `data-numeral`. 这是一个视图: 音乐和酒吧数字不变.

### 语名

`speakChord(record, key?)` 给屏幕阅读器所听到的名称和弦 在图表中,对于其他想要大声说出和弦的工具:

```ts
import { parseChord } from "barmark";
import { speakChord } from "@barmark/render";

const r = parseChord("Cø");
if (r.ok) speakChord(r.value); // "C minor seven flat five"
```

以一键也说出度相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.

## 故意摆设

设置元素上方或任何元素上的自定义属性 :

| 财产 | 它的设定 |
| --- | --- |
| `--barmark-font` | 和弦的字形 |
| `--barmark-text-font` | 歌词和 `###` 注释行( 默认格鲁吉亚) |
| `--barmark-label-font` | 元行、 中图变化、 标题和诊断( 默认系统 sans) |
| `--barmark-size` | 和弦大小, 所有大小( 默认) `1rem`(中文(简体) ) |
| `--barmark-ink` | 和弦和文本 |
| `--barmark-paper` | 背景情况 |
| `--barmark-muted` | 手持、杠号、牙套、元线 |
| `--barmark-rule` | 条行 |
| `--barmark-accent` | 错误 |
| `--barmark-directive` | 中图变化( 默认变色) |
| `--barmark-note` | `###` 注释行( 默认墨水颜色) |
| `--barmark-lyrics` | 语音行下和词行中的音节( 默认墨水颜色) |

```css
barmark-chart {
    --barmark-size: 0.9rem;
    --barmark-paper: transparent;
    --barmark-text-font: "Noto Serif", Georgia, serif;
}
barmark-chart::part(heading) {
    color: teal;
}
```

`::part()` 名称 : `title`, (中文(简体) ), `meta`, (中文(简体) ), `heading`, (中文(简体) ), `bar`, (中文(简体) ), `chord`, (中文(简体) ), `text`, (中文(简体) ), `bar-number`, (中文(简体) ), `rehearsal`, (中文(简体) ), `lyrics` (每个诗句的一行, 里面) 联合国 `bar`) (中文(简体) ). 这些,自定义属性和 属性是公共表面:改变它们是一种突破性的改变.

## 光、暗和印记

两种调色板都满足了WCAG AA对比(4.5:1为文本). `theme="auto"` 如下 `prefers-color-scheme`; 带有自己的暗模式切换器的页面 `theme` 或颜色属性。 打印总是使用灯光调色板, 和 Windows 高对比度保持条行和标记可见.

## 无障碍

-   所有东西都是以em为单位的 `--barmark-size`缩放 缩放图表; 区域宽度太大,不能将其容器包成行 而不是在侧面滚动.
-   每个栏目都有从解析图上建起的口语名称:"第9栏:一七 例四,持用","三相: D, E, F锐小","注 E","C over E". 段落按标题标出,重复使用("play") 两次").

## 字体

爱德温,MuseScore的音乐文字字体,无修改于 `@barmark/render/fonts/Edwin-Roman.otf` 以其 SIL 打开字体许可证 (单位:千美元)`fonts/OFL.txt`) (中文(简体) ). 登记在姓氏"标语"下 爱德温 提供文件并传递其 URL 为 `fontUrl`,或打电话 `fontFaceCss(url)` 每页一次;没有它,图表使用格鲁吉亚或 又一个静脉注射器.

## 它画的是什么

栏号坐落在左边缘的地沟; 节标题,歌词, 注释行和中图更改从第一行开始。 和弦开始 在他们那份酒吧左边 中图名称的更改 本身: `time: 3/4, tempo: 120` 绘制为"-时间 3/4 = Tempo = 120". 默认大小和弦为16px,12px以下没有标签.

无论作者打出什么字,弦都以犬形形式出现(`Cø` 显示为 Cm7(%% 5) . `%` 绘制为复制的栏;重放的一节 完全被绘制出来,它自己的歌词取代了所写的部分。 栏 数字按写作的条数,每条以带数表示:a 重复,一个结束,一个跳跃或一个回放不会移动它们,所以一个回放 区域中显示它所写的数字。 一条带有错误的行显示为写入,下划线, 和它的讯息. `layoutChart(text)` 如果 你想自己画,和 `typesetChord(parts)` 与 `glyphs` 在页面设置时给出和弦的片段(根和质 升起的扩展,低音在斜线后 `typesetNumeral(parts, key, style)` 纳什维尔或罗马数字,所以 PDF或画布抽屉匹配. 一个区块的 `bars` 计数其 最大行栏( 无行栏时为0), 其中 `columns` 也计算其 fermata,方向和排练细胞.

由多个部分组成的图表(巴马克语法7.4)绘制每个系统为 叠行,每部分按分数顺序排列,该部分的标签在 地沟和上行的一个酒吧号码 系统里的一部分 一个空行,在它的第一行写"tacet", 所以每个系统保持它的 形状; 一行是一行。 标题列出部件名称,以及 每个部分行由名称向屏幕阅读器宣布。 在屏幕上也一样 狭为一行,其行相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.

声线(巴马克语法4.3和7.7:一个部分所唱的行由:, 例如 `Vox.Mel` 在铅板下裸露 `Vox` 和弦行) 音标作为其音标名(每集音标注,无八进制)和 在下面,用斜体字,每个诗歌的音节 唱在那里: 音符上的音节,然后每个 `lyrics N:` 排行,编号"1", "2" 有几个时,第一个酒吧左边. 连字符跟随 其词相继而出,所持之音节也`:/`)绘制扩展器 线条。 音符用节奏来间隔,每节音符最宽,或者 音节. 文稿来自播放的解析器,放在文字下面 栏:重复第2节画在所唱的栏下,a 复出取出自相自相出语. 无词的语音线作为任何部分 线条有。 歌词排在无旋律上(图中之词,或歌唱者 在它覆盖的栏内画出它的字,一条行 在狭小的屏幕上,他们用他们的 条;在一个系统下,它们进入它的最后一行. 一个屏幕读取器听到 每个栏的注后写着:"栏2:注G 四,按,. 第1节 第2节,“grace that”.

## 许可证

麻省理工学院. 埃德温是"MuseScore Limited",根据SIL开放字体许可证1.1.

## 常见问题

### @barmark/render 是什么？

Render Barmark 和弦图作为干净,可访问的条形网格: HTML 有声明阴影 DOM,或者网页组件\.

### 如何安装 @barmark/render？

在项目目录运行 npm install @barmark/render，或使用 pnpm add / yarn add / bun add。

### @barmark/render 支持 TypeScript 吗？

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

### @barmark/render 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @barmark/render 需要什么版本的 Node\.js？

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

### @barmark/render 可以商用吗？

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

### @barmark/render 的下载量有多少？

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

### @barmark/render 还在维护吗？

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