# IniWrite

写入值到标准格式的 .ini 文件.

    IniWrite, Value, Filename, Section, Key
    IniWrite, Pairs, Filename, Section

## 参数

Value

  将被写入到 Key 的等号(=) 右边的字符串或数字.

  如果文本较长, 可以通过延续片段的方法将其分解成较短的几行, 这样可以增加可读性和可维护性.

Pairs

  [AHK_L 57+]: 将写入 ini 文件的 Section 的完整内容, 不包括 [SectionName] 头. Key 必须省略. Pairs 不能包含空行. 如果 section 已经存在, 则 ini 文件中此 section 中最后一个 key=value 对之前的所有内容都将被覆盖(译者注: 从原 section 头下第一行开始到最后一个 键=值 对之间的所有内容都将被被删除(即, 原有 section 中的所有键=值对和键=值对之间的注释(如果有) 将被删除) , 从 section 头下第一行开始写入 Pairs 的内容, 原最后一个键=值对后面的注释和 [SectionName] 头上的注释(如果有) 都将保持原样). Pairs 可以是不包含等号(=) 的内容, 但这可能产生不一致的效果. 注释可以写入文件, 但是在使用 IniRead 读出时将不包含注释.

Filename

  ini 文件名, 如果未指定绝对路径, 则假定在 %A_WorkingDir% 中.

Section

  ini 文件中的段名, 它是包含在方括号中的标题短语(在此参数中不需要加方括号).

Key

  ini 文件中的键名.

## 错误处理

[v1.1.04+]: 此命令失败时会抛出异常. 想了解更多信息, 请参阅运行时错误.

如果遇到问题则 ErrorLevel 被置为 1, 否则为 0.

## 备注

可以将超过 65,535 个字符的值写入文件, 但可能会产生不一致的结果, 因为 IniRead 或其他应用程序通常无法正确读取它们.

标准的 ini 文件看起来像这样:

    [SectionName]
    Key=Value

新文件将使用系统默认的 ANSI 代码页或者是 UTF-16, 这取决于 AutoHotkey 的版本.

Unicode: IniRead 和 IniWrite 依靠外部函数 GetPrivateProfileString 和 WritePrivateProfileString 来读写值. 这些函数仅支持 Unicode 为 UTF-16 编码的文件; 其他所有文件都被认为使用系统默认的 ANSI 代码页. 在 Unicode 脚本中, IniWrite 为每个新文件使用 UTF-16 编码. 如果不希望这样, 那么请确保在执行 IniWrite 前目标文件已经存在. 例如:

    FileAppend,, NonUnicode.ini, CP0 ; 在大多数情况下最后一个参数是可选的.

## 相关

IniDelete, IniRead, RegWrite

## 示例

将一个值写入位于标准格式 .ini 文件中 section2 的一个键.

    IniWrite, this is a new value, C:\Temp\myfile.ini, section2, key

dftg