guigo

package module
v0.0.0-...-8562607 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 33 Imported by: 0

README

GUIGo PkgGoDev

轻量、基于系统 WebView 的 Go 语言图形界面库

安装指南

go get -u github.com/xiaoqidun/guigo

应用案例

OFDGo:基于 GUIGo 构建桌面版 OFD、PDF 阅读与编辑工具

系统依赖

Windows

系统未内置时需安装 Microsoft Edge WebView2

Linux(Debian 13,Ubuntu 24.04/26.04)

apt-get install libwebkitgtk-6.0-4

授权协议

本项目使用 Apache License 2.0 授权协议

Documentation

Overview

Package guigo 轻量、基于系统 WebView 的 Go 语言图形界面库

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrUnsupportedPlatform 表示当前平台没有可用宿主实现
	ErrUnsupportedPlatform = errors.New("unsupported platform")
	// ErrCanceled 表示用户取消对话框
	ErrCanceled = errors.New("dialog canceled")
	// ErrClosed 表示窗口已经关闭
	ErrClosed = errors.New("window closed")
)
View Source
var ErrAssociationElevationRequired = errors.New("administrator privileges required")

ErrAssociationElevationRequired 表示所有用户范围需要以管理员权限运行

View Source
var ErrPrintBusy = errors.New("another print operation is active")

ErrPrintBusy 表示当前视图仍在处理另一个直接打印作业

View Source
var ErrPrintUnsupported = errors.New("requested printing capability is unavailable")

ErrPrintUnsupported 表示当前运行时没有请求的打印能力

View Source
var ErrTrayUnavailable = errors.New("system tray is unavailable")

ErrTrayUnavailable 表示当前桌面没有可用托盘宿主

Functions

func DefaultUserDataDir

func DefaultUserDataDir(appID string) (string, error)

DefaultUserDataDir 返回应用的默认浏览器数据目录,不创建或删除目录 目录位于os.UserCacheDir返回的位置下,使用guigo/应用标识作为子目录,Windows使用GUIGo目录名 入参: appID 稳定的应用标识 返回: string 绝对目录路径, error 参数或路径错误

func OpenURL

func OpenURL(rawURL string) error

OpenURL 使用系统默认浏览器打开http或https地址 入参: rawURL 外部地址 返回: error 错误信息

func PageContext

func PageContext(ctx context.Context) context.Context

PageContext 返回调用所属页面的上下文,导航或关闭窗口时取消 入参: ctx 处理器收到的调用上下文 返回: context.Context 页面上下文,非宿主上下文原样返回

func RegisterFileAssociations

func RegisterFileAssociations(o AssociationOptions, scope AssociationScope) error

RegisterFileAssociations 登记指定范围的打开方式,不修改默认应用或自动提权 入参: o 应用配置, scope 作用范围 返回: error 登记错误

func Run

func Run(ctx context.Context, options Options) error

Run 运行窗口事件循环,关闭后返回,同一进程不支持同时运行多个实例 Windows使用调用线程,Linux使用进程内固定的GTK线程 浏览器数据在关闭、启动失败和版本升级时保留,删除由调用方负责 入参: ctx 运行上下文, options 宿主选项 返回: error 启动、运行或上下文错误

func SupportsWindowMaterial

func SupportsWindowMaterial(material WindowMaterial) bool

SupportsWindowMaterial 查询当前平台是否提供指定窗口材质 入参: material 窗口材质 返回: bool 是否支持

func UnregisterFileAssociations

func UnregisterFileAssociations(o AssociationOptions, scope AssociationScope) error

UnregisterFileAssociations 删除指定范围的专用键及公共键中的应用值,不自动提权 入参: o 应用配置, scope 作用范围 返回: error 撤销错误

Types

type AssociationOptions

type AssociationOptions struct {
	// AppID 指定应用标识及专用注册表键名
	AppID string
	// Name 指定系统显示的应用名称
	Name string
	// Description 指定系统默认应用设置中的说明
	Description string
	// Executable 指定现有程序的绝对路径,不复制程序
	Executable string
	// Arguments 指定文件路径之前的固定启动参数
	Arguments []string
	// IconIndex 指定可执行文件内的图标索引
	IconIndex int
	// Types 指定需要登记的完整文件类型集合
	Types []FileAssociation
}

AssociationOptions 定义应用专用注册表资源,由调用方保持标识和类型集合稳定 应用能力保存在Software\<AppID>.FileAssociations,文件类型保存在Software\Classes\<AppID>.<ID> 撤销会整树删除专用键,不保留其中自行添加或修改的内容

type AssociationScope

type AssociationScope string

AssociationScope 指定独立管理的文件关联范围

const (
	// AssociationUser 仅登记当前用户的文件关联
	AssociationUser AssociationScope = "user"
	// AssociationMachine 登记所有用户可用的文件关联,需要管理员权限
	AssociationMachine AssociationScope = "machine"
)

type AssociationStatus

type AssociationStatus struct {
	// Supported 表示当前平台实现了文件关联
	Supported bool `json:"supported"`
	// Registered 表示该范围仍有本应用的登记资源
	Registered bool `json:"registered"`
	// Complete 表示类型和打开命令与当前配置完全一致
	Complete bool `json:"complete"`
	// Writable 表示当前进程权限允许操作该范围,实际写入仍可能失败
	Writable bool `json:"writable"`
}

AssociationStatus 描述指定范围内的登记状态,不代表用户已选择为默认应用

func QueryFileAssociations

func QueryFileAssociations(o AssociationOptions, scope AssociationScope) (AssociationStatus, error)

QueryFileAssociations 查询指定范围的登记状态,不修改注册表 入参: o 应用配置, scope 作用范围 返回: AssociationStatus 登记状态, error 查询错误

type BridgeError

type BridgeError struct {
	// Name 指定JavaScript错误名称,空值使用Error
	Name string
	// Code 指定业务错误代码,空值不传递
	Code string
	// Message 指定错误说明
	Message string
}

BridgeError 定义传递给JavaScript的结构化错误

func (*BridgeError) Error

func (e *BridgeError) Error() string

Error 返回错误说明 返回: string 错误信息

type DialogOptions

type DialogOptions struct {
	// Title 指定对话框标题
	Title string
	// DefaultPath 指定初始目录或文件路径
	DefaultPath string
	// DefaultName 指定初始文件名,目录选择时不使用
	DefaultName string
	// Filters 指定可选文件类型,目录选择时不使用
	Filters []FileFilter
}

DialogOptions 定义原生文件对话框

type FileAssociation

type FileAssociation struct {
	// ID 指定应用内唯一类型标识,最终ProgID由AppID和ID以点连接
	ID string
	// Name 指定文件类型的显示名称
	Name string
	// Extensions 指定带点的扩展名,同一配置内不重复
	Extensions []string
}

FileAssociation 定义应用支持的文件类型

type FileFilter

type FileFilter struct {
	// Name 指定文件类型的显示名称
	Name string
	// Pattern 指定通配符,多个模式使用分号分隔
	Pattern string
}

FileFilter 定义文件类型,Pattern使用*.txt;*.md格式

type HandlerFunc

type HandlerFunc func(context.Context, any) (any, error)

HandlerFunc 异步处理页面调用,调用结束、取消或页面退出时取消上下文 返回带Discard的Result时,上下文保持到页面确认接收或调用取消 入参: ctx 调用上下文, args 已解码参数,二进制为[]byte 返回: any 可JSON编码的值或Result, error 错误信息

type Instance

type Instance struct {
	// contains filtered or unexported fields
}

Instance 持有当前用户及会话内的实例入口,关闭后允许后续进程接管

func OpenInstance

func OpenInstance(ctx context.Context, key string, data []byte, receive func(context.Context, []byte) error) (*Instance, error)

OpenInstance 创建实例入口,已有实例时转交消息并返回nil 首个实例不调用receive处理自己的消息,调用方自行处理初始请求 receive串行执行,应快速接收或入队;返回nil表示已接受,不表示业务已完成 receive应响应上下文取消,不得同步调用当前实例的Close receive返回ErrClosed时,发送方等待入口释放后重新竞争 不同用户、登录会话及Windows提升权限分别隔离,不修改窗口应用标识 入参: ctx 生命周期上下文, key 调用方实例键, data 转交消息,最大1MiB, receive 接收回调 返回: *Instance 首个实例入口或nil, error 创建或转交错误

func OpenWindowInstance

func OpenWindowInstance(ctx context.Context, key string, data []byte, receive func(context.Context, []byte) error) (*Instance, error)

OpenWindowInstance 优先转交到当前虚拟桌面最近激活的同组窗口,没有时创建入口 Windows按窗口实时所属桌面选择,其他平台沿用OpenInstance的复用范围 返回入口后应传入Options.Instance启动窗口,并在运行结束后关闭入口 窗口登记前同组启动会等待;消息接收及用户隔离约定与OpenInstance相同 入参: ctx 生命周期上下文, key 调用方实例键, data 转交消息, receive 接收回调 返回: *Instance 新窗口入口或nil, error 创建或转交错误

func (*Instance) Close

func (i *Instance) Close() error

Close 停止接收并释放实例入口,可重复调用 返回: error 关闭错误

type Options

type Options struct {
	// Instance 指定OpenWindowInstance返回的入口,创建窗口时自动登记,调用方负责关闭入口
	Instance *Instance
	// AppID 指定稳定的应用标识,长度不超过128字节,以英文字母开头,不以点结尾
	// 允许英文字母、数字、点和连字符,保留大小写,不随程序版本或位置变化
	// Windows用于窗口身份,Linux用于程序名称
	AppID string
	// Title 指定窗口标题
	Title string
	// TitleBar 指定标题栏模式,零值使用系统标题栏
	TitleBar TitleBarMode
	// TitleBarColors 指定内容标题栏配色,零值保留系统外观,非零值需完整提供四种颜色
	TitleBarColors TitleBarColors
	// WindowMaterial 指定窗口材质,零值保持纯色,仅Windows11版本22621及以上支持云母Alt和亚克力
	// 页面根元素及需要显示材质的区域使用透明背景,其余区域保留自身底色
	// 材质背景由系统绘制,TitleBarColors用于决定明暗及文字颜色,不支持材质时返回错误
	WindowMaterial WindowMaterial
	// Icon 指定正方形PNG窗口图标数据,边长不超过2048像素,数据不超过16MiB,与IconPath互斥
	Icon []byte
	// IconPath 指定外置PNG图标路径,格式及尺寸限制与Icon一致,两者互斥
	IconPath string
	// Width 指定初始客户区宽度,零值使用1024逻辑像素
	Width int
	// Height 指定初始客户区高度,零值使用768逻辑像素
	Height int
	// MinWidth 指定最小客户区宽度,零值表示不限制
	MinWidth int
	// MinHeight 指定最小客户区高度,零值表示不限制
	MinHeight int
	// MaxWidth 指定最大客户区宽度,零值表示不限制,Linux仅约束初始尺寸及SetSize
	MaxWidth int
	// MaxHeight 指定最大客户区高度,零值表示不限制,Linux仅约束初始尺寸及SetSize
	MaxHeight int
	// FixedSize 禁止用户调整窗口大小,程序仍可调用SetSize
	FixedSize bool
	// Center 在首次显示前将可见边框按所在屏幕工作区居中,可调整窗口同时限制初始尺寸
	// Linux由窗口管理器决定窗口位置,GTK4不支持强制居中
	Center bool
	// Maximized 指定首次显示时最大化,FixedSize启用时忽略
	Maximized bool
	// UserDataDir 指定持久数据目录,优先于AppID,两者至少设置一个,目录由调用方清理
	// 相对路径基于当前工作目录,便携程序可传入可执行文件所在目录下的绝对路径
	UserDataDir string
	// LibraryPath 指定原生运行时模块的路径,空值查找系统安装的运行时
	LibraryPath string
	// EntryPath 指定资源入口路径,空值使用根路径
	EntryPath string
	// FS 提供内嵌或外置静态资源,Handler非空时不使用
	FS fs.FS
	// Handler 并发处理本地资源请求,不启动网络服务
	Handler http.Handler
	// ResourceHandler 优先提供可寻址资源,返回nil, nil时使用Handler
	ResourceHandler func(*http.Request) (*Resource, error)
	// Bindings 注册页面可调用的方法,处理器可能并发执行
	Bindings map[string]HandlerFunc
	// OnReady 在宿主就绪且首次导航前调用,回调返回后才加载页面
	OnReady func(*Window)
	// OnTitleBarChanged 在OnReady返回后于后台串行接收初始布局及布局、激活、最大化或DPI变化,可调用Window方法
	// 快速变化可合并为最新状态,回调不应阻塞,关闭时未交付的通知可丢弃
	OnTitleBarChanged func(TitleBarInfo)
	// OnClosing 返回是否允许用户关闭窗口,上下文取消时直接关闭
	OnClosing func(context.Context) bool
	// OnClose 在窗口退出后调用,回调结束后Run返回
	OnClose func()
	// OnDrop 在后台协程接收系统文件拖放的路径,多次回调可能并发执行
	OnDrop func([]string)
	// OnError 接收异步操作错误,多次回调可能并发执行
	OnError func(error)
}

Options 定义窗口、资源和生命周期配置,客户区尺寸单位为逻辑像素

type PrintCapabilities

type PrintCapabilities struct {
	// SystemDialog 表示支持系统打印窗口
	SystemDialog bool `json:"systemDialog"`
	// BrowserDialog 表示支持WebView内置打印窗口
	BrowserDialog bool `json:"browserDialog"`
	// DialogCompletion 表示打印窗口返回前底层已结束消费页面内容
	DialogCompletion bool `json:"dialogCompletion"`
	// Direct 表示支持按设备选项直接提交打印
	Direct bool `json:"direct"`
	// PageRanges 表示直接打印支持一基页码范围
	PageRanges bool `json:"pageRanges"`
	// DeviceSettings 表示支持指定设备、纸张及打印作业设置
	DeviceSettings bool `json:"deviceSettings"`
	// Backgrounds 表示支持显式控制背景打印
	Backgrounds bool `json:"backgrounds"`
	// HeadersFooters 表示支持显式控制浏览器页眉页脚
	HeadersFooters bool `json:"headersFooters"`
}

PrintCapabilities 描述运行时支持的打印机制,不代表打印机已连接或具备所有硬件功能

type PrintMargins

type PrintMargins struct {
	// Top 指定上边距,单位为毫米
	Top float64 `json:"top"`
	// Right 指定右边距,单位为毫米
	Right float64 `json:"right"`
	// Bottom 指定下边距,单位为毫米
	Bottom float64 `json:"bottom"`
	// Left 指定左边距,单位为毫米
	Left float64 `json:"left"`
}

PrintMargins 指定设备打印时的纸面边距

type PrintOptions

type PrintOptions struct {
	// Printer 指定系统队列名称,空值采用默认设备
	Printer string `json:"printer,omitempty"`
	// Orientation 指定portrait或landscape,空值采用系统默认方向
	Orientation string `json:"orientation,omitempty"`
	// Width 指定未旋转纸张宽度,单位为毫米,与Height同时设置
	Width float64 `json:"width,omitempty"`
	// Height 指定未旋转纸张高度,单位为毫米,与Width同时设置
	Height float64 `json:"height,omitempty"`
	// Margins 指定应用方向后物理纸面的毫米边距,nil采用系统默认值
	Margins *PrintMargins `json:"margins,omitempty"`
	// Scale 指定0.1至2之间的缩放比例,1表示100%,零值采用系统默认值
	Scale float64 `json:"scale,omitempty"`
	// Copies 指定1至999之间的份数,零值采用系统默认值
	Copies int `json:"copies,omitempty"`
	// Collation 指定collated或uncollated,空值采用系统默认顺序
	Collation string `json:"collation,omitempty"`
	// Color 指定color或grayscale,空值采用系统默认颜色
	Color string `json:"color,omitempty"`
	// Duplex 指定simplex、longEdge或shortEdge,空值采用系统默认单双面
	Duplex string `json:"duplex,omitempty"`
	// PageRanges 指定一基闭区间,如1-3,5,空值打印全部页面
	PageRanges string `json:"pageRanges,omitempty"`
	// PagesPerSide 指定每面1、2、4、6、9或16页,零值采用系统默认值
	PagesPerSide int `json:"pagesPerSide,omitempty"`
	// Backgrounds 控制背景打印,nil采用系统默认值
	Backgrounds *bool `json:"backgrounds,omitempty"`
	// HeadersFooters 控制浏览器页眉页脚,nil采用系统默认值
	HeadersFooters *bool `json:"headersFooters,omitempty"`
}

PrintOptions 设置当前顶层文档的直接打印参数,长度以毫米为单位 调用方负责准备完整文档、分页和资源就绪,并在底层消费结束前保留内容

type PrintPaper

type PrintPaper struct {
	// ID 保存驱动或打印服务的纸张标识
	ID string `json:"id"`
	// Name 保存纸张显示名称
	Name string `json:"name"`
	// Width 保存未旋转纸张宽度,单位为毫米
	Width float64 `json:"width"`
	// Height 保存未旋转纸张高度,单位为毫米
	Height float64 `json:"height"`
}

PrintPaper 保存设备支持的纸张,宽高按未旋转方向以毫米表示

type PrintRectangle

type PrintRectangle struct {
	// X 指定区域左边位置,单位为毫米
	X float64 `json:"x"`
	// Y 指定区域上边位置,单位为毫米
	Y float64 `json:"y"`
	// Width 指定区域宽度,单位为毫米
	Width float64 `json:"width"`
	// Height 指定区域高度,单位为毫米
	Height float64 `json:"height"`
}

PrintRectangle 保存以物理纸张左上角为原点的毫米区域

type PrintResult

type PrintResult struct {
	// Submitted 表示底层已接受提交,不代表设备出纸或作业完成
	Submitted bool `json:"submitted"`
}

PrintResult 表示作业已提交,不确认实体打印机已经出纸

type PrinterInfo

type PrinterInfo struct {
	// Name 指定系统队列名称
	Name string `json:"name"`
	// Default 表示当前系统默认队列
	Default bool `json:"default"`
}

PrinterInfo 标识系统打印队列,不表示设备一定在线

type PrinterProfile

type PrinterProfile struct {
	// Printer 保存实际查询的系统队列
	Printer PrinterInfo `json:"printer"`
	// Options 保存已解析默认值的设备选项,纸张宽高仍为未旋转尺寸
	Options PrintOptions `json:"options"`
	// Papers 保存设备声明支持的纸张
	Papers []PrintPaper `json:"papers"`
	// Width 保存应用方向后的物理纸面宽度,单位为毫米
	Width float64 `json:"width"`
	// Height 保存应用方向后的物理纸面高度,单位为毫米
	Height float64 `json:"height"`
	// PrintableArea 保存当前纸面坐标下的硬件可打印区域
	PrintableArea PrintRectangle `json:"printableArea"`
	// Color 表示设备支持彩色打印
	Color bool `json:"color"`
	// Duplex 表示设备支持自动双面,具体翻转方式仍需逐项查询
	Duplex bool `json:"duplex"`
	// MaxCopies 保存设备单次作业的份数上限
	MaxCopies int `json:"maxCopies"`
	// CustomPaper 表示设备支持自定义纸张,具体尺寸仍需查询校验
	CustomPaper bool `json:"customPaper"`
	// Properties 表示平台支持系统设备属性窗口
	Properties bool `json:"properties"`
	// Fingerprint 标识当前设置及设备几何信息,供提交前重新查询比较
	Fingerprint string `json:"fingerprint"`
}

PrinterProfile 是一次设备设置查询的独立结果,不缓存为永久设备能力

type Rect

type Rect struct {
	// X 指定矩形左边位置
	X float64 `json:"x"`
	// Y 指定矩形上边位置
	Y float64 `json:"y"`
	// Width 指定非负矩形宽度,零值表示空矩形
	Width float64 `json:"width"`
	// Height 指定非负矩形高度,零值表示空矩形
	Height float64 `json:"height"`
}

Rect 定义相对客户区左上角的逻辑像素矩形,不随页面缩放变化

type Resource

type Resource struct {
	// StatusCode 指定HTTP响应状态码,零值使用200
	StatusCode int
	// Header 指定响应头,nil表示不附加响应头
	Header http.Header
	// Body 提供可寻址响应流,返回资源后由宿主负责关闭
	Body io.ReadSeekCloser
}

Resource 提供已就绪的可寻址响应流,Body所有权交给宿主并由宿主关闭 ResourceHandler返回nil, nil时回退到Handler或FS 状态码默认200,范围请求需由处理器提供正确状态和范围内容

type Result

type Result struct {
	// Value 指定可JSON编码的结果
	Value any
	// Discard 在结果未交付时异步释放资源,页面确认接收后不再调用
	Discard func()
}

Result 保存调用结果及页面未接收时的资源释放操作

type TitleBarColors

type TitleBarColors struct {
	// Background 指定激活时的背景色
	Background string `json:"background"`
	// Foreground 指定激活时的前景色
	Foreground string `json:"foreground"`
	// InactiveBackground 指定失焦时的背景色
	InactiveBackground string `json:"inactiveBackground"`
	// InactiveForeground 指定失焦时的前景色
	InactiveForeground string `json:"inactiveForeground"`
}

TitleBarColors 定义内容标题栏的激活及失焦配色,颜色使用#RRGGBB格式

type TitleBarInfo

type TitleBarInfo struct {
	// Height 指定内容标题栏的可见高度,系统模式为零,同一DPI下不随最大化状态变化
	Height float64 `json:"height"`
	// Left 指定标题栏左侧系统窗口按钮的保留宽度
	Left float64 `json:"left"`
	// Right 指定标题栏右侧系统窗口按钮的保留宽度
	Right float64 `json:"right"`
	// Active 表示窗口处于激活状态
	Active bool `json:"active"`
	// Maximized 表示窗口已经最大化
	Maximized bool `json:"maximized"`
	// Colors 提供与系统按钮区域共用的内容标题栏配色,零值使用系统外观
	Colors TitleBarColors `json:"colors"`
	// Material 提供窗口材质,非纯色材质需要页面使用透明背景
	Material WindowMaterial `json:"material"`
}

TitleBarInfo 保存逻辑像素标题栏布局和窗口状态

type TitleBarMode

type TitleBarMode uint8

TitleBarMode 定义窗口标题栏的显示方式

const (
	// TitleBarSystem 使用系统标题栏,为默认值
	TitleBarSystem TitleBarMode = iota
	// TitleBarContent 将内容延伸到标题栏,保留系统窗口按钮
	// Windows下禁用浏览器缩放和捏合缩放,避免内容与系统按钮错位
	TitleBarContent
)

type Tray

type Tray struct {
	// contains filtered or unexported fields
}

Tray 持有窗口所属的系统托盘,可由后台协程操作,随窗口销毁而释放 托盘宿主丢失且无法恢复时窗口会重新显示,调用方可用Available查询当前状态

func (*Tray) Available

func (t *Tray) Available() bool

Available 查询托盘是否已注册且尚未关闭,不表示当前图标一定展开显示 返回: bool 托盘当前是否可用

func (*Tray) Close

func (t *Tray) Close() error

Close 移除托盘,不关闭窗口,重复调用或窗口已销毁时返回成功 已开始执行的回调不受影响 返回: error 移除错误

func (*Tray) SetOptions

func (t *Tray) SetOptions(options TrayOptions) error

SetOptions 完整替换托盘配置,包括回调,零值含义与NewTray相同 更新时可关闭已展开的菜单,已开始执行的回调不受影响 入参: options 新托盘配置,图标及菜单数据在返回前复制 返回: error 配置或更新错误,已关闭时返回ErrClosed

type TrayItem

type TrayItem struct {
	// ID 指定菜单项标识,在整个菜单树内唯一,由OnSelect接收,分隔线可省略
	ID string
	// Label 指定菜单项显示文字,按原文显示,不解释为助记键标记
	Label string
	// Disabled 禁止选择当前菜单项
	Disabled bool
	// Hidden 隐藏当前菜单项及其子菜单
	Hidden bool
	// Separator 将当前项显示为分隔线,不设置文字、选中状态及子菜单
	Separator bool
	// Checked 指定选中状态,nil表示普通菜单项,点击后由调用方通过SetOptions更新
	Checked *bool
	// Radio 将选中标记显示为单选圆点,需要同时设置Checked,分组互斥由调用方维护
	Radio bool
	// Children 指定子菜单,非空时当前项仅打开子菜单,不触发OnSelect
	Children []TrayItem
}

TrayItem 定义托盘菜单项,支持子菜单、分隔线及由调用方维护的选中状态

type TrayOptions

type TrayOptions struct {
	// Title 指定托盘标题和提示文字,空值使用创建窗口时的标题,Windows提示最多127个UTF16编码单元
	Title string
	// Icon 指定PNG图标数据,与IconPath互斥,格式及尺寸限制与Options.Icon一致
	// Icon和IconPath均为空时使用创建窗口时的图标,窗口也未指定时使用系统默认图标
	Icon []byte
	// IconPath 指定外置PNG图标路径,调用时读取,之后不依赖该文件
	IconPath string
	// Items 指定菜单树,空值表示没有菜单
	Items []TrayItem
	// MenuOnActivate 在主激活时打开菜单而不调用OnActivate,桌面也可能将所有点击统一为菜单操作
	MenuOnActivate bool
	// OnSelect 在后台协程接收启用菜单项的ID,多次回调可能并发执行
	OnSelect func(string)
	// OnActivate 在后台协程接收系统激活操作,多次回调可能并发执行
	OnActivate func()
	// OnSecondaryActivate 接收次要激活操作,如鼠标中键,具体手势由桌面决定
	// 回调在后台协程执行,多次回调可能并发执行
	OnSecondaryActivate func()
}

TrayOptions 定义托盘图标、菜单和交互回调

type Window

type Window struct {
	// contains filtered or unexported fields
}

Window 持有窗口宿主,由OnReady提供,所有公开方法可由后台协程调用

func (*Window) Activate

func (w *Window) Activate() error

Activate 请求恢复并显示窗口,是否获得焦点由桌面系统决定 首屏加载完成前调用时,窗口仍按正常启动流程显示 返回: error 请求投递错误

func (*Window) Close

func (w *Window) Close() error

Close 请求关闭窗口,OnClosing和页面beforeunload可以取消此次请求 返回: error 请求投递错误

func (*Window) Emit

func (w *Window) Emit(name string, value any) error

Emit 向页面发送命名事件,返回值表示消息已交给宿主而非页面已消费 入参: name 非空事件名称, value 可JSON编码的数据 返回: error 错误信息

func (*Window) Hide

func (w *Window) Hide() error

Hide 隐藏窗口但保留宿主,首次页面加载完成后仍保持隐藏,可用Activate恢复 调用方应保留托盘或其他恢复入口 返回: error 请求投递错误

func (*Window) ListPrinters

func (w *Window) ListPrinters(ctx context.Context) ([]PrinterInfo, error)

ListPrinters 查询当前系统队列,返回空列表时没有可用设备,调用方可提供文件输出 入参: ctx 查询上下文 返回: []PrinterInfo 系统打印队列, error 查询或取消错误

func (*Window) NewTray

func (w *Window) NewTray(options TrayOptions) (*Tray, error)

NewTray 为当前窗口创建独立托盘,可创建多个,随窗口销毁而释放 Windows使用系统通知区域,Linux需要支持StatusNotifierItem和DBusMenu的桌面宿主 无可用宿主时返回ErrTrayUnavailable,未适配的平台返回ErrUnsupportedPlatform 入参: options 托盘配置,图标及菜单数据在返回前复制 返回: *Tray 托盘句柄, error 创建错误

func (*Window) OpenDirectory

func (w *Window) OpenDirectory(o DialogOptions) (string, error)

OpenDirectory 选择已有目录 入参: o 对话框选项 返回: string 目录路径, error 错误信息,用户取消返回ErrCanceled

func (*Window) OpenFile

func (w *Window) OpenFile(o DialogOptions) (string, error)

OpenFile 选择单个已有文件 入参: o 对话框选项 返回: string 文件路径, error 错误信息,用户取消返回ErrCanceled

func (*Window) OpenFiles

func (w *Window) OpenFiles(o DialogOptions) ([]string, error)

OpenFiles 选择多个已有文件 入参: o 对话框选项 返回: []string 文件路径, error 错误信息,用户取消返回ErrCanceled

func (*Window) Print

func (w *Window) Print(ctx context.Context, options PrintOptions) (PrintResult, error)

Print 直接提交当前顶层文档,设备设置仍受打印机驱动能力约束 返回前内容须保持不变;取消上下文不保证撤回已经提交给系统的作业 入参: ctx 调用上下文, options 设备打印选项 返回: PrintResult 提交结果, error 配置、提交或取消错误

func (*Window) PrintCapabilities

func (w *Window) PrintCapabilities(ctx context.Context) (PrintCapabilities, error)

PrintCapabilities 查询当前窗口的打印接口能力,可从后台协程调用 入参: ctx 调用上下文 返回: PrintCapabilities 打印机制能力, error 查询或取消错误

func (*Window) QueryPrinter

func (w *Window) QueryPrinter(ctx context.Context, options PrintOptions) (PrinterProfile, error)

QueryPrinter 根据纸张、方向、颜色及双面请求读取设备可打印区域,不提交作业 空Printer选择系统默认设备;不支持的请求返回错误,不静默替换纸张或双面方式 入参: ctx 查询上下文, options 待核对设备设置 返回: PrinterProfile 设备能力及当前纸面, error 配置、查询或取消错误

func (*Window) ResourceURL

func (w *Window) ResourceURL(path string) string

ResourceURL 返回当前平台的宿主资源地址,不支持的平台返回空字符串 入参: path 资源路径 返回: string 宿主资源地址

func (*Window) SaveFile

func (w *Window) SaveFile(o DialogOptions) (string, error)

SaveFile 选择保存路径并提示覆盖已有文件 入参: o 对话框选项 返回: string 保存路径, error 错误信息,用户取消返回ErrCanceled

func (*Window) SetDragRegions

func (w *Window) SetDragRegions(regions []Rect) error

SetDragRegions 替换内容标题栏的原生拖动区域,空切片清除区域,系统模式返回错误 区域使用客户区逻辑像素,不随页面缩放变化,调用方负责排除交互控件并随布局更新 超出客户区的部分裁剪,系统按钮及调整大小的边缘优先,不改变页面内容或注入JS接口 入参: regions 拖动矩形集合,调用时复制,坐标和尺寸必须有限且尺寸非负 返回: error 设置错误

func (*Window) SetSize

func (w *Window) SetSize(width, height int) error

SetSize 修改客户区尺寸并遵循约束 入参: width 客户区宽度, height 客户区高度 返回: error 错误信息

func (*Window) SetTitle

func (w *Window) SetTitle(title string) error

SetTitle 修改窗口标题 入参: title 窗口标题 返回: error 错误信息

func (*Window) SetTitleBarColors

func (w *Window) SetTitleBarColors(colors TitleBarColors) error

SetTitleBarColors 更新内容标题栏配色,零值恢复系统外观,系统标题栏模式返回错误 入参: colors 激活及失焦配色,非零值必须完整提供四种#RRGGBB颜色 返回: error 配色、模式或窗口错误

func (*Window) SetWindowMaterial

func (w *Window) SetWindowMaterial(material WindowMaterial) error

SetWindowMaterial 更新窗口背景材质,不支持的材质返回错误 入参: material 窗口材质,纯色关闭系统背景材质 返回: error 材质或窗口错误

func (*Window) ShowPrintUI

func (w *Window) ShowPrintUI(ctx context.Context, kind string) error

ShowPrintUI 为当前顶层文档打开打印对话框,kind支持system、browser,空值采用system Windows返回表示对话框请求已交付,不能据此释放内容或认定打印成功 调用方可以监听页面afterprint,在对话框关闭后恢复界面;Linux取消返回ErrCanceled 入参: ctx 调用上下文, kind 打印窗口类型 返回: error 不支持、取消或窗口调用错误

func (*Window) ShowPrinterProperties

func (w *Window) ShowPrinterProperties(ctx context.Context, printer string) error

ShowPrinterProperties 打开系统设备属性,不修改调用方内容或自行提交作业 用户可能在系统窗口修改设备默认值,返回后调用方应重新查询设备并更新预览 入参: ctx 调用上下文, printer 系统队列名称 返回: error 不支持、取消或窗口调用错误

func (*Window) TitleBarInfo

func (w *Window) TitleBarInfo() (TitleBarInfo, error)

TitleBarInfo 返回当前标题栏布局和窗口状态 返回: TitleBarInfo 标题栏信息, error 查询错误

type WindowMaterial

type WindowMaterial uint8

WindowMaterial 定义窗口的背景材质

const (
	// WindowSolid 使用纯色窗口材质,为默认值
	WindowSolid WindowMaterial = iota
	// WindowMicaAlt 使用云母Alt窗口材质,对应Windows的DWMSBT_TABBEDWINDOW
	WindowMicaAlt
	// WindowAcrylic 使用亚克力窗口材质,对应Windows的DWMSBT_TRANSIENTWINDOW
	WindowAcrylic
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL