kyle-editor 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  轻量、美观的**微信公众号风格富文本编辑器**。纯前端实现,无任何后端依赖:图片/视频走**分片上传**(并发、重试、取消、秒传、断点续传),随时切换 **HTML 源码模式**查看或改写产物。支持 `<script>` 直接引入与 Vue 3 安装集成。
4
4
 
5
- - 体积:`dist/keditor.umd.js` 约 139 KB(gzip 37 KB),零运行时依赖,样式随 JS 注入
5
+ - 体积:`dist/keditor.umd.js` 约 202 KB(gzip 51 KB),零运行时依赖,样式随 JS 注入
6
6
  - 版式:677px 正文版心、17px/1.75 行距,与公众号观感一致
7
7
  - 安全:标签/属性白名单净化,拦截 `on*`、`javascript:`、`script/iframe`
8
8
 
@@ -15,6 +15,7 @@
15
15
  | 上传 | `chunkSize / concurrency / retries / fingerprint` 可配;内置 mock、http、simple 适配器,也可自定义 `init/put/complete` |
16
16
  | 源码 | 工具栏右侧常驻「源码」按钮(`⌘/Ctrl+Shift+K`),进入后正文按钮置灰;格式化缩进、复制、直接编辑并应用(回填自动净化) |
17
17
  | 其他 | 实时字数/词数/图片视频统计、预览(手机/平板/电脑屏宽)、全屏编辑、撤销重做(保留光标位置)、只读、窄屏工具栏可左右滑动(常显滚动条 + 边缘渐隐 + 首次引导气泡 + 鼠标拖拽平移)且「源码/预览/全屏」固定右端 |
18
+ | **自定义按钮** | `customButtons` 往工具栏加**下拉选择**按钮:数据可**静态配置**或**从接口读取**(`url` / `load`),选中后按配置**插入跳转链接**或直接打开;面板支持搜索、分组、加载/失败重试/空态、缓存与强制刷新;也可运行时 `addButton` / `removeButton` / `setButtonOptions` |
18
19
 
19
20
  ## 安装
20
21
 
@@ -92,96 +93,129 @@ const onUpload = (payload) => console.log(payload.stage, payload.percent)
92
93
  >
93
94
  > ESM / Webpack / Vite / React 用法见 [docs/integration.md](docs/integration.md)。
94
95
 
95
- ## 本地运行
96
+ ## 自定义工具栏按钮(下拉选择)
96
97
 
97
- ```bash
98
- npm install
99
- npm run build # 产出 dist/(es + cjs + umd,含 Vue 版本)
100
- npm run dev # 静态服务 http://127.0.0.1:5178
101
- ```
98
+ 不想改源码就能往工具栏加业务按钮。典型场景:插入公司模板、关联栏目、跳转后台页面。
102
99
 
103
- 打开:
100
+ ```js
101
+ const editor = KEditor.create('#editor', {
102
+ customButtons: [
103
+ // ① 数据从接口读取
104
+ {
105
+ name: 'column',
106
+ text: '栏目',
107
+ title: '插入栏目链接',
108
+ searchable: true, // 面板内搜索
109
+ url: '/api/columns', // 内部 fetch;自动识别 items/list/data/rows/records 结构
110
+ link: true, // 直接用每项自带的地址(url / href / link 字段)
111
+ insert: 'link',
112
+ },
113
+ // ② 数据静态配置
114
+ {
115
+ name: 'tpl',
116
+ text: '模板',
117
+ title: '插入模板',
118
+ options: [
119
+ { value: 'opening', label: '开场白', desc: '问候 + 本期导读', group: '通用' },
120
+ { value: 'ending', label: '结束语', desc: '引导关注与转发', group: '通用' },
121
+ ],
122
+ // 链接模板:{value} / {label} 以及选项任意字段都可作占位符
123
+ link: { url: 'https://mp.weixin.qq.com/s/tpl-{value}', text: '【{label}】', target: '_blank' },
124
+ },
125
+ ],
126
+ })
127
+
128
+ editor.on('customselect', ({ name, item, link, action }) => {
129
+ console.log(name, item.label, '→', link?.url, '(插入方式:' + action + ')')
130
+ })
131
+ ```
104
132
 
105
- - `index.html` — 说明首页
106
- - `demo/script.html` — UMD 引入 + 分片日志面板
107
- - `demo/esm.html` — 自定义上传适配器演示
108
- - `demo/vue.html` — Vue 3 组件 + `v-model`
109
- - `test/smoke.html` — 40 条内置冒烟用例(可视化结果)
133
+ > 没传 `toolbar` 时,自定义按钮会**自动追加**到默认工具栏末尾;传了 `toolbar` 数组则按名字定位:`toolbar: ['bold', '|', 'tpl', 'column']`。
110
134
 
111
- ## 验证
135
+ ### 数据源(优先级 `load` > `url` > `options`)
112
136
 
113
- ```bash
114
- npm run build
115
- npm run dev & # 启动静态服务
116
- node test/run-headless.mjs # 冒烟用例(需本机 Chrome)
117
- node test/check-page.mjs # 三个 demo 页面健康检查
137
+ ```js
138
+ // 方式 A:静态数组(也支持纯字符串、或接口原始对象,字段自动归一)
139
+ { options: [{ value: 'a', label: '选项 A', desc: '说明', url: 'https://x.com/a' }] }
140
+ { options: ['选项 A', '选项 B'] }
141
+
142
+ // 方式 B:自定义函数(可异步,能用编辑器实例与闭包里的 axios / 鉴权头)
143
+ { load: async () => (await fetch('/api/tags').then((r) => r.json())).map((t) => ({ value: t.id, label: t.name })) }
144
+
145
+ // 方式 C:直接给接口地址
146
+ {
147
+ url: '/api/columns',
148
+ fetchOptions: { method: 'POST', headers: { Authorization: 'Bearer x' }, body: '{}', timeout: 8000 },
149
+ pick: (json) => json.result.records, // 结构特殊时手动提取数组
150
+ }
118
151
  ```
119
152
 
120
- 当前状态:`40/40` 用例通过,demo 页面无控制台报错。
153
+ - **缓存**:默认只请求一次,面板右上角的刷新按钮可强制重新拉取;`cache: false` 则每次打开都请求
154
+ - **加载态**:面板自动显示 spinner + 骨架屏;**失败**时显示错误文案与「重试」按钮;**空数据**可用 `emptyText` 自定义提示
155
+ - **在编辑器外部拿数据**(Vue / React 里自己请求):`editor.setButtonOptions('column', list)`
121
156
 
122
- ## 文档
157
+ ### 跳转链接配置
123
158
 
124
- | 文档 | 内容 |
125
- |------|------|
126
- | [docs/integration.md](docs/integration.md) | Script / ESM / Vue3 / React / Nuxt 集成,常见问题 |
127
- | [docs/api.md](docs/api.md) | 全部配置项、实例方法与事件、工具栏自定义 |
128
- | [docs/upload-adapter.md](docs/upload-adapter.md) | 分片上传流程、后端接口约定、自定义适配器 |
159
+ ```js
160
+ { link: true } // 用每项自带地址
161
+ { link: 'https://x.com/{value}' } // 地址模板
162
+ { link: { url: '...', text: '【{label}】', target: '_blank' } }
163
+ { link: { mode: 'open', url: 'https://x.com/{value}' } } // 不写正文,直接新窗口打开
164
+ { link: (item) => ({ url: item.raw.href, text: item.label }) } // 完全动态
165
+ ```
129
166
 
130
- ## 目录结构
167
+ - `mode: 'insert'`(默认)在光标处插入 `<a>`,`target: '_blank'` 时自动带 `rel="noopener noreferrer"`
168
+ - `mode: 'open'` 直接 `window.open(url, '_blank', 'noopener,noreferrer')`,不改动正文
169
+ - **安全**:地址经白名单校验,`javascript:` / `vbscript:` / `data:` 等一律不会变成链接
131
170
 
132
- ```
133
- src/
134
- ├── index.js # 入口(导出 create/KEditor/适配器/工具函数)
135
- ├── core/ # 编辑器内核
136
- │ ├── editor.js # 组装 DOM、事件、状态、对外 API
137
- │ ├── toolbar.js # 工具栏声明式配置
138
- │ ├── commands.js # 富文本指令(字号/颜色/对齐/列表/表格/链接…)
139
- │ ├── sanitize.js # HTML 白名单净化 + Word 粘贴清洗
140
- │ ├── paste.js # 粘贴/拖拽(截图直传、外链图片本地化)
141
- │ ├── history.js # 快照式撤销栈(保留光标)
142
- │ ├── selection.js # 选区与光标工具
143
- │ ├── format.js # HTML 美化输出
144
- │ └── icons.js # 内置 SVG 图标
145
- ├── upload/ # 分片上传
146
- │ ├── chunk-uploader.js # 切片、并发、重试、进度、取消
147
- │ ├── adapters.js # mock / http / simple 适配器
148
- │ └── fingerprint.js # 秒传与断点续传指纹
149
- ├── media/media.js # 图片视频插入、占位块、压缩、替换
150
- ├── ui/ # 样式注入、弹层、源码面板、预览、气泡工具条、toast
151
- └── vue/index.js # Vue 3 插件 + 组件 + useKEditor
152
-
153
- types/ # 手写 TypeScript 声明(核心 + Vue)
154
- docs/ # 集成文档(index / integration / api / upload-adapter / npm-publish)
155
- demo/ # script / esm / vue 三种集成示例页
156
- test/ # 无头冒烟用例、页面健康检查、发布配置校验、视觉截图
171
+ ### 接管选中行为
172
+
173
+ ```js
174
+ {
175
+ name: 'tpl',
176
+ options: [/* ... */],
177
+ link: 'https://x.com/{value}',
178
+ insert: 'link', // 'auto'(默认) | 'link' | 'html' | 'text' | false
179
+ onSelect: (item, ctx) => {
180
+ analytics.track('insert_tpl', item.value) // 埋点,不阻断默认插入
181
+ },
182
+ }
183
+
184
+ // 完全自己处理:返回 false 则不改正文
185
+ { onSelect: (item, ctx) => { ctx.insertHtml(item.raw.html); return false } }
157
186
  ```
158
187
 
159
- ## 开发与验证
188
+ ### 运行时增删
160
189
 
161
- ```bash
162
- python3 -m http.server 5178 --bind 127.0.0.1 # 或 npm run dev
163
-
164
- npm run build # 产出 dist/:keditor.{es.js,cjs,umd.js} + keditor-vue.{es.js,cjs,umd.js}
165
- npm test # 无头 Chrome 跑 66 项功能冒烟(test/smoke.html)
166
- npm run test:pages # 4 个 demo 页面健康检查(挂载/控制台错误)
167
- npm run test:types # .d.ts 语法校验(无需 tsc)
168
- npm run test:package # 63 项发布配置校验(包名/exports/.cjs 后缀/裸说明符)
169
- npm run verify # 上述全部一次跑完
170
- npm run test:visual # 9 个关键界面截图到 test/screenshots/
190
+ ```js
191
+ editor.addButton({ name: 'season', text: '节气', options: [...], link: 'https://x.com/{value}' })
192
+ editor.addButton(spec, { at: 0 }) // 插到指定位置
193
+ editor.removeButton('season') // 移除并中断未完成的接口请求
194
+ editor.setButtonOptions('season', list) // 外部灌入数据
195
+ editor.getButtonValue('column') // 读当前选中项
196
+ editor.setButtonValue('column', 'tech') // 设置选中项(按钮文案同步)
171
197
  ```
172
198
 
173
- 当前状态:构建通过,**86/86 冒烟用例通过**,4 个 demo 页面零控制台错误,63 项发布配置校验通过。覆盖范围包括:输入与统计、全部工具栏指令、列表嵌套、表格与行列增删、颜色面板(选色/最近使用/自定义)、段落样式面板、字号面板、图片与视频的网络链接插入、链接校验、图片拖拽缩放(把手定位/拖拽改变宽度/取消选中隐藏)、图片对齐(缩小后工具栏与气泡两条入口均居中生效且按钮高亮)、粘贴净化(含 XSS 拦截)、拖拽上传、分片进度与取消、历史撤销重做、源码模式双向同步与按钮态、预览、只读、Vue 插件与 v-model、UMD 全局挂载。
199
+ ### 普通按钮(非下拉)
174
200
 
175
- ## 发布到 npm
201
+ ```js
202
+ { name: 'date', type: 'button', text: '插入日期', icon: 'plus', onClick: ({ editor }) => editor.commands.insertHTML('<p>2026-10-13</p>') }
203
+ ```
176
204
 
177
- 包名 `kyle-editor`(`keditor` 已被占用)。发布配置、本地验证、版本管理、私有源与 CI 自动发布全流程见 **[docs/npm-publish.md](docs/npm-publish.md)**。
205
+ ## 本地运行
178
206
 
179
207
  ```bash
180
- npm login # 登录(浏览器授权)
181
- npm run release # 构建 + 全量验证 + npm publish --access public
208
+ npm install
209
+ npm run build # 产出 dist/(es + cjs + umd,含 Vue 版本)
210
+ npm run dev # 静态服务 http://127.0.0.1:5178
182
211
  ```
183
212
 
184
- 已实测:从 tarball 全新安装后,CJS / ESM × 核心 / `kyle-editor/vue` 四个入口均能正确解析并拿到完整导出。
213
+ ## 验证
214
+
215
+ ```bash
216
+ npm run build
217
+ npm run dev & # 启动静态服务
218
+ ```
185
219
 
186
220
  ## 已知限制
187
221