轻之舟百科

模組:String/doc

< Module:String
IdleTap-bot​（留言 | 貢獻）2026年8月4日 (二) 03:37的修訂 （改写不存在的 escapePattern/count/endswith 函数示例为 nowiki，消除脚本错误（由IdleTap-bot导入维护））
(差異) ←上個修訂 | 最新修訂 (差異) | 下個修訂→ (差異)

此頁面為 Module:String 的說明文件

這個模組提供了基本的字串操作函數。

此處提供的大多數函數都可以使用命名參數、未命名參數或混合參數調用。 如果使用命名參數，Mediawiki將自動從參數中刪除任何前導或尾隨空格。取決於預期用途，保留或刪除此類空白各有優劣的。

全局參數

編輯
ignore_errors
如果設置為「true」或「1」，則任何錯誤條件都將導致返回空字串而不是錯誤消息。
error_category
如果發生錯誤，則指定要包含在錯誤消息中的分類的名稱。預設分類為Category:字串模組報告的錯誤（1）。
no_category
如果設置為「true」或 1，則在生成錯誤時不會添加任何類別。

此模組的單元測試可在Module:String/testcases進行。

len

編輯

此函數返回目標字串的長度。

用法：

{{#invoke:String|len|target_string}}

或

{{#invoke:String|len|s= target_string }}

參數：

s
目標字串

範例：

  • {{#invoke:String|len| abcdefghi }} → 11
  • {{#invoke:String|len|s= abcdefghi }} → 9

sub

編輯
此函數返回指定索引處目標字串的子字串。

用法：

{{#invoke:String|sub|target_string|start_index|end_index}}

或

{{#invoke:String|sub|s= target_string |i= start_index |j= end_index }}

參數：

s
返回此字串的子集
i
要返回的子字串的第一個索引，預設為1。
j
要返回的字串的最後一個索引，預設為最後一個字元。

字串的第一個字元的索引為1。如果i或j是負值，則將其解析為透過從字串末尾計數來選擇字元。因此，值-1與選擇字串的最後一個字元相同。

如果請求的索引超出給定字串的範圍，則會報告錯誤。

範例：

  • "{{#invoke:String|sub| abcdefghi }}" → " abcdefghi "
  • "{{#invoke:String|sub|s= abcdefghi }}" → "abcdefghi"
  • "{{#invoke:String|sub| abcdefghi | 3 }}" → "bcdefghi "
  • "{{#invoke:String|sub|s= abcdefghi |i= 3 }}" → "cdefghi"
  • "{{#invoke:String|sub| abcdefghi | 3 | 4 }}" → "bc"
  • "{{#invoke:String|sub|s= abcdefghi |i= 3 |j= 4 }}" → "cd"

sublength

編輯

此函數實現了模板連結：{{Str sub old}}的功能，保留僅為維持舊的模板。

用法：

{{#invoke:String|sublength|s= 目標字串 |i= 開始索引 |len= 長度 }}

參數：

s
字串
i
返回的子串的開始索引。第一個個字元的索引為0。
len
返回的字串的長度，預設為最後一個字元。

範例：

  • {{#invoke:String|sublength|s= abcdefghi }} → abcdefghi
  • {{#invoke:String|sublength|s= abcdefghi |i= 3 }} → defghi
  • {{#invoke:String|sublength|s= abcdefghi |i= 3 |len= 4 }} → defg

match

編輯

此函數從源字串返回一個匹配指定模式的子字串。

用法：

{{#invoke:String|match|源字串|模式字串|開始索引|匹配數量|純標記|無匹配輸出}}

或者

{{#invoke:String|match|s= 源字串 |pattern= 模式字串 |start= 開始索引|match= 匹配數量|plain= 純標記 |nomatch= 無匹配輸出 }}

參數：

s
在這個字串內搜索
pattern
需要在字串內搜索的模式或者字串
start
源字串內的索引，從此索引開始搜索。字串的第一個字元的索引為1。預設為1。
match
在一些情況下，可能需要在單個字串中進行多次匹配。此參數指定了返回哪一個匹配，其中第一個匹配就是match=1。如果指定了負數，那麼返回的匹配從最後一個匹配開始數的。因此match=-1表達返回最後一個匹配。預設為1。
plain
pattern是否應該理解為純字串，而非正則表達式。預設為false。
nomatch
如果沒有找到匹配，返回nomatch的值，而不是一個錯誤。

如果match_number或start_index超出了查詢的字串的範圍，此函數會產生錯誤。如果沒有找到匹配，也會產生錯誤。

如果添加了參數ignore_errors=true，那麼錯誤會被禁止，失敗時返回的是一個空字串。

匹配是Lua的一種正則表達式，更多資訊可以參考：

範例：

  • {{#invoke:String|match| abc123def456 |%d+}} → 123
  • {{#invoke:String|match|s= abc123def456 |pattern= %d+ }} → 123
  • {{#invoke:String|match| abc123def456 |%d+|6}} → 23
  • {{#invoke:String|match|s= abc123def456 |pattern= %d+ |start= 6 }} → 3
  • {{#invoke:String|match|s= abc123def456 |pattern= %d+ |start= 6 |match= 2 }} → 456
  • {{#invoke:String|match|s= abc123%d+ |pattern= %d+ }} → 123
  • {{#invoke:String|match|s= abc123%d+ |pattern= %d+ |plain= true }} → %d+
  • {{#invoke:String|match|s= abc |pattern= %d }} → 字串模組出錯：找不到匹配
  • {{#invoke:String|match|s= abc |pattern= %d |nomatch= No numeric characters in string }} → No numeric characters in string
  • {{#invoke:String|match|s= abc |pattern= %d |ignore_errors= true }} →
  • {{#invoke:String|match|s= 0012001200 |pattern= 0*(%d*) }} → 12001200

pos

編輯

返回在目標字串中的位置pos處的單個字元。

用法：

{{#invoke:String|pos|目標字串|索引值}}

或

{{#invoke:String|pos|target= 目標字串 |pos= 索引值 }}

參數：

目標
在此字串內搜索
pos
需要返回的字元所在的索引。

第一個字元的索引值為1。

如果為負值，則此函數會從字串的最後面開始倒數。也就是說，pos=-1相當於返回最後一個字元。

如果此值為0，或者超出了字串的長度，則會返回錯誤。

範例：

  • {{#invoke:String|pos| abcdefghi | 4 }} → c
  • {{#invoke:String|pos|target= abcdefghi |pos= 4 }} → d

str_find

編輯

此函數與模板連結：{{str_find}}的行為重複，包含了其所有的技巧，僅為支持存在的模板，但是對於新的代碼和模板不推薦使用。新的代碼建議直接使用find函數。

返回源字串中匹配目的的第一個索引。索引是從1開始數的，如果源字串中找不到目標字串，則返回-1。

注意：如果目標字串是空白或者缺失，則函數返回值為1，這可能不是預期的行為，必須要單獨考慮。

用法：

{{#invoke:String|str_find|源字串|目標字串}}

或

{{#invoke:String|str_find|source= 源字符串 |target= 目标字符串 }}

參數：

source
在此字串內搜索
target
在源內搜索的字串

範例：

  • {{#invoke:String|str_find| abc123def }} → 1
  • {{#invoke:String|str_find|source= abc123def }} → 1
  • {{#invoke:String|str_find| abc123def |123}} → 5
  • {{#invoke:String|str_find|source= abc123def |target= 123 }} → 4
  • {{#invoke:String|str_find| abc123def |not}} → -1

find

編輯

此函數在一個字串內搜索另一個字串。

用法：

{{#invoke:String|find|源字串|目標字串|開始索引|純標記}}

或

{{#invoke:String|find|source= 源字串 |target= 目標字串 |start= 開始索引 |plain= 純標記 }}

參數：

source
在此字串內搜索
target
在源字串內搜索的字串
start
在源字串的此位置索引版主開始搜索。預設為1
plain
布爾值標記，表示目的應該被理解為純文本，而不是Scribunto ustring模式，預設為true

此函數返回了在索引>"start"，其中"source"中可以持續到"target"。索引是從1開始數的。如果沒有找到目標字串，函數返回0。如果索引或者目的缺失或者是空的，此函數也會返回0。

此函數應該可以安全地操作UTF-8字串。

範例：

  • {{#invoke:String|find|abc123def|12}} → 4
  • {{#invoke:String|find|source=abc123def|target=12}} → 4
  • {{#invoke:String|find|source=abc123def|target=pqr}} → 0
  • {{#invoke:String|find| abc123def |123}} → 5
  • {{#invoke:String|find|source= abc123def |target= 123 }} → 4
  • {{#invoke:String|find|source=abc123def|target=%d |start=3 |plain=false }} → 4

與未命名的參數使用時，兩端的空格會被保留且被計入：

  • {{#invoke:String|find| abc123def |c|false}} → 5
  • {{#invoke:String|find|source= abc123def |target=c|plain=false}} → 3
  • {{#invoke:string|find|abc 123 def|%s|plain=false}} → 4

檢測字串是否存在：

  • {{#ifexpr:{{#invoke:string|find|haystack|needle}}|Found needle|Didn't find needle}} → Didn't find needle

replace（gsub）

編輯

此函數在一個字串內替換到目的字串或者模式。此函數是透過調用mw.ustring.gsub實現的。

用法：

{{#invoke:String|replace|源字符串|模式字符串|替换字符串|替换次数|纯标记}}

或

{{#invoke:String|replace|source= 源字符串 |pattern= 模式字符串 |replace= 替换字符串 |count= 替换次数 |plain= 纯标记 }}

參數：

source
在此字串內搜索
pattern
在源內查找此字串或者模式
replace
使用此字串替換
count
需要替換的次數，預設為all
plain
布爾值標記，表示目的應該被理解為純文本，而不是Scribunto ustring模式，預設為true

範例：

  • "{{#invoke:String|replace| abc123def456 |123|XYZ}}" → " abcXYZdef456 "
  • "{{#invoke:String|replace|source= abc123def456 |pattern= 123 |replace= XYZ }}" → "abcXYZdef456"
  • "{{#invoke:String|replace| abc123def456 |%d+|XYZ|1|false}}" → " abcXYZdef456 "
  • "{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |count=1 |plain= false }}" → "abcXYZdef456"
  • "{{#invoke:String|replace|source= abc123def456 |pattern= %d+ |replace= XYZ |plain= false }}" → "abcXYZdefXYZ"
  • {{#invoke:String|replace|source= 0012001200 |pattern= ^0* |plain= false }} → 12001200

rep

編輯

將一個字串重複n次，其本質為string.rep。

用法：

{{#invoke:String|rep|源|次数}}

參數：

源
需要重複的字串
次數
重複的次數

範例：

  • "{{#invoke:String|rep|hello|3}}" → "hellohellohello"
  • "{{#invoke:String|rep| hello | 3 }}" → " hello hello hello "

escapePattern

編輯
注意
本 wiki 的 Module:String 未實現公開的 escapePattern 函數（僅內部 _escapePattern），以下僅為原版文檔參考範例，實際調用會報錯。

在模式中，將類字元'替換為字面字元。例如，在模式中，字元.會捕獲任何字元，escapePattern會將其轉換為%.，這樣就捕獲了字面字元「.」。

用法：

  • {{#invoke:String|escapePattern|模式字符串}}

參數：

模式字串
需要轉義的模式字串

範例：

  • "{{#invoke:String|escapePattern|A.D.}}" → "{{#invoke:String|escapePattern|A.D.}}"
  • "{{#invoke:String|escapePattern|10%}}" → "{{#invoke:String|escapePattern|10%}}"

count

編輯

返回指定的模式的次數。返回不會將匹配交連。

用法：

{{#invoke:String|count|源字符串|匹配字符串|纯标记}}

或

{{#invoke:String|count|source= 源字符串 |pattern= 匹配字符串|plain= 纯标记 }}

參數：

source_string
在此字串內數出現次數
pattern
在源內需要數的字串或者模式
plain
布爾值標記，表示目的應該被理解為純文本，而不是Scribunto ustring模式，預設為true

範例：

  • 數「a」："{{#invoke:String|count|aabbcc|a}}" → "{{#invoke:String|count|aabbcc|a}}"
  • 數「aba」出現的次數："{{#invoke:String|count|ababababab|aba}}" → "{{#invoke:String|count|ababababab|aba}}"
  • 數a或c出現的次數："{{#invoke:String|count|aabbcc|[ac]|plain=false}}" → "{{#invoke:String|count|aabbcc|[ac]|plain=false}}"
  • 數非a出現的次數："{{#invoke:String|count|aaabaaac|[^a]|plain=false}}" → "{{#invoke:String|count|aaabaaac|[^a]|plain=false}}"
  • 數開頭的a出現的次數："{{#invoke:String|count|aaabaaac|^a|plain=false}}" → "{{#invoke:String|count|aaabaaac|^a|plain=false}}"

join

編輯

將傳入的所有字串連成一個字串，第一個字串表示分隔符

用法：

{{#invoke:String|join|分隔符|字符串1|字符串2|...}}

參數：

分隔符
被連接在一起的各個字串之間的字串
注意對此參數，開頭和結尾的空格不會被移除。
字串1/字串2/...
需要連接進來的字串

範例：

  • "{{#invoke:String|join|x|foo|bar|baz}}" → "fooxbarxbaz"
  • "{{#invoke:String|join||a|b|c|d|e|f|g}}" → "abcdefg"
  • "{{#invoke:String|join|,|a|b|c|d|e|f|g}}" → "a,b,c,d,e,f,g"
  • "{{#invoke:String|join|, |a|b|c|d|e|f|g}}" → "a, b, c, d, e, f, g"
  • "{{#invoke:String|join| – |a|b|c|d|e|f|g}}" → "a – b – c – d – e – f – g"

前面的這個例子使用了html實體&ndash;，但是unicode字元也是有用的。

endswith

編輯
注意
本 wiki 的 Module:String 未實現公開的 endswith 函數，以下僅為原版文檔參考範例，實際調用會報錯。
   關於startswith函數，請見「Module:String2 § startswith」。

用法：

{{#invoke:String|endswith|源字符串|搜索字符串}}

或

{{#invoke:String|endswith|source= 源字符串 |pattern= 搜索字符串}}

如果源字串是以指定的搜索字串結尾的，返回yes。使用命名參數會移除掉空格。搜索字串不是個Lua模式，而是按照字面解釋的。

  • "{{#invoke:String|endswith|xxxyyy|y}}" → "{{#invoke:String|endswith|xxxyyy|y}}"
  • "{{#invoke:String|endswith|xxxyyy|z}}" → "{{#invoke:String|endswith|xxxyyy|z}}"
字串處理模板
切短
根據數量處理
模板連結：{{str mid}} 按位置及長度選取子串。
模板連結：{{trunc}} 切短到規定的字數。
模板連結：{{str left}} 切短或重複填充到規定的字數。
模板連結：{{str crop}} 從末尾切短特定數量的字元。
模板連結：{{chop head and tail}} To crop a specified number of characters off the beginning and end.
模板連結：{{str right}} 返回從左向右移除若干個字元後的字串
模板連結：{{str rightc}} 返回從後向前指定數量的字串，如果字串為空則返回一個參數
模板連結：{{str rightmost}} To trim down to the last specified number of characters.
模板連結：{{str sub old}} To trim down to a specified number, starting at a given number from the left.
模板連結：{{str sub new}} Select a substr based on starting and ending index.
模板連結：{{str index}} 返回字串的第×個字元
根據條件處理
模板連結：{{trim}} 移除首尾空格。
模板連結：{{str letter/trim}} To trim down to the beginning letters.
模板連結：{{str number/trim}} To trim down to the beginning numbers.
模板連結：{{trim brackets}} To trim any leading or trailing square brackets.
模板連結：{{trim quotes}} To trim leading or trailing matches quotes.
模板連結：{{String split}} 從長字串中抽取短字串。
模板連結：{{first word}} 切短至首個空格前。
模板連結：{{remove first word}} 移除首個空格前的內容。
模板連結：{{last word}} 切短至最後一個空格前。
模板連結：{{remove last word}} 移除最後一個空格前的內容。
專用於Wiki語法
模板連結：{{除鏈}} 去除Wiki連結的括號（Wiki代碼）。
模板連結：{{remove file prefix}} 從檔案名中去除「File:」（或「Image:」）。
模板連結：{{PAGENAMEBASE}} 去除字串末尾的括號文本（消歧義）。
模板連結：{{title disambig text}} 返回字串末尾的括號文本（消歧義）。
模板連結：{{WikiProjectbasename}} Removes "WikiProject" from a pagename.
模板連結：{{remove unranked}} Removes the string "unranked_" from the left of a string (taxonomy).
模板連結：{{ship prefix}} Returns the length of a ship's name prefix, if listed (ship names).
模板連結：{{title year}} Returns the 4-digit year from a pagename, if any.
插入、替換、長度
模板連結：{{strloc insert}} Inserts a string at character location strloc, or appends if strloc<=0.
模板連結：{{loop}} 特定次數重複字串。
模板連結：{{replace}} 在字串中查找並全部替換某字串後返回。
模板連結：{{str rep}} 在字串中查找並替換首次出現的某字串後返回。
模板連結：{{digits}} 移除字串中不是數字（0～9）的字元。
模板連結：{{str len}} 返回字串長度。
模板連結：{{str ≥ len}} 檢查一個字串和某一給定長度相比是「更長或等長」還是「更短」。
模板連結：{{str ≤ len}} 檢查一個字串和某一給定長度相比是「更短或等長」還是「更長」。
模板連結：{{str ≠ len}} 檢查一個字串和某一給定長度相比是「不等長」還是「等長」。
模板連結：{{str ≤ ≥ len}} 檢查一個字串和某一給定長度相比是「更短」、「等長」還是「更長」。
分析、技術
模板連結：{{str endswith}} 檢查是否以給定的字串結尾。
模板連結：{{str find}}
模板連結：{{strfind short}}		在一個字串中搜尋並返回特定字串的位置。
模板連結：{{str find0}} Zero-based substring search.
模板連結：{{str sub find}} 從指定的偏移量開始搜索一個子字串。
模板連結：{{str letter}} 返回一個字串開頭的所有字元。
模板連結：{{str number}} 返回一個字串開頭的所有數字。
模板連結：{{str gtr str}} 判斷兩個字串是否相等，然後根據返回相應的值。
模板連結：{{ASCII code}} 返回單個字元的ASCII碼值
模板連結：{{a or an}} Takes a noun and produces the appropriate indefinite article, based on whether the first letter is a vowel.
   
Module:String
...Magic words About {{padleft:|}}.
...ParserFunctions About {{#titleparts:|}}, {{#expr:|}}, {{#ifeq:|}}, etc.


取自「https://130.wiki/index.php?title=Module:String/doc&oldid=4524」