移動檔案或目錄 (file.move)
聲明
操作成敗, 錯誤資訊 = file.move(來源路徑, 目標路徑 [, 模式])
參數
- 來源路徑
文字型,來源檔案或目錄的絕對路徑 - 目標路徑
文字型,移動後的檔案或目錄的完整絕對路徑,包含目標檔名或目錄名 - 模式 20250914+
文字型,可選參數,移動模式。取值:- 空字串或省略:預設模式(no-clobber),當目標已存在時回傳失敗
- "overwrite" 或 "o":覆蓋模式,直接替換已存在的目標(已存在的目標會被刪除)
- "merge" 或 "m":合併模式(僅用於目錄),保留目標中已存在的檔案
- "overwrite-merge" 或 "om"/"mo":覆蓋合併模式,合併目錄但覆蓋同名檔案
回傳值
- 操作成敗
布林型,操作成功回傳 true,操作失敗回傳 false - 錯誤資訊
文字型,操作失敗時的錯誤資訊
說明
將
來源路徑指向的檔案或目錄移動為目標路徑;在同一目錄下更名即為重新命名
該函式是「移動為」語義,不是「移動進」語義。目標路徑指定最終的檔案或目錄,不會自動追加來源檔名或目錄名;即使目標已存在且為目錄,或者目標路徑以/結尾,也不會將來源檔案或目錄放入該目錄中
例如,要把/a/b/c移動到/d/e/中並保留名稱c,目標路徑應寫為/d/e/c,不能只寫/d/e/
目標已存在時,按模式參數處理:預設模式回傳失敗,覆蓋模式替換目標本身,目錄合併模式則將來源目錄內容合併到目標目錄
關鍵詞:重新命名檔案、重新命名目錄、重新命名資料夾、移動檔案、移動目錄、移動資料夾
該函式在 20250313 以後的版本方可使用
範例
ok, err = file.move(XXT_SCRIPTS_PATH..'/1.zip', XXT_SCRIPTS_PATH..'/2.zip')
if not ok then
sys.alert('移動失敗:'..err)
end
注:上述程式碼中使用了非本章函式 sys.alert
移動到另一個目錄並保留名稱
-- 假設 /d/e 是已存在的目錄,/d/e/c 尚不存在
file.move('/a/b/c', '/d/e/c') -- 正確:將 c 移動為 /d/e/c
-- 以下為獨立的錯誤寫法範例,目標是 e 本身,不是 e 目錄中的 c
-- file.move('/a/b/c', '/d/e/') -- 預設模式下因目標已存在而失敗
-- 覆蓋模式會替換 e 本身,不會生成 /d/e/c(20250914+)
-- file.move('/a/b/c', '/d/e/', 'overwrite')
封裝「移動進目錄」函式
以下為自訂封裝範例,需要 20250914 以後的版本。目標目錄須已存在,函式會保留來源檔案或目錄名,並將可選的 mode 參數傳給 file.move。發生同名衝突時,仍按指定模式處理。
local function file_move_into(src_path, dst_dir, mode)
if file.exists(dst_dir) ~= "directory" then
return false, "Target is not a directory"
end
local name, err = file.path.last_component(src_path)
if not name then
return false, err
end
-- 避免將目標目錄本身或其父目錄作為最終目標。
if name == "" or name == "/" or name == "." or name == ".." then
return false, "Source path must end with a file or directory name"
end
local dst_path, path_err = file.path.add_component(dst_dir, name)
if not dst_path then
return false, path_err
end
return file.move(src_path, dst_path, mode)
end
-- 假設 /d/e 是已存在的目錄,將 c 移動為 /d/e/c
local ok, err = file_move_into("/a/b/c", "/d/e/")
if not ok then
print("移動失敗:"..err)
end
-- 如需替換 /d/e/c,可在呼叫時指定覆蓋模式:
-- file_move_into("/a/b/c", "/d/e/", "overwrite")
注:上述程式碼使用了 file.exists、file.path.last_component 和 file.path.add_component。