@microi.net/cli 5.8.4 → 5.8.6

package/skills/v8-frontend-events/SKILL.md

@@ -1,180 +1,180 @@
----
-name: v8-frontend-events
-description: Microi 前端 V8 事件与客户端能力指南。用于编写浏览器端字段、按钮、列表事件，或使用 V8.EventName、V8.Form、V8.Print 蓝牙打印（佳博 GP-M322、ZICOX CC4、TSPL、CPCL、ESC/POS、BLE、SPP）、扫码、弹窗、表单联动和界面交互。
----
-
-> **Codex 非阻塞自动更新：** 当前宿主为 Codex 时，吾码 CLI、Codex 插件与工作区 AI/MCP 由后台自动更新；需要诊断时读取 `../microi-codex-installer/SKILL.md`。更新失败、等待空闲或尚未重载均不得阻断当前、正在进行或新建任务。非 Codex 宿主跳过此项。
-
-# Microi V8 前端事件大全
-
-你正在为 Microi 吾码平台编写 **前端 V8 事件** 代码。前端事件运行在浏览器，通过 `V8.EventName` 区分事件类型，可访问表单/列表/弹窗等丰富的客户端 API。
-
-> **表单生命周期事件**（InFormV8、SubmitFormV8、SubmitBeforeServerV8、SubmitAfterServerV8、OutFormV8、DataFilterV8）见 `v8-table-event/SKILL.md`。  
-> **菜单按钮事件**（MoreBtns/FormBtns 等）见 `v8-menu-buttons/SKILL.md`。  
-> 本文重点是 **字段事件、按钮事件、列表事件、模板引擎、其它前端钩子**。
-
-<!-- microi-progressive:begin -->
-<!-- microi-progressive:chunk id=v8-frontend-events-000 sha256=69ad0ebf0c8aca6edcbc0bbfe7e280986525bf28f68da8cb33c8efbc4509f7da -->
-## 能力路由
-
-- 查询前端 V8 全部上下文、导航、表单、列表、网络、引擎与工具入口时，读取 `../v8-utilities/references/client-api-index.md`。
-- 需求包含“蓝牙打印、标签打印、TSC/TSPL、CPCL、ESC/POS、小票打印、佳博/GP-M322、ZICOX/芝柯/CC4、BLE/SPP”时，必须先读取 `references/bluetooth-print.md`；需要完整指令签名、型号转换范围、编码或位图参数时，再读取 `references/bluetooth-print-api.md`。
-- `microi.app` 是 5+ 在线壳，不能假设存在 `uni` 或 Web Bluetooth。BLE 连接、发现和写入必须统一使用 `plus.bluetooth`，禁止用 `uni.writeBLECharacteristicValue` 写入由 `plus.bluetooth` 建立的连接。5+ `V8.Print.getConnectionState()` 的 `mtu/maxWriteBytes/recommendedPacketSize/writeType/packetIntervalMs` 描述本次连接能力。Android GP-M322 在特征支持时优先 `writeNoResponse`，即使协商出 180 字节有效载荷也只采用 100 字节连续发送稳定档，并保留约 8ms 包间保护；不支持无响应写时兼容 `write`，空 MTU 成功、失败、超时或旧壳只用 20 字节。详见蓝牙参考。
-- 浏览器模板打印、PDF/纸张模板、`mic_print`、`PageObj`、`PrintObj` 使用 `print-engine/SKILL.md`，不要与直接蓝牙指令混为一套 API。
-- 扫码使用 `V8.Method.ScanCode`，结果从 Promise/回调取得；`V8.ScanCodeRes` 只作兼容结果槽，详见客户端 API 索引。
-- 登录后的敏感操作使用 `V8.Identity.Verify` 完成 Passkey/严格人脸交互；前端只取得一次性 Ticket，后端接口引擎必须重算 `ActionHash` 并原子消费，不能把前端成功当作授权。
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-frontend-events-001 sha256=eaab87d01b0fd2b6964326ee11edd7b793899c679930c575a0a2b309d36a367a -->
-## 字段事件（在【字段属性】中配置）
-
-### FieldValueChange — 值变更事件（最常用）
-
-```javascript
-// V8.EventName === 'FieldValueChange'
-// V8.ThisValue   — 当前字段新值
-// V8.OldValue    — 仅表格行内字段事件可靠提供；普通表单读取 V8.OldForm
-// V8.Form        — 整个表单数据
-// V8.FormMode    — 'Add' / 'Edit' / 'View'
-// V8.LoadMode    — 'Design' 表示设计器中，'View' 是真实表单
-
-// ★ 关键：设计模式下不要执行业务逻辑（防止设计器卡顿）
-if (V8.LoadMode === 'Design') return;
-
-// 选择部门 → 联动加载该部门下的人员到 联系人 控件
-var deptId = V8.ThisValue && V8.ThisValue.Id;
-if (deptId) {
-  var users = await V8.FormEngine.GetTableData('Diy_Employee', {
-    _SelectFields: ['Id', 'Name', 'Account'],
-    _Where: [['DeptId', '=', deptId]]
-  });
-  V8.FieldSet('Contact', 'Data', users.Code === 1 ? users.Data : []);
-} else {
-  V8.FieldSet('Contact', 'Data', []);
-}
-
-// 联动设置另一字段值
-V8.FormSet('CustomerName', V8.ThisValue.Name);
-
-// 联动显隐
-V8.FieldSet('TaxNo', 'Visible', V8.ThisValue === '企业');
-
-// 联动必填
-V8.FieldSet('Reason', 'Required', V8.ThisValue === '退款');
-```
-
-### FieldOnKeyup — 键盘抬起事件
-
-```javascript
-// V8.EventName === 'FieldOnKeyup'
-// 表格行内键盘事件为 V8.EventName === 'TableFieldOnKeyup'
-// V8.KeyCode     — 键码；当前键盘 V8 不提供原生 V8.Event
-
-if (V8.KeyCode === 13) {
-  V8.FormSubmit({ CloseForm: false });
-}
-```
-
-### V8CodeBlur — 失焦专用代码
-
-```javascript
-// 当前运行时仍使用 V8.EventName === 'FieldValueChange'
-// V8.ThisValue 是失焦时的当前输入值
-// 失焦校验手机号
-if (V8.ThisValue && !/^1[3-9]\d{9}$/.test(V8.ThisValue)) {
-  V8.Tips('手机号格式不正确', false);
-  V8.Form.Phone = ''; // 静默清空，避免再次触发当前字段事件
-}
-```
-
-### FieldSlotButtonClick — 单行文本插槽按钮
-
-单行文本 `Text` 开启【插槽按钮】后，必须在【插槽按钮V8代码】中配置行为，不要再写“弹出表格Id”。
-
-```javascript
-// V8.EventName === 'FieldSlotButtonClick'
-// V8.ThisValue — 当前输入框值
-// V8.Event     — 原生点击事件
-
-if (V8.LoadMode === 'Design') return;
-
-V8.OpenAnyTable({
-  SysMenuId: '目标业务菜单Id',
-  MultipleSelect: false,
-  SubmitEvent: function (selectData, callback) {
-    callback({ Code: 1, Data: selectData });
-  }
-});
-// 或 V8.OpenAnyForm / V8.OpenAppDialog / V8.ApiEngine.Run 等任意前端 V8 能力
-```
-
-`ReadOnlyButton` 的产品文案是【禁用插槽按钮】：只控制按钮是否可点击，不等同于字段只读，应保留用于权限和状态控制。
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-frontend-events-002 sha256=faf64dbf6ded2a086c347bea31edecb7d6fc8b765114290d17998b7370d17372 -->
-## 按钮事件
-
-### V8BtnRun — 按钮点击执行（菜单按钮、表单按钮）
-
-```javascript
-// V8.Form        — 当前行/表单数据
-// V8.FormMode    — Add / Edit / View
-// V8.TableId     — 当前 diy_table 的 Id
-// V8.TableRowSelected — 批量按钮中选中的行数组
-// V8.ClientType  — 'PC' / 'IOS' / 'Android' / 'H5' / 'WeChat'
-
-V8.ConfirmTips('确认审核通过？', function() {
-  V8.ApiEngine.Run({
-    ApiEngineKey: 'order_approve',
-    Id: V8.Form.Id
-  }, function(r) {
-    if (r.Code === 1) { V8.Tips('审核成功', true); V8.RefreshTable({ _PageIndex: 1 }); }
-    else V8.Tips(r.Msg || '失败', false);
-  });
-});
-```
-
-### V8BtnLimit — 按钮显隐（V8CodeShow）
-
-```javascript
-// 推荐：直接 return boolean
-return V8.Form.Status === '待审核' && V8.CurrentUser.RoleName.indexOf('审批员') !== -1;
-
-// 兼容旧写法：V8.Result = true/false
-// V8.Result = V8.Form.Status === '待审核';
-```
-
-`V8CodeShow` 与点击事件使用同一套前端 V8 能力，允许直接使用 `await`。平台所有
-按钮入口（列表按钮、表单顶部按钮、更多按钮和子表打开的嵌套表单按钮）都必须走
-异步执行器并等待结果后再决定显隐；不得在某一层退回同步 `new Function`，否则同一段
-代码在列表可用、进入嵌套表单后会报 `await is only valid in async functions`。回归测试
-至少覆盖“主表详情 → 定制子表 → 子记录详情”链路中的含 `await` 显隐代码。
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-frontend-events-003 sha256=6c44ac4b3bc74f128b5efb8b7b51851ca28bdfc3e8f8b52a3d50f9fc043d4977 -->
-## 模板引擎事件
-
-`TableTemplateEngine` / `FormTemplateEngine` — 见 `v8-template-engine/SKILL.md`。
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-frontend-events-004 sha256=4071ce5e92d2352e455e4dbe5310cc3d8f8c349721ad53f734397d30dc0b2c4e -->
-## 工作流事件（前端）
-
-`WFNodeEnd` — 流程节点结束后前端通知。详见 `v8-workflow/SKILL.md`。
-
-<!-- /microi-progressive:chunk -->
-<!-- microi-progressive:chunk id=v8-frontend-events-005 sha256=717095c6c96b1895cf607d787854a6f99c9ac90cc9282bdc95b5f9b4cfa4095e -->
-## 设计模式保护（CRITICAL）
-
-```javascript
-// 任何前端字段事件都应在头部加这个判断！
-if (V8.LoadMode === 'Design') return;
-```
-否则在【表单设计器】中编辑字段时，事件会被误触发，可能弹提示、报错或触发副作用。
-<!-- /microi-progressive:chunk -->
-## 详细参考路由（渐进披露）
-
-仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。
-
-- [references/progressive-01-列表事件.md](references/progressive-01-列表事件.md)：列表事件；常用前端 API；前端 FormEngine 菜单上下文与兼容授权；异步写法（async/await vs 回调）；死循环陷阱
-<!-- microi-progressive:end -->
+---
+name: v8-frontend-events
+description: Microi 前端 V8 事件与客户端能力指南。用于编写浏览器端字段、按钮、列表事件，或使用 V8.EventName、V8.Form、V8.Print 蓝牙打印（佳博 GP-M322、ZICOX CC4、TSPL、CPCL、ESC/POS、BLE、SPP）、扫码、弹窗、表单联动和界面交互。
+---
+
+> **Microi吾码基础规范（强制）：** 任何 AI 模型与宿主每次新建或接续吾码任务，先完整读取 `../workspace-conventions/SKILL.md`，必须执行版本播报、`@microi.net/cli` 后台自动升级、Skills/MCP 同步和进度播报。安装与诊断读取 `../microi-codex-installer/SKILL.md`；更新失败延后重试，不阻断当前工作。
+
+# Microi V8 前端事件大全
+
+你正在为 Microi 吾码平台编写 **前端 V8 事件** 代码。前端事件运行在浏览器，通过 `V8.EventName` 区分事件类型，可访问表单/列表/弹窗等丰富的客户端 API。
+
+> **表单生命周期事件**（InFormV8、SubmitFormV8、SubmitBeforeServerV8、SubmitAfterServerV8、OutFormV8、DataFilterV8）见 `v8-table-event/SKILL.md`。  
+> **菜单按钮事件**（MoreBtns/FormBtns 等）见 `v8-menu-buttons/SKILL.md`。  
+> 本文重点是 **字段事件、按钮事件、列表事件、模板引擎、其它前端钩子**。
+
+<!-- microi-progressive:begin -->
+<!-- microi-progressive:chunk id=v8-frontend-events-000 sha256=69ad0ebf0c8aca6edcbc0bbfe7e280986525bf28f68da8cb33c8efbc4509f7da -->
+## 能力路由
+
+- 查询前端 V8 全部上下文、导航、表单、列表、网络、引擎与工具入口时，读取 `../v8-utilities/references/client-api-index.md`。
+- 需求包含“蓝牙打印、标签打印、TSC/TSPL、CPCL、ESC/POS、小票打印、佳博/GP-M322、ZICOX/芝柯/CC4、BLE/SPP”时，必须先读取 `references/bluetooth-print.md`；需要完整指令签名、型号转换范围、编码或位图参数时，再读取 `references/bluetooth-print-api.md`。
+- `microi.app` 是 5+ 在线壳，不能假设存在 `uni` 或 Web Bluetooth。BLE 连接、发现和写入必须统一使用 `plus.bluetooth`，禁止用 `uni.writeBLECharacteristicValue` 写入由 `plus.bluetooth` 建立的连接。5+ `V8.Print.getConnectionState()` 的 `mtu/maxWriteBytes/recommendedPacketSize/writeType/packetIntervalMs` 描述本次连接能力。Android GP-M322 在特征支持时优先 `writeNoResponse`，即使协商出 180 字节有效载荷也只采用 100 字节连续发送稳定档，并保留约 8ms 包间保护；不支持无响应写时兼容 `write`，空 MTU 成功、失败、超时或旧壳只用 20 字节。详见蓝牙参考。
+- 浏览器模板打印、PDF/纸张模板、`mic_print`、`PageObj`、`PrintObj` 使用 `print-engine/SKILL.md`，不要与直接蓝牙指令混为一套 API。
+- 扫码使用 `V8.Method.ScanCode`，结果从 Promise/回调取得；`V8.ScanCodeRes` 只作兼容结果槽，详见客户端 API 索引。
+- 登录后的敏感操作使用 `V8.Identity.Verify` 完成 Passkey/严格人脸交互；前端只取得一次性 Ticket，后端接口引擎必须重算 `ActionHash` 并原子消费，不能把前端成功当作授权。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-frontend-events-001 sha256=eaab87d01b0fd2b6964326ee11edd7b793899c679930c575a0a2b309d36a367a -->
+## 字段事件（在【字段属性】中配置）
+
+### FieldValueChange — 值变更事件（最常用）
+
+```javascript
+// V8.EventName === 'FieldValueChange'
+// V8.ThisValue   — 当前字段新值
+// V8.OldValue    — 仅表格行内字段事件可靠提供；普通表单读取 V8.OldForm
+// V8.Form        — 整个表单数据
+// V8.FormMode    — 'Add' / 'Edit' / 'View'
+// V8.LoadMode    — 'Design' 表示设计器中，'View' 是真实表单
+
+// ★ 关键：设计模式下不要执行业务逻辑（防止设计器卡顿）
+if (V8.LoadMode === 'Design') return;
+
+// 选择部门 → 联动加载该部门下的人员到 联系人 控件
+var deptId = V8.ThisValue && V8.ThisValue.Id;
+if (deptId) {
+  var users = await V8.FormEngine.GetTableData('Diy_Employee', {
+    _SelectFields: ['Id', 'Name', 'Account'],
+    _Where: [['DeptId', '=', deptId]]
+  });
+  V8.FieldSet('Contact', 'Data', users.Code === 1 ? users.Data : []);
+} else {
+  V8.FieldSet('Contact', 'Data', []);
+}
+
+// 联动设置另一字段值
+V8.FormSet('CustomerName', V8.ThisValue.Name);
+
+// 联动显隐
+V8.FieldSet('TaxNo', 'Visible', V8.ThisValue === '企业');
+
+// 联动必填
+V8.FieldSet('Reason', 'Required', V8.ThisValue === '退款');
+```
+
+### FieldOnKeyup — 键盘抬起事件
+
+```javascript
+// V8.EventName === 'FieldOnKeyup'
+// 表格行内键盘事件为 V8.EventName === 'TableFieldOnKeyup'
+// V8.KeyCode     — 键码；当前键盘 V8 不提供原生 V8.Event
+
+if (V8.KeyCode === 13) {
+  V8.FormSubmit({ CloseForm: false });
+}
+```
+
+### V8CodeBlur — 失焦专用代码
+
+```javascript
+// 当前运行时仍使用 V8.EventName === 'FieldValueChange'
+// V8.ThisValue 是失焦时的当前输入值
+// 失焦校验手机号
+if (V8.ThisValue && !/^1[3-9]\d{9}$/.test(V8.ThisValue)) {
+  V8.Tips('手机号格式不正确', false);
+  V8.Form.Phone = ''; // 静默清空，避免再次触发当前字段事件
+}
+```
+
+### FieldSlotButtonClick — 单行文本插槽按钮
+
+单行文本 `Text` 开启【插槽按钮】后，必须在【插槽按钮V8代码】中配置行为，不要再写“弹出表格Id”。
+
+```javascript
+// V8.EventName === 'FieldSlotButtonClick'
+// V8.ThisValue — 当前输入框值
+// V8.Event     — 原生点击事件
+
+if (V8.LoadMode === 'Design') return;
+
+V8.OpenAnyTable({
+  SysMenuId: '目标业务菜单Id',
+  MultipleSelect: false,
+  SubmitEvent: function (selectData, callback) {
+    callback({ Code: 1, Data: selectData });
+  }
+});
+// 或 V8.OpenAnyForm / V8.OpenAppDialog / V8.ApiEngine.Run 等任意前端 V8 能力
+```
+
+`ReadOnlyButton` 的产品文案是【禁用插槽按钮】：只控制按钮是否可点击，不等同于字段只读，应保留用于权限和状态控制。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-frontend-events-002 sha256=faf64dbf6ded2a086c347bea31edecb7d6fc8b765114290d17998b7370d17372 -->
+## 按钮事件
+
+### V8BtnRun — 按钮点击执行（菜单按钮、表单按钮）
+
+```javascript
+// V8.Form        — 当前行/表单数据
+// V8.FormMode    — Add / Edit / View
+// V8.TableId     — 当前 diy_table 的 Id
+// V8.TableRowSelected — 批量按钮中选中的行数组
+// V8.ClientType  — 'PC' / 'IOS' / 'Android' / 'H5' / 'WeChat'
+
+V8.ConfirmTips('确认审核通过？', function() {
+  V8.ApiEngine.Run({
+    ApiEngineKey: 'order_approve',
+    Id: V8.Form.Id
+  }, function(r) {
+    if (r.Code === 1) { V8.Tips('审核成功', true); V8.RefreshTable({ _PageIndex: 1 }); }
+    else V8.Tips(r.Msg || '失败', false);
+  });
+});
+```
+
+### V8BtnLimit — 按钮显隐（V8CodeShow）
+
+```javascript
+// 推荐：直接 return boolean
+return V8.Form.Status === '待审核' && V8.CurrentUser.RoleName.indexOf('审批员') !== -1;
+
+// 兼容旧写法：V8.Result = true/false
+// V8.Result = V8.Form.Status === '待审核';
+```
+
+`V8CodeShow` 与点击事件使用同一套前端 V8 能力，允许直接使用 `await`。平台所有
+按钮入口（列表按钮、表单顶部按钮、更多按钮和子表打开的嵌套表单按钮）都必须走
+异步执行器并等待结果后再决定显隐；不得在某一层退回同步 `new Function`，否则同一段
+代码在列表可用、进入嵌套表单后会报 `await is only valid in async functions`。回归测试
+至少覆盖“主表详情 → 定制子表 → 子记录详情”链路中的含 `await` 显隐代码。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-frontend-events-003 sha256=6c44ac4b3bc74f128b5efb8b7b51851ca28bdfc3e8f8b52a3d50f9fc043d4977 -->
+## 模板引擎事件
+
+`TableTemplateEngine` / `FormTemplateEngine` — 见 `v8-template-engine/SKILL.md`。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-frontend-events-004 sha256=4071ce5e92d2352e455e4dbe5310cc3d8f8c349721ad53f734397d30dc0b2c4e -->
+## 工作流事件（前端）
+
+`WFNodeEnd` — 流程节点结束后前端通知。详见 `v8-workflow/SKILL.md`。
+
+<!-- /microi-progressive:chunk -->
+<!-- microi-progressive:chunk id=v8-frontend-events-005 sha256=717095c6c96b1895cf607d787854a6f99c9ac90cc9282bdc95b5f9b4cfa4095e -->
+## 设计模式保护（CRITICAL）
+
+```javascript
+// 任何前端字段事件都应在头部加这个判断！
+if (V8.LoadMode === 'Design') return;
+```
+否则在【表单设计器】中编辑字段时，事件会被误触发，可能弹提示、报错或触发副作用。
+<!-- /microi-progressive:chunk -->
+## 详细参考路由（渐进披露）
+
+仅在当前任务涉及对应主题时读取；下列文件合计保留了原 SKILL.md 的全部详细知识。
+
+- [references/progressive-01-列表事件.md](references/progressive-01-列表事件.md)：列表事件；常用前端 API；前端 FormEngine 菜单上下文与兼容授权；异步写法（async/await vs 回调）；死循环陷阱
+<!-- microi-progressive:end -->

package/skills/v8-frontend-events/references/bluetooth-print-api.md

@@ -1,135 +1,135 @@
-# V8.Print TSC、CPCL 适配与 ESC/POS 源码 API
-
-本表直接按 `Microi.Client/src/utils/ble/tsc.js`、`esc.js`、
-`printer-compatibility.js` 与编码文件整理。方法名
-（包括历史拼写）必须与源码完全一致，不能根据打印机手册自行改名。
-
-## 目录
-
-- [构建器与编码](#构建器与编码)
-- [TSC/TSPL 的 28 个方法](#tsctspl-的-28-个方法)
-- [ZICOX CC4 的 CPCL 映射](#zicox-cc4-的-cpcl-映射)
-- [ESC/POS 的 25 个方法](#escpos-的-25-个方法)
-- [参数与组合规则](#参数与组合规则)
-
-## 构建器与编码
-
-```javascript
-var tsc = V8.Print.createNew();
-var esc = V8.Print.createNewESC();
-```
-
-两个构建器都把指令累积到普通字节数组，`getData()` 返回该数组。TSC 返回值还带不可枚举
-协议/操作元数据：普通遍历与 GP-M322 字节值不变，CC4 发送前据此生成 CPCL。不要复制或
-序列化 TSC 数组后再交给 `prepareSend`。TSC 的全部文本命令、
-ESC 的 `setText` 和二维码内容通过本地 `TextEncoder('gb18030', {
-NONSTANDARD_allowLegacyEncoding: true })` 编码；映射表来自同目录的
-`encoding-indexes.js`，不需要网络请求。
-
-## TSC/TSPL 的 28 个方法
-
-| 方法 | 当前生成的指令/作用 |
-|---|---|
-| `init()` | 空操作，历史兼容入口 |
-| `addCommand(content)` | 以 GB18030 追加原始 TSC 文本；只用于固定可信命令 |
-| `setSize(width,height)` | `SIZE width mm,height mm` |
-| `setSpeed(speed)` | `SPEED speed` |
-| `setDensity(density)` | `DENSITY density` |
-| `setGap(gap)` | `GAP gap mm,0 mm` |
-| `setBline(bline)` | `BLINE bline mm,0 mm`，黑标纸 |
-| `setCountry(country)` | `COUNTRY country` |
-| `setCodepage(codepage)` | `CODEPAGE codepage` |
-| `setCls()` | `CLS`，清除图像缓冲区 |
-| `setFeed(feed)` | `FEED feed`，向前走纸 |
-| `setBackFeed(backup)` | `BACKFEED backup`，回拉 |
-| `setDirection(direction)` | `DIRECTION direction` |
-| `setReference(x,y)` | `REFERENCE x,y`，坐标原点 |
-| `setFromfeed()` | 注意源码拼写；实际生成 `FORMFEED` |
-| `setHome()` | `HOME`，定位下一张标签 |
-| `setSound(level,interval)` | `SOUND level,interval` |
-| `setLimitfeed(limit)` | `LIMITFEED limit` |
-| `setBar(x,y,width,height)` | `BAR` 线条 |
-| `setBox(x1,y1,x2,y2,thickness)` | `BOX` 方框 |
-| `setErase(x,y,width,height)` | `ERASE` 清除区域 |
-| `setReverse(x,y,width,height)` | `REVERSE` 区域反相 |
-| `setText(x,y,font,xScale,yScale,text)` | `TEXT`；旋转值在源码中固定为 `0` |
-| `setQR(x,y,level,width,mode,content)` | `QRCODE`；旋转值固定为 `0` |
-| `setBarCode(x,y,type,height,readable,narrow,wide,content)` | `BARCODE`；旋转值固定为 `0` |
-| `setBitmap(x,y,mode,imageData)` | 生成 TSC `BITMAP` 二进制数据 |
-| `setPagePrint()` | `PRINT 1,1` |
-| `getData()` | 返回当前字节数组 |
-
-最小顺序通常是 `setSize` → `setGap`/`setBline` → `setCls` → 内容 →
-`setPagePrint` → `getData`。字体名、条码类型、纸张传感器、速度和浓度由打印机固件决定，
-构建器不验证范围。
-
-## ZICOX CC4 的 CPCL 映射
-
-| TSC 方法 | CC4 CPCL 结果 |
-|---|---|
-| `setSize(w,h)` | 203 dpi 下按 `8 dots/mm` 生成页宽/页高 |
-| `setSpeed` / `setDensity` | `SPEED` / `CONTRAST`，钳制到当前安全范围 |
-| `setGap` / `setBline` | `GAP-SENSE` / `BAR-SENSE` |
-| `setFeed` / `setBackFeed` | `POSTFEED` / `PREFEED` |
-| `setDirection(0/1)` | `ZPROTATE` / `ZPROTATE180` |
-| `setReference` | 转换坐标时叠加参考点 |
-| `setBar` / `setBox` / `setReverse` | `LINE` / `BOX` / `INVERSE-LINE` |
-| `setText` | `SETMAG` + `T`，字体名按 16/24/32 档映射 |
-| `setBarCode` | `BARCODE`，可选 `BARCODE-TEXT` |
-| `setQR` | 厂家 SDK 格式 `BARCODE QR ...` + 数据 + `ENDQR` |
-| `setBitmap` | `CG` + 原始单色位图字节 |
-| `setPagePrint` | 最终统一补 `FORM` + `PRINT`，每份必须恰好一次 |
-
-`init`、`setCls` 不输出。`addCommand`、`setCountry`、`setCodepage`、`setFromfeed`、
-`setHome`、`setSound`、`setLimitfeed`、`setErase` 与未知方法会抛错，并且适配发生在分包前，
-所以失败时不得写入任何一包。该白名单只表达当前有证据的等价转换，不代表 CC4 固件不具备
-其它 CPCL 能力。
-
-`createNewESC()` 的数组标记为 ESC/POS，CC4 直接原样发送，不进入 CPCL 转换。
-
-## ESC/POS 的 25 个方法
-
-| 方法 | 当前生成的指令/作用 |
-|---|---|
-| `init()` | ESC `@` 初始化 |
-| `setText(content)` | 以 GB18030 追加文字 |
-| `setFontSize(n)` | GS `! n` |
-| `bold(n)` | ESC `E n` |
-| `setUnderline(n)` | ESC `- n` |
-| `setUnderline2(n)` | FS `- n` |
-| `setSelectSizeOfModuleForQRCode(n)` | 设置二维码模块尺寸，源码钳制到 1–15 |
-| `setSelectErrorCorrectionLevelForQRCode(n)` | 设置二维码纠错值，源码不验证范围 |
-| `setStoreQRCodeData(content)` | 以 GB18030 暂存二维码内容 |
-| `setPrintQRCode()` | 输出已暂存二维码 |
-| `setHorTab()` | 水平 Tab |
-| `setAbsolutePrintPosition(where)` | 设置绝对横向位置 |
-| `setRelativePrintPositon(where)` | 设置相对横向位置；`Positon` 是现有公开拼写 |
-| `setSelectJustification(which)` | 对齐：常见值 0 左、1 中、2 右 |
-| `space(n)` | 设置水平制表位置 |
-| `setLeftMargin(n)` | 设置左边距 |
-| `textMarginRight(n)` | 设置字符右间距 |
-| `rowSpace(n)` | 设置行间距 |
-| `setPrintingAreaWidth(width)` | 设置打印区域宽度 |
-| `setSound(n,t)` | 蜂鸣器；大于 9 钳制为 9，小于 0 改为 1，0 会原样保留 |
-| `setBitmap(imageData)` | 生成 ESC/POS 光栅位图数据 |
-| `setPrint()` | 换行/打印当前行 |
-| `setPrintAndFeed(feed)` | 打印并走纸指定单位 |
-| `setPrintAndFeedRow(row)` | 打印并走纸指定行数 |
-| `getData()` | 返回当前字节数组 |
-
-ESC/POS 二维码需要按顺序调用尺寸、纠错、`setStoreQRCodeData`、
-`setPrintQRCode`。源码中虽保留条码类型数组，但没有公开 ESC/POS 条码方法，不能虚构
-`setBarCode`；条码需求应先确认型号并扩展实现。
-
-## 参数与组合规则
-
-- `setBitmap` 的参数是 ImageData 风格对象：`width`、`height`、RGBA `data`。它不是图片
-  URL、Base64 或 DOM `<img>`；调用前先在 Canvas 得到 `getImageData()`。
-- 当前位图算法按透明/非透明像素进行非常简单的黑白映射，不做通用抖动和灰度阈值处理；
-  大图先缩放、二值化，逐型号验证方向、颜色和内存。
-- TSC `setText`、`setQR`、`setBarCode` 把值放入带双引号的协议字段。移除双引号、CR/LF、
-  NUL 和控制字符，限制长度；不要让接口返回值直达 `addCommand`。
-- ESC 参数最终作为单字节或低/高字节写入，负数、浮点数、超范围值可能截断或生成无效命令。
-  坐标、宽度、走纸、字号和蜂鸣器参数应先转为目标机型允许的整数。
-- GB18030 只解决字节编码，不能替代打印机代码页、中文字库和字体配置。二维码通常比文字
-  字库更能稳定承载 Unicode 业务标识，但仍受打印机二维码命令实现限制。
+# V8.Print TSC、CPCL 适配与 ESC/POS 源码 API
+
+本表直接按 `Microi.Client/src/utils/ble/tsc.js`、`esc.js`、
+`printer-compatibility.js` 与编码文件整理。方法名
+（包括历史拼写）必须与源码完全一致，不能根据打印机手册自行改名。
+
+## 目录
+
+- [构建器与编码](#构建器与编码)
+- [TSC/TSPL 的 28 个方法](#tsctspl-的-28-个方法)
+- [ZICOX CC4 的 CPCL 映射](#zicox-cc4-的-cpcl-映射)
+- [ESC/POS 的 25 个方法](#escpos-的-25-个方法)
+- [参数与组合规则](#参数与组合规则)
+
+## 构建器与编码
+
+```javascript
+var tsc = V8.Print.createNew();
+var esc = V8.Print.createNewESC();
+```
+
+两个构建器都把指令累积到普通字节数组，`getData()` 返回该数组。TSC 返回值还带不可枚举
+协议/操作元数据：普通遍历与 GP-M322 字节值不变，CC4 发送前据此生成 CPCL。不要复制或
+序列化 TSC 数组后再交给 `prepareSend`。TSC 的全部文本命令、
+ESC 的 `setText` 和二维码内容通过本地 `TextEncoder('gb18030', {
+NONSTANDARD_allowLegacyEncoding: true })` 编码；映射表来自同目录的
+`encoding-indexes.js`，不需要网络请求。
+
+## TSC/TSPL 的 28 个方法
+
+| 方法 | 当前生成的指令/作用 |
+|---|---|
+| `init()` | 空操作，历史兼容入口 |
+| `addCommand(content)` | 以 GB18030 追加原始 TSC 文本；只用于固定可信命令 |
+| `setSize(width,height)` | `SIZE width mm,height mm` |
+| `setSpeed(speed)` | `SPEED speed` |
+| `setDensity(density)` | `DENSITY density` |
+| `setGap(gap)` | `GAP gap mm,0 mm` |
+| `setBline(bline)` | `BLINE bline mm,0 mm`，黑标纸 |
+| `setCountry(country)` | `COUNTRY country` |
+| `setCodepage(codepage)` | `CODEPAGE codepage` |
+| `setCls()` | `CLS`，清除图像缓冲区 |
+| `setFeed(feed)` | `FEED feed`，向前走纸 |
+| `setBackFeed(backup)` | `BACKFEED backup`，回拉 |
+| `setDirection(direction)` | `DIRECTION direction` |
+| `setReference(x,y)` | `REFERENCE x,y`，坐标原点 |
+| `setFromfeed()` | 注意源码拼写；实际生成 `FORMFEED` |
+| `setHome()` | `HOME`，定位下一张标签 |
+| `setSound(level,interval)` | `SOUND level,interval` |
+| `setLimitfeed(limit)` | `LIMITFEED limit` |
+| `setBar(x,y,width,height)` | `BAR` 线条 |
+| `setBox(x1,y1,x2,y2,thickness)` | `BOX` 方框 |
+| `setErase(x,y,width,height)` | `ERASE` 清除区域 |
+| `setReverse(x,y,width,height)` | `REVERSE` 区域反相 |
+| `setText(x,y,font,xScale,yScale,text)` | `TEXT`；旋转值在源码中固定为 `0` |
+| `setQR(x,y,level,width,mode,content)` | `QRCODE`；旋转值固定为 `0` |
+| `setBarCode(x,y,type,height,readable,narrow,wide,content)` | `BARCODE`；旋转值固定为 `0` |
+| `setBitmap(x,y,mode,imageData)` | 生成 TSC `BITMAP` 二进制数据 |
+| `setPagePrint()` | `PRINT 1,1` |
+| `getData()` | 返回当前字节数组 |
+
+最小顺序通常是 `setSize` → `setGap`/`setBline` → `setCls` → 内容 →
+`setPagePrint` → `getData`。字体名、条码类型、纸张传感器、速度和浓度由打印机固件决定，
+构建器不验证范围。
+
+## ZICOX CC4 的 CPCL 映射
+
+| TSC 方法 | CC4 CPCL 结果 |
+|---|---|
+| `setSize(w,h)` | 203 dpi 下按 `8 dots/mm` 生成页宽/页高 |
+| `setSpeed` / `setDensity` | `SPEED` / `CONTRAST`，钳制到当前安全范围 |
+| `setGap` / `setBline` | `GAP-SENSE` / `BAR-SENSE` |
+| `setFeed` / `setBackFeed` | `POSTFEED` / `PREFEED` |
+| `setDirection(0/1)` | `ZPROTATE` / `ZPROTATE180` |
+| `setReference` | 转换坐标时叠加参考点 |
+| `setBar` / `setBox` / `setReverse` | `LINE` / `BOX` / `INVERSE-LINE` |
+| `setText` | `SETMAG` + `T`，字体名按 16/24/32 档映射 |
+| `setBarCode` | `BARCODE`，可选 `BARCODE-TEXT` |
+| `setQR` | 厂家 SDK 格式 `BARCODE QR ...` + 数据 + `ENDQR` |
+| `setBitmap` | `CG` + 原始单色位图字节 |
+| `setPagePrint` | 最终统一补 `FORM` + `PRINT`，每份必须恰好一次 |
+
+`init`、`setCls` 不输出。`addCommand`、`setCountry`、`setCodepage`、`setFromfeed`、
+`setHome`、`setSound`、`setLimitfeed`、`setErase` 与未知方法会抛错，并且适配发生在分包前，
+所以失败时不得写入任何一包。该白名单只表达当前有证据的等价转换，不代表 CC4 固件不具备
+其它 CPCL 能力。
+
+`createNewESC()` 的数组标记为 ESC/POS，CC4 直接原样发送，不进入 CPCL 转换。
+
+## ESC/POS 的 25 个方法
+
+| 方法 | 当前生成的指令/作用 |
+|---|---|
+| `init()` | ESC `@` 初始化 |
+| `setText(content)` | 以 GB18030 追加文字 |
+| `setFontSize(n)` | GS `! n` |
+| `bold(n)` | ESC `E n` |
+| `setUnderline(n)` | ESC `- n` |
+| `setUnderline2(n)` | FS `- n` |
+| `setSelectSizeOfModuleForQRCode(n)` | 设置二维码模块尺寸，源码钳制到 1–15 |
+| `setSelectErrorCorrectionLevelForQRCode(n)` | 设置二维码纠错值，源码不验证范围 |
+| `setStoreQRCodeData(content)` | 以 GB18030 暂存二维码内容 |
+| `setPrintQRCode()` | 输出已暂存二维码 |
+| `setHorTab()` | 水平 Tab |
+| `setAbsolutePrintPosition(where)` | 设置绝对横向位置 |
+| `setRelativePrintPositon(where)` | 设置相对横向位置；`Positon` 是现有公开拼写 |
+| `setSelectJustification(which)` | 对齐：常见值 0 左、1 中、2 右 |
+| `space(n)` | 设置水平制表位置 |
+| `setLeftMargin(n)` | 设置左边距 |
+| `textMarginRight(n)` | 设置字符右间距 |
+| `rowSpace(n)` | 设置行间距 |
+| `setPrintingAreaWidth(width)` | 设置打印区域宽度 |
+| `setSound(n,t)` | 蜂鸣器；大于 9 钳制为 9，小于 0 改为 1，0 会原样保留 |
+| `setBitmap(imageData)` | 生成 ESC/POS 光栅位图数据 |
+| `setPrint()` | 换行/打印当前行 |
+| `setPrintAndFeed(feed)` | 打印并走纸指定单位 |
+| `setPrintAndFeedRow(row)` | 打印并走纸指定行数 |
+| `getData()` | 返回当前字节数组 |
+
+ESC/POS 二维码需要按顺序调用尺寸、纠错、`setStoreQRCodeData`、
+`setPrintQRCode`。源码中虽保留条码类型数组，但没有公开 ESC/POS 条码方法，不能虚构
+`setBarCode`；条码需求应先确认型号并扩展实现。
+
+## 参数与组合规则
+
+- `setBitmap` 的参数是 ImageData 风格对象：`width`、`height`、RGBA `data`。它不是图片
+  URL、Base64 或 DOM `<img>`；调用前先在 Canvas 得到 `getImageData()`。
+- 当前位图算法按透明/非透明像素进行非常简单的黑白映射，不做通用抖动和灰度阈值处理；
+  大图先缩放、二值化，逐型号验证方向、颜色和内存。
+- TSC `setText`、`setQR`、`setBarCode` 把值放入带双引号的协议字段。移除双引号、CR/LF、
+  NUL 和控制字符，限制长度；不要让接口返回值直达 `addCommand`。
+- ESC 参数最终作为单字节或低/高字节写入，负数、浮点数、超范围值可能截断或生成无效命令。
+  坐标、宽度、走纸、字号和蜂鸣器参数应先转为目标机型允许的整数。
+- GB18030 只解决字节编码，不能替代打印机代码页、中文字库和字体配置。二维码通常比文字
+  字库更能稳定承载 Unicode 业务标识，但仍受打印机二维码命令实现限制。