# Fastboard iOS SDK API 参考 (/zh-CN/api-reference/whiteboard/fastboard/ios)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
本页提供 **Fastboard iOS 1.4.6** 的 Swift API 参考,固定依赖 Whiteboard iOS 2.16.145,最低 iOS 12。房间操作在主线程、入房成功后调用。
## Fastboard 类 [#fastboard-类]
### createFastRoom [#createfastroom]
```swift
public class func createFastRoom(withFastRoomConfig config: FastRoomConfiguration) -> FastRoom
```
创建 `FastRoom` 实例。
**参数**
- `config`:`FastRoom` 实例的配置。详见 [FastRoomConfiguration](#roomconfig)。
**返回**
方法调用成功时返回 `FastRoom` 对象。
### FastRoomConfiguration [#fastroomconfiguration]
`FastRoomConfiguration` 类,提供初始化 `FastRoomConfiguration` 实例的方法。
```swift
public init(appIdentifier: String,
roomUUID: String,
roomToken: String,
region: Region,
userUID: String,
userPayload: FastUserPayload? = nil)
```
**参数**
- `appIdentifier`:String。互动白板项目的 AppIdentifier。详见[获取互动白板项目的安全密钥](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/setup-and-access/enable-service#获取互动白板项目的安全密钥)。
- `roomUUID`:String。房间的 UUID,即房间的唯一标识符。详见[创建房间](/zh-CN/api-reference/api-ref/whiteboard/restful/create-room)请求成功后响应包体中 `uuid` 参数的值。
- `roomToken`:String。房间的 Room Token,用于加入房间时的用户鉴权。可以通过以下方式获取:
- 调用[生成 Room Token](/zh-CN/api-reference/api-ref/whiteboard/restful/generate-room-token)。
- 在 app 服务端用代码生成,详见[在 app 服务端生成 Token](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/setup-and-access/generate-token#在-app-服务端生成-token)。
- `region`:数据中心。详见 [`Region`](#region)。
- `userUID`:String。用户的 UID,即用户的唯一标识符,字符串格式,不能超过 1024 字节。请确保同一房间内每个用户的 UID 唯一。
- `userPayload`:用户光标显示的用户信息,包括用户的昵称和头像。详见 [`FastUserPayload`](#fastuserpayload)。
### Region [#region]
数据中心,包含以下枚举:
- `CN`:中国杭州,服务区覆盖东亚、东南亚、以及其他数据中心未覆盖的地区。
- `US`:美国硅谷,服务区覆盖北美洲、南美洲。
- `SG`:新加坡,服务区覆盖新加坡、东亚、东南亚。
- `IN`:印度孟买,服务区覆盖印度。
- `EU`:欧洲(法兰克福),服务区覆盖欧洲。
### FastUserPayload [#fastuserpayload]
```swift
public init(nickName: String)
public init(nickName: String, avatar: String)
```
创建 `FastUserPayload` 时传入用户光标的昵称和可选头像 URL。1.4.6 的 `nickName`、`avatar` 和内部字典未声明为 public,业务不能直接读取或修改;需要变更时创建新的对象。
## FastRoom 类 [#fastroom-类]
`FastRoom` 类提供管理互动白板实时房间的方法。
### joinRoom [#joinroom]
```swift
public func joinRoom()
public func joinRoom(completionHandler: ((Result)->Void)? = nil)
```
### disconnectRoom [#disconnectroom]
```swift
public func disconnectRoom()
public func disconnectRoom(completionHandler: (() -> Void)?)
```
完成回调在挂起入房已取消且房间离开后触发。
### insertImg [#insertimg]
```swift
public func insertImg(_ src: URL, imageSize: CGSize)
```
插入图片。
该方法可以将指定的网络图片插入并展示到当前白板页面上。
**参数**
- `src`:URL。图片地址。请确保 app 客户端能够访问该 URL,否则图片无法正常展示。
- `imageSize`:CGSize。图片的尺寸。
### insertMedia [#insertmedia]
```swift
public func insertMedia(_ src: URL, title: String, completionHandler: ((String?)->Void)? = nil)
```
App ID 完成回调为 String?;参数无效、未取得 App ID 或会话已取消时可能为 nil;setup 失败也可能返回 ID。
### insertPptx [#insertpptx]
```swift
public func insertPptx(_ pages: [WhitePptPage],
title: String,
completionHandler: ((String?)->Void)? = nil)
public func insertPptx(uuid: String,
url: String,
title: String,
completionHandler: ((String?)->Void)? = nil)
```
App ID 完成回调为 String?;参数无效、未取得 App ID 或会话已取消时可能为 nil;setup 失败也可能返回 ID。
### insertStaticDocument [#insertstaticdocument]
```swift
public func insertStaticDocument(_ pages: [WhitePptPage],
title: String,
completionHandler: ((String?)->Void)? = nil)
```
App ID 完成回调为 String?;参数无效、未取得 App ID 或会话已取消时可能为 nil;setup 失败也可能返回 ID。
### followSystemPencilBehavior [#followsystempencilbehavior]
```swift
public static var followSystemPencilBehavior: Bool
```
默认值为 `true`。在 iPad 的常规尺寸类下,控制 SDK 是否跟随系统的 Apple Pencil 绘制偏好和双击动作。
- `true`:iOS 14 及以上跟随“仅使用 Apple Pencil 绘制”偏好;iOS 12.1 及以上安装 Pencil 双击交互,由当前 overlay 响应切换橡皮、返回上一工具或显示调色板。
- `false`:移除上述双击交互,是否仅使用 Pencil 绘制由房间 `drawOnlyApplePencil` 配置决定。
自定义 overlay 需实现对应的 Pencil 动作处理;此开关不提供手写涂鸦转文字等识别 API。
### addApp [#addapp]
```swift
public func addApp(_ param: WhiteAppParam, completionHandler: ((String?) -> Void)? = nil)
```
添加 App。lazy 模式或最小化状态可先返回 ID;eager 模式尝试等待 setup 并确认焦点,但 setup 异常可仅记录日志,仍可能返回 ID。返回 ID 不保证初始化或渲染成功;创建失败或未取得 ID 的结果按本端错误/空值接口处理。originSize 写入 attributes.originSize。 App ID 完成回调为 String?;参数无效、未取得 App ID 或会话已取消时可能为 nil;setup 失败也可能返回 ID。
### focusApp [#focusapp]
```swift
public func focusApp(_ appId: String, completionHandler: @escaping (Bool, Error?) -> Void)
```
可等待的布尔值表示共享 focus、本端 Box 焦点和 zIndex 已提交;不表示 App setup 或首帧完成。
### insertPresentation [#insertpresentation]
```swift
public func insertPresentation(_ pages: [WhitePptPage],
title: String,
originSize: WhiteWindowOriginSize? = nil,
completionHandler: ((String?) -> Void)? = nil)
```
插入转换后的静态图片页,创建 Presentation;动态 ppt:// 和原始 PDF/PPT URL 需先转换。原有静态接口继续创建 DocsViewer。 App ID 完成回调为 String?;参数无效、未取得 App ID 或会话已取消时可能为 nil;setup 失败也可能返回 ID。
### dispatchDocsEvent [#dispatchdocsevent]
```swift
public func dispatchDocsEvent(_ event: WhiteWindowDocsEventKey,
options: WhiteWindowDocsEventOptions? = nil,
completionHandler: @escaping (Result) -> Void)
```
统一控制 MainView、DocsViewer、Slide、Presentation。target 省略时跟随焦点,或指定 mainView/appId;page 从 1 开始,scale=1 为适配尺寸。accepted 表示命令接收,拒绝时检查 reason/message;不保证渲染完成。 Swift 返回 `Result`;.success 中还需检查 accepted,业务拒绝和生命周期错误分别处理。
### getPageState [#getpagestate]
```swift
public func getPageState(_ options: WhiteWindowPageStateOptions? = nil,
completionHandler: @escaping (WhiteUnifiedPageState?, Error?) -> Void)
```
查询统一页面状态,返回 target、可选 appId、1-based page/pageCount、可选相对 scale。状态 target 为 mainView/DocsViewer/Slide/Presentation。
### querySlidePageState [#queryslidepagestate]
```swift
public func querySlidePageState(_ appId: String? = nil,
completionHandler: @escaping (WhiteSlidePageState?, Error?) -> Void)
```
查询当前焦点或指定 Slide App 的页码和总页数,页码从 1 开始。
### setSlideDelegate [#setslidedelegate]
```swift
public func setSlideDelegate(_ delegate: WhiteSlideDelegate?)
```
### updateWritable [#updatewritable]
```swift
public func updateWritable(_ writable: Bool, completion: ((Error?) -> Void)?)
```
在主线程且房间已加入后更新可写状态。completion 的 error 为空表示成功;未入房返回 notReady,已有修改进行中返回 busy,退出或会话切换可返回 operationCancelled。completion 参数没有默认值;无需结果时显式传 nil。
### 面板控制 [#面板控制]
```swift
public func dismissAllSubPanels()
public func setAllPanel(hide: Bool)
public func setPanelItemHide(item: FastRoomDefaultOperationIdentifier, hide: Bool)
```
在主线程调用。dismissAllSubPanels 收起所有展开的子面板;setAllPanel 控制全部面板显隐;setPanelItemHide 控制指定默认操作项的显隐。自定义覆盖层应实现对应控制方法。
## FastRoomThemeManager 类 [#fastroomthememanager-类]
`FastRoomThemeManager` 类提供设置白板用户界面主题的方法。
### apply [#apply]
```swift
public func apply(_ theme: FastRoomThemeAsset)
```
应用白板主题。
Fastboard SDK 在 iOS 13.0 或以上版本上默认跟随系统的主题设置,在早于 iOS 13.0 版本上默认使用浅色主题。如果默认的主题设置无法满足你的需要,你可以调用该方法应用 SDK 提供的预定义主题或自定义主题。
**参数**
- `theme`:白板主题.
- 预定义主题:
- `FastRoomDefaultTheme.defaultLightTheme`:浅色主题。
- `FastRoomDefaultTheme.defaultDarkTheme`:暗色主题。
- `FastRoomDefaultTheme.defaultAutoTheme`:自动主题,即跟随系统主题设置。该选项仅适用于 iOS 13.0 或以上版本。
- 自定义主题:详见 [FastRoomThemeAsset](#themeasset)。
**示例**
- 应用预定义的暗色主题:
```swift
FastRoomThemeManager.shared.apply(FastRoomDefaultTheme.defaultDarkTheme)
```
- 应用自定义主题:
```swift
let white = FastRoomWhiteboardAssets(whiteboardBackgroundColor: .green, containerColor: .yellow)
let control = FastRoomControlBarAssets(backgroundColor: .blue, borderColor: .gray, effectStyle: .init(style: .regular))
let panel = FastRoomPanelItemAssets(
normalIconColor: .black,
selectedIconColor: .red,
selectedIconBgColor: .clear,
highlightColor: .black,
highlightBgColor: .cyan,
disableColor: .gray,
subOpsIndicatorColor: .yellow,
pageTextLabelColor: .orange,
selectedBackgroundCornerradius: 4,
selectedBackgroundEdgeinset: .zero)
let theme = FastRoomThemeAsset(whiteboardAssets: white, controlBarAssets: control, panelItemAssets: panel)
FastRoomThemeManager.shared.apply(theme)
```
### FastRoomThemeAsset [#fastroomthemeasset]
白板主题样式。
```swift
open class FastRoomThemeAsset: NSObject {
@objc
public init(whiteboardAssets: FastRoomWhiteboardAssets,
controlBarAssets: FastRoomControlBarAssets,
panelItemAssets: FastRoomPanelItemAssets) {
self.whiteboardAssets = whiteboardAssets
self.controlBarAssets = controlBarAssets
self.panelItemAssets = panelItemAssets
}
@objc
open var whiteboardAssets: FastRoomWhiteboardAssets
@objc
open var controlBarAssets: FastRoomControlBarAssets
@objc
open var panelItemAssets: FastRoomPanelItemAssets
}
```
`FastRoomThemeAsset` 类包含如下属性:
- `whiteboardAssets`:白板的样式。详见 [FastRoomWhiteboardAssets](#whiteboardassets)。
- `controlBarAssets`:控制条的样式。详见 [FastRoomControlBarAssets](#controlbarassets)。
- `panelItemAssets`:按钮的样式。详见 [FastRoomPanelItemAssets](#panelitemassets)。
### FastRoomWhiteboardAssets [#fastroomwhiteboardassets]
白板的样式。
```swift
open class FastRoomWhiteboardAssets: NSObject {
@objc
public init(whiteboardBackgroundColor: UIColor, containerColor: UIColor) {
self.whiteboardBackgroundColor = whiteboardBackgroundColor
self.containerColor = containerColor
}
@objc
open var whiteboardBackgroundColor: UIColor
@objc
open var containerColor: UIColor
}
```
`FastRoomWhiteboardAssets` 类包含如下属性:
- `whiteboardBackgroundColor`:白板背景色。
- `containerColor`:挂载白板的 HTML 容器的颜色。
### FastRoomControlBarAssets [#fastroomcontrolbarassets]
控制条的样式。
```swift
open class FastRoomControlBarAssets: NSObject {
@objc
public init(backgroundColor: UIColor, borderColor: UIColor, effectStyle: UIBlurEffect? = nil) {
self.backgroundColor = backgroundColor
self.borderColor = borderColor
self.effectStyle = effectStyle
}
@objc
open var backgroundColor: UIColor
@objc
open var borderColor: UIColor
@objc
open var effectStyle: UIBlurEffect?
}
```
`FastRoomControlBarAssets` 包含如下属性:
- `backgroundColor`:控制条的背景色。
- `borderColor`:控制条边框的颜色。
- `effectStyle`:毛玻璃效果。详见 [UIBlurEffect](https://developer.apple.com/documentation/uikit/uiblureffect)。
### FastRoomPanelItemAssets [#fastroompanelitemassets]
按钮的样式。
```swift
open class FastRoomPanelItemAssets: NSObject {
@objc
public init(normalIconColor: UIColor,
selectedIconColor: UIColor,
selectedIconBgColor: UIColor,
highlightColor: UIColor,
highlightBgColor: UIColor,
disableColor: UIColor,
subOpsIndicatorColor: UIColor,
pageTextLabelColor: UIColor,
selectedBackgroundCornerradius: CGFloat,
selectedBackgroundEdgeinset: UIEdgeInsets) {
self.normalIconColor = normalIconColor
self.selectedIconColor = selectedIconColor
self.selectedIconBgColor = selectedIconBgColor
self.highlightColor = highlightColor
self.highlightBgColor = highlightBgColor
self.disableColor = disableColor
self.subOpsIndicatorColor = subOpsIndicatorColor
self.pageTextLabelColor = pageTextLabelColor
self.selectedBackgroundCornerRadius = selectedBackgroundCornerradius
self.selectedBackgroundEdgeinset = selectedBackgroundEdgeinset
}
@objc
open var selectedBackgroundCornerRadius: CGFloat
@objc
open var selectedBackgroundEdgeinset: UIEdgeInsets
@objc
open var normalIconColor: UIColor
@objc
open var selectedIconColor: UIColor
@objc
open var selectedIconBgColor: UIColor
@objc
open var highlightColor: UIColor
@objc
open var highlightBgColor: UIColor
@objc
open var disableColor: UIColor
@objc
open var subOpsIndicatorColor: UIColor
@objc
open var pageTextLabelColor: UIColor
}
```
`FastRoomPanelItemAssets` 类包含如下属性:
- `normalIconColor`:普通状态下(即按钮未被选中时),按钮图标的颜色。
- `selectedIconColor`:选中状态下按钮图标的颜色。
- `selectedIconBgColor`:选中状态下按钮的背景色。
- `highlightColor`:高亮状态下(即按钮被按住时),按钮图标的颜色。
- `highlightBgColor`:高亮状态下(即按钮被按住时),按钮的背景色。
- `disableColor`:不可点击状态下按钮的颜色。
- `subOpsIndicatorColor`:下拉按钮的颜色。
- `pageTextLabelColor`:页码的颜色。
- `selectedBackgroundCornerRadius`:选中状态的背景圆角。
- `selectedBackgroundEdgeinset` :选中状态的背景内边距。
## FastRoomDefaultOperationItem 类 [#fastroomdefaultoperationitem-类]
`FastRoomDefaultOperationItem` 类用于自定义白板用户界面上的操作组件。
### defaultColors [#defaultcolors]
```swift
public static var defaultColors: [UIColor]
```
调色盘默认的颜色集合。
你可以在该属性中传入自定义的 `[UIColor]` 对象,修改调色盘的颜色集合。通过该属性设置的调色盘颜色集合应用于铅笔、文字和图形等工具。
## 原生 SDK 与插件配置 [#原生-sdk-与插件配置]
```swift
config.whiteSdkConfiguration.useMultiViews = true
config.whiteSdkConfiguration.enableAppliancePlugin = true
let pluginOptions = WhiteAppliancePluginOptions()
pluginOptions.extras = ["useBackgroundThread": true]
config.whiteRoomConfig.appliancePluginOptions = pluginOptions
```
在 Fastboard.createFastRoom 前配置。入房成功后可用 fastRoom.room 与 fastRoom.whiteSDK;回调通过 commonDelegate、roomDelegate、setSlideDelegate 设置。详见[教具插件文档](/zh-CN/realtime-media/whiteboard/fastboard-sdk/build/appliance-plugin/overview?platform=ios)。