說明:簡易時間線語法

維基百科,自由的百科全書
維基百科使用手冊

簡易時間線的特性就是從wiki文本中產生一個嵌入式圖像。這個圖像可以是一維的圖表(水平或垂直),或者是二維的圖表。名為「簡易時間線」即表示可以用水平或垂直的方向作為時間刻度,用另一個方向來表示其它參數,但也可能是其他不同的形式。簡易時間線的語法並不支持簡繁轉換

參見簡易時間線簡易時間線索引

簡介

只要腳本介於兩個專用標籤之間就可以產生圖像時間線:

<timeline>
腳本
</timeline>

簡易時間線就會被調用生成一個PNG格式圖像和一個連結映射(可選項)。

注意:即使「簡易時間線」的創造是為了簡單方便,但是製作一個複雜的時間線表依然不是一件輕鬆的事情。一個簡單的時間線可以花費半個小時來完成(如果有一個合適的例子用來作為基礎可以節省更多時間)大型的時間線可能要花費幾個小時來創作並且修改。然而,對於現有無論多複雜的時間線進行增加或者更正都是直接快捷的,甚至是對於沒有接觸過這些語法的使用者。

若有問題請聯絡簡易時間線的作者

可支持字型

Unicode有少許支援,現在只可以使用FreeSans.ttf字型。此字型目前還不支援其它字型。(效果如下)

建議使用預定義的五種字號:XS=超小、S=小(默認)、M=中、L=大、XL=超大。

This documentation is originally a wikified version of the original EasyTimeline documentation.

可用命令

腳本命令定義:

下述命令是必選的:ImageSize(圖像尺寸)、PlotArea(圖形區)、Period(時段)和TimeAxis(時間軸)。下述命令至少要選一個:PlotData(圖形數據)和/或 TextData(文字數據),它們都可以重複多次。所有其它命令都是可選的。

大小寫:命令及其屬性都能接受大寫、小寫以及混合拼寫。請在使用時保持一致以利於維持可讀性,例如對於命令使用混合拼寫,而所有屬性使用小寫。

一般語法規則

腳本可包含命令和註釋。每個命令都有一個或多個屬性。

命令

命令應該從行首開始。 有些命令帶有多行的數據和/或選項。 這些另外的行應該以至少一個空格或完整的空行開始。(下面示範相關的數據行)

根據命令的類型,它可表示為以下的多種形式之一:

命令 = 屬性(或多個屬性)

DateFormat = dd/mm/yyyy

命令 名字 = 屬性(或多個屬性)

Color Jp = value:red legend:Japan

命令 =
  屬性(或多個屬性)
  屬性(或多個屬性)
  等等……

PlotData =
  fontsize:XS width:20
  bar:Japan from:start till:19/02/1945 color:JT
  bar:Japan from:19/02/1945 till:14/03/1945 color:AI

註釋

可用單行和多行註釋:

  • # 號後文字就是一行註釋
  • 介於#><#之間的文字也是註釋。用這種方式標記,可使用多行來書寫註釋。

例如:

Dateformat = dd/mm/yyyy # European date format
Period = from:01/09/1939 till:02/09/1945 #> 该图表将表现二战的
  整个历史。 <#

屬性

當有許多屬性指定到同一個命令時,它們可以用成對的 '名稱:數值'來表示。 當有許多數值指定到同一個屬性時,它們必須放入圓括號中。

例如:

AlignBars = justify
Color SB = value:rgb(0.8,0,0.7) legend:Sea_Battles

參數和數據項

大部分命令只接受在同一行指定的屬性。

數據塊: 有一些命令、像是BarDataPlotDataTextDataColors認為一個數據塊是由一個或多個數據行組成。數據行應該以一個或多個空格開始,遇到以非空字符開始的行就認為數據塊已結束(例外:應忽略空行,它們可能用來對同一個塊中相關的數據行進行分組)。

數據塊內的屬性按照概念可分成參數數據項。數據塊可同時包含參數和數據項。

數據項:在數據行屬性中,textfromtillat僅在它們所出現的行起作用。

參數:在數據行屬性中,像是colorfontsize,根據上下文的不同會有不同的含義。如果它們出現在沒有數據項的行中,它們將為後面的數據行設定新的默認屬性。如果它們出現的行中同時也有數據項,那麼它們只能在此行起作用,取代前面設定的默認屬性。

例如:

# 在该例子中将分别画出红蓝两条系列,
# 但在每一系列中将有一段使用绿色描绘以标示战争时期。

PlotData =
  color:red fontsize:S                               # 默认值
  bar:USSR from:1919 till:1922 text:Lenin            # 红条
  bar:USSR from:1922 till:1953 text:Stalin           # 红条
  bar:USSR from:1939 till:1945 text:WWII color:green # 绿条
  bar:USSR from:1953 till:1964 text:Krushchev        # 红条
   
  color:blue                                         # 改变默认颜色
  bar:US from:1913 till:1921 text:Wilson             # 蓝条
  bar:US from:1917 till:1918 text:WWI color:green    # 绿条
  bar:US from:1921 till:1923 text:Harding            # 蓝条

#> 此多行注释并不终止PlotData命令,
   即使前一行并未以空格开头。<#

   bar:US from:1923 till:1929 text:Coolidge          # 蓝条

TextData =                                           # 此处PlotData命令结束
   tabs:...etc

特殊字符

  • ##><#(井號、井號+大於號、小於號+井號):參見Comments
  • ~(波浪線)在文字中:換行
  • ^在文字中:縮進
  • _(下劃線)在文字中:空格
  • $(美元符號)用在任何用戶自定義常量前

命令參考

每一個命令都列出了有效的屬性,一些命令或屬性是可選的[表示為(可選)]。

一些命令的某些屬性是互斥的。(應用時再解釋)

AlignBars

條塊(Bar)總是以相同的距離繪製。 這個命令用來說明是否條塊應該排列得儘可能分開,或者保留空白在圖表的左(或上)邊與第一條之間,還是保留空白在圖表的右(或下)邊與最後一欄之間。

early(默認)
第一條放置在圖表最左(或最上)的位置('粘貼'到軸上),在最後一條與圖表的右(或下)邊之間留出空白。
late
early相反,最後一條儘可能地放置在圖表的右(或下)邊,在軸線(圖表的左/上邊)與第一條之間留出空白。
justify
第一條和最後一條放置得儘可能分開,圖表的兩邊都不留空白。當只有一條存在時,justify就表示"居中"。

例如:

TimeAxis = orientation:horizontal orientation:vertical

Alignbars =

BackgroundColors

這個命令允許指定圖表不同部分的背景顏色。 任何顏色id的指定在首次使用時都應該先進行定義Colors.

canvas (可選)
為全部圖像指定背景顏色。
bars (可選)
為所有bars指定背景顏色。

例如:

BackgroundColors = bars:darkgrey

BackgroundColors = canvas:lightgrey bars:darkgrey

BackgroundColors = canvas:lightgrey

BarData

這是一個可選命令,它可以調整哪些條塊將被顯示、以何種順序顯示。如果它被省略,欄將按照它在PlotData命令中的出現的順序進行繪製。

對於使用許多條的複合時間線,推薦使用這個命令:

  • 這將簡化對顯示數據的重新佈置;
  • PlotData中指定的條塊名字將和此列表比對,從而減少輸入錯誤的可能。
bar
定義了條塊的識別號,其他的命令(特別是PlotData)將使用該識別作為對其之引用。它也是坐標軸上顯示的標籤,除非設置了text屬性。bar識別號不可包含空格:使用下劃線代替,它們將被自動轉換為空格。
text (可選)
指定顯示於坐標軸上的標籤,以取代條塊識別號。參見text input。該文本可以包含一個內部連結(參見註釋1)。
link (可選)
指定一個連結(URL)。參見註釋1。坐標軸上的標籤即顯示為一個超連結。

註釋

  1. 要麼使用link屬性、要麼在text屬性中使用內部連結,二者不能並用。

示例

BarData =
  bar:Japan
  bar:US       text:"美国"          # 将PlotData数据定位到条块“US”但显示为“美国”
  bar:China    text:[[中国]]        # “中国”标签将指向维基百科中的中国条目

以下代碼產生同樣的輸出(只列出PlotData的改變):

bar:US        text:[[United_States]]

bar:US        text:"United States"     link:http://www.wikipedia.org/wiki/United_States

bar:United_States                      link:http://www.wikipedia.org/wiki/United_States

Colors

這個命令可用來定義顏色並用一個id(身份識別)來表示。 其它命令將用在這裏指定的id來調用顏色。 這個命令可指定一個或多個的顏色定義,每一個都必須位於獨立的縮進行。

id
其它命令將使用這個id來指定文本、欄或背景的顏色。
value
實際顏色定義。顏色值可用下述任一種方式表示:
  • 預定義顏色值,有32種預定義的顏色名稱是公認的(參見Ploticus color page,在這裏定義了這些顏色值)。
  • rgb (紅,綠,藍): 指定3個介於0(最小)和1(最大)之間的數字
  • hsv (色調,飽和度,值): 指定3個介於0和1之間的數字
  • gray (值): 指定一個介於0 (黑) 和 1 (白)
legend (可選)
指定圖例中對於使用該種顏色的項目的文字說明,如果該屬性被忽略,圖例中則不顯示任何文本。參見Text Input以獲得詳細規則。

Example:

Colors =
  id:war       value:red   legend:War Period
  id:peace     value:blue  legend:Peace Time
  id:treaty    value:rgb(0.6,0,0.6)
  id:lightgrey value:gray(0.9)
  id:darkgrey  value:gray(0.1)

DateFormat

這個命令定義了在其它命令中出現的日期應該如何解釋。

有效的日期格式:

dd/mm/yyyy
日期解釋為 日/月/年
注意: 這種格式只允許用於01/01/1800以後的日期
mm/dd/yyyy
日期解釋為 月/日/年
注意: 這種格式只允許用於01/01/1800以後的日期
yyyy
這種格式使用從 -9999 到 +9999的整數

例如:

DateFormat = mm/dd/yyy

Define

這一個命令允許定義本文常數,例如,為在多個時間段出現的部分腳本代碼定義速記。本文常數應該總是以一個$(美元符號)開始。

例如:

Define $broad       = width:30
Define $narrow      = width:10
Define $bardefaults = $broad fontsize:S

DrawLines

Some timelines extend over several clearly distinct periods. A line demarcating these periods may serve as a visual aid.

Lines specified here will be drawn over the whole width/length of the chart (depending on the orientation defined by TimeAxis).

at
Specify the date/year where the line should be drawn, in compliance with the specified DateFormat.
color
Specify the color in which the line should drawn.
Note: The color id specified should be defined first with command Colors.

Example:

LineData=
  at:start      color:red
  at:end        color:red
  at:07/12/1941 color:red

ImageSize (必選)

This command defines the overall size of the final image. Specify values in absolute measurements.

width
Width of final image: maximum is 1600 pixels
height
Height of final image: maximum is 1200 pixels

Example:

ImageSize = width:800 height:600

Legend

A legend will only be shown when this command is present. There are several ways to define the appearance and position of the legend. Some attributes are mutually exclusive (see below).

orientation (O)
Specify hor[izontal] or ver[tical] (default).
Restriction: orientation = 'horizontal' and position = 'right' are mutually exclusive
position (O)
Defines placement of the legend relative to the chart area. Specify top, bottom (default) or right.
Restriction: orientation = 'horizontal' and position = 'right' are mutually exclusive
columns (O)
Specify 1, 2, 3 or 4. When this attribute is omitted the number of columns is determined as follows:
  • Orientation horizontal : Attribute columns does not apply here. All entries will be on the same line.
  • Orientation vertical :
    • Position right : All entries will be in one column
    • Position top or bottom : The number of columns depends on the number of entries to be shown:
      1-5 entries: 1 column, 6-10 entries: 2 columns, 11 or more entries: 3 columns.

Tip: you may consider omitting the following parameters at first, and only add them when defaults settings are not satisfactory.

columnwidth (O)
Defines the distance between columns. You can specify an absolute distance or a relative distance (as percentage of the page width).
Restriction: this parameter is ignored when columns = 1 is defined or implied.
left (O)
Defines the distance between the left side of the legend and the left side of the page. You can specify an absolute distance or a relative distance (as percentage of the page width).
top (O)
Defines the distance between the top of the legend and the bottom of the page. You can specify an absolute distance or a relative distance (as percentage of the page height).

Examples:

Legend = orientation:vertical position:bottom columns:3 columnwidth:140

Legend = orientation:horizontal position:bottom

Legend = left:100 top:120 columns:3

Period (必選)

Defines the time period that will be displayed in the chart. Both parameters are mandatory. Specify dates in compliance with specified DateFormat.

from
Timeline starts here. The specified value can be referenced as start in commands like PlotData and TextData.
till
Time ends here. The specified value can be referenced as end in other commands.

Example:

Period = from:01/09/1939 till:02/09/1945

PlotArea (必選)

width
以絕對或相對測量來指定數值。
height
以絕對或相對測量來指定數值。
left
圖像左邊和圖形區左邊的空白餘量。以絕對或相對測量來指定數值。
bottom
圖像底邊和圖形區底邊的空白餘量。以絕對或相對測量來指定數值。

例如:

PlotArea = width:640 height:420 left:160 bottom:120

PlotArea = width:80% height:70% left:20% bottom:20%

PlotData

用於定義欄 (用符號表示時間周期), 並且在欄後的特定位置上加入文字。

For texts which are not related to a certain period or date/year or which require extensive formatting use command TextData.

Attributes text, at, from and till always apply only to the line on which they occur. All other attributes, when not combined with one these four, act as default for the remainder of the command block or until a new default is specified, and may be overruled for a single line. See Parameters vs Data Items for more info and an example.

圖形區有許多的屬性,其中有些時互斥的。這些屬性可被分為以下幾種:

  • 位置屬性
  • 欄相關屬性
  • 文字屬性
  • 標記屬性

位置屬性

at
Specifies at which date/year a text should be positioned. Depending on attribute align the text either starts, ends or is centered at this position. Use date/year format as specified in DateFormat or specify start or end which refers to time frame defined by command Period.
NB: This attribute can not be combined with attributes from or till.
from
Specifies at which date/year a bar should start. Use date/year format as specified in DateFormat or specify start which refers to time frame defined by command Period.
NB: This attribute should be used in combination with attribute till and can not be combined with attribute at.
till
Specifies at which date/year a bar should end. Use date/year format as specified in DateFormat or specify end which refers to time frame defined by command Period.
NB: This attribute should be used in combination with attribute from and can not be combined with attribute at.
shift
Specifies a horizontal and vertical displacement in absolute measurements for a text. This allows:
  • Texts to be shifted to avoid overlaps
  • Placement of text beside a bar, instead of on top of it.

Examples:

PlotData=
  bar:Japan from:start      till:19/02/1945 color:JT
  bar:Japan from:19/02/1945 till:14/03/1945 color:AI
  bar:Japan from:02/09/1945 till:end        color:AO

  at:07/12/1941 shift:(0,-15) text:"<-- WW2 reaches Asia"

欄相關屬性

bar
Specifies to which bar all other attributes apply.
When command BarData has not been used, bars will be drawn in the order in which they occur in any PlotData data block. The id specified here will also be the text presented along the axis, next to the bar.
When command BarData has been used, bars will presented in the order specified there, also the bar id specified here will be validated against that list. Also the text presented along the axis will depend on the definition in BarData.
color
指定欄應該被繪製的顏色。
The color id specified should be defined first with command Colors.
width
Specifies the width of the bar in absolute or relative measurements.

例如:

BarData=
  id:US text:United States
  id:SB text:Sea Battles

Colors=
  id:US value:blue legend:United_States
  id:SB value:rgb(0.8,0,0.7) legend:Sea_Battles

PlotData=
  width=0.3                                                            # see note 1
  bar:SB     from:07/08/1942 till:09/02/1943 text:Guadalcanal color:SB # see note 2
  bar:US     from:start      till:end color:US                         # see note 3
  bar:Midway from:start      till:end color:US                         # see note 4
  bar:US     at:07/12/1941   text:7/12 Pearl Harbour                   # see note 5

Notes:

  1. this line establishes a default bar width for the remainder of the data block
  2. this line specifies a bar to be drawn and a text to placed on it at the same time
  3. bar US will be drawn before bar SB, even when specified after it, because command BarData determines the sequence
  4. bar Midway will be rejected because it is not declared with command BarData
  5. the last line will not result in a bar being plotted, it merely specifies on which bar the text should be placed

文字屬性

text
Defines a text that should be plotted on or near a bar. The anchor position can be defined either explicitly with attribute at, or implicitly with attributes from and till. In the latter case the text will be positioned in the middle of the defined bar segment. See also Text Input for rules
The text may include embedded links (see Notes 1 & 2) for use in clickable maps.
textcolor (O)
Defines the color of the text. The color id specified should be defined first with command Colors. When not specified color black will be assumed.
fontsize (O)
Specify a point size between 6 and 30, or (preferably) one of tags XS, S (default), M, L or XL. See Font Support for more details.
align (O)
Specify center (default), left or right.
link (O)
Specify a web link (see Note 1) (URL) for use in clickable maps. The text will be shown as a blue clickable link.

Notes

  1. Either use attribute link, or an embedded link in attribute text, not both.
  2. On PNG images only one clickable link will be shown per text segment (text with line breaks (~) constitutes several segments).

Example:

PlotData=
   bar:US at:07/12/1941 align:left textcolor:black fontsize:XS text:7/12 [[Pearl Harbour]]

produces the same result as:

PlotData=
   bar:US at:07/12/1941 align:left textcolor:black fontsize:XS text:"7/12 Pearl Harbour" link:http://www.wikipedia.org/wiki/Pearl_Harbour

標記屬性

mark
Places a marker in a bar at the specified position. Specify as mark:(symbol, color). The only value for symbol supported to date is line. The color id specified should be defined first with command Colors. When not specified color black will be assumed.

Example:

PlotData=
  bar:test width:15 color:red
  from:1900 till:2000
  at:1990 mark:(line,white)

will be shown as:

ScaleMajor

This command divides the timeline into smaller periods, either

  • Graphically, through thin vertical or horizontal lines in the chart
  • Textually, through stubs in the time axis, below or to the left of the chart
  • Both graphically and textually

Note: the orientation of the lines and/or placement of the stubs depends on the orientation of the TimeAxis.

gridcolor (O)
Defines the color for the grid lines. When this attribute is omitted no grid lines will be drawn.
Note: The color id specified should be defined first with command Colors.
unit (O)
Specifies the unit by which the grid spacing is incremented. Specify day, month or year (default).
Note: When DateFormat yyyy is specified, only unit year is allowed.
increment (O)
Specifies the numbers of units by which the grid spacing is incremented. Default is 1.
start (O)
Specifies where the first grid line and/or stub should be displayed. Defaults to start of defined Period.

Examples:

ScaleMajor = gridcolor:red start:1940

ScaleMajor = gridcolor:red unit:month increment:3 start:01/09/1939

ScaleMinor

This command defines a further subdivision of the timescale. See ScaleMajor for syntax .

Example:

ScaleMajor = grid:red  unit:year  increment:1 start:01/01/1940
ScaleMinor = grid:blue unit:month increment:3 start:01/10/1939

TextData

Used to define a text block that can be positioned anywhere on the chart.

text
The actual text. See also Text Input for rules. The text may include embedded links (see Notes 1 & 2).
pos
Defines the top-left corner of the text block in absolute or relative measurements. Define as pos:(x,y).
link (O)
Specify a web link (see Note 1) (URL) for use in clickable maps. The label along the axis will be shown as a blue clickable link.
textcolor (O)
Defines the color of the text. The color id specified should be defined first using Colors. When not specified, the color is black.
fontsize (O)
Specify a point size between 6 and 30, or (preferably) one of tags XS, S (default), M, L or XL (see Font Support for more details).
tabs (O)
Defines position and alignment for tab character: ^ (caret). Specify multiple tab settings as tabs: (x1-a1,x2-a2,x3-a3, etc..) where
  • xn is the horizontal displacement in absolute measurements from the left side of the text
  • an is the alignment for the text segment (specify center, left or right)
lineheight (O)
Defines spacing between consecutive lines in absolute measurements. Specify a value up to 40 pixels or 0.4in. When not specified a default lineheight will be based on the font size currently in use.

Notes:

  1. Either use attribute link, or an embedded link in attribute text, not both.
  2. On PNG images only one clickable link will be shown per text segment (text with tabs (^) constitutes several segments).

Example:

TextData =
  pos:(20,67) textcolor:black fontsize:S
  tabs:(10-right,14-left,50-left,90-left,230-left)
  text:^1^1940^27/9^Germany,Italy and Japan sign [[Tripartite Pact]]
  text:^10^1944^1-22/7^Bretton Woods 44 nations establish
  text:^^^^^IMF and World Bank

will be shown as:

Tripartite Pact

TimeAxis

Defines the orientation of the time axis, and textual representation of stubs along that axis.

format (O)
Specify in which format dates should be presented along the time axis.
Currently only format yyyy (default) is supported. More formats may follow.
orientation (O)
Specify hor[izontal] (default) or ver[tical].

Example:

TimeAxis = orientation:horizontal format:yyyy

Presets

At the moment two presets are available:

  • Preset = TimeVertical_OneBar_UnitYear
  • Preset = TimeHorizontal_AutoPlaceBars_UnitYear

Not clear if whether there is documentation about them.

輸入規則

尺寸和位置比例

Absolute measures may be used for specifying sizes, positions and position shifts, measured in pixels.

Example:

PlotArea = width:800 height:600 left:50 bottom:50

Relative measures may be used for specifying sizes and positions. Specify a number between 0 and 100, immediately followed by a % (percentage) sign. For horizontal measurements the percentage is related to image width, for vertical measurements to image height.

The first coordinate is horizontal from left to right, the second is vertically upward.

Example:

PlotArea = width:80% height:80% left:10% bottom:5%

文字輸入

Text input is subject to a few rules:

1 No unicode is allowed yet. See also font support.

2 When text should contain spaces, either specify these by using underscores or place the text between double quotes.

Exception: when the text attribute is the last attribute on a line, spaces are allowed (no confusion will arise where the text stops and the next attribute starts, that is—to be precise—when no colons occur in the text).

Example: (the following are all equivalent)

BarData =
  text:Japanese_mandate_since_1914 bar:Marshalls

BarData =
  text:"Japanese mandate since 1914" bar:Marshalls

BarData =
  bar:Marshalls text:Japanese mandate since 1914

3 In data lines following command TextData two characters have special meaning:

~ (tilde) means line break
^ (caret) means tab

Example showing line breaks:

TextData =
  .. text:Generated for Wikipedia~Version 1.1 - 2 Januari 2004

# will be shown as:
#
#  Generated for Wikipedia
#  Version 1.1 - 2 Januari 2004

Example showing tabs:

TextData =
  tabs:(4-right,12-right,14-left,34-left)
  text:^1^1940^27/9^Berlin Ger,It,Jap sign Tripartite Pact
  text:^10^1944^1-22/7^Bretton Woods 44 nations establish
  text:^^^^^IMF and World Bank

# will be shown as:
#
#      1    27/9 Berlin Ger,It,Jap sign Tripartite Pact
#     10  1-22/7 Bretton Woods 44 nations establish
#                                    IMF and World Bank

可點擊的圖

Both output formats available in MediaWiki, i.e. PNG and SVG, can contain clickable links. Texts shown in blue, and bars, may then be clicked, to surf to another web page.

Links can be specified with commands BarData, PlotData and TextData, either with attribute link, or as embedded links, via attribute text.

嵌入式連結

Embedded links are links that are (part of a) displayable text, specified with attribute text. Their counterpart are explicit links (URL only) which are defined with attribute link.

Both type of links can be specified with commands BarData, PlotData and TextData and are used for clickable maps.

In embedded links, internal link style is as usual, interwiki link style does not work, external link style is as usual with single brackets, but here with a pipe instead of a space. Blank spaces and underscores in the url should be written as %20.

Examples:

  text:example [[Help:Link]] internal link

will be shown as:

Help:Link
  text:[[Help:Link|Link]]

will be shown as:

Help:Link
  text:[http://en.wikipedia.org/wiki/Rembrandt|Rembrandt van Rijn] paints Night Watch

will be shown as:

en.wikipedia.org/..

Attempt to use interwiki link style:

  text:[[en:Main_Page]]
and similar with nl: and m: give:
m:Main Page

The third one to Meta-Wikipedia works properly, except from Meta itself, the other links work like Main_Page (internal page, the prefix is ignored) or e.g. //zh.wikipedia.org/w/Main_Page (gives File not found), depending on the URL of the referring page (e.g. different for a preview page and a diff page).

EasyTimeline code with a template parameter is not allowed