函数速查
函数的参数、默认值和用法与当前版本保持同步。content 表示音符或花括号包裹的内容，label 表示已声明的标签，length 可使用 px 或 em。
没有匹配的函数
@note
别名：@n
创建音符
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | name | string | 必填 | 数字音名或大写字母音名，可自带升降号与八度； |
| 2 | acc | string | "" | 额外升降号， |
| 3 | octave | number | 4 | 字母音名使用绝对八度；数字音名使用相对八度，省略时为 0 |
| 4 | color | string | "#000" | 音符颜色，使用 CSS 颜色值 |
@note(A, acc=#, octave=3, color=#c33)
简写：数字音名按“升降号、音名、相对八度”书写；字母音名按“音名、升降号、绝对八度”书写。1,, 比当前调性基准低两个八度，1' 高一个八度。
- 简写的升降号完全由自身决定，省略时为空，不继承
@set(note.acc=...)；显式调用省略acc时仍继承默认值 A#3等价于@note(A, #, 3)，默认acc为空时也等价于@note(A#3)#1'等价于@note(1, #, 1)，默认acc为空时也等价于@note("#1'")- 支持组合升降号，如
A##bn99；无歧义时也接受后置写法，如A3#、6#,, - 升降号后紧跟数字时归入下一音符：
6#3解析为6和#3
@dash
别名：@-
增时线
1 @dash()
无参数。添加一根增时线，扩展前方音符或休止符的完整时值；也可简写为 1 -。每根线的基础时值为一个四分音符，可用减时线或附点调整。装饰音覆盖延长后的完整音符，例如 1 ^ $tr - 在两拍内持续颤音。
@rest
多小节休止
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | n | number | 1 | 休止的小节数 |
| 2 | width | length | 3em | 横线的最小宽度 |
| 3 | size | length | 1em | 数字字号与笔画尺寸 |
@meter(4,4) | @rest(19) |
使用当前拍号产生 19 个整小节的静音（必须先声明拍号）
@bar
别名：@|
小节线
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | type | number | 0 | 0：普通线 |
| 2 | length | length | 1.25em | 小节线高度 |
@bar(0, length=1.25em)
有语法糖简写，见 type 参数的说明。
@div
别名：@/
减时线
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | 仅位置参数 | content | 必填 | 要减时的内容，可包含多个音符或增时线 |
| 2 | n | number | 1 | 减时层数，每级将时值减半，取非负整数 |
| 3 | autobeam | boolean | true | 是否参与不同 div 之间的自动连线，同一 div 内部的连线不受影响 |
@div({1 2 -}, n=2, autobeam=true)
简写：在目标后加 /，可重复或作用于内容块。@div(1, 2) 等价于 1//，@div({1 2/ -}, 2) 等价于 {1 2/ -}//。默认参数使用 div.n、div.autobeam 设置。
@dot
别名：@.
附点
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | 仅位置参数 | content | 必填 | 单个可见时间元素，如音符、增时线或折叠和弦 |
| 2 | n | number | 1 | 附点数，第一点增加原时值的一半，后续各点增加量再减半 |
@dot(1, n=2)
简写：目标后加 .，可重复。@dot(1, 2) 等价于 1..；{1^2}. 等价于 {1.^2}。
@dot({1 2/ -}, 2) 包含多个时间元素，会报错；需要分别为各元素添加附点。
@tuplet
多连音
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | 仅位置参数 | content | 必填 | 连音内容，各元素按同一比例缩放时值 |
| 2 | normal | number | 必填 | 目标总时长，以内容中的最短时值为单位 |
@tuplet({1/ 2 3}, normal=4)
本例最短单位为八分音符，原内容占 5 个单位，缩放后占 4 个单位：形成五连音，总时长为一个二分音符
@voice
别名：@v
声部
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | 仅位置参数 | content | 必填 | 声部的音符内容 |
| 2 | name | string | "" | 显示在左侧的声部名称，空值隐藏名称 |
支持额外参数（位置参数类型：string）
@voice({1 2 3}, 钢琴, 男=ha ha ha, 女=la la la)
- 额外参数：每项为一行歌词；命名参数同时给出歌词行名，位置参数表示无行名。省略声部名但仍需歌词时，保留空位，如
@voice({1 2 3}, , ha ha ha)。
歌词可用引号包裹；显式调用中含逗号等歧义字符时必须加引号。英文用空格或连字符 - 分词，用 @ 占位。
简写：N 声明音符行，L 声明歌词行，括号内的名称可省略：
N(钢琴): 1 2 3
L(男): ha ha ha
L: la la la
行首允许空白，换行结束当前声明；在行末加 \ 可续行。这种写法中的歌词允许直接使用逗号。
@voices
别名：@vs
多个声部
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 仅命名参数 | connect | string | "[-]" | 视觉连接：[1-4] 为现有括线，{5-7} 为弯曲大括号；[3]、{3} 表示单个声部，省略范围端点表示首/末声部，空字符串只保留公共连谱线。 |
支持额外参数（位置参数类型：content）
@voices(
@voice({1 2 3}, 钢琴, 男=ha ha ha),
@voice({3 4 5}, , "la la la")
)
接受多个声部作为位置参数，将它们按时间对齐、分行排布；声部名称和歌词由各自的 @voice 提供
视觉连接：仅命名参数 connect 使用字符串，如 connect="[1-4]{5-7}"。
[] 是现有括线，{} 是弯曲大括号；编号从 1 开始，省略起点/终点表示首/末声部。
[3] 等价于 [3-3]，{3} 等价于 {3-3}，用于单个声部。
默认 "[-]" 连接全部声部；"" 只保留公共细连谱线。未指定的声部仍有细线，范围可以重叠，不改变声部或播放关系。
用 @set(voices.connect="{1-2}[3-]") 设置后续多声部块的默认方案，显式参数写在所有声部之后。
简写：连续声明多个 N: 声部及其 L: 歌词，会自动组成 voices
N(钢琴): 1 2 3
L(男): ha ha ha
N: 3 4 5
L: la la la
连接声明 V{}:、V[]:、V|: 分别指定后续声部的弯曲大括号、现有括线和仅细线，后面的 N: 可以同行，也可以换行。
到下一条 V 声明或当前块末尾结束，组间不空行；空行结束整个多声部块。
出现 V 声明时，当前块完整替换默认连接方案，不影响后面的块。V 不创建音轨，L 仍属于前面的 N。
V{}: N(右手): 1 2 3
N(左手): 5 6 7
V[]: N(女高): 6 6 5
L: 啊 啊 啊
N(女低): 1 2 3
@br
换行
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | offset | number | 1 | 后续内容偏移的谱面行数，2 表示空出一行再继续 |
1 2 @br() 3 4
@br() 换到下一行，@br(2) 空出一行再继续
简写：仅在顶层，连续至少两个换行表示换行
@pagebreak
别名：@pb
强制换页
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | justify | boolean | true | 是否分配当前页的剩余空间；无限页高时不拉伸 |
1 2 @br() 3 4 @pagebreak() 5 6
同时换行并开启新页，不占音乐时值。同一时刻的并行调用只换一次页，justify=false 优先。
@page
设置文档页面
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | width | length | 794px | 页面宽度，须大于左右页边距之和 |
| 2 | height | length | 0px | 页面高度，小于等于 0 表示不自动分页、高度随内容增长；宽度为 |
| 3 | top | length | 45px | 页面上边距 |
| 4 | bottom | length | 48px | 页面下边距，启用页码时至少为 |
| 5 | left | length | 40px | 页面左边距 |
| 6 | right | length | 40px | 页面右边距 |
| 7 | gap | length | 1em | 谱面行之间的最小间距 |
| 8 | numbering | string | "" | 页码格式，空值隐藏； |
| 9 | font | string | "" | 页码字体，空值沿用当前字体设置 |
| 10 | fillRatio | number | 0.5 | 自然宽度达到该比例后撑满 |
@page(
width=794px, height=1123px, top=48px, bottom=48px,
left=40px, right=40px, gap=1em, numbering="1/1", fillRatio=0.5
)
尺寸接受 px 或 em。页边距和行距须非负；左右边距之和须小于页宽，固定页高时上下边距之和须小于页高。
@head
左、中、右三区布局
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | left | content | "" | 左区零时长内容，如调性、拍号与速度记号 |
| 2 | center | content | "" | 中区零时长内容，如标题与副标题 |
| 3 | right | content | "" | 右区零时长内容，如作者与署名 |
| 4 | gap | length | 5px | 每个区内相邻行的垂直间距 |
常用于谱头：
@head(left={{@key(C) @meter(4,4)}},
center={@text(标题)}, right={@text(作者)})
简写：相邻的 H.*: 行合并为同一个谱头，每条声明生成所在区的一行；空行或普通内容结束组合
H.title: 标题
H.subtitle: 副标题
H.author: 作者
H.signature: 1=C 4/4
H.tempo: 94
title / subtitle 居中，分别预设大、小字号；author 小字号右对齐；signature 和 tempo 放在左区。H.left:、H.center:、H.right: 可直接写对应区的零时长内容。以 @ 或 { 开头的值按 jpFun 解析，其余按字段的文本规则处理。
@stack
临时多声部
支持额外参数（位置参数类型：content）
@stack({1 2}, {3/ 4/ 5})
接受至少两个内容参数，各分支同时开始、保留各自时值，整体时长取最长分支。适合节奏不同的临时多声部。
简写：{1 2} & {3/ 4/ 5}。可继续用 & 连接更多分支；若要写和弦，请使用 up / down。
@up
把同一时间位置的可见对象向上堆叠
支持额外参数（位置参数类型：content）
@up(1, 3, 5)
第一个内容参数为宿主，其余依次叠在上方；所有成员共享宿主时值。常用于和弦、速度记号和音符注释。
简写：1 ^ 3 ^ 5。复杂内容可用 {...} 包裹；需要独立节奏的并行分支时，使用 & / @stack。
@down
把同一时间位置的可见对象向下堆叠
支持额外参数（位置参数类型：content）
@down(1, $p)
第一个内容参数为宿主，其余依次叠在下方并共享其时值，常用于力度等下方标记。
简写：1 _ $p。与 ^ 混写时共用同一宿主：1^2_3 将 2 放在 1 上方、3 放在下方。
@arp
别名：@arpeggio
琶音
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | content | content | 必填 | 由 |
| 2 | direction | string | "" | 空值从低到高、不画箭头； |
@arp({1 ^ 3 ^ 5}, direction=up)
给和弦绘制琶音记号，播放时按方向错开成员起点并保持共同终点。复合成员的内部音符按比例压缩到剩余时值，装饰音在确定后的区间内展开。
@grace
倚音
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | host | content | 必填 | 被倚音修饰的宿主内容 |
| 2 | grace | content | 必填 | 倚音内容，多个音符可用大括号组合，也可以含多个声部 |
| 3 | side | string | "pre" |
|
@grace(1, {3 2}, side=pre)
简写：箭头始终指向宿主
2>1：2是1的前倚音，位于左上方1<2：2是1的后倚音，位于右上方{3 2}>1：一组前倚音，等价于上例1>2>3：允许嵌套，1修饰2，2修饰3
倚音默认带一条减时线，按八分音符书写；再加 / 变为十六分音符
倚音内容可以是换行以外的任意结构，例如 {1 & 3}>2 的两个声部同时奏出
@slide
滑入或滑出记号
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | 仅位置参数 | content | 必填 | 被修饰的内容 |
| 2 | side | string | "pre" | pre 滑入，post 滑出 |
| 3 | direction | string | "up" | up 上行，down 下行 |
@slide(5, side=pre, direction=up)
仅绘制，不改变时值和播放。pre 修饰内容首端，post 修饰末端；up/down 表示随时间上行/下行。
@tie
连音线
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 仅命名参数 | height | length | 0em | 弧线高度，支持 px/em；em 相对调用处字号，非正数自动调整，最高 0.5em |
支持额外参数（位置参数类型：label）
1@a 2 3@b @tie(a, b, height=0.5em)
- 位置参数：端点标签，可传多个，按顺序连接；省略时查找最近的可标记对象，包括增时线
- height：仅命名的弧线高度参数，默认
0（自动）；非正数按水平跨度自动调整，在2.5em跨度处平滑达到0.5em上限，正数指定固定弧高。em 相对调用处字号；可用@set(tie.height=0.8em)设置局部默认值，显式传参优先
同行端点用一条弧线连接，自动高度按水平跨度计算；跨行时自动拆成多段，自动模式下各段统一使用 0.45em 高度。同轨同音且时间连续的音段建立播放连接，各段保留自己的装饰，例如 1 ^ $tr 1 @tie() 的后一音段不继承颤音。涉及增时线的连接仅绘制，不合并播放音符。
@beam
减时线连接
支持额外参数（位置参数类型：label）
事后将多个减时线强行相连
1/@a 2/@b | 3/@c @beam(a, b, c)
位置参数：已标记音符的标签，按传入顺序连接减时线，显式指定一组。先用 / 或 @div 为目标添加减时线，再用 @beam 控制连接。端点须同轨、同谱面行且相邻，可跨小节线；连线直接穿过小节线，保留原有间距。
@gliss
滑音连线
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | 仅位置参数 | label | 必填 | 一个端点的标签，先后按谱面时间确定 |
| 2 | 仅位置参数 | label | 必填 | 另一个端点的标签 |
1 -@a 5@b @gliss(a, b)
若附属对象无音高，将使用前面最近的的同轨有音高对象的音高
@dyn
渐强渐弱
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | from | label | 必填 | 渐变起点的标签 |
| 2 | to | label | 必填 | 渐变终点的标签 |
| 3 | dv | number | 必填 | 力度变化量，正数渐强，负数渐弱 |
1 ^ $p 2@a 3 4@b
@dyn(a, b, 24)
端点须位于同一音轨、不同时间；变化量沿区间线性增加，叠加在每个音符原有力度上。本例从 a 到 b 渐强，终点增加 24 的力度。
端点也可标在增时线上。终点没有力度时，取同轨、不晚于终点的最后一个原始力度作为保持基准；找不到时给出警告并仅绘制。增时线延续的音符保持起音时的力度。
@box
给目标结构或对象加外框
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | 仅位置参数 | content | 必填 | 需要加框的内容或结构 |
| 2 | padding | length | 0em | 内容到框线的内边距，负值向内收缩 |
| 3 | stroke | length | 1px | 框线宽度 |
| 4 | width | length | -1px | 约束内部排版的宽度，非正值表示随内容自动确定 |
@box({1 2 3}, padding=0.2em, stroke=0.08em)
@volta
反复的跳房子
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | from | label | 必填 | 区间起点的标签，区间允许跨谱面行 |
| 2 | to | label | 必填 | 区间终点的标签 |
| 3 | pass | number | 必填 | 进入此区间的演奏遍数，须为正整数 |
支持额外参数（位置参数类型：number）
|: 1 2 | 3@a 4@b :| 5@c 6@d | 7
@volta(a, b, 1) @volta(c, d, 2)
- 额外位置参数：更多遍数；例如
@volta(a, b, 1, 2)让前两遍共用一个房子。遍数顺序不限，谱面按升序显示。
本例第一遍演奏 a 到 b，第二遍演奏 c 到 d。
播放区间包含终点事件的完整时值，但不包含其结束时刻的小节线或后续事件。
@ottava
八度号
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | 仅位置参数 | label | 必填 | 起点标签 |
| 2 | 仅位置参数 | label | 必填 | 终点标签 |
| 3 | shift | number | 1 | 非零整数八度数，正数为高，负数为低 |
1@a 2 3 -@b | 4
@ottava(a, b, 1)
shift 为非零整数八度数，正数在上方标高八度号，负数在下方标低八度号，默认 1。标签使用谱面数字字体的斜体。
@adjust
别名：@adj
微调目标的绘制位置与排版占位
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | 仅位置参数 | content | 必填 | 要微调的内容或关系对象 |
| 2 | dx | length | 0px | 排版后的水平偏移，正值向右，不改变占位 |
| 3 | dy | length | 0px | 排版后的垂直偏移，正值向下，不改变占位 |
| 4 | dw | length | 0px | 增减水平占位，按原左右比例分配，最终宽度不小于 0 |
| 5 | dh | length | 0px | 增减下方占位，最终高度不小于 0 |
@adjust(1, dx=2px, dy=-1px, dw=0.2em, dh=0px)
位置偏移在排版后应用，相邻对象保持原位；占位调整在排版前应用。只包裹关系对象时，平移作用于该关系对象本身。
@set
设置局部默认值
支持额外参数
@set(fontsize=20, strict=true)
{ @set(note.octave=5, note.color=#f00) C D E }
接受命名参数，可一次设置多项：
- 系统选项：如
fontsize=20将字号设为 20px，strict=true开启严格模式 - 函数默认参数：按
函数主名.参数名=值书写，例如note.octave=5、note.color=#f00；显式传参优先
设置从当前位置起生效，限于当前作用域及其子作用域；离开内容块后恢复外层设置。它按源码作用域解析，与演奏时间无关。
@key
别名：@1
设置时间线上的 1= 调性基准
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | tonality | string | 必填 |
|
| 2 | size | length | 1em | 调性记号字号 |
1 ^ @key(F#3)
调性沿时间线影响后续数字音名。谱面记号显示音名与升降号，省略八度；通常用 ^ 叠在音符上方。
@meter
设置拍号
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | num | number | 必填 | 拍号分子，每小节包含的单位拍数 |
| 2 | den | number | 必填 | 拍号分母，以几分音符为单位拍 |
| 3 | size | length | 0.7em | 拍号字号 |
@meter(6, 8)
设置 6/8 拍号：每小节含六个八分音符的时值。
分子或分母为 0 时表示散板。
@tempo
设置时间线上的速度
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | bpm | number | 必填 | 每分钟四分音符数 |
| 2 | size | length | 1em | 速度记号字号 |
@tempo(96)
速度从当前时间位置起生效；用 1 ^ @tempo(96) 可将记号叠在音符上方
@program
别名：@instrument
设置当前音轨的 MIDI 音色
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | program | number | 必填 | 从 0 开始编号的 MIDI 音色，须为 |
@program(40) 1 2 3
切换为小提琴音色。设置将作用于当前音轨的后续音符。
@text
文本标记
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | 仅位置参数 | string | 必填 | 文本内容，可直接换行；含逗号等歧义字符时需加引号 |
| 2 | size | length | 0.8em | 文本字号 |
| 3 | lineheight | number | 1.25 | 相对自身字号的行高倍数 |
| 4 | align | string | "left" | 文本对齐方式： |
| 5 | font | string | "" | 文本字体，空值沿用当前字体设置 |
@text(进入主题, size=0.8em, align=center)
简写：直接写双引号文本，如 "进入主题"；可跨行，双引号须配对
@symbol
别名：@$
创建一个乐谱符号
| 位置 | 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| 1 | name | string | 必填 | 已注册记号名称，见函数说明中的记号列表 |
| 2 | size | length | 0.5em | 记号尺寸 |
1 ^ @symbol(p, size=0.5em)
简写：$name，如 1 ^ $p。名称读取到下一个空白或当前内容区间末尾，连续的标点也属于名称。
已注册记号
$tr：颤音：本音与调内上方二度交替。可写为$tr++，每个紧接的+添加一截波浪尾巴$fermata：延长记号：覆盖区间速度减半，目标音实际时长翻倍$prall：上波音：本音、调内上方二度、本音$mordent：下波音：本音、调内下方二度、本音$accent：重音$tremolo：轮指$harmonic：泛音$tenuto：保持音$marcato：强调音：尖顶记号；播放同重音，所附着音符力度增加 20，最高 127$staccato：断奏$turn：回音$iturn：逆回音$p：弱；支持$p、$pp、$ppp等连续 p，整体居中$mp：中弱$mf：中强$f：强；支持$f、$ff、$fff等连续 f，整体居中$dc：从头反复：跳回曲首再演一遍$ds：从记号处反复：跳回最近的 $segno$segno：反复记号：D.S. 的回跳目标$fine：终止记号：回跳之后经过这里就结束乐曲