属性控件改写 plugin-options-modify

约 988 字大约 3 分钟

...

2026-09-28

插件说明

属性控件改写插件：包装 OptionItem 的 createTarget，把指定选项的默认控件替换或增强（如 select 换成 number input、select 换成弹窗式单选/多选下拉）。无第三方依赖。

核心能力：

按 optionNames 枚举或 filter 函数匹配要改写的选项
内置「select 转 number input」「select 转弹窗式单选/多选下拉」处理器
支持自定义 modifyHandler，可搭配 Vue / React 组件实现任意控件改写

安装：

npm install @sv-print/plugin-options-modify

示例代码

import pluginOptionsModify, {
  getSelectToInputModifyHandler,
  InputValueGetHandler,
  InputValueSetHandler,
  getSelectToMultiselectModifyHandler,
  PopupSelectValueGetHandler,
  PopupSelectValueSetHandler,
  PopupSelectDestroyHandler,
} from '@sv-print/plugin-options-modify';

await hiprint.register({
  // 需 await 注册；init 不收插件数组
  plugins: [
    pluginOptionsModify({
      list: [
        {
          // 方式一：按 optionNames 枚举，把 select 换成 number input
          optionNames: ['fontSize', 'lineHeight'],
          modifyHandler: getSelectToInputModifyHandler(
            `<input type="number" value="1" step="1" min="1" class="auto-submit"/>`,
          ),
          setValueHandler: (item, value) => {
            InputValueSetHandler(item, value || 9);
          },
          getValueHandler: InputValueGetHandler, // get/set 需成对提供
        },
        {
          // 方式二：按 filter 匹配，把默认 select 替换为弹窗式多选下拉
          filter: (key, target) => key.startsWith('columns'),
          modifyHandler: getSelectToMultiselectModifyHandler({ mode: 'multiple' }),
          getValueHandler: PopupSelectValueGetHandler,
          setValueHandler: PopupSelectValueSetHandler,
          destroyHandler: PopupSelectDestroyHandler,
        },
      ],
    }),
  ],
});

高级用法

list 项参数

参数	类型	说明
optionNames	string[]	按 option 名称枚举匹配
filter	`(key, target) => boolean`	按函数匹配，与 optionNames 二选一
modifyHandler	`(key, target) => target`	替换/增强控件 DOM，返回处理后的 target
getValueHandler	`(item) => value`	从改写后的控件取值
setValueHandler	`(item, value) => void`	向改写后的控件设值
destroyHandler	`(item) => void`	控件销毁时清理（弹窗下拉等需要）

getValue / setValue 需成对提供。可根据自身项目的组件自定义 modifyHandler（如 Vue / React 组件）实现对选项的自修改、自取值和设置。

内置处理器

处理器	说明
`getSelectToInputModifyHandler(html)`	把 select 替换为指定 html 控件（如 number input）
`InputValueGetHandler` / `InputValueSetHandler`	input 类控件的取值/设值
`getSelectToMultiselectModifyHandler(options)`	把 select 替换为弹窗式单选/多选下拉，外观与 hiprint 内置多选下拉一致
`PopupSelectValueGetHandler`	弹窗下拉取值；按 setValue 传入值的类型还原返回类型
`PopupSelectValueSetHandler`	弹窗下拉设值
`PopupSelectDestroyHandler`	弹窗下拉销毁清理（含类型映射缓存）

弹窗式下拉配置（PopupSelectOptions）

字段	类型	默认值	说明
mode	`'single' \| 'multiple'`	`'single'`	单选 / 多选
showSearch	boolean	`false`	顶部显示搜索框，按文字/值模糊匹配过滤选项
searchPlaceholder	string	`'搜索…'`	搜索框占位文本
allowCustom	boolean	`false`	允许输入自定义值，按「添加」按钮新增为选项
customPlaceholder	string	`'输入自定义值'`	自定义输入框占位文本
customButtonText	string	`'添加'`	自定义添加按钮文本
beforeAddCustom	`(v, key) => boolean \| void`	-	自定义值添加前钩子；返回 `false` 取消添加
showReset	boolean	`true`	是否显示「恢复默认」按钮
resetText	string	`'恢复默认'`	恢复默认按钮文本
showConfirm	boolean	`mode === 'multiple'`	是否显示「确认」按钮
confirmText	string	`'确认'`	确认按钮文本
autoClose	boolean	`mode === 'single'`	单选模式下选中后是否自动关闭弹窗
topbarThreshold	number	`5`	选项数超过该阈值才显示顶部搜索/自定义输入；`0` 表示不限制
shouldShowTopbar	`(count, key) => boolean`	-	自定义是否显示顶部栏；优先级高于 topbarThreshold

PopupSelectValueGetHandler 会根据 setValue 传入值的类型还原返回类型：setValue(9) 后续返回 9（number）、setValue("9") 返回 "9"（string）、setValue([1, 2]) 返回 [1, 2]（number 数组）。无需再手动 parseFloat / String 包装，但 setValue 之前需确保传入原始类型。

版权所有

版权归属：sv-print

许可证：署名 4.0 国际 (CC-BY-4.0)