Help us shape the future of Go! Take the 2026 Go Developer Survey

guigo

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

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

 Go to latest Published: Oct 24, 2026 License: Apache-2.0 Imports: 28 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 ErrPrintBusy = errors.New("another print operation is active")

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

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

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

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 Run 

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

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

Types

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 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 Options 

type Options struct {
	// AppID 指定稳定的应用标识，长度不超过128字节，以小写字母开头，不以点结尾
	// 允许小写字母、数字、点和连字符，不随程序版本或位置变化
	AppID string
	// Title 指定窗口标题
	Title string
	// TitleBar 指定标题栏模式，零值使用系统标题栏
	TitleBar TitleBarMode
	// TitleBarColors 指定内容标题栏配色，零值保留系统外观，非零值需完整提供四种颜色
	TitleBarColors TitleBarColors
	// 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"`
}

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

type TitleBarMode 

type TitleBarMode uint8

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

const (
	// TitleBarSystem 使用系统标题栏，为默认值
	TitleBarSystem TitleBarMode = iota
	// TitleBarContent 将内容延伸到标题栏，保留系统窗口按钮
	TitleBarContent
)

type Window 

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

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

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) ListPrinters 

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

ListPrinters 查询当前系统队列，返回空列表时没有可用设备，调用方可提供文件输出 入参: ctx 查询上下文 返回: []PrinterInfo 系统打印队列, 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) 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 查询错误

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.