# 组件接口

浏览器全局为 `NJWLTable`，版本为 `NJWLTable.version`。

## 新表：mount(element, config)

- `key`：当前账号内的唯一表标识；账号隔离由存储接口负责。
- `rows`：当前数据数组，记录推荐有唯一字符串 `id` 或 `uid`。不要把同一个表重复 id 当不同记录。
- `columns`：字段数组，每项 `id, label, value(record)`；操作列配置 `actions:true` 并使用 `render(record)` 返回 DOM Node。
- `type`：text / number / date（日期字符串）/ timestamp（数字时间戳）；`format(value)` 控制显示；`enumOrder` 控制枚举自然顺序；`categorical:true` 标记分类分组。
- `customValue(record)`：可选，用于多选字段自定义排序；`options`：完整候选；`directionLabels:[正序文案,倒序文案]`；`defaultDirection`；`widthSpec:[最小宽度,弹性权重]`。
- `edit(record)`：返回 `value, options:[[值,标签]], save(value):Promise`；或配置 type/required 的基础输入。没有 edit 即只读。保存失败应 reject，组件保留草稿。调用者负责版本校验、提交后更新内存记录，必要时重新读取。
- `defaults`：`search,filters,sortRules:[{key,direction,order}],columns,group,scroll`。direction 为 asc/desc/custom；order 是自定义值顺序。默认分组只在有分类主项或重复值时显示。
- `loadState():Promise<view|null>`、`saveState(view,{keepalive}):Promise`：业务适配层提供，组件不内置 URL 或 Token。
- `maxSortRules`：可选；与业务存储协议允许的上限一致。
- `watermark():Node|null`：可选水印来源。

返回 `ready` Promise、`filtered()`、`view`、`render()`、`flush()`、`destroy()`。替换数据集时重新 mount；销毁会断开观察器并释放弹窗。

## 既有复杂表：createControls(host)

让业务保留现有行渲染、整行编辑、标签和表单，只把通用控件交给组件。参考随交付提供的 `adapters/crm-host.js`。

host 提供 `element(slot)`（sortRules、sortAnnounce、listHead、rows）、`field(key)`、`rules/setRules`、`columns/orderedColumns/setColumns`、`records/render/locked`、`table/scroll`。可选 `candidates, groupPath, addInGroup, watermark, editingColumn, widthSpec, beforeColumnMove, afterSortRender, defaultSortKey, defaultHint`。

组件返回 renderSortRules、addSortRule、moveSortRule、renderVisualGroups、applyColumnOrder、fitColumnWidths、openCustomOrder、openColumns、compareSortRule 等。CRM 与新表 mount 使用的正是这一实现，不是两份同名代码。

`guardDialog(dialog)`：未保存关闭提示、提交锁定；调用返回对象 begin() 开始提交，end(true) 成功关闭，end() 失败后恢复控件。`lockControls(elements,on)` 用于既有业务编辑流程。

## 修改边界

应用样式只管理外层布局和业务字段呈现。不要在应用 CSS 中覆盖 `.sort-rule`、`.custom-order-*`、`.visual-group`、`.group-caption`、`.column-drag` 等组件内部类。需要改变这些实现，登记 fork 并修改组件源文件；构建输出可由脚本生成，不能作为第二份手工源码。


## 1.1 自动网址与显示偏好

- urlHref(value)：整格字符串识别，返回规范化 http/https 地址或 null。无协议域名补 https；保留显示原文。拒绝邮箱、用户信息、空白/控制字符、非 HTTP(S) 协议、协议相对地址；只对显式 HTTP(S) 支持 IP 和 localhost。无法仅靠语法区分域名与类似 readme.md 的文件名，误识别可单项或整列关闭。
- linkNode(value,{enabled=true,label=value})：返回安全 DOM 链接或文本节点，可给 createControls 宿主使用。不解析 HTML、不探测外网。链接新标签页打开并设置 noopener noreferrer。
- columns[].autoLink:false：应用强制禁用该字段。自定义 render 返回的 DOM 保持原样，应用自行使用 linkNode，不修改既有按钮或链接。
- view.links = {disabledFields:[fieldId], disabledCells:[[rowId,fieldId,originalValue]]}。字段关闭优先；恢复字段不会清除单项关闭。后端按账号和表 key 校验并保留此结构，限制大小；本版本不引入业务数据字段。recordKey 必须稳定且唯一，缺少稳定 ID 时单项设置禁用，字段设置仍可用。
- 编辑取消不保存偏好；业务保存失败保留草稿和勾选状态，成功后提交偏好到视图存储。视图保存失败显示错误，不能当作服务端持久化成功；业务保存与视图存储为两个独立操作。