模組:Carousel

模块文档[查看] [编辑] [历史] [清除缓存]

页面轮展模块，可用于首页特色条目、优良条目展示。

用法

Step 1: 创建JSON页面

首先，需要创建一个JSON页面，其中记录了要轮展嵌入的页面，以及轮展的顺序。以下是一个例子（User:PhiLiP/carousel-example.json）：

[
    {
        "title": "1689年波士顿起义",
        "displayTimeRanges": [
            [
                20150304123013,
                null
            ]
        ]
    },
    {
    	"title": "孔子鸟属",
    	"displayTimeRanges": [
    		[20060313005324, 20090614110222]
    	]
    },
    {
        "title": "1850年大西洋飓风季",
        "displayTimeRanges": [
            [
                20141030151730,
                null
            ]
        ]
    },
    {
        "title": "1873年铸币法案",
        "displayTimeRanges": [
            [
                20160805143015,
                null
            ]
        ]
    },
    {
        "title": "1880年民主党全国大会",
        "displayTimeRanges": [
            [
                20141213150114,
                null
            ]
        ]
    }
]

Step 2: 调用轮展模块

效果：

在要显示轮展内容的位置，按下述方式调用模块：

{{#invoke:Carousel|main|candidateList=User:PhiLiP/carousel-example.json}}

可选参数

效果：

（当前时间戳为20250526040756，显示第1条）

1689年波士顿起义是一场发生在1689年4月18日的起义，旨在反对新英格兰自治领总督埃德蒙·安德罗斯爵士的统治。在自治领民兵和波士顿市民的精心组织下，“暴民”在城内逮捕自治领官员。被清教徒认为支持自治领政府统治的英国圣公会教徒也遭拘捕。不过这次起义期间双边都没有出现人员伤亡。前马萨诸塞湾殖民地的领导人重新取得政府控制权。之前被自治领政府撤职的其他殖民地政府官员重新掌握了权力。1686年获命成为自治领总督的安德罗斯上任后无视地方代表权、对镇民大会设限、积极推行圣公会、强制执行航海法案，还否认马萨诸塞殖民地已有土地所有权的合法性，种种极其不得人心的行径和英国发生的光荣革命共同影响，导致殖民地清教徒决定揭竿而起，推翻他的统治。

除了candidateList外，有两个可选参数timeStart和timeInterval。timeStart定义轮展的起始时间（以MediaWiki时间戳规定的UTC时间，默认值19700101000000，即UTC时间1970年1月1日0时0分0秒）；timeInterval定义每轮展示的秒数（默认值86400秒，即1天）。下为示例：

（从UTC时间2025年5月26日0时0分0秒起，每小时更换一次。）

{{#invoke:Carousel|main|candidateList=User:PhiLiP/carousel-example.json|timeStart=20250526000000|timeInterval=3600}}

上述文档嵌入自Module:Carousel/doc。 (编辑 | 历史)
编者可以在本模块的沙盒 (创建 | 镜像)和测试样例 (创建)页面进行实验。
本模块的子页面。

local p = {}
local lang = mw.language.new('zh')

function tostringOrNil(value)
	if value ~= nil then
		value = tostring(value)
	end
	return value
end

function getCandidateList(pageName, currentTime)
	local page = mw.title.new(pageName)
	local candidates =
		mw.text.jsonDecode(page:getContent(), mw.text.JSON_TRY_FIXING)

	-- change mw timestamp to unix timestamp
	for _, item in pairs(candidates) do
		for i in pairs(item.displayTimeRanges) do
			item.displayTimeRanges[i][1] = tonumber(
				lang:formatDate('U', tostring(item.displayTimeRanges[i][1]))
			)
			-- use current time when the "end time" is null
			item.displayTimeRanges[i][2] = tonumber(
				lang:formatDate(
					'U', tostringOrNil(
						item.displayTimeRanges[i][2] or currentTime
					)
				)
			)
		end
	end
	return candidates
end

function pickCandidate(candidateList, currentTime, timeStart, timeInterval)
	local processedTime = timeStart
	local currentDisplayStart =
		math.floor(currentTime / timeInterval) * timeInterval
	local currentDisplayEnd = currentDisplayStart + timeInterval
	local iii = 100
	while iii > 0 do
		local cycleItems = 0
		local nextStatusChanged = 0xffffffffffffffff
		for _, item in pairs(candidateList) do
			if processedTime >= currentDisplayStart and
				processedTime < currentDisplayEnd then
				return item.title
			end
			for _, range in pairs(item.displayTimeRanges) do
				local rangeStart = range[1]
				local rangeEnd =
					math.ceil(range[2] / timeInterval) * timeInterval
				if rangeStart > processedTime then
					nextStatusChanged = math.min(nextStatusChanged, rangeStart)
				end
				if rangeEnd > processedTime then
					nextStatusChanged = math.min(nextStatusChanged, rangeEnd)
				end
				if processedTime < rangeStart or
					processedTime > rangeEnd then
					-- continue
					-- mw.log(rangeStart)
					-- mw.log(rangeEnd)
					-- mw.log('---------')
				else
					-- processedTime = processedTime + timeInterval
					cycleItems = cycleItems + 1
					break
				end
			end
			-- mw.log(processedTime)
		end
		mw.log("nextStatusChanged: ", nextStatusChanged)
		mw.log("CycleItems: ", cycleItems)
		mw.log("ProcessedTime (before): ", processedTime)
		if cycleItems > 0 then
			-- TODO: nextStatusChanged - processedTime < timeInterval?
			processedTime = processedTime + math.floor(
				math.ceil((nextStatusChanged - processedTime) / timeInterval)
				/ cycleItems
			)
			* cycleItems * timeInterval;
		else
			processedTime = math.max(processedTime, nextStatusChanged)
		end
		mw.log("ProcessedTime: ", processedTime)
		iii = iii - 1
	end
	return 'NO'
end

function p.getCandidate(frame)
	local args = frame.args
	local currentTime = tonumber(
		lang:formatDate('U', tostringOrNil(args.currentTime))
	)
	local candidateList = getCandidateList(
		args.candidateList,
		args.currentTime
	)
	local timeStart = tonumber(
		lang:formatDate(
			"U", tostringOrNil(args.timeStart) or '19700101000000'
		)
	)
	local timeInterval = tonumber(args.timeInterval) or 86400
	local title = args.titlePrefix or 'Wikipedia:特色条目/'
	title = title .. pickCandidate(
		candidateList, currentTime, timeStart, timeInterval)
	return title
end

function p.main(frame)
	return mw.getCurrentFrame():expandTemplate({
		title = p.getCandidate(frame)
	})
end

return p