视频播放器（videoplayer）

选择器： videoplayer · 设计器组件： 视频播放器 · 按名称： videoplayer#名称 或 #名称
支持库： 组件类库 → 视频播放器类 · 补全： sp / videoplayer / 视频播放器
对比： DIY 会话请用 视频类（预览到图片框）；本组件自带悬停控制条与伴音。

硬约束与叠画

1. 控件名来自窗口 XML「名称」；属性赋值无括号，方法调用必须带括号。
2. 事件写 函数 控件名.事件名(参数…)，形参名以本页事件表为准（如 当前值）。
3. 悬停条各功能可逐项 置显示* 开关；外观优先走本页 YSS（勿为换肤去改 DesignControl 布局）。
4. 需授权开通；无权限时工具箱不可落点、工程无法稳定编译进本组件。
5. 本地文件打开后会尝试 伴音（与画面同源）；网络 URL 一般无伴音。音量跟属性「音量」/悬停条音量条。

能力速览

能力	说明
播放 / 暂停 / 停止	停止=暂停并回 0ms，画面回品牌占位（无显式封面时）
进度	点击或拖动进度条均可跳转；亦可用 置进度
倍速	置倍速(百分数)；悬停条下拉 50/75/100/125/150/200
全屏	整屏铺满当前监视器；双击画面 / Esc / 全屏钮
封面	须 置封面(路径) 才作为暂停/停止封面；属性栏「封面」 alone 不会顶替未播放背景
未播放背景	无显式封面时绘制带呼吸光晕的「Y++视频播放器」品牌占位
水印	文字/图片水印、九宫格 1–9（5=居中）、模式开关
帧率	按源帧率 + 墙钟追帧，避免定时器慢于片源导致的「慢动作」

属性

属性	类型	读写	说明
源	文本	读写	当前源路径或 URL
封面	文本	读写	设计器路径缓存；未播放默认品牌占位。运行时要当封面须 置封面
播放列表	文本	读写	换行分隔的源列表
当前项	整数	读写	播放列表索引（从 0 起）
跳秒	整数	读写	快进/快退步长（秒），默认 10
音量	整数	读写	0–100（伴音与悬停条同步）
悬停条高度	整数	读写	底栏区域高度（像素，默认 40）；不改变按钮大小
功能控制位	（已废弃）		运行时忽略；默认全开。请用 置显示进度条 等
功能按钮位置	文本	读写	左对齐 / 居中 / 右对齐
按钮大小	整数	读写	功能按钮边长（像素，默认 28）
按钮间距	整数	读写	功能按钮默认间距（像素，默认 8）
自动播放	逻辑	读写	打开源后自动播放
循环	逻辑	读写	播完后循环
显示悬停条	逻辑	读写	真=悬停显示控制条；指针离开或静止约 3 秒后自动隐藏
文字色 / 背景色 / 圆角 / 边框…			外壳外观（亦可用 YSS）

方法

功能显示

方法	签名	说明
置显示悬停条 / 取显示悬停条	(逻辑) / ()	总开关
置显示进度条 / 取显示进度条
置显示音量 / 取显示音量
置显示上一个 / 取显示上一个		播放列表切集
置显示下一个 / 取显示下一个
置显示快退 / 取显示快退
置显示快进 / 取显示快进
置显示播放暂停 / 取显示播放暂停
置显示全屏 / 取显示全屏
置功能按钮位置 / 取功能按钮位置	0左/1中/2右
置按钮间距 / 取按钮间距	像素
置按钮后间距 / 取按钮后间距	(槽, 间距)	-1 恢复默认
置按钮图标 / 取按钮图标	(槽, 路径)	槽：0播放 1暂停 2上一个 3下一个 4快退 5快进 6音量 7全屏 8倍速；空=内置矢量；支持 SVG/PNG/JPG

播放控制

方法	签名	说明
播放 / 暂停 / 停止		见上表
是否播放中	() → 逻辑
取播放状态	() → 整数	0停止 1播放中 2暂停
置进度 / 取进度 / 取时长	毫秒
置跳秒 / 取跳秒	秒
切换全屏 / 是否全屏	()
置倍速 / 取倍速	百分数	100=1.0x

封面与水印

方法	签名	说明
置封面 / 取封面	(路径)	显式暂停/停止封面；空路径清除后回品牌占位
置文字水印 / 取文字水印	(文本, …)	可带不透明度、九宫格、字体类
置文字水印位置	(九宫格, [偏移X], [偏移Y])
置图片水印 / 取图片水印	(路径, [不透明度=70], …)	空路径清除
置图片水印位置	(九宫格, [偏移X], [偏移Y])
置水印模式 / 取水印模式	0–4	0自动 1仅文字 2仅图片 3两者 4关
切换水印 / 置水印位置 / 切换水印位置

九宫格（拨号盘 1–9）： 1左上 2顶中 3右上 4左中 5居中 6右中 7左下 8底中 9右下。

悬停条：点音量弹出竖条；点倍速下拉选档；点全屏或双击画面进入/退出整屏。

事件

事件	参数	说明
播完		当前源结束
播放错误	文本	打开/播放失败
进度改变	整数 当前值（毫秒）	点击/拖动进度条、播放推进
滑块按下 / 滑块松开	整数 当前值（毫秒）	进度条按下/松开（可选）
列表项改变	整数 当前项	上一个/下一个或程序置项
全屏切换	逻辑

函数 视频播放器1.进度改变 (整数 当前值) {
    标签状态.标题 = "进度 " + 到文本(当前值) + " / " + 到文本(视频播放器1.取时长()) + " ms"
}

进度条：点击与拖动都会跳到对应毫秒并继续播放（拖动中节流预览，松开精确定位）。

YSS 样式

写样式前先读窗体 XML 取控件 名称 与 typeId（videoplayer），见 window-xml.md。选择器别名：videoplayer ≡ 视频播放器。

已支持（可换肤）

1. 外壳（与按钮等通用键一致）

键	作用
background / background-color	控件底板（未铺视频帧时可见）
color	前景参考色
border-color / border-width / border-radius	描边与圆角
transparent-background	不铺底板
:hover / :pressed / :focus / :disabled	伪态映射到悬停/按下/焦点/禁用色槽

2. 底栏与进度（基选择器专用键，复用色槽、不改控件布局）

键	作用	内部色槽
chrome-background / chrome-color	悬停底栏实心色	pressedBackColor
track-color / progress-track-color	进度条轨道	disabledBackColor
progress-color / progress-fill-color / fill-color	进度已填充段	backColor2
item-hover-background / chrome-item-hover	底栏按钮悬停高亮	hoverBackColor

注意： 在视频播放器上写 track-color 不会改底板 background（与进度条控件不同）。未设置时用内置默认灰轨 / 蓝填充 / 半透底栏。

示例

视频播放器 {
    background: #0D0D0D;
    color: #F0F0F0;
    border-color: #3F3F46;
    border-width: 1;
    border-radius: 4;
    chrome-background: #101018cc;
    track-color: #505058;
    progress-color: #3B9EFF;
    item-hover-background: #3B9EFF55;
}

视频播放器:hover {
    border-color: #007ACC;
}

videoplayer#视频播放器1 {
    progress-color: #00C853;
}

尚未接线（勿依赖）

下列伪元素/子选择器目前不会生效（解析会忽略或匹配失败），请用上一节基选择器键：

• 视频播放器:chrome { … }
• 视频播放器:progress { … }
• 视频播放器:progress-fill { … }
• 视频播放器:item:hover { … }（请用 item-hover-background）

水印颜色/字体走 API（置文字水印 + 字体类），不走上述 YSS 键。品牌占位「Y++视频播放器」光晕为内置绘制，暂无 YSS 键。

通用外壳更多键见 YSS.md。

完整示例

函数 主窗口.创建完毕 () {
    视频播放器1.置显示悬停条(真)
    视频播放器1.置跳秒(15)
    视频播放器1.置功能按钮位置(1)
    视频播放器1.置按钮间距(12)
}

函数 按钮选视频.单击 (整数 X, 整数 Y) {
    文本 路径 = 打开文件对话框("选择视频", "", "视频|*.mp4;*.mkv;*.mov|所有|*.*")
    如果 (取文本长度(路径) <= 0) { 返回 }
    视频播放器1.源 = 路径
    视频播放器1.置文字水印("Y++", 80)
    视频播放器1.置水印位置(5)
    视频播放器1.播放()
}

函数 视频播放器1.进度改变 (整数 当前值) {
    输出("pos=" + 到文本(当前值))
}

函数 视频播放器1.播完 () {
    输出("ended")
}

窗体旁 .yss 放入上一节样式即可换底栏/进度色；改完保存后 F5 看运行时效果。