Japan Bank Holiday and Gotobi Library (MT5/MT4)：使用手册、函数与示例

Japan Bank Holiday and Gotobi Library 是一个用于 MetaTrader 5 和 MetaTrader 4 的免费函数库。它在您自己的 EA、指标或脚本中回答日元市场的日历问题。本手册面向开发者，适用于两个平台上的 1.00 版。

可以回答的问题

• 日本国民节假日，包括调休假日、国民休息日和一次性节日，并给出每个节日的英文名称。
• 日本银行休息日：周六、周日、国民节假日以及 12 月 31 日至 1 月 3 日。其余日期均为东京营业日。
• gotobi 日（五十日）：每月的 5 日、10 日、15 日、20 日、25 日以及月末最后一天。如果遇上银行休息日，gotobi 日会提前到同月的前一个营业日。
• 东京定盘价的时间（日本时间 09:55），以及服务器时间与日本时间的相互换算。日本没有夏令时（JST = UTC+9）。

适用年份：1980 至 2099 年。规则通过计算得出，因此没有需要更新的节假日表。不使用 DLL，不发送网络请求，不读写文件，不含交易函数。

安装

1. 在产品页面点击“免费下载”（Free Download），会打开 MetaTrader；或者在工具箱 > 市场中找到它（在 MT4 中，这个窗口叫作“终端”）。MT5 版和 MT4 版是两个独立的产品。
2. 市场会将本库安装为 MQL5\Libraries\Market\Japan Bank Holiday and Gotobi Library.ex5（MT5）或 MQL4\Libraries\Market\Japan Bank Holiday and Gotobi Library MT4.ex4（MT4）。通过文件 > 打开数据文件夹（File > Open Data Folder）可以看到这些文件夹。
3. 已安装的产品及其更新位于工具箱 > 市场 > 已购买。
4. 函数库不需要加载到图表上。您自己的程序通过导入块（#import）来加载它。

导入

将适用于您平台的头文件保存到 Include 文件夹中，并在您程序的开头添加一行：

• JpMarketCalendar_Market.mqh（MT5）：保存到 MQL5\Include。
• JpMarketCalendar_Market_MT4.mqh（MT4）：保存到 MQL4\Include。

#include <JpMarketCalendar_Market.mqh>       // MT5
#include <JpMarketCalendar_Market_MT4.mqh>   // MT4

每个头文件都会导入全部 17 个函数，并定义夏令时规则 JP_DST_NONE （0）、 JP_DST_US （1）和 JP_DST_EU （2）。如果您自己粘贴导入块，其第一行必须与已安装的文件完全一致（两个反斜杠）： #import "Market\\Japan Bank Holiday and Gotobi Library.ex5" （MT5）或 #import "Market\\Japan Bank Holiday and Gotobi Library MT4.ex4" （MT4）。

两个入门程序，都不下单：

• JpCalendarDemo.mq5 / JpCalendarDemo_MT4.mq4：一个脚本，打印服务器时间和日本时间、接下来的几次定盘，以及您所选年份的节假日和 gotobi 日。如果它能打印出这些内容，就说明本库已正确安装和导入。
• JpCalendarExample.mq5 / JpCalendarExample_MT4.mq4：一个 EA，用 Comment() 显示 gotobi 日的定盘时间、节日名称或下一个 gotobi 日。

全部六个文件编译时都是 0 个错误、0 个警告。下面是演示脚本在 MT5 模拟服务器上的输出；MT4 版打印的内容相同。

函数参考

日期参数使用日本时间，可以传入当天的任意时刻。在 1980-2099 年范围之外，函数返回 false、0、"" 或 -1。两个设置函数接受 -43200 至 50400 之间 900 秒的整数倍；对于其他任何值，它们会打印原因、返回 false，并保留之前的设置。

示例

日本的今天：

datetime jst = JpNowJst();                       // Japan time now
if(JpIsBankHoliday(jst))
   Print("Tokyo banks are closed: ", JpHolidayName(jst));   // "" on a plain weekend
else if(JpIsGotobi(jst) && jst < JpTokyoFixing(jst))
   Print("Gotobi morning, fixing at ", TimeToString(JpJstToServer(JpTokyoFixing(jst))), " server time");

尚未过去的下一次 gotobi 日定盘：

datetime jst = JpNowJst();
datetime g   = JpNextGotobi(jst);                // today counts all day
if(g != 0 && JpTokyoFixing(g) < jst)             // today's fixing has passed
   g = JpNextGotobi(g + 86400);
Print("Next gotobi fixing: ", TimeToString(JpJstToServer(JpTokyoFixing(g))), " server time");

某个月的 gotobi 日：

datetime days[];                                 // must be a dynamic array
int n = JpGotobiDaysOfMonth(2027, 5, days);      // 5 days: 10, 14, 20, 25 and 31
for(int i = 0; i < n; i++)
   Print(TimeToString(days[i], TIME_DATE));

时区和策略测试器

• 服务器时间不是日本时间：在上面的演示中，服务器显示 10 月 13 日 21:43，而日本已是 10 月 14 日 03:43。在查询某一天之前，请先用 JpServerToJst() 换算，或者使用 JpNowJst()。
• 默认时差为自动：在 MT5 上为 TimeTradeServer() - TimeGMT()，按 15 分钟取整，并在每次调用时重新读取。终端刚启动后的几秒钟内，它可能读到 0。
• MT4 没有 TimeTradeServer()，因此使用 TimeCurrent()，即最后一笔报价的时间；在刚启动后或休市期间，它可能不正确。在 MT4 上，请自己设置时差。
• 在策略测试器中，TimeGMT() 返回服务器时间，因此自动时差为 0。本库会在测试器日志中写入一次提示。请在 OnInit() 中设置时差。
• 自动时差是当前的时差。对于跨越夏令时切换的历史K线，请用 JpSetServerTimeZone() 设置服务器的规则。
• 设置只对调用它的程序有效：请在每个 EA 或指标的 OnInit() 中调用。

input int ServerGmtWinter = 2;   // server GMT offset outside summer time, in hours
input int ServerDstRule   = 1;   // summer time rule: 0 none, 1 US, 2 EU

int OnInit()
  {
   if(!JpSetServerTimeZone(ServerGmtWinter * 3600, ServerDstRule))
      return(INIT_PARAMETERS_INCORRECT);         // the library printed the reason
   return(INIT_SUCCEEDED);
  }

美国规则：3 月的第二个周日至 11 月的第一个周日（2007 年之前采用较早的美国日期）。欧洲规则：3 月的最后一个周日至 10 月的最后一个周日（1996 年之前结束于 9 月的最后一个周日）。冬季为 GMT+2、美国夏令时期间为 GMT+3 的服务器，应设为 7200 和规则 1。演示脚本会显示您的服务器当前的时差；您的经纪商可以告诉您它采用哪种夏令时。如果想在 MT5 上保持自动时差实时有效，请像示例 EA 那样，只在 MQLInfoInteger(MQL_TESTER) 为 true 时调用设置函数。

所用规则及其核对方式

• 日本《国民节假日法》及其修订：固定日期的节日；周一节日，即成人节和体育节自 2000 年起、海之日和敬老日自 2003 年起；自 2016 年起的山之日；按年号划分的天皇诞辰；以及 2020 年和 2021 年调整的日期。
• 调休假日：国民节日恰逢周日时，其后第一个不是国民节日的日子放假（2007 年起；此前仅限次日）。
• 国民休息日：夹在两个国民节日之间的日子（1986 年起），例如 2026 年 9 月 22 日。
• 一次性节日：1989-02-24、1990-11-12、1993-06-09、2019-05-01 和 2019-10-22。
• 春分日和秋分日：使用适用于 1980-2099 年的标准近似公式。日本政府在前一年的 2 月公布每个春分日和秋分日。
• 银行休息日：周六、周日、国民节假日以及 12 月 31 日至 1 月 3 日（《银行法》）；所有年份都采用现行规则。
• gotobi 日：如果 5 日需要提前到上个月，那一天本身已是上个月的月末 gotobi 日，因此只在上个月列出。所以 2027 年 5 月有 5 个 gotobi 日。
• 以上是制作 1.00 版时（2026 年 10 月）施行的规则。

发布前的核对：两个版本编译时都是 0 个错误、0 个警告；MT4 版由同一份源代码生成（只有时间函数不同）。1980 年至 2027 年的全部 789 个国民节假日都与日本内阁府的列表逐日一致；该列表目前截至 2027 年。春分和秋分的公式在 2027 年之前的每一年都给出官方日期，并且在 2099 年之前的每一年都与天文计算结果一致。从市场路径导入的方式在策略测试器中也能加载。

开发者常问的问题

• 我的程序因与函数库有关的错误而停止。请确认本库已安装，并且 #import 这一行与文件名完全一致。MT4 版的文件名以 MT4 结尾。
• 到了晚上，日本日期差了一天。您传入的是服务器时间。请先用 JpServerToJst() 换算。
• JpGotobiDaysOfMonth() 返回 -1。请传入动态数组（ datetime days[]; ）、1980 至 2099 之间的年份以及 1 至 12 之间的月份。
• 在 OnTick() 中使用够快吗？够快。结果按年缓存。缓存保留 2 年，因此在许多年份之间来回跳转的循环会比较慢。

产品页面：Japan Bank Holiday and Gotobi Library（MT5）和 Japan Bank Holiday and Gotobi Library MT4。如有任何不清楚之处，请在 MQL5 上给我发送私信，并附上您使用的代码以及“智能交易”（Experts）选项卡中的最后几行。