 的调用、返回值与桌面端实现原理)
Puter 应用开发取色指南puter.ui.showColorPicker() 的调用、返回值与桌面端实现原理【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterputer.ui.showColorPicker()是 Puter 前端 SDK 中用于向用户弹出颜色选择对话框的 UI API。无论是运行在 Puter 桌面中的 App还是通过 puter.js 接入的网站都可以用它快速获得一个原生风格的取色窗口并将用户选中的颜色直接应用到页面样式上。读完本文你将掌握该方法的三种调用形式、参数与返回值约定、完整的可运行示例以及从 puter.js SDK 到桌面 GUI 的整条消息链路实现细节。一、方法概述Puter 前端 SDK 将 UI 相关的对话框方法统一挂在puter.ui命名空间下showColorPicker()负责“让用户选择一个颜色”它在官方 API 文档 src/docs/src/UI/showColorPicker.md 中的原始定义是Presents the user with a color picker dialog allowing them to select a color.向用户展示一个允许其选择颜色的取色对话框。从文档 frontmatter 可以看到该方法声明的适用平台为platforms: [websites, apps]即同时覆盖两类运行场景apps运行在 Puter 桌面环境中的 App此时 SDK 与桌面窗口管理器通过postMessage消息通道协作websites把 puter.js 直接嵌入自有页面的“独立站点”模式此时 SDK 会降级使用页内 Web 组件渲染对话框。它和showFontPicker()、showDirectoryPicker()、showOpenFilePicker()、showSaveFilePicker()共同构成 Puter UI 的“选取器Picker”家族同类组件的清单可参考 src/puter-js/src/ui/components.md 中的组件总表。二、函数签名与三种调用形式文档给出了三种调用语法三种形式最终返回同一个 Promiseputer.ui.showColorPicker() puter.ui.showColorPicker(defaultColor) puter.ui.showColorPicker(options)2.1 无参数调用直接弹出取色窗口不带任何预设颜色puter.ui.showColorPicker().then((color) { // color 为用户选中的颜色 });2.2 传入默认颜色字符串puter.ui.showColorPicker(#3b82f6);传入的参数若为字符串会被 SDK 视为“默认选中的颜色”。这一点在 GUI 源码中也有印证src/gui/src/UI/UIWindowColorPicker.js 在创建窗口前会判断「第一个参数是否为字符串」是则将其作为默认颜色注入options.default。2.3 传入 options 对象puter.ui.showColorPicker({ defaultColor: #ff6b35, });SDK 中 src/puter-js/src/modules/UI.js 的ColorPickerOptions类型定义如下/** * Options that configure showColorPicker(). * * typedef {Object} ColorPickerOptions * property {string} [defaultColor] The color initially selected when the picker opens. */2.4 参数说明参数类型说明默认值defaultColorstring取色窗口打开时预选中的颜色桌面端#f00独立 Web 组件模式#3b82f6optionsobject配置对象当前核心字段为defaultColor{}options.defaultColorstring同上窗口打开时预选的颜色见上options.default/options.defaultValuestringdefaultColor的历史别名为兼容旧代码而保留无default与defaultValue这两个别名并非文档杜撰而是模块 JSDoc 中明确标注的兼容项src/puter-js/src/modules/UI.js/** * Shows a color picker. Resolves to the chosen color. Accepts either a * default color or an options object. default and defaultValue are * legacy aliases for defaultColor. */桌面 GUI 侧解析默认颜色时的优先级也完全一致见 src/gui/src/UI/UIWindowColorPicker.js 中options.defaultValue ?? options.defaultColor ?? options.default ?? #f00在 Puter 桌面端没有指定任何默认值时最终落到红色#f00。三、返回值与“取消”语义调用返回Promisestring即一个可直接用于 CSS 的颜色字符串puter.ui.showColorPicker().then((color) { document.body.style.backgroundColor color; // 直接把返回值赋给 CSS 属性 });值得开发者注意的细节桌面端返回的是带透明通道的 hex8 格式。桌面 GUI 在用户点击“选择”按钮后通过 src/gui/src/UI/UIWindowColorPicker.js 中colorPickerWidget.getHex8String()取色返回值形如#ff6b35ff前 6 位为 RGB后 2 位为 Alpha 通道。这是由底层取色控件的hex8String属性给出的见 src/gui/src/UI/UIColorPickerWidget.js 的 JSDoc 示例#ff0000ff。由于取色窗口本身带有 Alpha透明度滑杆因此选择任意半透明颜色都能被如实返回。这种 8 位十六进制写法在支持 CSS Color 4 的现代浏览器中可直接作为background-color、color、border-color等属性的值。用户取消选择时不会 resolve 出一个颜色。如果用户直接关闭取色窗口桌面 GUI 侧窗口的on_close回调会 resolve 为false经 IPC 消息映射后 SDK 侧收到的是undefined而在独立 Web 组件模式下response事件携带的detail为null。因此稳健的写法应当先判空再使用返回值。四、完整可运行示例4.1 官方文档示例src/docs/src/UI/showColorPicker.md 自带一个开箱即用的最小示例——用户选完颜色后整个页面背景随之改变html body script srchttps://js.puter.com/v2//script script puter.ui.showColorPicker().then((color){ document.body.style.backgroundColor color; }) /script /body /html4.2 带默认颜色与取消分支的完整示例在真实应用中建议同时处理默认颜色与用户取消两种情形html body stylebackground-color: #f5f7fa; font-family: sans-serif; button idpick选择主题色/button div idresult stylemargin-top: 12px; color: #333;尚未选择颜色/div script srchttps://js.puter.com/v2//script script document.getElementById(pick).addEventListener(click, () { puter.ui.showColorPicker({ defaultColor: #3b82f6 }).then((color) { // 用户取消关闭窗口时 color 为 null / undefined需先判空 if (!color) { document.getElementById(result).textContent 已取消选择; return; } document.body.style.backgroundColor color; document.getElementById(result).textContent 已选择颜色: color; }); }); /script /body /html这段代码演示了options传参、预选颜色、Promise 链式使用以及取消分支处理四个要点可直接复制到 Puter 或任何已引入 puter.js 的页面中运行。五、桌面端实现链路源码级解析要理解showColorPicker()在 Puter 桌面中的真实行为需要沿着“SDK → 桌面 GUI → 取色控件 → 回传”整条链路阅读源码。5.1 puter.js SDK 侧统一入口与分支SDK 的实现位于 src/puter-js/src/modules/UI.jsshowColorPicker (options) { if ( this.messageTarget ) { return new Promise((resolve) { this.#postMessageWithCallback(showColorPicker, resolve, { options: options ?? {} }); }); } // Standalone fallback: render web component return new Promise((resolve) { const opts typeof options string ? { defaultColor: options } : (options ?? {}); const el document.createElement(puter-color-picker); const defaultColor opts.defaultValue || opts.defaultColor || opts.default || #3b82f6; el.setAttribute(default-color, defaultColor); el.addEventListener(response, (e) resolve(e.detail)); document.body.appendChild(el); el.open(); }); };这段代码揭示了两个关键事实运行在 Puter 桌面App 模式存在messageTarget时SDK 通过#postMessageWithCallback发送showColorPicker消息给桌面 GUI由桌面窗口完成取色独立站点Website 模式无messageTarget时SDK 自动降级为在页面内创建puter-color-pickerWeb 组件。组件注册表见 src/puter-js/src/ui/registerComponents.js其中包含[puter-color-picker, PuterColorPicker]的映射。5.2 GUI 桌面端 IPC 处理与鉴权桌面 GUI 收到消息后的处理位于 src/gui/src/IPC.js。处理流程依次为鉴权检查若当前用户未登录会先尝试拉起注册窗口只有鉴权通过才继续否则直接 return参数归一化若options是字符串则转换成{ defaultColor: 字符串 }安全处理出于安全原因桌面端会强制清空外部传入的window_optionsevent.data.options.window_options {}防止 App 注入窗口行为关联父窗口将取色窗口的parent_uuid设置为请求方 App 的实例 ID保证窗口归属正确打开窗口调用UIWindowColorPicker(options)等待用户操作回传结果向请求方 iframe 发送colorPicked消息携带color: selected_color ? selected_color.color : undefined。// src/gui/src/IPC.js节选 else if ( event.data.msg showColorPicker ) { // Auth if ( !window.is_auth() !(await UIWindowSignup({ referrer: app_name })) ) return; // set options if ( typeof event.data.options string ) { event.data.options { defaultColor: event.data.options }; } event.data.options event.data.options ?? {}; // Clear window_options for security reasons event.data.options.window_options {}; event.data.options.window_options.parent_uuid event.data.appInstanceID; // Open color picker let selected_color await UIWindowColorPicker(event.data.options); ... }SDK 侧则通过 src/puter-js/src/modules/UI.js 中msg colorPicked的分支取出e.data.color触发注册的回调从而让.then()拿到颜色字符串else if ( e.data.msg colorPicked ) { // execute callback this.#callbackFunctionse.data.original_msg_id; }5.3 取色窗口与其底层控件桌面端的取色窗口由 src/gui/src/UI/UIWindowColorPicker.js 实现。该模块使用UIWindow创建一个标题为select_color本地化文案、宽度 350、不可调整大小、单实例single_instance: true的小窗口窗口内渲染两个核心元素挂载div classpicker的取色控件一个“选择”按钮.select-btn。按钮点击后窗口 resolve 出{ color: colorPickerWidget.getHex8String() }并自行关闭而窗口被用户直接关闭时on_close回调会 resolve 为false成为前文所述“取消即返回空值”的来源。真正的取色控件在 src/gui/src/UI/UIColorPickerWidget.js它基于iro.ColorPicker构建默认布局defaultLayout由三部分组成组件类型作用iro.ui.Box色域框水平/垂直两个维度选取色相与饱和度265×265iro.ui.SliderAlpha 滑杆调节透明度sliderType: alphairo.ui.Slider色相滑杆调节色相sliderType: hue控件封装的setColor()支持三种输入兼容性很强6 位十六进制#f00/#ff00008 位十六进制#ff0000ff会同时解析 RGB 与 AlphaHSLA 对象含h/s/l/a属性a缺省时视为1。这解释了为什么带 Alpha 的 hex8 颜色也能在打开时被精确还原到取色界面上。5.4 完整调用时序Puter App (puter.js SDK) 桌面 GUI (IPC 处理) 取色窗口 │ │ │ │ postMessage(showColorPicker,...) │ │ │ ───────────────────────────────────▶ │ │ │ │ 鉴权检查、参数归一化、 │ │ │ 清空 window_options │ │ │ ── 打开 UIWindowColorPicker ──▶ │ │ │ │ 用户取色/点击选择 │ │ ◀────────── { color: hex8 } ───── │ │ postMessage(colorPicked, color) │ │ │ ◀─────────────────────────────────── │ │ │ resolve(color) │ │六、独立 Web 组件形态puter-color-picker当 puter.js 运行在无桌面消息通道的独立网站中时showColorPicker()走的是 Web 组件降级路径。该组件的完整说明位于 src/puter-js/src/ui/components.md关键规格如下能力模态取色对话框内置 80 个预设色块、一个十六进制输入框以及一个用于任意颜色选取的原生 HTML5 颜色输入控件属性default-colorstring—— 对话框打开时的初始颜色例如#3b82f6事件response——detail为选中的十六进制颜色字符串取消时为null样式该组件与puter-notification、puter-context-menu等组件一样会自动适配系统的prefers-color-scheme: dark深色模式。若不想通过puter.ui.showColorPicker()而是直接操作组件可以手动创建并监听const el document.createElement(puter-color-picker); el.setAttribute(default-color, #ff6b35); el.addEventListener(response, e { if (e.detail) console.log(Picked:, e.detail); }); document.body.appendChild(el); el.open();七、最佳实践与常见问题返回值可直接作为 CSS 颜色使用。桌面端返回的 hex8 字符串如#ff6b35ff与现代浏览器的 CSS 颜色语法兼容直接赋给backgroundColor、color、boxShadow等属性即可无需二次转换。务必处理取消分支。用户可能直接关闭取色窗口桌面 App 模式下 Promise 会 resolve 为undefined独立组件模式下detail为null。在赋值给样式前先做判空可避免误把null/undefined拼进 CSS。defaultColor应传合法的十六进制色值。底层控件只解析十六进制与 HSLA 对象传 CSS 命名色如red或rgb()写法不在解析路径内官方示例统一使用#3b82f6、#ff6b35这类 hex 写法。桌面端会强制先鉴权。未登录用户触发该 API 时桌面 GUI 会先弹出注册/登录窗口见 IPC 处理中的UIWindowSignup调用这是框架行为而非 Bug同时外部传入的window_options会被清空App 无法借此定制取色窗口的窗口级行为。选取器 API 高度同构。若你还需选择字体、目录、打开文件或保存文件可以对照阅读 showFontPicker 文档、showDirectoryPicker 文档、showOpenFilePicker 文档 与 showSaveFilePicker 文档它们的调用形式、返回值语义均返回 Promise与桌面/独立双模式机制几乎一致。八、相关文档与源码索引API 文档src/docs/src/UI/showColorPicker.mdSDK 实现与类型定义src/puter-js/src/modules/UI.jsWeb 组件规格说明src/puter-js/src/ui/components.md桌面 GUI IPC 处理src/gui/src/IPC.js取色窗口实现src/gui/src/UI/UIWindowColorPicker.js底层取色控件iro.js 封装src/gui/src/UI/UIColorPickerWidget.js通过本文你不仅掌握了puter.ui.showColorPicker()的三种调用方式、参数与返回值约定还从消息链路层面理解了桌面端鉴权、安全处理、hex8 颜色格式以及底层 iro.ColorPicker 布局足以在自己的 Puter App 或网站中稳定、规范地接入颜色选择能力。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Puter 应用开发取色指南：puter.ui.showColorPicker() 的调用、返回值与桌面端实现原理
Puter 应用开发取色指南puter.ui.showColorPicker() 的调用、返回值与桌面端实现原理【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterputer.ui.showColorPicker()是 Puter 前端 SDK 中用于向用户弹出颜色选择对话框的 UI API。无论是运行在 Puter 桌面中的 App还是通过 puter.js 接入的网站都可以用它快速获得一个原生风格的取色窗口并将用户选中的颜色直接应用到页面样式上。读完本文你将掌握该方法的三种调用形式、参数与返回值约定、完整的可运行示例以及从 puter.js SDK 到桌面 GUI 的整条消息链路实现细节。一、方法概述Puter 前端 SDK 将 UI 相关的对话框方法统一挂在puter.ui命名空间下showColorPicker()负责“让用户选择一个颜色”它在官方 API 文档 src/docs/src/UI/showColorPicker.md 中的原始定义是Presents the user with a color picker dialog allowing them to select a color.向用户展示一个允许其选择颜色的取色对话框。从文档 frontmatter 可以看到该方法声明的适用平台为platforms: [websites, apps]即同时覆盖两类运行场景apps运行在 Puter 桌面环境中的 App此时 SDK 与桌面窗口管理器通过postMessage消息通道协作websites把 puter.js 直接嵌入自有页面的“独立站点”模式此时 SDK 会降级使用页内 Web 组件渲染对话框。它和showFontPicker()、showDirectoryPicker()、showOpenFilePicker()、showSaveFilePicker()共同构成 Puter UI 的“选取器Picker”家族同类组件的清单可参考 src/puter-js/src/ui/components.md 中的组件总表。二、函数签名与三种调用形式文档给出了三种调用语法三种形式最终返回同一个 Promiseputer.ui.showColorPicker() puter.ui.showColorPicker(defaultColor) puter.ui.showColorPicker(options)2.1 无参数调用直接弹出取色窗口不带任何预设颜色puter.ui.showColorPicker().then((color) { // color 为用户选中的颜色 });2.2 传入默认颜色字符串puter.ui.showColorPicker(#3b82f6);传入的参数若为字符串会被 SDK 视为“默认选中的颜色”。这一点在 GUI 源码中也有印证src/gui/src/UI/UIWindowColorPicker.js 在创建窗口前会判断「第一个参数是否为字符串」是则将其作为默认颜色注入options.default。2.3 传入 options 对象puter.ui.showColorPicker({ defaultColor: #ff6b35, });SDK 中 src/puter-js/src/modules/UI.js 的ColorPickerOptions类型定义如下/** * Options that configure showColorPicker(). * * typedef {Object} ColorPickerOptions * property {string} [defaultColor] The color initially selected when the picker opens. */2.4 参数说明参数类型说明默认值defaultColorstring取色窗口打开时预选中的颜色桌面端#f00独立 Web 组件模式#3b82f6optionsobject配置对象当前核心字段为defaultColor{}options.defaultColorstring同上窗口打开时预选的颜色见上options.default/options.defaultValuestringdefaultColor的历史别名为兼容旧代码而保留无default与defaultValue这两个别名并非文档杜撰而是模块 JSDoc 中明确标注的兼容项src/puter-js/src/modules/UI.js/** * Shows a color picker. Resolves to the chosen color. Accepts either a * default color or an options object. default and defaultValue are * legacy aliases for defaultColor. */桌面 GUI 侧解析默认颜色时的优先级也完全一致见 src/gui/src/UI/UIWindowColorPicker.js 中options.defaultValue ?? options.defaultColor ?? options.default ?? #f00在 Puter 桌面端没有指定任何默认值时最终落到红色#f00。三、返回值与“取消”语义调用返回Promisestring即一个可直接用于 CSS 的颜色字符串puter.ui.showColorPicker().then((color) { document.body.style.backgroundColor color; // 直接把返回值赋给 CSS 属性 });值得开发者注意的细节桌面端返回的是带透明通道的 hex8 格式。桌面 GUI 在用户点击“选择”按钮后通过 src/gui/src/UI/UIWindowColorPicker.js 中colorPickerWidget.getHex8String()取色返回值形如#ff6b35ff前 6 位为 RGB后 2 位为 Alpha 通道。这是由底层取色控件的hex8String属性给出的见 src/gui/src/UI/UIColorPickerWidget.js 的 JSDoc 示例#ff0000ff。由于取色窗口本身带有 Alpha透明度滑杆因此选择任意半透明颜色都能被如实返回。这种 8 位十六进制写法在支持 CSS Color 4 的现代浏览器中可直接作为background-color、color、border-color等属性的值。用户取消选择时不会 resolve 出一个颜色。如果用户直接关闭取色窗口桌面 GUI 侧窗口的on_close回调会 resolve 为false经 IPC 消息映射后 SDK 侧收到的是undefined而在独立 Web 组件模式下response事件携带的detail为null。因此稳健的写法应当先判空再使用返回值。四、完整可运行示例4.1 官方文档示例src/docs/src/UI/showColorPicker.md 自带一个开箱即用的最小示例——用户选完颜色后整个页面背景随之改变html body script srchttps://js.puter.com/v2//script script puter.ui.showColorPicker().then((color){ document.body.style.backgroundColor color; }) /script /body /html4.2 带默认颜色与取消分支的完整示例在真实应用中建议同时处理默认颜色与用户取消两种情形html body stylebackground-color: #f5f7fa; font-family: sans-serif; button idpick选择主题色/button div idresult stylemargin-top: 12px; color: #333;尚未选择颜色/div script srchttps://js.puter.com/v2//script script document.getElementById(pick).addEventListener(click, () { puter.ui.showColorPicker({ defaultColor: #3b82f6 }).then((color) { // 用户取消关闭窗口时 color 为 null / undefined需先判空 if (!color) { document.getElementById(result).textContent 已取消选择; return; } document.body.style.backgroundColor color; document.getElementById(result).textContent 已选择颜色: color; }); }); /script /body /html这段代码演示了options传参、预选颜色、Promise 链式使用以及取消分支处理四个要点可直接复制到 Puter 或任何已引入 puter.js 的页面中运行。五、桌面端实现链路源码级解析要理解showColorPicker()在 Puter 桌面中的真实行为需要沿着“SDK → 桌面 GUI → 取色控件 → 回传”整条链路阅读源码。5.1 puter.js SDK 侧统一入口与分支SDK 的实现位于 src/puter-js/src/modules/UI.jsshowColorPicker (options) { if ( this.messageTarget ) { return new Promise((resolve) { this.#postMessageWithCallback(showColorPicker, resolve, { options: options ?? {} }); }); } // Standalone fallback: render web component return new Promise((resolve) { const opts typeof options string ? { defaultColor: options } : (options ?? {}); const el document.createElement(puter-color-picker); const defaultColor opts.defaultValue || opts.defaultColor || opts.default || #3b82f6; el.setAttribute(default-color, defaultColor); el.addEventListener(response, (e) resolve(e.detail)); document.body.appendChild(el); el.open(); }); };这段代码揭示了两个关键事实运行在 Puter 桌面App 模式存在messageTarget时SDK 通过#postMessageWithCallback发送showColorPicker消息给桌面 GUI由桌面窗口完成取色独立站点Website 模式无messageTarget时SDK 自动降级为在页面内创建puter-color-pickerWeb 组件。组件注册表见 src/puter-js/src/ui/registerComponents.js其中包含[puter-color-picker, PuterColorPicker]的映射。5.2 GUI 桌面端 IPC 处理与鉴权桌面 GUI 收到消息后的处理位于 src/gui/src/IPC.js。处理流程依次为鉴权检查若当前用户未登录会先尝试拉起注册窗口只有鉴权通过才继续否则直接 return参数归一化若options是字符串则转换成{ defaultColor: 字符串 }安全处理出于安全原因桌面端会强制清空外部传入的window_optionsevent.data.options.window_options {}防止 App 注入窗口行为关联父窗口将取色窗口的parent_uuid设置为请求方 App 的实例 ID保证窗口归属正确打开窗口调用UIWindowColorPicker(options)等待用户操作回传结果向请求方 iframe 发送colorPicked消息携带color: selected_color ? selected_color.color : undefined。// src/gui/src/IPC.js节选 else if ( event.data.msg showColorPicker ) { // Auth if ( !window.is_auth() !(await UIWindowSignup({ referrer: app_name })) ) return; // set options if ( typeof event.data.options string ) { event.data.options { defaultColor: event.data.options }; } event.data.options event.data.options ?? {}; // Clear window_options for security reasons event.data.options.window_options {}; event.data.options.window_options.parent_uuid event.data.appInstanceID; // Open color picker let selected_color await UIWindowColorPicker(event.data.options); ... }SDK 侧则通过 src/puter-js/src/modules/UI.js 中msg colorPicked的分支取出e.data.color触发注册的回调从而让.then()拿到颜色字符串else if ( e.data.msg colorPicked ) { // execute callback this.#callbackFunctionse.data.original_msg_id; }5.3 取色窗口与其底层控件桌面端的取色窗口由 src/gui/src/UI/UIWindowColorPicker.js 实现。该模块使用UIWindow创建一个标题为select_color本地化文案、宽度 350、不可调整大小、单实例single_instance: true的小窗口窗口内渲染两个核心元素挂载div classpicker的取色控件一个“选择”按钮.select-btn。按钮点击后窗口 resolve 出{ color: colorPickerWidget.getHex8String() }并自行关闭而窗口被用户直接关闭时on_close回调会 resolve 为false成为前文所述“取消即返回空值”的来源。真正的取色控件在 src/gui/src/UI/UIColorPickerWidget.js它基于iro.ColorPicker构建默认布局defaultLayout由三部分组成组件类型作用iro.ui.Box色域框水平/垂直两个维度选取色相与饱和度265×265iro.ui.SliderAlpha 滑杆调节透明度sliderType: alphairo.ui.Slider色相滑杆调节色相sliderType: hue控件封装的setColor()支持三种输入兼容性很强6 位十六进制#f00/#ff00008 位十六进制#ff0000ff会同时解析 RGB 与 AlphaHSLA 对象含h/s/l/a属性a缺省时视为1。这解释了为什么带 Alpha 的 hex8 颜色也能在打开时被精确还原到取色界面上。5.4 完整调用时序Puter App (puter.js SDK) 桌面 GUI (IPC 处理) 取色窗口 │ │ │ │ postMessage(showColorPicker,...) │ │ │ ───────────────────────────────────▶ │ │ │ │ 鉴权检查、参数归一化、 │ │ │ 清空 window_options │ │ │ ── 打开 UIWindowColorPicker ──▶ │ │ │ │ 用户取色/点击选择 │ │ ◀────────── { color: hex8 } ───── │ │ postMessage(colorPicked, color) │ │ │ ◀─────────────────────────────────── │ │ │ resolve(color) │ │六、独立 Web 组件形态puter-color-picker当 puter.js 运行在无桌面消息通道的独立网站中时showColorPicker()走的是 Web 组件降级路径。该组件的完整说明位于 src/puter-js/src/ui/components.md关键规格如下能力模态取色对话框内置 80 个预设色块、一个十六进制输入框以及一个用于任意颜色选取的原生 HTML5 颜色输入控件属性default-colorstring—— 对话框打开时的初始颜色例如#3b82f6事件response——detail为选中的十六进制颜色字符串取消时为null样式该组件与puter-notification、puter-context-menu等组件一样会自动适配系统的prefers-color-scheme: dark深色模式。若不想通过puter.ui.showColorPicker()而是直接操作组件可以手动创建并监听const el document.createElement(puter-color-picker); el.setAttribute(default-color, #ff6b35); el.addEventListener(response, e { if (e.detail) console.log(Picked:, e.detail); }); document.body.appendChild(el); el.open();七、最佳实践与常见问题返回值可直接作为 CSS 颜色使用。桌面端返回的 hex8 字符串如#ff6b35ff与现代浏览器的 CSS 颜色语法兼容直接赋给backgroundColor、color、boxShadow等属性即可无需二次转换。务必处理取消分支。用户可能直接关闭取色窗口桌面 App 模式下 Promise 会 resolve 为undefined独立组件模式下detail为null。在赋值给样式前先做判空可避免误把null/undefined拼进 CSS。defaultColor应传合法的十六进制色值。底层控件只解析十六进制与 HSLA 对象传 CSS 命名色如red或rgb()写法不在解析路径内官方示例统一使用#3b82f6、#ff6b35这类 hex 写法。桌面端会强制先鉴权。未登录用户触发该 API 时桌面 GUI 会先弹出注册/登录窗口见 IPC 处理中的UIWindowSignup调用这是框架行为而非 Bug同时外部传入的window_options会被清空App 无法借此定制取色窗口的窗口级行为。选取器 API 高度同构。若你还需选择字体、目录、打开文件或保存文件可以对照阅读 showFontPicker 文档、showDirectoryPicker 文档、showOpenFilePicker 文档 与 showSaveFilePicker 文档它们的调用形式、返回值语义均返回 Promise与桌面/独立双模式机制几乎一致。八、相关文档与源码索引API 文档src/docs/src/UI/showColorPicker.mdSDK 实现与类型定义src/puter-js/src/modules/UI.jsWeb 组件规格说明src/puter-js/src/ui/components.md桌面 GUI IPC 处理src/gui/src/IPC.js取色窗口实现src/gui/src/UI/UIWindowColorPicker.js底层取色控件iro.js 封装src/gui/src/UI/UIColorPickerWidget.js通过本文你不仅掌握了puter.ui.showColorPicker()的三种调用方式、参数与返回值约定还从消息链路层面理解了桌面端鉴权、安全处理、hex8 颜色格式以及底层 iro.ColorPicker 布局足以在自己的 Puter App 或网站中稳定、规范地接入颜色选择能力。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考