Differences

This shows you the differences between two versions of the page.

--- api:term:zh [2023/10/20 06:44]
hfsr
+++ api:term:zh [2023/12/01 07:03] (current)
hfsr [Term(终端) API]
@@ Line 1: / Line 1: @@
 Term(终端) API
 =======
-此API提供了向屏幕输出内容和读取用户输入的简便方法。因此你无需再手动操作GPU API实现这些功能。
+此API提供了向屏幕输出内容和读取用户输入的简化版方法。因此你无需手动操作GPU API实现这些功能。
 - `term.isAvailable(): boolean`
-返回term API是否可用，即是否存在主GPU和屏幕。换言之，`term.read`和`term.write`函数能否起到实际作用。
+  返回term API是否可用，即是否存在首选GPU和屏幕。换言之，`term.read`和`term.write`函数能否起到实际作用。
+\\
 - `term.getViewport(): number, number, number, number, number, number`
-(OpenOS 1.6新加入)
+（OpenOS 1.6新加入）
-获取宽度、高度、x偏移量、y偏移量、x相对坐标、y相对坐标。
+  获取可视区域的宽度、高度、x偏移量、y偏移量、x相对坐标、y相对坐标。
+\\
 - `term.gpu(): table`
-(OpenOS 1.6新加入)
+（OpenOS 1.6新加入）
-获取term API使用的GPU代理。
+  获取term API所使用GPU的代理对象。
+\\
 - `term.pull([...]): ...`
-(OpenOS 1.6新加入)
+（OpenOS 1.6新加入）
-与`event.pull`的作用完全一致，接收同样的参数，返回同样的结果。此方法用于在等待事件结果时令光标闪烁。
+  与`event.pull`的作用完全一致，接收同样的参数，返回同样的结果。此方法用于在等待事件结果时令光标闪烁。
+\\
 - `term.getCursor(): number, number`
-获取光标的当前位置。
+  获取光标的当前位置。
+\\
 - `term.setCursor(col: number, row: number)`
-将光标位置设定为给定坐标。
+  将光标位置设定为给定坐标。
+\\
 - `term.getCursorBlink(): boolean`
-获取光标闪烁是否启用，即光标是否每隔半秒在其位置实际显示的"像素"和纯白色方块间来回变换。
+  获取光标闪烁功能是否启用，即光标是否每隔半秒在其位置实际显示的"像素"和纯白色方块间来回变换。
+\\
 - `term.setCursorBlink(enabled: boolean)`
-设定光标闪烁功能是否启用。
+  设定光标闪烁功能是否启用。
+\\
 - `term.clear()`
-清空整个屏幕，并将光标位置重置为(1, 1)。
+  清空整个屏幕，并将光标位置重置为(1, 1)。
+\\
 - `term.clearLine()`
-清空光标所在的行，并将光标的横坐标重置为1。
+  清空光标所在的行，并将光标的横坐标重置为1。
+\\
 - `term.read([history: table[, dobreak:boolean[, hint:table or function[, pwchar:string]]]]): string`
-从终端读取一些文本，即让用户能够输入一些文本。例如，此函数被shell和Lua解释器用来读取用户输入。此函数会使当前行从光标位置算起的剩余部分变为可编辑区域。在此区域中可以输入、删除文字，还可以使用左右方向键和home/end键移动光标。
+  从终端读取一些文本，即让用户能够输入一些文本。例如，shell和Lua解释器用此函数来读取用户输入。
+  此函数会使当前行从光标位置算起的剩余部分变为可编辑区域。在此区域中可以输入、删除文字，还可以使用左右方向键和home/end键移动光标。
-  ***自OpenOS 1.6起** 此处指定的参数列表已被视为过时。第一个参数为`option`（选项）参数。其索引值被作为`histroy`（历史）对待，命名键取代了旧的参数。出于兼容性考虑，OpenOS 1.6仍然支持以前的用法，即参数列表。
+  ***自OpenOS 1.6起，此处指定的参数列表已被废弃。**第一个参数为`option`（选项）参数。其中带索引号的数组元素会被作为之前的`histroy`（历史）对待，键被命名的元素取代了之前的参数。为了兼容性，OpenOS 1.6仍支持以前的用法，即参数列表。
-  *新的 `ops` 参数支持新键：`nowrap`。`term.read`的默认行为（`nowrap`为`false`）垂直绑定了光标和输入。先前的行为模式下会水平滚动输入，即现在的 `term.read({nowrap=true})`。
+  *新`ops`参数中支持一个新键：`nowrap`。现在`term.read`的默认行为模式是垂直换行光标和输入。旧的行为模式是水平滚动输入，即现在的`term.read({nowrap=true})`。  \\
+  可选的`history`表作用为提供预定义文本，这些文本可以通过上下方向键循环选择。此表必须成序列（即表中键值必须为从1开始的连续不间断的整数）。此功能的使用例为被shell和Lua解释器的命令历史功能。如果有文本输入并且被按下回车键确定，这条文本就会被加入表的末尾。
-  The optional `history` table can be used to provide predefined text that can be cycled through via the up and down arrow keys. It must be a sequence (i.e. the keys must be a gap-less integral interval starting at 1). This is used for the command history in shell and Lua interpreter, for example. If text is entered and confirmed with enter, it will be added to the end of this table.
+  `dobreak` 参数在设定为`false`（**设定为`nil`时默认为`true`！**）时，输入完成后（如用户按下回车键）不会换行。
-  The `dobreak` parameter, when set to `false` (**`nil` defaults to `true`!**) will not enter a new line after input was completed (e.g. by the user pressing enter).
+  `hint`参数用于tab键补全。此参数可以为内容是字符串的表，或者接收两个参数并返回字符串表的函数，函数的参数为当前文本和在此文本中的位置，即回调函数的签名为 `function(line:string, pos:number):table`。
-  The `hint` parameter is used for tab completion. It can either be a table with strings or a function that returns a table of strings and takes two parameters, the current text and the position in that text, i.e. the signature of the callback is `function(line:string, pos:number):table`.
+  `pwchar`参数若给定，输入内容将会被给定字符串的第一个字符遮盖。例如，给定`"*"`将会导致输入的字符显示为星号。但返回值当然还是输入的实际内容。
-  The `pwchar` parameter, when given, causes input to be masked using the first char of the given string. For example, providing `"*"` will make all entered characters appear as stars. The returned value will still be the actual text inserted, of course.
+  此函数在输入成功后会返回一个字符串，管道关闭（^d）时会返回`nil`，管道中断（^c）时返回`false`。
-  The function will return a string if input was successful, `nil` if the pipe was closed (^d), or `false` if the pipe was interrupted (^c)
+**注1：**`io.stdin:read()` 使用了此函数。\\
+**注2：**此函数将会把输入的字符串与\n（换行符）一并返回。如果你只想要输入的字符串，请使用`io.read()`。
-  //Note//: `io.stdin:read()` uses this function.
+\\
-  //Note 2//: This will return the entered string with the \n (new line character). If you want only the entered string to be returned, use `io.read()`.
 - `term.write(value: string[, wrap: boolean])`
-  Allows writing optionally wrapped text to the terminal starting at the current cursor position, updating the cursor accordingly. It automatically converts tab characters to spaces using `text.detab`. If `wrap` is true, it will automatically word-wrap the text. It will scroll the displayed buffer if the cursor exceeds the bottom of the display area, but *not* if it exceeds the right of the display area (when `wrap` is false).
+  用于将文本输出到终端上，从光标的当前位置起始，可选是否自动换行，输出时同步更新光标位置。
-  //Note//: This method respects io redirection. That is to say, `term.write` writes to the same stream as io.stdout
+  此函数会自动将tab字符用`text.detab`转换。若`wrap`为`true`，函数将会对文本自动换行。若光标超出了显示区域底部，则函数会自动滚动显示缓冲区。但是（当`wrap`为`false`时）在超出显示区域右边界时**不会**滚动。
+**注：**此方法遵循io重定义。即`term.write`与io.stdout写入的是同一个流。
-- `term.bind(gpu)`
+\\
+- `term.bind(gpu)`
-  (new in OpenOS 1.6)
+（OpenOS 1.6新加入) ）
+  将某个`gpu`代理对象（而不是地址）绑定到终端。启动过程中，在GPU与屏幕均可用后，此方法会自动调用。请注意如果手动将终端重新绑定到高度和宽度不同的屏幕，终端绘制区域将会被剪裁，不能最大化显示。此函数改变了所有终端输出使用的GPU，而不只是term API使用的，即包含`io.write`、`print`、`io.stdout:write`以及所有使用同样输出流的函数。`term.bind`可用于修改上述函数使用的`gpu`。
-  Binds a `gpu` proxy (not address) to the terminal. This method is called automatically during boot when the gpu and screen become available. Note that if manually rebinding a terminal to a screen with different width and height, the terminal draw area will be truncated and not maximized. This changes the gpu used in all terminal output, not just via the term api, i.e. `io.write`, `print`, `io.stdout:write`, etc all use the same output stream, and term.bind is used to change the `gpu` used.
+\\
 - `term.screen(): string`
-  (new in OpenOS 1.6)
+（OpenOS 1.6新加入）
+  为了便利而引入的方法，仅仅是在终端绑定的GPU（参见`term.bind`）上调用了 `getScreen`。
-  Convenience method, simply calls `getScreen` on the terminal's bound gpu (see `term.bind`)
+\\
 - `term.keyboard(): string`
-  (new in OpenOS 1.6)
+（OpenOS 1.6新加入）
+  获取终端用于接收按键事件的键盘地址。
-  Gets the address of the keyboard the terminal is accepting key events from.