函数调用与参数

上一章用 1、2/ 等记号写出了简谱。这些记号其实都是“简写”，它们的完整写法被称为 函数调用。你可以把“函数”理解为一条写谱指令，“调用”就是请 jpFun 按这条指令做事。使用函数调用的写法，我们可以做到很多简写无法做到的事。

这一章我们将学会两件事：调用一个函数，以及修改它的参数。你不需要有编程经验，也不需要一次记住所有函数，只要理解基本的调用方式即可。

从一个音符开始

note 是用来写音符的函数名，英文意思就是“音符”。写下 @note(1)，就是请它写一个 do。下面两种写法的效果相同：

简写与完整写法

在编辑器中打开

1 @note(1)

复制代码

把 @note(1) 拆开来看：

• @ 表示下面要输入指令了！是 jpFun 函数调用的固定前缀。
• 接下来是函数名 note，指定要调用创建音符的函数。
• ( 和 ) 是一对括号，里面填写这条指令需要的信息。
• 1 指定要写哪个音。这样的信息叫作参数。试着把括号里的 1 改成 3，谱面上的音符也会跟着变成 mi。

关于标点：请使用英文半角标点：()、,、=、"，不要换成中文的 （）、，、＝、“”。

下面给出具体的要求：函数调用形如 @函数名(参数1, 参数2, ...)，有以下规则必须遵守：

• 以 @ 开头
• @ 之后紧跟函数名。解析时不区分函数名大小写，本文统一使用小写写法。
• 函数名后紧跟左括号 (。写 @note(1)，不要写 @ note(1) 或 @note (1)。
• 参数之间用英文逗号 , 分隔。
• 最右边以右括号 ) 结束。不需要填写参数时，也要保留括号。例如 @br() 表示换到下一谱面行；只写 @br 不会调用函数（原因见下一章）。

按顺序填写参数

一条指令可能需要不止一项信息，这时用英文逗号 , 分隔。例如设置 3/8 拍：

@meter(3, 8)

meter 是设置拍号的函数。它规定第一个参数是分子，第二个参数是分母，所以这里的 3 和 8 不能随便交换。把它们交换，会变成 8/3，而不是原来的 3/8。

这种依靠先后顺序来确定含义的写法，叫作位置参数。每个位置的含义由函数规定，可以在函数速查中查询。

按名字填写参数

如果不仅想写一个 do，还想把它改成红色，可以这样写：

给音符指定颜色

在编辑器中打开

@note(1)
@note(1, color="#f00")

复制代码

color 是“颜色”参数的名字，"#f00" 是红色的颜色值（直接写red也是可以的）。这里的 = 不是数学里的等式，而是把右边的值填给左边指定的参数：color="#f00" 就是“颜色用红色”。

这种写明 参数名=值 的写法，叫作命名参数。可用的名称和含义以函数说明为准。位置参数和命名参数可以混用，但位置参数要写在命名参数前面。上例先写音名 1，再写 color="#f00"，就是这个顺序。

普通具名参数同时具有位置和名称，两种方式都能填写。例如拍号的第一个参数叫 num（分子），第二个叫 den（分母），所以下面三行都表示 3/8 拍：

@meter(3, 8)
@meter(3, den=8)
@meter(num=3, den=8)

函数速查还会标出仅命名参数：它没有对应的位置，必须写出 参数名=值。例如连音线的 height 和多声部的 connect。之所以有这种特例，是因为这两个函数接收任意数目的位置参数。

不填写的参数：默认值

为什么只写 @note(1) 也能得到黑色的音符？因为颜色参数有默认值：不填写它时，就使用预先规定的黑色。

@note 还可以调整升降记号、八度等，而颜色是排在最后的参数。使用命名参数，可以跳过这些暂时不想修改的设置，直接指定颜色，不必把前面的默认值全部抄写一遍。

不过，并不是每个参数都可以省略，因为不是所有参数都有默认值。例如 @note 的音名是必填的，你需要告诉它究竟要写哪个音。查阅函数说明时，先看哪些参数必填，再找自己想修改的参数即可。

如果想修改默认值怎么办？请使用 @set 函数。参看 设置。

参数里还能填什么

除了音名和颜色，参数也可以填写文字、字号等。以写文字的 @text 为例：

文字和字号

在编辑器中打开

@text("轻快地")
@text("轻快地", size=20px)

复制代码

第一个参数是要显示的文字。文字用一对英文双引号 " 包起来，引号本身不会印在谱面上。这类值叫作字符串。先养成保留双引号的习惯，也不要用单引号代替，因为单引号已经用于升高八度。

第二行的 size 是字号参数，20px 是一个长度：20 是大小，px 是单位，两者之间不加空格。把 20px 改成 30px，文字就会变大。其他单位等到需要时再学。

不同参数接受不同种类的值，文档把这个要求叫作参数的类型。例如文字参数填字符串，字号参数填长度。下一章我们将讲解所有参数的类型。

试一试

打开“给音符指定颜色”的谱例，做两次修改：

1. 把第二个音符从 do 改成 mi，保留红色。
2. 再把它改成蓝色，蓝色的颜色值是 "#00f"。

完成后，你应该能看到一个黑色的 do 和一个蓝色的 mi。如果结果不对，检查逗号、引号和括号是否成对、是否用了英文标点。

小结

• 函数是一条写谱指令，调用时写成 @函数名(...)；... 表示按需填写的参数。
• 位置参数按顺序填写，命名参数写成 参数名=值，并放在位置参数之后；标为“仅命名”的参数不能省略名称。
• 有默认值的参数可以不填；需要调整时，再用命名参数单独指定。
• 日常写谱仍然可以用 1 等简写，需要更多设置时再用完整函数调用。这样的简写也叫作“语法糖”。在编辑器中把光标放到简写上，可以查看对应的完整调用。

下一章基本类型会介绍参数里可以填写的六类值，从数值和文字，到一段乐谱和对象的标签。已经熟悉这些类型的话，也可以继续尝试音符、调性和音高中的写法。