模块:RailSystems/doc

本页使用了标题或全文手工转换,现处于中国大陆简体模式
求闻百科,共笔求闻

RailSystems模块可用于处理、访问轨道交通线路系统,并允许进行面向对象使用,支持管理线路连接、标志色、车站的页面名称和显示名称等数据。许多其他模块和模板都使用了本模块。

本模块共提供3个可用于面向对象的类:系统(System)、线路(Line)和车站(Station)。

数据存储

本模块的各个子页面存储各轨道交通系统的数据,详见Special:前缀索引/Module:RailSystems/。例如,Module:RailSystems/SHMetro存储上海轨道交通系统的数据,访问与上海轨道交通有关的数据时就会使用此页面的数据,Module:RailSystems/SuzhouRT则是存储的苏州轨道交通的数据。

子页面的数据都是通过mw.loadData加载的,因此有一些限制,可以指定override参数表示另一个模块的名称,将加载该模块以调整数据的行为。

为确保兼容性,本模块会尝试加载Module:Adjacent stations的子页面,并尽可能地转换为RailSystems的格式。请注意这种转换是有限的。建议有能力的用户直接创建对应的RailSystems子页面的版本,Adjacent stations的子模块将被逐渐弃用。

数据格式

本模块的子页面均为记录各个轨道交通线网的表,遵从#System的数据格式。这些表均通过mw.loadData加载,因此不能存有任何的函数。下列列表列举出了表中可以拥有的各个字段及其说明,加粗内容为字段名称(也就是键)。

System的数据格式

  • name:可选字符串。该线网系统的名称,如“苏州轨道交通”。
  • icon:字符串或表。若为字符串,则为图标文件名称。
  • icon:字符串或表。若为表,表示轨道交通系统的图标。
    • file:轨道交通系统的图标文件名称、
    • size:图标的默认大小。
    • link:图标的默认链接,可以是空字符串。
    • alt:图标的替换文字。
  • line_index:表。该线网系统的线路ID的索引。
    • 准则名称:由线路ID组成的数组。准则名称可以是all、open等,也可以是自定义的准则名称,如tram(表示列举所有的有轨电车线路)。
      之所以使用line_index,是因为线路在lines字段中是以表的形式存在的,且迭代顺序不确定。此外,还存在一个线路数据对应多个键的情况。
  • lines:表。该线网系统的所有线路。
  • stationNames:表。指定一些特殊的车站的显示名称和页面名称。将影响该轨道交通系统中的所有车站。该字段的值的各个字段都有两种写法:
    • 车站ID:字符串。键为车站ID,值的格式为“页面名称|线路名称”。如果其值含有链接的话,那么获取该车站的ID时,直接返回这个整个字符串。
    • 车站ID:表。键为车站ID,值的格式如下:
      • page:字符串。该车站对应的页面名称。可能为nil,表示该车站没有对应页面,生成链接时将产生纯文本。
      • name:字符串。该车站的显示名称。
      • link:可选字符串,一般不建议使用,表示该车站的链接。
  • override:可选字符串。指定一个模块名称,加载该系统时,将导入(require)此模块,并根据该模块的内容覆盖默认的行为,通常不需要使用。
  • stationFormat:可选字符串。表示各站对应页面名称的默认格式。默认为“%s站”。
  • plain_link_template:已经弃用,不再有用

Line的数据格式

  • short_name:字符串。线路的短名称,如“1号线”。
  • full_name:字符串,可选。线路的长名称,如“上海轨道交通1号线”。
  • name:字符串,可选。线路的通用名称,一般和短名称一致。
  • page:字符串,可选。该线路的页面名称。若不存在且不等于false,则取线路的完整名称,若仍不存在,则取线路的通用名称。若为false,则表示指定该线路没有页面名称,不产生链接。
  • link:字符串,可选且不建议。若存在,则获取线路链接(line:getLink())时,强制使用此值,忽略nameType和isStyled参数,因此不建议使用。
  • title:字符串。已弃用。一个形如“页面名称|线路名称”的字符串。
  • color:字符串。线路的十六进制颜色(不带井号)。
  • textColor:字符串。当文字显示在以线路颜色为底色的环境下时,文字应当显示的颜色。默认为白色,但对于部分线路应当设为黑色。
  • icon:字符串或表。与#System的数据格式中的icon相同。
  • stations:数组。该线路的车站列表。可选,但如果不存在,部分功能将受到限制。
  • terminus:数组。格式和用法同stations,用来表示终点站。调用Line:getTerminalStation时,如果该字段存在则根据该字段获取终点站,否则根据stations的值来推断终点站。
  • notOpen:布尔值,表示线路是否未开通。我们约定这里的开通是指的施工状态的开通,通常,受疫情、天气等因素临时影响运营的,不在此字段考虑范围内。若为true,表示线路未开通,此时该线路的所有车站(包括与已开通车站的换乘站)都是未开通的。
  • planning:布尔值,表示线路是否仍在规划中。若为true,则该线路的所有车站都是规划中的。
  • terminals:表。已弃用,表示线路的终点站。
    • left:表。
    • right:表。
  • isLoop:布尔值,表示是否为环线。如果为环线,则首尾两站也可以视为邻站。
  • trainTime:表。已弃用。
    • leftright字符串。已弃用。列车时间,格式为hh:mm:ss的格式。
  • openDates:表。已弃用。

Station的数据格式

在数据中,可以直接使用字符串表示一个简单车站,不为该车站指定特殊属性,其车站ID即为该字符串的值。尝试生成车站链接时,会尝试根据车站的ID从系统数据的stationNames参数中查找命名规则。如果表示一个带有特殊情况的车站(比如一条已开通的线路的多个车站中,有一个没有开通),或者一个抽象车站(将一条子线,或者线路的主线支线部分抽象为一个车站),则使用表,这种情况下表的格式如下:

  • id:字符串。车站的id。通常与车站名称一致。有时候不同的车站会有相同的名称(例如上海轨道交通4号线和6号线的浦电路是不同的车站),此时车站的id应当不同。
  • type:字符串,可选。表示车站的类型。"branches"表示该车站是由线路的主线和支线抽象而成的车站。"adjacent_branches"表示某站在主线和支线上的两个相邻车站构成的一个抽象车站(通常在轨道交通系统数据中不会使用)。"line"表示将一个子线路,将该线路抽象为车站,当有一段连续的车站未开通时,可以将这些车站放在一个子线路中,并将这个子线路的notOpen设为true。
  • notOpen:表示该车站是否暂未开通。若车站属于一个未开通的线路,则认为该线路中的所有车站是未开通的,不再需要为各车站设置notOpen的值。
  • planning:表示该车站是否还在规划中。若车站属于一个规划中的线路,则认为该线路中的所有车站都在规划中,不再需要为各车站设置planning的值。
  • icon:字符串或表。与#System的数据格式中的icon相同。
  • main:表,可选。若type为branches或adjacent_branches,则该值为一条线路数据,参见#Line的数据格式
  • branch:表,可选。若type为branches或adjacent_branches,则该值为一条线路数据,参见#Line的数据格式
  • line:表,可选。若type为line,则该值为一条线路数据,参见#Line的数据格式

System

System类表示一个轨道交通系统。每个轨道交通系统都有其data字段,其值为一个表(可以是mw.loadData返回的只读表)。

下面的所有例子中,system均表示一个System对象(注意大小写)。

System.of

System.of(data, override)

根据轨道交通系统的数据,生成一个System对象。通常只是用于内部使用,一般情况下请使用System.load。

data
该轨道交通系统的数据,是一个表,可以是mw.loadData返回的只读表。
override
值为函数组成的表,用来覆盖其自身及其返回的线路、车站对象的默认行为。一般不需要使用。

System.load

System.load(name)

从本模块的子页面(Module:RailSystems/name)中加载数据,根据加载的数据来返回一个System对象。例如,System.load 'SHMetro'就会加载Module:RailSystems/SHMetro的数据,并根据这些数据,返回一个表示上海轨道交通的线网系统对象。

如果Module:RailSystems/name不存在,则会尝试加载Module:Adjacent stations/name,并将其转换为本模块格式的数据。这种转换是有限的,这样做只是为了与Module:Adjacent stations保持兼容,并不建议这么做。

如果对应的数据不存在,则会抛出错误。如果name为nil,则返回nil,不抛出错误。

system:getIcon

system:getIcon(params)

返回该系统的图标。参数params是一个表,可以为nil。如果params是一个表,则可以拥有如下字段:

  • size:图标的大小,如果未指定,则取线路数据中的icon字段定义的图标大小。
  • link:图标的链接,如果未指定,则取线路数据中的icon字段定义的图标链接。可以是空字符串,表示没有链接。

注意:图标文件是由线路数据中的icon字段指定的,无法通过params参数指定。

system:getLines

system:getLines(criterion, condition)

获取该线网中的所有线路,返回由线路对象组成的数组。

criterion
一个指定线网列表的准则。通常可用的值由数据中的line_index字段决定。以上海轨道交通为例,Module:RailSystems/SHMetro中的line_index有all、tram、metro等字段,其中metro字段的值为{'1', '2', '3', ..., '26', '磁', '浦', '崇'},因此System.load 'SHMetro':getLines 'metro'将会返回由1号线至26号线以及磁浮线、浦江线、崇明线组成的数组。
如果线路数据没有line_index字段,则该函数会产生错误。
该参数的默认值为'all'。
condition
该线路需要符合的条件。默认为nil,即不需要满足任何条件。参见#line:meets

system:getLine

system:getLine(key)

返回该线网中的线路对象。key的值为线网数据中的lines字段的键。如果线路不存在,则返回nil。

调用此函数不需要线路数据中有line_index字段。

system:getLineOrThrow

system:getLineOrThrow(key)

返回该线网中的线路对象。如果线路不存在,则抛出异常。

system:getLineOrAnonymous

system:getLineOrAnonymous(key)

返回该线网中的线路对象。如果线路不存在,则返回仅使用该id的线路。

system:getStation

system:getStation(id)

根据指定的车站id,返回一个Station对象。

由于这种方法并未指定车站所属的线路,因此车站对象不会受到任何线路数据的影响,但是,该Station对象仍有可能受到系统数据中的stationNames字段影响。

该方法并不要求系统中确实存在这个id的车站,如果是一个不存在的车站,仍能正常返回结果。

Line

Line表示一条轨道交通线路。system:getLine(key)可用从线网系统中获得一个线路对象。

下面所有的例子中,line均表示一个Line对象。

Line.of

Line.of(data, system)

根据指定的线路数据和所属的系统,返回一个线路对象。通常用于内部使用。

line:getIcon

line:getIcon(params)

根据线路数据中的icon字段,返回线路的图标。如果该线路的图标不存在(大多数情况都是如此),则直接使用系统的图标。

line:getName

line:getName(nameType, isStyled)

返回线路的名称。nameType参数决定你是要获取该线路的完整名称、长名称、短名称还是简写名称。例如,

local line4 = System.load 'SHMetro':getLine '4'
print (line4:getName 'short')  -- '4号线'
print (line4:getName 'full')  -- '上海轨道交通4号线'
print (line4:getName 'blink')  -- '4'

根据线路数据,线路名称会依次尝试根据data.<nameType>_namedata.namedata.short_namedata.title决定。

isStyled视为布尔值,如果为true,则如果该线路未开通,就会显示为灰色,如果线路仍在规划中,则会显示为斜体(这两种情况可能会叠加)。

line:getStyledName

line:getStyledName(nameType)

相当于line:getName(nameType, true)

line:getColor

line:getColor(prefixed)

返回该线路的标志色。prefixed参数会在线路标志色前面加个井号,这样可以直接用于CSS。

local line = System.load 'SHMetro':getLine '4'
print (line:getColor())  -- '4F1F91'
print (line:getColor(true))  -- '#4F1F91'

如果线路没有指定标志色,则会返回nil。

line:getPage

line:getPage()

返回该线路对应的页面的名称。可能为nil。

会依次尝试根据线路数据的data.pagedata.titledata.full_namedata.name决定。其中,若由data.title决定,则取管道符之前的部分。

line:getLink

line:getLink(nameType, rich, isStyled)

返回一个该线路的维基链接。nameTypeisStyled参数请见#line:getName

local line4 = System.load 'SHMetro':getLine '4'
print (line:getLink())  -- '[[上海轨道交通4号线|4号线]]'
print (line:getLink(nil, true))  -- '[[上海轨道交通4号线|<span style="color:#4F1F91">■</span> 4号线]]''

如果nameType为"blink",那么会根据data.textColor决定文字颜色。

line:getRichLink

line:getRichLink(nameType, isStyled)

相当于line:getLink(nameType, true, isStyled)

line:getAdjacentStations

line:getAdjacentStations(station_id, condition)

返回该线路车站的指定条件的相邻车站。如果该线路数据没有stations字段,该函数会抛出错误。

如果该线路找到了id为station_id的车站,则会返回像{left = 左侧邻站对象, right = 右侧邻站对象}这样的表。如果没有符合指定条件的邻站(比如该车站是线路的终点站),则该侧相邻车站对象为nil。如果线路位于支线交汇处导致某个方向的邻站不止一个(例如龙溪路站),则这种情况下,相邻车站对象可以将多个车站看成一个抽象车站对象。

如果该线路没有找到id为station_id的车站,则返回nil(不是空表)。

condition的值请参考#station:meets

line:getStation

line:getStation(id, condition)

返回该线路中id为指定的id的车站。如果该线路不存在该车站,则返回nil;如果存在车站但不符合指定的条件(condition),也会返回nil。

如果该线路数据的车站列表(stations字段)中存在由线路组成的抽象车站(type为"line"或"branches"),则会尝试在该抽象车站中包含的车站中查找。

如果线路数据没有stations字段,则直接返回nil。

line:getSubline

line:getSubline(line)

该方法主要用于模块内部。line是另一个车站对象。

line:listStations

line:listStations(condition)

返回由该线路中的所有车站组成的数组。condition参数参见#station:meets

如果线路数据中没有stations字段,则无法列举出所有车站,将抛出错误。

line:getTerminalStation

line:getTerminalStation(direction, type, condition)

返回该线路指定方向的终点站的Station对象。direction可以是'left'或'right',如果为'both',则会返回像{left = 左侧终点站对象, right = 右侧终点站对象}这样的表。

type参数主要用于主线与支线。其值可以为'left'或'right',若为'both',则会返回像{main = 主线终点站对象, branch = 支线终点站对象}这样的表。

该方法会根据线路数据中的terminus字段或stations字段推断终点站。如果上述字段均不存在,则该方法返回nil。

line:renderStationList

line:renderStationList {isStyled = isStyled, showInterchange = showInterchange, condition = condition, interchangeCondition = interchangeCondition, stationCondition = stationCondition}

返回该线路所有车站链接字符串组成的列表。所有参数均可选。其中interchangeCondition和stationCondition参数若未指定,则使用condition参数。请参见#line:meets#station:meets

如果线路数据的stations字段不存在,则抛出错误。如果stations字段中有类型为"branches"的抽象车站,则这个抽象车站只会显示为“主线/支线”。

line:meets

line:meets(condition)

返回该线路是否满足指定的条件。condition可以是字符串、表或函数。

  • 若condition为字符串,则其值可以是'not_open'、'open'或'planning'。
  • 若condition为表,则其数据必须与该表匹配。
  • 若condition为函数,则返回condition(line)的值。

Station

Station对象通常是通过对线路对象调用getStationlistStations方法获得的。

下面的例子中,station均表示一个Station对象。

Station.of

Station.of(data, line, system)

根据指定的数据、线路和系统,构造一个Station对象。

参数line表示该车站是位于指定线路的车站。参数system表示该车站是位于指定系统的车站,若line参数存在,则默认为line.system。

line参数意义在于,如果该线路未开通(线路数据指定了未开通,但是车站自身数据未指定是否未开通),则一定认为该车站是未开通的。

system参数意义在于,获取名称和页面时受到该系统数据stationNames影响。

该函数主要由模块内部使用。

station:getIcon

station:getIcon(params)

返回该车站的图标,由该车站数据的icon字段决定。如果不存在,则尝试获取线路或系统的图标,如果扔不存在,则返回nil。

station:meets

station:meets(condition)

返回该线路是否满足指定的条件。condition可以是字符串、表或函数。

  • 若condition为字符串,则其值可以是'not_open'、'open'或'planning'。注意:车站是否未开通或处于规划中,由该车站对象自身的数据和车站对象对应的线路对象(若有)的数据共同决定。例如,对于指定了线路的车站对象,如果该线路未开通,则认为车站一定未开通(包括与已开通线路的换乘站)。
  • 若condition为表,则其数据必须与该表匹配。
  • 若condition为函数,则返回condition(line)的值。

station:getName

station:getName(isStyled, notShort)

返回车站名称。

参数说明:

isStyled
布尔值。若为true,则未开通的车站会显示为灰色,规划中的车站显示为斜体,与已开通线路的换乘站显示为粗体。
notShort
布尔值。若为true,则车站名称结尾加上“站”字。这种情况下会根据页面名称推断站名,一般不建议这样做。若为false,则一般与车站id相同。

station:getStyledName

station:getStyledName(notShort)

等同于station:getName(true, notShort)

station:getPage

station:getPage()

返回该车站的页面名称。页面名称通常由该对象所属的System对象的数据中的stationNames对象指定。

local SHMetro = System.load 'SHMetro'
print(SHMetro:getStation '人民广场':getPage())  -- '人民广场站 (上海市)'
print(SHMetro:getStation '浦电路4':getPage())  -- '浦电路站 (4号线)'

若该车站为抽象车站,则会抛出错误。

station:getLink

station:getLink(isStyled, notShort)

返回该车站的维基链接。参见#station:getName#station:getPage。同样也会受到系统数据(若有)中的stationNames字段影响。

station:getLines

station:getLines(criterion, condition, avoid)

获取该车站在线网中所属的线路组成的数组。例如,在上海轨道交通中,真如站是11号线与14号线的换乘站:

local SHMetro = System.load 'SHMetro'
local Zhenru = SHMetro:getStation '真如'
mw.logObject(
Zhenru:getLines()  -- 其值大致相当于 {SHMetro:getLine '11', SHMetro:getLine '14'}
)

criterioncondition参数与#system:getLines中的参数类似。

avoid参数是字符串,用于在结果中回避该车站对象自身所属的线路。前提是该车站对象必须指定了所属的线路。例如:

local SHMetro = System.load 'SHMetro'
local L11Zhenru SHMetro:getLine '11':getStation '真如'
mw.logObject(
Zhenru:getLines()  -- 其值大致相当于 {SHMetro:getLine '11', SHMetro:getLine '14'}
Zhenru:getLines(nil, nil, true)  -- 其值大致相当于 {SHMetro:getLine '14'}

通过invoke调用

本模块除了可以由Lua使用之外,也可以直接通过维基文本来使用。

stationLink

返回车站链接。其中name参数与station_id参数等价。

  • 模板链接:{{#invoke:RailSystems|stationLink|name=真如|system=SHMetro}}
  • 模板链接:{{#invoke:RailSystems|stationLink|name=盘蠡路|system=SuzhouRT}}
  • 模板链接:{{#invoke:RailSystems|stationLink|name=浦电路4|system=SHMetro}}
  • 模板链接:{{#invoke:RailSystems|stationLink|name=浦电路4|short=false|system=SHMetro}}

参数styled可用于将未开通或者计划中的车站添加特殊的样式。

lineColor

返回线路颜色。

  • 模板链接:{{#invoke:RailSystems|lineColor|line=1|system=SHMetro}}
    • 效果:EA0437
  • 模板链接:{{#invoke:RailSystems|lineColor|line=1|prefixed=1|system=SHMetro}}
    • 效果:
  1. EA0437
  • 模板链接:{{#invoke:RailSystems|lineColor|default=ffffff|line=114514|system=SHMetro}}
    • 效果:ffffff

lineLink

返回线路链接。如果optional为true,那么当线路id不存在时,返回空白字符串,否则抛出错误(下同)。

  • 模板链接:{{#invoke:RailSystems|lineLink|line=1|system=SHMetro}}
  • 模板链接:{{#invoke:RailSystems|lineLink|line=114514|optional=true|system=SHMetro}}
    • 效果:
  • 模板链接:{{#invoke:RailSystems|lineLink|line=1|rich=1|system=SHMetro}}
  • 模板链接:{{#invoke:RailSystems|lineLink|line=1|style=full|system=SHMetro}}

参数styled可用于将未开通或者计划中的线路添加特殊的样式。

lineName

返回线路名称,name_type参数与style参数等价。

linePage

返回线路对应的页面名称。

lineRichLink

与lineLink类似,但rich始终为true。参数styled可用于将未开通或者计划中的线路添加特殊的样式。

lineStationList

显示车站列表,其中name参数与line_id参数等价。

参数styled可用于将未开通或者计划中的车站添加特殊的样式。

lineTerminalLink

返回该车站的终点站链接。

  • 模板链接:{{#invoke:RailSystems|lineTerminalLink|direction=left|line=2|system=SHMetro}}
  • 模板链接:{{#invoke:RailSystems|lineTerminalLink|condition=open|direction=left|line=2|system=SHMetro}}
  • 模板链接:{{#invoke:RailSystems|lineTerminalLink|direction=left|line=11|system=SHMetro}}
  • 模板链接:{{#invoke:RailSystems|lineTerminalLink|direction=left|line=10|system=SHMetro}}

参数styled可用于将未开通或者计划中的车站添加特殊的样式。

lineTerminalName

返回该车站的终点站名称(一般不带链接)。

  • 模板链接:{{#invoke:RailSystems|lineTerminalName|direction=left|line=2|system=SHMetro}}
    • 徐泾东
  • 模板链接:{{#invoke:RailSystems|lineTerminalName|condition=open|direction=left|line=2|system=SHMetro}}
    • 徐泾东
  • 模板链接:{{#invoke:RailSystems|lineTerminalName|direction=left|line=11|system=SHMetro}}
    • 嘉定北/花桥
  • 模板链接:{{#invoke:RailSystems|lineTerminalName|direction=left|line=10|system=SHMetro}}
    • 虹桥火车站/航中路

测试

  1. 测试成功,结果:[[宁波站|宁波站]]
  2. 测试成功,结果:[[宁波站|宁波站]]
  3. 测试成功,结果:[[高桥西站(宁波)|高桥西]]
  4. 测试成功,结果:[[高桥西站(宁波)|高桥西站]]
  5. 测试成功,结果:[[泽民站|泽民]]
  6. 结果[[内嵌模板站|内嵌{{!}}模板]]不符合预期[[内嵌模板站|内嵌|模板]]
  7. 测试成功,结果:3180b7
  8. 测试成功,结果:#3180b7
  9. 测试成功,结果:[[宁波轨道交通1号线|1号线]]
  10. 测试成功,结果:[[西铁线|西铁线]]
  11. 测试成功,结果:[[宁波东站|宁波东站]]
  12. 测试成功,结果:高桥西
  13. 测试成功,结果:宁波站
  14. 测试成功,结果:宁波东站
  15. 测试成功,结果:余姚
  16. 测试成功,结果:马渚
  17. 测试成功,结果:杭州湾
  18. 测试成功,结果:22:06
  19. 测试成功,结果:06:08
  20. 测试成功,结果:往[[高桥西站(宁波)|高桥西]]方向:22:06
  21. 测试成功,结果:往[[霞浦站(宁波)|霞浦]]方向:06:08
  22. 测试成功,结果:06:07-22:08
  23. 测试成功,结果:06:07-22:10
  24. 测试成功,结果:在2016年的3月的19日,月份2016年3月,日期2016年3月19日开通
  25. 结果[[Category:需要去除时间判断模板的页面]]不符合预期2016年
  26. 测试成功,结果:[[Category:需要去除时间判断模板的页面]]
  27. 结果[[Category:需要去除时间判断模板的页面]]不符合预期2016年3月
  28. 测试成功,结果:[[Category:需要去除时间判断模板的页面]]
  29. 测试成功,结果:2016年3月19日
  30. 测试成功,结果:[[Category:需要去除时间判断模板的页面]]
  31. 测试成功,结果:2019年12月28日
  32. 测试成功,结果:二期规划中
  33. 测试成功,结果:规划中
  34. 函数调用出错:attempt to call a nil value,预期为1号线从[[高桥西站(宁波)|高桥西]] |到[[霞浦站(宁波)|霞浦]]
  35. 函数调用出错:attempt to call a nil value,预期为1号线从[[高桥西站(宁波)|高桥西站]] |到[[霞浦站(宁波)|霞浦站]]

测试完成,共成功30次,失败5次。