网页界面之约 0.3.0

有标识元素与事件队列之宿主，乃可具此包。浏览器以文树行之；他宿主能守同约，方得自称具之。客依此包，诸术皆须备，阙一则拒装。

零点二点零于零点一点零之四术（读页面语言、设置节点文字、设置节点属性、等待界面事件）之上，增：控件之值读写、显隐禁读、类名、焦点、输入之光标与选区、滚动、模态框、页面之状。旧术之签不易；设置节点属性之白册加广；等待界面事件改为依类型自统一事列取事（见[网页事件之约](../网页事件/规范.文言.md)）。

零点三点零于零点二点零之上惟增术（旧术之签与义不易）：读取节点属性、移除节点属性、读取节点文字（读回与去除）、点击节点（程序性之点）、设置节点位置、读取节点矩形（置浮层）。此诸术为云控制台与阅读页由 JavaScript 迁入豫言所遇之缺而设，见[前端补全计划](../../豫言操作系统/文档/前端补全计划.汉语.md)。

诸术皆以元素标识求页中既有之元素，不生柄，不授客以原生文树之物。文皆豫言字符串。

败之义

此包诸败，皆属违约之调用或平台之故，一律发豫言事故，客可捕之；事故之辞用华言而存其因：元素阙、元素类不符、参数越界或式不合、属性或链接不在白册、浏览器拒其事（如已开之 dialog 复 showModal）。宿主不得以败为成，亦不得使宿主之异常越豫言之界而客不能捕。此包无“可复之业情”，故无以返值示错者。

险元素：script、style、iframe、object、embed、link、meta、base、frame、frameset、applet 不可为读写之目标（iframe 惟可设 class、title、hidden 及 data-、aria-；其址惟经网页文树之设置页面框架地址而改）。

诸术

页面之语与文

• 读取页面语言：取根元素之语标，未设则空文。
• 设置节点文字：以纯文尽易元素之文，不析 HTML；文至多八 MiB（UTF-16 码元）；br、input 等空元素惟受空文。

属性

设置节点属性（标识、名、值）：名须以 ASCII 小写字母始，余为小写字母、数与横线，至多六十四字；值不得含控制字（制表、换行、回车不在此限），至多六万五千五百三十六码元。许之属性（白册，与网页文树共一表）：

| 属性 | 所施元素 | 值之律 | | --- | --- | --- | | class | 任意 | 见设置节点类名 | | id | 任意 | 不含空白、引号、尖括号、和号、反引号、反斜杠与控制字，一至一百二十八字，且文档中无他元素已用；空文则去之 | | role | 任意 | 小写字母与横线，至多三十二字 | | title | 任意 | 至多四千零九十六字 | | hidden disabled readonly checked selected open | 任意 | 布尔属性，值惟 空文、true（有）、false（去） | | tabindex | 任意 | 惟许 -1 与 0 | | type | button：button submit reset；input：button submit reset checkbox radio text search number email url tel password range date time datetime-local | 值在所列之集 | | placeholder | input、textarea | 至多四千零九十六字 | | datetime | time | 数字、T、Z、冒号、点、加、减、空格，至多六十四字 | | maxlength | input、textarea | 至多六位数 | | rows | textarea | 至多六位数 | | colspan rowspan | td、th | 至多六位数 | | for | label | 字律同 id | | value | input、option、button | 任意（至多六万五千五百三十六码元） | | href | 惟 a | 见下 | | target | 惟 a | 惟许 _blank、_self；设 _blank 则宿主必并设 rel 为 noopener noreferrer | | aria-、data- | 任意 | 名以 aria- 或 data- 起，后接小写字母、数与横线；值任意（受上总限） |

data-yy- 之前缀专留宿主，客不得设（data-yy 乃操作之键，客可设）。style、src、srcdoc、rel、name、action、formaction、sandbox 及诸 on* 事处之属性，一概拒之。

a 之 href 惟许：以斜杠起而不以双斜杠起之站内径、以井号起之锚、https:// 址、http:// 址（不分大小写）。含空白、控制字或反斜杠之址，与 javascript:、data:、vbscript:、mailto:、双斜杠之无协议址，一概拒之。http: 惟于 a 之 href 放行。

类名

设置节点类名（标识、类名，以空格隔）：尽易元素之 class。每名惟许 Unicode 之字、数、下划线与横线（故华文可用），间隔惟 ASCII 空格（连空格并为一）；至多三十二名，名至多六十四字，总长至多五百一十二；空文则去 class。

设置节点类标记（标识、单个类名、有无）：增或去元素上单个类名（应 classList.toggle(类名, 有无)）：阳则加，阴则去，余类不动。类名惟许其一，字律同设置节点类名（至多六十四字，不得含空格）。

控件之值

• 读取节点值：读 input、textarea、select 之现值；值按 UTF-8 计逾八 MiB 则发事故（宿主与客交换数据之单次限为十六 MiB，不可使之化为不能捕之宿主异常）。读取选区文字同此限。
• 设置节点值：设上述控件之值，不发 input 与 change 之事；值至多八 MiB；文件输入框不可设；select 无同值之选项则发事故。

显隐禁读

设置节点显示（阳显阴隐，应 hidden）、设置节点禁用（应 disabled）、设置节点只读（应 readonly）。

焦点

• 聚焦节点：使元素得焦点；不可聚焦者不报错，焦点不移。
• 读取聚焦标识：现得焦点元素之标识；无焦点或其元素无标识则空文。
• 节点包含焦点：元素自身或其后代有焦点则阳。

光标与选区

• 设置输入光标（标识、起、止）：设 input 或 textarea 之选区。
• 读取输入光标（标识）：返（起，止）二整数。
• 位置以豫言字符（Unicode 码点）计，不以 JavaScript 之 UTF-16 码元计；宿主任其互换（如 😀 于豫言占一位，于浏览器占二码元）。须零不逾起、起不逾止、止不逾文长，否则发事故；不支光标之输入类（如 number、email）发事故。
• 读取选区文字：取现选之文。聚焦之输入框内有选区则返之，否则返页上所选之文（getSelection），无选区则空文。

滚动

• 读取滚动度量：返癸象文 {"顶","总高","可视高"}，依次为 scrollTop、scrollHeight、clientHeight（四舍五入取整）。
• 设置滚动顶：设 scrollTop。

模态框

打开模态框、关闭模态框：施 showModal 与 close 于 dialog 元素；元素非 dialog、宿主不支或浏览器拒之（如已开而复开）则发事故。dialog 之 cancel（Esc）与 close 走网页事件之包：客以订阅界面事件订之，且可于策略中同步止 cancel 之默认。浏览器惟于页已得用户激活时许取消 cancel（未经交互则 cancel 不可取消，dialog 如常而闭），是时事之载带 可取消:false 与 已阻止默认:false。

页面之状与可见

• 读取页面状态：返癸象文 {"可见","联机","窄屏"}。可见为 document.hidden 之反，联机为 navigator.onLine，窄屏由定媒体查询 (max-width: 700px) 决（宿主无媒体查询则阴）。
• 读取节点可见：元素已入文档，且其自身与诸祖先之计算样式 display 皆非 none，则阳。

属性之读回与去除、文之读回（零点三点零）

• 读取节点属性：字符串（标识）、字符串（名），返（爻、字符串）：读元素上某属性之原样文（getAttribute，非 DOM 之属性，亦非计算之样式）。标识除元素标识外，尚可为保留字“文档根”（html 元素）与“页体”（body 元素），故标识为“文档根”“页体”之元素，惟可由保留字指其根元素。属性在则返（阳，值），布尔属性在则值为空文（如 <details open>）；无则返（阴，空文）。名须为 [a-z][a-z0-9:_-]*（至多六十四字），不得以 on 首，不得为 style 或 srcdoc。元素为危险元素、iframe 上读白册之外之属性、值逾六万五千五百三十六 UTF-16 码元，则发事故。type=password 输入框之 value 属性视为无（与界面事载同规）。常用：读根元素之 data-lang，读 details 之 open，读 aria-expanded。
• 移除节点属性：字符串（标识）、字符串（名），返有：去元素上一白册内之属性（removeAttribute）；属性本无则无事；名不在“属性”一节之白册（含 data-yy- 之首、style、on*）则发事故。去 class 等于以空文设类名；去 id 等于以空串设 id；去 target 不自去前所强加之 rel。
• 读取节点文字：字符串（标识），返字符串：读元素之 textContent；文按 UTF-8 计逾八 MiB 则发事故；危险元素与不存在之元素发事故。

点、位与矩形（零点三点零）

• 点击节点：字符串（标识），返有：于元素行一次程序性之点（HTMLElement.click()）。页上对此元素之诸订阅（含网页事件包之委托订阅）照常收 click 之事；此事非“受信之事”，浏览器不因此开弹窗或择文件之框。文件输入框、危险元素、href 不合上文链接之律之 a、不存在之元素，发事故；被禁用之元素点之无效而不发事故。回放为己所拦之点，须先撤拦截之订阅，再点，随后重订（否则宿主复拦此点）。
• 设置节点位置：字符串（标识）、整数、整数，返有：置元素之 style.left、style.top 为所给之像素整数（负十万至十万），用于置悬浮之示等浮层。元素之 position（absolute 或 fixed）由页面样式表别定；此包不开他样式。
• 读取节点矩形：字符串（标识），返字符串：返癸象文 {"左":整数,"上":整数,"右":整数,"下":整数}，乃元素相对视口之位（getBoundingClientRect，四舍五入取整）；display:none 或未入文档之元素四项皆零。

事

等待界面事件：依宿主收事之序取一界面类之事，返（事名，目标标识）；目标无标识则后者空文。他类（消息、定时等）之事留于统一事列，不被吞。宿主闭队列则返（关闭，空文），其后亦然。

界面事有二源：（一）旧式隐听：宿主于文档中有标识之元素自发 click、input、change、submit 之事，其行同零点一点零；（二）网页事件包之订阅界面事件所得之事（含委托：无标识之后代触发，则后者空文）。同名之事已为订阅界面事件所覆，则旧式隐听让之，同一击不再报二遍。欲得事之载（键盘、值、操作键等），客当改用等待网页事件。

限额

| 项 | 限 | | --- | --- | | 文与控件之值 | 至多八 MiB | | 属性之值 | 至多六万五千五百三十六码元 | | 类名 | 至多三十二名，名至多六十四字，总长至多五百一十二 | | 光标之位 | 零至文长（码点） |

跨宿主之一致

• 诸元素依当前文档中之标识求之；同标识有多元素，取文档序之首。
• 白册、限额与败之类须合此文；宿主可更严，不可更宽。
• 属性与链接之验成于宿主；客不得倚“先写而后为浏览器所阻”。

一致性之例

1. 设置节点文字("盒", "<img src=x onerror=alert(1)>")：元素中惟此纯文，无子元素。
2. 设置节点属性("链", "href", "javascript:alert(1)")：发事故；设 target 为 _blank 后，元素之 rel 为 noopener noreferrer。
3. 输入框值为“a😀bc”：设置输入光标(标识, 1, 3) 后，读取选区文字 为“😀b”，读取输入光标 为（1，3）。
4. 设置节点值("下拉", "不存在之值")：发事故；读取节点值("盒")（盒乃 div）：发事故。
5. （零点三点零）根元素为 <html data-lang="wen">：读取节点属性（“文档根”，“data-lang”）为（阳，“wen”），读取节点属性（“文档根”，“data-无”）为（阴，“”）；<details id="项" open>：读取节点属性（“项”，“open”）为（阳，“”）；移除节点属性（“项”，“open”）后为（阴，“”）。
6. （零点三点零）点击节点（“钮”）之后，订此钮 click 之客得事；为拦截订阅所拦之客，须先撤订阅，乃可令点击达页上他监听者。点击节点（“链”）（href 为 javascript:…）：发事故。
7. （零点三点零）设置节点位置（“提示”，12，34）后，元素 style.left 为 12px、style.top 为 34px；读取节点矩形（“提示”）之左、上与之相符（于 position:absolute 而无偏移之容器中）。

界

此包不定：造节点、选择符（见网页文树包零点三点零之查询）、事之键盘与组字之载（见网页事件）、定时、剪贴、网络、任意样式（style）之读写（惟设置节点位置一项为例外）、getComputedStyle 之余属性、拖放与择文件。