frontend: let a figure be sized by its height as well as its width

A writer with a tall panel does not want to shrink it from the left edge: what
they know is "this one is too tall". The format had a width and nothing else, so
the only way to make a figure shorter was to guess a percentage and check the
page — and the previous commit's answer, "type 638px", asked them to do the
arithmetic themselves.

So `{height=300px}` joins `{width=…}`, in the same attribute block, and the
editor grows a second box beside the first. Both are typeable as well as
pre-set, both write through the reader's own parse function, and the hint beside
them says what the picture will measure on the page.

Three rules, and the point of all three is that a figure cannot be stretched:

* **a width is exact, a height is a cap.** A width has a reference — the column,
  or a length the writer chose — while nothing measures a height against
  anything, and enlarging a picture past its own pixels only makes it soft. In
  the flow of a sentence a height is always a downscale, which comes to the same
  thing as exact.
* **given one, the other follows from the picture's own shape** — `max-height`
  for a height, `width` for a width — so the height is never written by hand.
* **given both, they are a box to fit inside**, not a box to fill. Two numbers
  that need not have the picture's proportions can only mean "no bigger than",
  and the check asserts the drawn rectangle still matches the file's ratio.

Whichever box is left empty keeps the other's setting, so a size can be set in
two steps, and clearing either goes back to the natural size.

`check-image.mjs`: 26 checks to 36. Two of the new ones found real bugs while
being written. The first: with both a width and a height in one `{…}` block,
neither side parsed — the patterns were anchored to the whole block, so a figure
with two numbers silently printed at its natural size. The attribute block is now
split into declarations first. The second was mine: returning "contain" for a
height-only figure left a 1276×2000 box around a small picture, which the caption
then sat under. A height is a cap, and a cap needs no contain.

The MCP tool takes the same two arguments, so a model can write either number,
and a percentage height is refused with the reason it cannot work: a sentence is
flowed text, so there is nothing for it to be a percentage of and the browser
ignores it. v8 is deployed and DSH has verified both numbers round-tripping.
This commit is contained in:
2026-09-24 13:18:52 +08:00
parent b19f28492e
commit 1531263bd2
10 changed files with 499 additions and 104 deletions
+28 -6
View File
@@ -442,13 +442,14 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
| 工具 | 作用 | 关键参数 |
|---|---|---|
| `image_upload` | 传一张图,返回可写进句子的 Markdown 与那个句子对象 | `data_base64`、`caption?` `filename?` `width?` |
| `image_upload` | 传一张图,返回可写进句子的 Markdown 与那个句子对象 | `data_base64`、`caption?` `filename?` `width?` `height?` |
```jsonc
{"name": "image_upload", "arguments": {
"data_base64": "iVBORw0KGgo…", // 也可以直接给 data:image/png;base64,…
"caption": "图 3 惯性—冲量相空间", // 不给就用 filename 的主干
"width": "70%" // 或 400px;不传按原尺寸(不超过栏宽)
"width": "70%", // 或 400px;不传按原尺寸(不超过栏宽)
"height": "300px" // 可选,只能像素;图不会超过这个高
}}
// → {"key": "2026/09/9f8c1a4b7e2d0c33.png",
// "url": "/api/images/2026/09/9f8c1a4b7e2d0c33.png",
@@ -469,10 +470,31 @@ Header: Authorization: Bearer <MCP_HTTP_TOKEN>
`paragraph_get` / `paper_document` 的 `text` 按同一条规则断行,图以它存储的 Markdown 原样印在自己的行上——
文本画不出图片,而地址是"哪一张图"的唯一答案,读回来还能原样搬走。
`width` 写法宽容(`70%`、`70 %`、`{width=70%}`、`w=400px` 都收),含义严格:像素 1–4000、百分比 1–100,
超出会被拒绝而不是默默忽略——网页端读不懂的尺寸会退回原尺寸,那等于写了个不生效的值。
**只写数字按百分比算**(`60` = `60%`),和网页端一致:只有写成 `px` 才算像素,因为这是
`frontend/src/utils/rich.ts` 里 `parseImageWidth` 的读法,页面和工具必须读同一种。
**宽和高可以分别填**,写法都在句子正文里:
| 想要的效果 | 句子正文里写 | 结果 |
|---|---|---|
| 宽正好 500px,高自动 | `{width=500px}` | 500×(按原比例算) |
| 占栏宽的 70% | `{width=70%}` | 列宽×0.7,高自动 |
| **高不超过 300px**,宽自动 | `{height=300px}` | 宽 = 300×原比例,按比例缩 |
| 放进 500×300 的框里 | `{width=500px height=300px}` | 等比缩放塞进框内 |
| 原尺寸 | 不写 | 按原图,最多不超过栏宽 |
三条规则:
1. **宽是精确值,高是上限。** 宽有参照物(栏宽或你给的像素),所以给多少就是多少;高没有参照物,
也没必要把图放大到比它本身还大(只会糊),所以 `height` 是"不超过这个高"。你说的场景(把太高的图压矮)
两种情况结果一样。
2. **永远只给宽度或只给高度时,另一边由浏览器按原比例算**——所以图不可能被拉变形。两个都给就是
"放进这个框里",也是等比缩放,不会拉伸。
3. **写法宽容,含义严格。** `70%`、`70 %`、`{width=70%}`、`w=400px` 都收;宽 1–4000px 或 1–100%,
高 1–4000px(**高不能用百分比**:句子里没有可参照的高度,浏览器会直接忽略,那等于写了个不生效的值)。
`width` 只写数字按**百分比**算(`60` = `60%`);`height` 只写数字按**像素**算。
超出范围或读不懂的一律拒绝并说明,而不是默默退回原尺寸。
这几种写法在网页端可以点着填:段落编辑器里,凡是"整句只有一张图"的行都有「宽」「高」两个框,
可以用预设,也可以直接打字(如 `63%`、`380px`、`250`),旁边实时显示这会在版面上占多大
(如 `原图 1857×1986 · 显示 893×955`)。
同一个大小在网页端也能改:段落编辑器里,凡是"整句只有一张图"的行都会出现「宽度」下拉框,
可以选 25/50/70/100%,也可以直接填任意值(如 `63%`、`380px`),旁边实时显示这会在版面上