NoVNC API 文档翻译

原文地址：https://github.com/novnc/noVNC/blob/master/docs/API.md

时间：2019-05-21

 

 

noVNC API

The interface of the noVNC client consists of a single RFB object that is instantiated once per connection.

noVNC客户端的接口由单个RFB对象组成，每个连接实例化一次

 

RFB

The RFB object represents a single connection to a VNC server. It communicates using a WebSocket that must provide a standard RFB protocol stream.

RFB对象表示与VNC服务器的单个连接。它使用必须提供标准RFB协议流的WebSocket进行通信。

 

Constructor（构造函数）

RFB()

Creates and returns a new RFB object.

创建并返回一个新的RFB对象。

 

Properties（属性）

viewOnly

Is a boolean indicating if any events (e.g. key presses or mouse movement) should be prevented from being sent to the server. Disabled by default.

是一个布尔值，指示是否应该阻止将任何事件（例如按键或鼠标移动）发送到服务器。默认情况下禁用。

 

focusOnClick

Is a boolean indicating if keyboard focus should automatically be moved to the remote session when a mousedown or touchstart event is received.

是一个布尔值，指示在收到mousedown或touchstart事件时是否应自动将键盘焦点移动到远程会话。

 

touchButton

Is a long controlling the button mask that should be simulated when a touch event is recieved. Uses the same values as MouseEvent.button. Is set to 1 by default.

是一个长控制按钮蒙版，应该在收到触摸事件时模拟。使用与MouseEvent.button相同的值。默认设置为1。

 

clipViewport

Is a boolean indicating if the remote session should be clipped to its container. When disabled scrollbars will be shown to handle the resulting overflow. Disabled by default.

是一个布尔值，指示是否应将远程会话剪切到其容器。禁用时，将显示滚动条以处理产生的溢出。默认情况下禁用。

 

dragViewport

Is a boolean indicating if mouse events should control the relative position of a clipped remote session. Only relevant if clipViewport is enabled. Disabled by default.

是一个布尔值，指示鼠标事件是否应控制剪切的远程会话的相对位置。仅在启用clipViewport时相关。默认情况下禁用。

 

scaleViewport

Is a boolean indicating if the remote session should be scaled locally so it fits its container. When disabled it will be centered if the remote session is smaller than its container, or handled according to clipViewport if it is larger. Disabled by default.

是一个布尔值，指示远程会话是否应在本地扩展，以便它适合其容器。禁用时，如果远程会话小于其容器，则它将居中，或者如果它更大，则根据clipViewport处理。默认情况下禁用。

 

resizeSession

Is a boolean indicating if a request to resize the remote session should be sent whenever the container changes dimensions. Disabled by default.

是一个布尔值，指示每当容器更改维度时是否应发送调整远程会话大小的请求。默认情况下禁用。

 

showDotCursor

Is a boolean indicating whether a dot cursor should be shown instead of a zero-sized or fully-transparent cursor if the server sets such invisible cursor. Disabled by default.

是一个布尔值，指示如果服务器设置此类不可见光标，是否应显示点光标而不是零大小或完全透明的光标。默认情况下禁用。

 

background

Is a valid CSS background style value indicating which background style should be applied to the element containing the remote session screen. The default value is rgb(40, 40, 40) (solid gray color).

是一个有效的CSS背景样式值，指示应将哪种背景样式应用于包含远程会话屏幕的元素。默认值为rgb（40,40,40）（纯灰色）。

 

capabilities Read only

Is an Object indicating which optional extensions are available on the server. Some methods may only be called if the corresponding capability is set. The following capabilities are defined:

是一个Object，指示服务器上可用的可选扩展。如果设置了相应的功能，则只能调用某些方法。定义了以下功能：

 

name	type	description
power	boolen	Machine power control is available（机器功率控制可用）

 

Events（事件）

connect

The connect event is fired when the RFB object has completed the connection and handshaking with the server.

当RFB对象完成与服务器的连接和握手时，将触发connect事件。

 

disconnect

The disconnect event is fired when the RFB object disconnects.

当RFB对象断开连接时，将触发disconnect事件。

 

credentialsrequired

The credentialsrequired event is fired when more credentials must be given to continue.

当必须提供更多凭据以继续时，将触发credentialsrequired事件。

 

securityfailure

The securityfailure event is fired when the security negotiation with the server fails.

与服务器的安全协商失败时会触发securityfailure事件。

 

clipboard

The clipboard event is fired when clipboard data is received from the server.

从服务器收到剪贴板数据时会触发剪贴板事件。

 

bell

The bell event is fired when a audible bell request is received from the server.

当从服务器收到声音响铃请求时，将触发铃声事件。

 

desktopname

The desktopname event is fired when the remote desktop name changes.

远程桌面名称更改时会触发desktopname事件。

 

capabilities

The capabilities event is fired when RFB.capabilities is updated.

更新rfb.capabilities时将触发Capabilities事件。

 

Methods（方法）

RFB.disconnect()

Disconnect from the server.

断开与服务器的连接。

 

RFB.sendCredentials()

Send credentials to server. Should be called after the credentialsrequired event has fired.

将凭据发送到服务器。应在credentialsrequired事件触发后调用。

 

RFB.sendKey()

Send a key event.

发送重要事件。

 

RFB.sendCtrlAltDel()

Send Ctrl-Alt-Del key sequence.

发送Ctrl-Alt-Del键序列。

 

RFB.focus()

Move keyboard focus to the remote session.

将键盘焦点移动到远程会话。

 

RFB.blur()

Remove keyboard focus from the remote session.

从远程会话中删除键盘焦点。

 

RFB.machineShutdown()

Request a shutdown of the remote machine.

请求关闭远程计算机。

 

RFB.machineReboot()

Request a reboot of the remote machine.

请求重新启动远程计算机。

 

RFB.machineReset()

Request a reset of the remote machine.

请求重置远程计算机。

 

RFB.clipboardPasteFrom()

Send clipboard contents to server.

将剪贴板内容发送到服务器

 

Details（细节）

RFB()

The RFB() constructor returns a new RFB object and initiates a new connection to a specified VNC server.

RFB（）构造函数返回一个新的RFB对象，并启动与指定VNC服务器的新连接。

 

Syntax

let rfb = new RFB( target, url [, options] );

 

Parameters

target

A block HTMLElement that specifies where the RFB object should attach itself. The existing contents of the HTMLElement will be untouched, but new elements will be added during the lifetime of the RFB object.

一个块HTMLElement，指定RFB对象应该附加到哪里。 HTMLElement的现有内容将不受影响，但在RFB对象的生命周期内将添加新元素。

 

url

A DOMString specifying the VNC server to connect to. This must be a valid WebSocket URL.

指定要连接的VNC服务器的DOMString。这必须是有效的WebSocket URL。

 

options Optional

An Object specifying extra details about how the connection should be made.

一个Object，指定有关如何建立连接的额外详细信息。

 

　　Possible options:

　　shared

　　A boolean indicating if the remote server should be shared or if any other connected clients should be disconnected. Enabled by default.

　　一个布尔值，指示是否应该共享远程服务器或是否应断开任何其他连接的客户端。默认情况下启用。

 

　　credentials

　　An Object specifying the credentials to provide to the server when authenticating. The following credentials are possible:

　　一个Object，指定在进行身份验证时提供给服务器的凭据。可以使用以下凭据：

 

　　　　name type description

　　　　"username" DOMString The user that authenticates

　　　　"password" DOMString Password for the user

　　　　"target" DOMString Target machine or session

 

　　repeaterID

　　A DOMString specifying the ID to provide to any VNC repeater encountered.

　　DOMString，指定要提供给遇到的任何VNC转发器的ID。

 

connect

The connect event is fired after all the handshaking with the server is completed and the connection is fully established. After this event the RFB object is ready to recieve graphics updates and to send input.

在完成与服务器的所有握手并完全建立连接之后，将触发connect事件。在此事件之后，RFB对象已准备好接收图形更新并发送输入。

 

disconnect

The disconnect event is fired when the connection has been terminated. The detail property is an Object that contains the property clean. clean is a boolean indicating if the termination was clean or not. In the event of an unexpected termination or an error clean will be set to false.

终止连接时会触发disconnect事件。 detail属性是一个包含属性clean的Object。 clean是一个布尔值，表示终止是否干净。如果发生意外终止或错误，则清除将设置为false。

 

credentialsrequired

The credentialsrequired event is fired when the server requests more credentials than were specified to RFB(). The detail property is an Object containing the property types which is an Array of DOMString listing the credentials that are required.

当服务器请求的凭据多于为RFB（）指定的凭据时，将触发credentialsrequired事件。 detail属性是一个包含属性类型的Object，它是一个DOMString数组，列出了所需的凭据。

 

securityfailure

The securityfailure event is fired when the handshaking process with the server fails during the security negotiation step. The detail property is an Object containing the following properties:

在安全协商步骤期间与服务器的握手过程失败时会触发securityfailure事件。 detail属性是一个包含以下属性的Object：

Property	Type	Description
status	long	The failure status code（失败状态代码）
reason	DOMString	The optional reason for the failure（失败的可选原因）

The property status corresponds to the SecurityResult status code in cases of failure. A status of zero will not be sent in this event since that indicates a successful security handshaking process. The optional property reason is provided by the server and thus the language of the string is not known. However most servers will probably send English strings. The server can choose to not send a reason and in these cases the reason property will be omitted.

在失败的情况下，属性状态对应于SecurityResult状态代码。在此事件中不会发送状态为零，因为这表示成功的安全握手过程。可选属性原因由服务器提供，因此字符串的语言未知。但是大多数服务器可能会发送英文字符串服务器可以选择不发送原因，在这些情况下，将省略属性。

 

clipboard

The clipboard event is fired when the server has sent clipboard data. The detail property is an Object containing the property text which is a DOMString with the clipboard data.

服务器发送剪贴板数据时会触发剪贴板事件。 detail属性是一个包含属性文本的Object，它是带有剪贴板数据的DOMString。

 

bell

The bell event is fired when the server has requested an audible bell.

当服务器请求响铃时，会触发铃声事件。

 

desktopname

The desktopname event is fired when the name of the remote desktop changes. The detail property is an Object with the property name which is a DOMString specifying the new name.

当远程桌面的名称更改时，将触发desktopname事件。 detail属性是一个Object，其属性名称是指定新名称的DOMString。

 

capabilities

The capabilities event is fired whenever an entry is added or removed from RFB.capabilities. The detail property is an Object with the property capabilities containing the new value of RFB.capabilities.

只要在RFB.capabilities中添加或删除条目，就会触发capabilities事件。 detail属性是一个Object，其属性功能包含RFB.capabilities的新值。

 

RFB.disconnect()

The RFB.disconnect() method is used to disconnect from the currently connected server.

RFB.disconnect（）方法用于断开与当前连接的服务器的连接。

 

Syntax（语法）

RFB.disconnect( );

RFB.sendCredentials()

The RFB.sendCredentials() method is used to provide the missing credentials after a credentialsrequired event has been fired.

RFB.sendCredentials（）方法用于在触发凭证所需事件后提供缺少的凭据。

 

Syntax

RFB.sendCredentials( credentials );

Parameters

credentials（证书）

• An Object specifying the credentials to provide to the server when authenticating. See RFB() for details.
• 一个Object，指定在进行身份验证时提供给服务器的凭据。有关详细信息，请参阅RFB（）。

 

RFB.sendKey()

The RFB.sendKey() method is used to send a key event to the server.

RFB.sendKey（）方法用于将密钥事件发送到服务器。

 

Syntax

RFB.sendKey( keysym, code [, down] );

Parameters

keysym

• A long specifying the RFB keysym to send. Can be 0 if a valid code is specified.
• 指定要发送的RFB密钥的long。如果指定了有效代码，则可以为0。

code

• A DOMString specifying the physical key to send. Valid values are those that can be specified toKeyboardEvent.code. If the physical key cannot be determined then null shall be specified.
• 指定要发送的物理密钥的DOMString。有效值是可以指定给KeyboardEvent.code的值。如果无法确定物理密钥，则应指定null。

down Optional

• A boolean specifying if a press or a release event should be sent. If omitted then both a press and release event are sent.
• 一个布尔值，指定是否应发送按下或释放事件。如果省略，则发送按下和释放事件。

 

RFB.sendCtrlAltDel()

The RFB.sendCtrlAltDel() method is used to send the key sequence left Control, left Alt, Delete. This is a convenience wrapper around RFB.sendKey().

RFB.sendCtrlAltDel（）方法用于发送左键Control，左Alt，Delete的键序列。这是RFB.sendKey（）的便利包装器。

 

Syntax

RFB.sendCtrlAltDel( );

RFB.focus()

The RFB.focus() method sets the keyboard focus on the remote session. Keyboard events will be sent to the remote server after this point.

RFB.focus（）方法将键盘焦点设置在远程会话上。此后，键盘事件将发送到远程服务器。

 

Syntax

RFB.focus( );

RFB.blur()

The RFB.blur() method remove keyboard focus on the remote session. Keyboard events will no longer be sent to the remote server after this point.

RFB.blur（）方法删除远程会话上的键盘焦点。此后，键盘事件将不再发送到远程服务器。

 

Syntax

RFB.blur( );

RFB.machineShutdown()

The RFB.machineShutdown() method is used to request to shut down the remote machine. The capability power must be set for this method to have any effect.

RFB.machineShutdown（）方法用于请求关闭远程计算机。必须为此方法设置能力才能产生任何效果。

 

Syntax

RFB.machineShutdown( );

RFB.machineReboot()

The RFB.machineReboot() method is used to request a clean reboot of the remote machine. The capability power must be set for this method to have any effect.

RFB.machineReboot（）方法用于请求彻底重启远程计算机。必须为此方法设置能力才能产生任何效果。

 

Syntax

RFB.machineReboot( );

RFB.machineReset()

The RFB.machineReset() method is used to request a forced reset of the remote machine. The capability power must be set for this method to have any effect.

RFB.machineReset（）方法用于请求强制重置远程计算机。必须为此方法设置能力才能产生任何效果。

 

Syntax

RFB.machineReset( );

RFB.clipboardPasteFrom()

The RFB.clipboardPasteFrom() method is used to send clipboard data to the remote server.

RFB.clipboardPasteFrom（）方法用于将剪贴板数据发送到远程服务器。

 

Syntax

RFB.clipboardPasteFrom( text );

Parameters

text

• A DOMString specifying the clipboard data to send. Currently only characters from ISO 8859-1 are supported.
• 指定要发送的剪贴板数据的DOMString。目前仅支持ISO 8859-1中的字符。