@doubao-dev/plugin-app-dev 0.0.0-stage → 0.0.40-canary-dea0ddc73-20261026073950

package/dist/skills/doubao-plugin-app/references/frontend/lynx/css/values-and-units.md

@@ -0,0 +1,314 @@
+# CSS 值和单位
+
+Lynx 支持的 CSS 值类型和单位。
+
+## 长度单位
+
+### 绝对单位
+
+- `px` - 像素（最常用）
+
+### 相对单位
+
+- `%` - 相对于父元素
+- `vw` - 视口宽度的百分比（viewport width）
+- `vh` - 视口高度的百分比（viewport height）
+- `rem` - 相对于根元素字体大小（**推荐**）
+- `em` - 相对于字体大小
+- `rpx` - 响应式像素（Lynx 特有，自动适配屏幕宽度）
+
+### 不支持的单位
+
+- ❌ `cm`, `mm`, `in`, `pt`, `pc` - 物理单位
+- ❌ `ch`, `ex` - 字体相关
+- ❌ `vmin`, `vmax`（部分支持）
+
+Lynx 不会在运行时把不支持的 CSS 单位自动归一化为 `px`。如果样式来自 Web、设计系统或外部配置，应在样式生成前转换为 Lynx 支持的单位；不要把 `in`、`pt`、`ex` 等不支持单位直接输出到 Lynx 样式中。
+
+对于 Web CSS 中的 `in`，Lynx 仍不原生支持，但样式生成或迁移层可以按 CSS 绝对长度规则转换后输出：`1in = 96px`，例如 `0.25in = 24px`、`1.25in = 120px`。这个转换不随 Android、iOS 或设备物理 DPI 改变。其他不支持单位仍应视为不支持；本文档不提供明确转换方式。除非迁移层有明确规则，不要自动类推为可转换单位，尤其不要把字体相关单位（如 `ex`、`ch`）转换为通过证据。
+
+## rem 响应式适配（推荐）
+
+推荐使用 `rem` 配合 `vw` 实现响应式适配，这是 Web 标准的方案，具有更好的兼容性。
+
+```css
+/* 在根元素设置基准字体大小 */
+page {
+  font-size: calc(100vw / 23.4375); /* 1rem = 16px @ 375px 宽度 */
+}
+
+/* 使用 rem 进行屏幕适配 */
+.container {
+  width: 100%;
+  padding: 2rem; /* 32px @ 375px */
+}
+
+.card {
+  width: 21.4rem; /* 约 342px @ 375px */
+  margin: 1rem;
+}
+```
+
+**设置方法**：
+
+1. 在 `page` 元素上设置 `font-size: calc(100vw / 23.4375)`
+2. 基准计算公式：`基准宽度 / 期望的基准字体大小`（如 375px / 16px = 23.4375）
+3. 所有尺寸使用 rem 单位
+
+## rpx 响应式像素（Lynx 特有）
+
+⚠️ **注意**：`rpx` 是 Lynx **特有**的单位，不具备 Web 兼容性。若需同时支持 Web 渲染，建议使用 `rem`。
+
+`rpx` 会根据屏幕宽度自动缩放，实现原理：`value × screen_width / 750`，功能完整且适用于自适应布局。
+
+**换算规则**（以 750rpx 为基准宽度）：
+
+- 在 375px 宽度的屏幕上：1rpx = 0.5px
+- 在 750px 宽度的屏幕上：1rpx = 1px
+- 在 1125px 宽度的屏幕上：1rpx = 1.5px
+
+```css
+/* 全宽 */
+.full-width {
+  width: 750rpx;
+}
+
+/* 半宽 */
+.half-width {
+  width: 375rpx;
+}
+```
+
+**rpx 使用场景**：
+
+- 仅用于 Lynx 项目且不需要 Web 兼容性时
+- 需要随屏幕宽度缩放的大小
+
+## 颜色值
+
+### 颜色名称
+
+```css
+color: red;
+background-color: blue;
+border-color: transparent;
+```
+
+### 十六进制
+
+```css
+/* 简写 */
+color: #f00;
+
+/* 完整 */
+color: #ff351a;
+
+/* 带透明度 */
+color: #ff351a80; /* 50% 透明 */
+color: rgba(255, 53, 26, 0.5);
+```
+
+### RGB/RGBA
+
+```css
+color: rgb(255, 53, 26);
+color: rgba(255, 53, 26, 0.5);
+```
+
+### HSL/HSLA
+
+```css
+color: hsl(9, 100%, 55%);
+color: hsla(9, 100%, 55%, 0.5);
+```
+
+## 数值
+
+```css
+/* 无单位数字 */
+opacity: 0.5;
+flex-grow: 1;
+z-index: 100;
+line-height: 1.5;
+
+/* 带单位 */
+width: 100px;
+font-size: 14px;
+```
+
+## 百分比
+
+```css
+/* 相对于父元素宽度 */
+width: 50%;
+
+/* 相对于父元素高度 */
+height: 100%;
+
+/* 相对于字体大小 */
+line-height: 150%;
+```
+
+## 特殊值
+
+### auto
+
+```css
+width: auto;
+height: auto;
+margin: auto;
+```
+
+### none
+
+```css
+display: none;
+background: none;
+border: none;
+```
+
+### inherit
+
+```css
+color: inherit;
+font-size: inherit;
+```
+
+### initial
+
+```css
+color: initial;
+```
+
+### 全局关键字
+
+- `initial` - 初始值
+- `inherit` - 继承父元素
+
+## 字符串
+
+```css
+/* 字体名称 */
+font-family: 'PingFang SC', 'Helvetica Neue', sans-serif;
+
+/* 图片 URL */
+background-image: url('https://example.com/image.png');
+```
+
+## 函数
+
+### 计算
+
+```css
+/* calc 部分支持 - 仅用于长度属性 */
+width: calc(100% - 20px);
+height: calc(50% + 100px);
+padding: calc(var(--base) * 2);
+```
+
+**支持 calc() 的属性：**
+
+- 尺寸：`width`, `height`, `min-width`, `max-width`, `min-height`, `max-height`
+- 盒模型：`padding`, `margin`, `flex-basis`
+- 间距：`gap`, `column-gap`, `row-gap`
+
+**不支持 calc() 的属性：**
+
+- 枚举值属性：`flex-direction`, `justify-content`, `linear-orientation` 等
+- 整数值属性：`order`, `z-index`, `font-weight` 等
+- 颜色属性：`color`, `background-color` 等
+
+### 环境变量
+
+```css
+/* 安全区域 */
+.safe-area {
+  padding-top: env(safe-area-inset-top);
+  padding-bottom: env(safe-area-inset-bottom);
+}
+```
+
+### 渐变色
+
+```css
+/* 线性渐变 */
+background: linear-gradient(to bottom, #ff351a, #00ebeb);
+background: linear-gradient(45deg, #ff351a 0%, #00ebeb 100%);
+
+/* 径向渐变 */
+background: radial-gradient(circle, #ff351a, #00ebeb);
+```
+
+### 动画时间函数
+
+用于 `transition-timing-function`、`animation-timing-function` 等属性。
+
+#### 关键字
+
+- `linear`
+- `ease`（在 Lynx 中等价于 `ease-in-out`）
+- `ease-in`
+- `ease-out`
+- `ease-in-out`
+- `ease-in-ease-out`（Lynx 中的 `ease`/`ease-in-out` 同义词）
+- `step-start`（等价于 `steps(1, start)`）
+- `step-end`（等价于 `steps(1, end)`）
+
+> **注意**：在 Lynx 引擎内部，`ease`、`ease-in-out`、`ease-in-ease-out` 均映射到同一种时间函数；这与 Web CSS 标准不同（Web 中 `ease` 和 `ease-in-out` 是两条不同的贝塞尔曲线）。
+
+#### 函数
+
+```css
+/* 自定义贝塞尔曲线 */
+transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+
+/* 步进函数 - 必须带方向参数 */
+animation-timing-function: steps(5, end);
+animation-timing-function: steps(3, jump-start);
+animation-timing-function: steps(4, jump-none);
+animation-timing-function: steps(4, jump-both);
+
+/* Lynx 特有扩展 */
+transition-timing-function: square-bezier(1, 0.5);
+```
+
+**`cubic-bezier(...)` 说明**：
+- 语法为 `cubic-bezier(x1, y1, x2, y2)`
+- 超出 `[0, 1]` 范围的控制点会被解析并生效
+- 当 x 坐标超出 `[0, 1]` 时，引擎会使用起点/终点的梯度进行线性外推，不会报错或被截断
+- 若 x1 和 x2 都在 `[0, 1]` 内，曲线是单调递增的；超出该范围时曲线可能非单调
+
+**`steps(...)` 说明**：
+- 语法为 `steps(n, direction)`，**必须**包含方向参数
+- 不支持省略方向参数的 `steps(1)` 写法（会被视为无效）
+- 支持的 direction：`start`、`jump-start`、`end`、`jump-end`、`jump-none`、`jump-both`
+
+## 内在尺寸
+
+### 支持的值
+
+- ✅ `max-content` - 内容最大宽度
+- ✅ `fit-content` - 适应内容宽度
+
+```css
+.container {
+  width: max-content; /* 根据内容自动调整 */
+  width: fit-content; /* 适应内容，不超过容器 */
+}
+```
+
+### 部分支持
+
+- ⚠️ `min-content` - 在大多数情况下支持，但在 `flex-basis` 中会被视为 0px
+
+```css
+/* ✅ 支持 */
+.container {
+  width: min-content;
+}
+
+/* ❌ 不支持 - 在 flex-basis 中视为 0px */
+.flex-item {
+  flex-basis: min-content; /* 不要这样用 */
+}
+```

package/dist/skills/doubao-plugin-app/references/frontend/lynx/layout/flex-layout.md

@@ -0,0 +1,334 @@
+# Flexbox 布局
+
+Lynx 支持 CSS Flexbox 的常用能力，整体遵循 Flexbox 弹性分配模型。迁移 Web 布局时仍需关注默认布局、内在尺寸和默认值差异。
+
+## 启用 Flex
+
+```css
+.container {
+  display: flex;
+}
+```
+
+## 常见布局模式
+
+### 水平居中
+
+```css
+.center-horizontal {
+  display: flex;
+  flex-direction: row;
+  justify-content: center; /* 主轴居中 */
+}
+```
+
+### 垂直居中
+
+```css
+.center-vertical {
+  display: flex;
+  flex-direction: column;
+  justify-content: center; /* 主轴居中 */
+}
+```
+
+### 水平垂直居中
+
+```css
+.center-both {
+  display: flex;
+  justify-content: center; /* 主轴居中 */
+  align-items: center; /* 交叉轴居中 */
+}
+```
+
+```jsx
+<view className="center-both">
+  <text>Centered Content</text>
+</view>
+```
+
+### 两端对齐
+
+```css
+.space-between {
+  display: flex;
+  flex-direction: row;
+  justify-content: space-between;
+}
+```
+
+```jsx
+<view className="space-between">
+  <text>Left</text>
+  <text>Right</text>
+</view>
+```
+
+### 等分布局
+
+```css
+.equal-width {
+  display: flex;
+}
+
+.equal-width .item {
+  flex: 1; /* 每个 item 等分空间 */
+}
+```
+
+### 左侧固定，右侧自适应
+
+```css
+.layout {
+  display: flex;
+}
+
+.sidebar {
+  width: 200px; /* 固定宽度 */
+}
+
+.main {
+  flex: 1; /* 占据剩余空间 */
+}
+```
+
+```jsx
+<view className="layout">
+  <view className="sidebar">
+    <text>Sidebar</text>
+  </view>
+  <view className="main">
+    <text>Main Content</text>
+  </view>
+</view>
+```
+
+### 底部固定按钮
+
+```css
+.page {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+}
+
+.content {
+  flex: 1; /* 内容区域占据剩余空间 */
+}
+
+.footer {
+  /* 固定在底部 */
+}
+```
+
+## Flex Wrap
+
+```css
+.wrap-container {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+}
+
+.wrap-container .item {
+  width: calc(50% - 8px); /* 两列布局 */
+}
+```
+
+## 多行对齐
+
+```css
+.multi-line {
+  display: flex;
+  flex-wrap: wrap;
+  align-content: space-between; /* 多行之间的对齐 */
+  gap: 16px;
+}
+```
+
+## 属性值参考
+
+### flex-direction
+
+| 值               | 说明             |
+| ---------------- | ---------------- |
+| `row`            | 水平排列（默认） |
+| `column`         | 垂直排列         |
+| `row-reverse`    | 水平反向排列     |
+| `column-reverse` | 垂直反向排列     |
+
+### flex-wrap
+
+| 值             | 说明           |
+| -------------- | -------------- |
+| `nowrap`       | 不换行（默认） |
+| `wrap`         | 换行           |
+| `wrap-reverse` | 反向换行       |
+
+### flex-flow
+
+`flex-direction` 和 `flex-wrap` 的简写属性。
+
+```css
+.container {
+  flex-flow: row wrap; /* 等同于 flex-direction: row; flex-wrap: wrap; */
+}
+```
+
+### justify-content
+
+| 值              | 说明                        |
+| --------------- | --------------------------- |
+| `flex-start`    | 起点对齐                    |
+| `center`        | 居中对齐                    |
+| `flex-end`      | 终点对齐                    |
+| `space-between` | 两端对齐，中间等分          |
+| `space-around`  | 环绕对齐                    |
+| `space-evenly`  | 均匀对齐                    |
+| `stretch`       | 拉伸对齐（默认，Lynx 2.1+） |
+
+### align-items
+
+| 值           | 说明             |
+| ------------ | ---------------- |
+| `stretch`    | 拉伸填满（默认） |
+| `flex-start` | 交叉轴起点对齐   |
+| `center`     | 交叉轴居中对齐   |
+| `flex-end`   | 交叉轴终点对齐   |
+| `baseline`   | 基线对齐         |
+
+### align-self
+
+单个项目的对齐方式，覆盖容器的 `align-items`。
+
+| 值           | 说明                 |
+| ------------ | -------------------- |
+| `auto`       | 继承自父元素（默认） |
+| `stretch`    | 拉伸填满             |
+| `flex-start` | 交叉轴起点对齐       |
+| `center`     | 交叉轴居中对齐       |
+| `flex-end`   | 交叉轴终点对齐       |
+| `baseline`   | 基线对齐             |
+
+### align-content
+
+多行内容的对齐方式（需要 `flex-wrap: wrap`）。
+
+| 值              | 说明             |
+| --------------- | ---------------- |
+| `stretch`       | 拉伸填满（默认） |
+| `flex-start`    | 起点对齐         |
+| `center`        | 居中对齐         |
+| `flex-end`      | 终点对齐         |
+| `space-between` | 两端对齐         |
+| `space-around`  | 环绕对齐         |
+
+### flex
+
+`flex-grow`、`flex-shrink`、`flex-basis` 的简写。
+
+```css
+.item {
+  flex: 1; /* 等同于 flex: 1 1 0% */
+  flex: auto; /* 等同于 flex: 1 1 auto */
+  flex: none; /* 等同于 flex: 0 0 auto */
+}
+```
+
+### flex-grow
+
+项目的放大比例，默认 `0`（不放大）。
+
+### flex-shrink
+
+项目的缩小比例，默认 `1`（可缩小）。
+
+`flex-shrink` 只在主轴可用空间不足时生效：`flex-direction: row` 时看容器宽度，`flex-direction: column` 时看容器高度。如果父容器主轴尺寸没有被 `width` / `height`、`max-width` / `max-height`、外层约束或视口约束限制，子项总尺寸不会产生负剩余空间，也就不会触发压缩。不显式设置主轴尺寸通常可以避免压缩，但如果尺寸来自外层容器、视口或其它布局约束，仍可能触发 `flex-shrink`。
+
+压缩量不是只按 `flex-shrink` 数值分配。当前 Lynx Flex 布局按缩放收缩因子分配负剩余空间：
+
+```text
+scaled shrink factor = flex-shrink * flex base size
+```
+
+`flex base size` 通常来自 `flex-basis`；当 `flex-basis: auto` 时，会使用主轴方向上的 `width` / `height` 或内容测量结果。也就是说，基础尺寸更大的项目即使 `flex-shrink` 相同，也会分摊更多压缩量。
+
+示例：父容器宽度为 `500px`，两个子项总基础宽度为 `600px`，需要压缩 `100px`。
+
+```css
+.item-a {
+  width: 200px;
+  flex-shrink: 1;
+}
+
+.item-b {
+  width: 400px;
+  flex-shrink: 2;
+}
+```
+
+`item-a` 的收缩权重是 `200 * 1 = 200`，`item-b` 的收缩权重是 `400 * 2 = 800`。最终 `item-a` 压缩 `20px`，宽度为 `180px`；`item-b` 压缩 `80px`，宽度为 `320px`。
+
+如果多个项目的基础尺寸相同，看起来会像只按 `flex-shrink` 数值等比压缩；一旦基础尺寸不同，基础尺寸也会参与分配。
+
+### flex-basis
+
+项目在分配多余空间之前的初始大小，默认 `auto`。
+
+```css
+.item {
+  flex-basis: 100px; /* 固定大小 */
+  flex-basis: auto; /* 根据内容大小 */
+}
+```
+
+### order
+
+项目的排列顺序，默认 `0`。数值越小，排列越靠前。
+
+```css
+.item:first-child {
+  order: -1; /* 排到最前面 */
+}
+```
+
+### gap / row-gap / column-gap
+
+项目之间的间距。
+
+```css
+.container {
+  gap: 16px; /* 行和列间距都是16px */
+  row-gap: 8px; /* 行间距8px */
+  column-gap: 12px; /* 列间距12px */
+}
+```
+
+## 注意事项
+
+1. **min-content 不支持**: `flex-basis: min-content` 会被视为 0px
+
+   ```css
+   /* ❌ 不支持 */
+   .item {
+     flex-basis: min-content;
+   }
+
+   /* ✅ 替代方案 */
+   .item {
+     flex-basis: auto;
+   }
+   ```
+
+2. **Text 组件**: Flex 子元素如果是 Text，可能需要设置 `white-space: nowrap` 防止换行
+
+   ```css
+   .flex-item-text {
+     white-space: nowrap;
+   }
+   ```
+
+3. **内容不会自动形成 Web 式收缩下限**: Lynx 的 `flex-shrink` 不会套用 Web flex item 的 `min-content` / auto minimum size 保护。空间不足时，包含 Text、图片或嵌套子节点等内容的 flex item 也可能继续沿主轴被压缩；Web 则可能因为内容形成默认最小宽度或最小高度而不继续收缩。可以把 Lynx 的默认表现理解为 Web flex item 在主轴方向显式设置最小值为 `0`。需要固定尺寸或保护内容的项目请设置 `flex-shrink: 0`，或显式设置主轴方向的 `min-width` / `min-height`。需要 Web 预览页对齐 Lynx 压缩行为时，通常要在 Web 侧设置 `min-width: 0`（row 方向）或 `min-height: 0`（column 方向）。
+
+4. **justify-content 默认值**: Lynx 中 `justify-content` 默认值为 `stretch`（Web 中默认为 `flex-start`）