Skip to content

Commit 8ca5796

Browse files
JustineoJustineo
committed
feat: add Chinese translation for README and plugins documentation
1 parent 3846a89 commit 8ca5796

File tree

4 files changed

+485
-0
lines changed

4 files changed

+485
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@
1111
<p align="center">
1212
<a href="https://chrome.google.com/webstore/detail/tempad-dev/lgoeakbaikpkihoiphamaeopmliaimpc"><img src="https://img.shields.io/badge/Install%20on%20Chrome%20Web%20Store-4285F4?logo=chromewebstore&logoColor=%23fff" alt="Install on Chrome Web Store"></a>
1313
<a href="https://discord.gg/MXGXwtkEck"><img src="https://img.shields.io/badge/Chat%20on%20Discord-5865F2?logo=discord&logoColor=%23fff" alt="Chat on Discord"></a>
14+
<a href="./README.zh-Hans.md"><img src="https://img.shields.io/badge/%E4%B8%AD%E6%96%87%E7%89%88%20%C2%BB-000" alt="前往中文版"></a>
1415
</p>
1516

1617
<p align="center">

‎README.zh-Hans.md‎

Lines changed: 321 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
1+
<p align="center">
2+
<picture>
3+
<source media="(prefers-color-scheme: dark)" srcset="packages/extension/assets/hero-dark.svg">
4+
<source media="(prefers-color-scheme: light)" srcset="packages/extension/assets/hero-light.svg">
5+
<img alt="展示扩展面板的截图。" src="packages/extension/assets/hero-light.svg" width="540" height="200">
6+
</picture>
7+
</p>
8+
9+
<p align="center">面向 <b>所有人</b> 的 Figma Inspect 面板。</p>
10+
11+
<p align="center">
12+
<a href="https://chrome.google.com/webstore/detail/tempad-dev/lgoeakbaikpkihoiphamaeopmliaimpc"><img src="https://img.shields.io/badge/Install%20on%20Chrome%20Web%20Store-4285F4?logo=chromewebstore&logoColor=%23fff" alt="在 Chrome Web Store 安装"></a>
13+
<a href="https://discord.gg/MXGXwtkEck"><img src="https://img.shields.io/badge/Chat%20on%20Discord-5865F2?logo=discord&logoColor=%23fff" alt="在 Discord 上聊天"></a>
14+
</p>
15+
16+
<p align="center">
17+
<a href="https://github.com/ecomfe/tempad-dev/actions/workflows/build.yml"><img src="https://img.shields.io/github/actions/workflow/status/ecomfe/tempad-dev/build.yml?branch=main&label=build" alt="build"></a>
18+
<a href="https://github.com/ecomfe/tempad-dev/actions/workflows/check-rewrite.yml"><img src="https://img.shields.io/github/actions/workflow/status/ecomfe/tempad-dev/check-rewrite.yml?branch=main&label=script-rewrite" alt="check-script-rewrite"></a>
19+
</p>
20+
21+
<p align="center">
22+
<picture>
23+
<source media="(prefers-color-scheme: dark)" srcset="packages/extension/assets/code-dark.png">
24+
<source media="(prefers-color-scheme: light)" srcset="packages/extension/assets/code-light.png">
25+
<img alt="展示扩展面板代码视图的截图。" src="packages/extension/assets/code-light.png" width="720">
26+
</picture>
27+
</p>
28+
29+
---
30+
31+
## 主要功能
32+
33+
### 查看 CSS 代码
34+
35+
<picture>
36+
<source media="(prefers-color-scheme: dark)" srcset="packages/extension/assets/code-dark.png">
37+
<source media="(prefers-color-scheme: light)" srcset="packages/extension/assets/code-light.png">
38+
<img alt="展示所选元素的 CSS 和 JavaScript 代码。" src="packages/extension/assets/code-light.png" width="720">
39+
</picture>
40+
41+
选择任意元素后，你可以在插件的 Code 面板中获取对应的 CSS 代码。除了标准的 CSS 代码之外，TemPad Dev 还会以 JavaScript 对象的形式提供样式，方便在 JSX 等场景中直接使用。
42+
43+
<picture>
44+
<source media="(prefers-color-scheme: dark)" srcset="packages/extension/assets/unit-dark.png">
45+
<source media="(prefers-color-scheme: light)" srcset="packages/extension/assets/unit-light.png">
46+
<img alt="展示偏好设置中的单位与根字体大小设置。" src="packages/extension/assets/unit-light.png" width="720">
47+
</picture>
48+
49+
你可以配置 CSS 单位和根字体大小，将 CSS 中的 `px` 尺寸转换为 `rem`。同时也可以设置 `scale` 系数，根据实际交付需求对 `px` 数值进行缩放。
50+
51+
> [!WARNING]
52+
> 切换单位只会影响 TemPad Dev 面板中的输出，不会影响 Figma 画布本身。
53+
54+
### 深度选择模式
55+
56+
<picture>
57+
<source media="(prefers-color-scheme: dark)" srcset="packages/extension/assets/deep-dark.png">
58+
<source media="(prefers-color-scheme: light)" srcset="packages/extension/assets/deep-light.png">
59+
<img alt="展示偏好设置中的深度选择模式。" src="packages/extension/assets/deep-light.png" width="720">
60+
</picture>
61+
62+
在 Figma 的只读视图中，选择节点通常需要不断双击逐层下钻，才能选中最底层的节点。虽然 Figma 提供了 <kbd>⌘</kbd> + 单击 的快捷方式，但很多用户并不知道这一功能，每次都需要额外的键盘操作。为此，TemPad Dev 在偏好设置中提供了深度选择模式。
63+
64+
### 测量到选中项模式
65+
66+
<picture>
67+
<source media="(prefers-color-scheme: dark)" srcset="packages/extension/assets/measure-dark.png">
68+
<source media="(prefers-color-scheme: light)" srcset="packages/extension/assets/measure-light.png">
69+
<img alt="展示偏好设置中的测量到选中项模式。" src="packages/extension/assets/measure-light.png" width="720">
70+
</picture>
71+
72+
在 Figma 的只读视图中，需要按住 <kbd>⌥</kbd> 并移动鼠标，才能显示其他节点与当前选中节点之间的间距。基于与深度选择模式类似的考虑，TemPad Dev 也在偏好设置中提供了测量到选中项模式。
73+
74+
### 将选中项滚动到视图中
75+
76+
<picture>
77+
<source media="(prefers-color-scheme: dark)" srcset="packages/extension/assets/scroll-dark.png">
78+
<source media="(prefers-color-scheme: light)" srcset="packages/extension/assets/scroll-light.png">
79+
<img alt="展示将选中项滚动到视图中的功能。" src="packages/extension/assets/scroll-light.png" width="720">
80+
</picture>
81+
82+
当你在 TemPad Dev 的 Inspect 面板中将鼠标悬停在节点名称区域时，会出现一个按钮。点击后，当前选中的节点会被滚动到 Figma 视口的正中央。Figma 也提供了类似的 <kbd>⇧2</kbd> 快捷键，但该操作会放大并填满视口，往往不符合实际需求。Figma 的插件 API 实际上提供了在保持 100% 缩放的情况下移动视图的接口，因此我们也将这一能力作为补充提供了出来。
83+
84+
---
85+
86+
### 插件
87+
88+
<picture>
89+
<source media="(prefers-color-scheme: dark)" srcset="packages/extension/assets/plugins-dark.png">
90+
<source media="(prefers-color-scheme: light)" srcset="packages/extension/assets/plugins-light.png">
91+
<img alt="展示偏好设置中的插件区域。" src="packages/extension/assets/plugins-light.png" width="720">
92+
</picture>
93+
94+
插件可以用来自定义内置的代码输出，或添加自定义的代码块。
95+
96+
一个 TemPad Dev 插件本质上是一个简单的 JavaScript 文件，通过名为 `plugin` 的导出暴露一个插件对象。要安装插件，只需将插件文件的 URL 粘贴到 _Preferences > Plugins_ 中即可。一些内置插件也可以通过 `@{name}` 语法启用，例如 `@foo`，它对应的是我们 [插件注册表](https://github.com/ecomfe/tempad-dev/blob/main/packages/extension/plugins/available-plugins.json) 中的插件名称。
97+
98+
> [!NOTE]
99+
> 插件代码存储在浏览器的本地存储中，不支持版本管理或自动更新，需要你在 UI 中手动更新。
100+
101+
#### 创建插件
102+
103+
使用 `@tempad-dev/plugins` 包中提供的、带完整类型定义的 `definePlugin` 函数，可以简化插件的创建过程。
104+
105+
```sh
106+
npm install -D @tempad-dev/plugins # 或 pnpm add -D @tempad-dev/plugins
107+
```
108+
109+
下面是一个简单的示例插件，它会覆盖内置的 CSS 代码块，并隐藏 JavaScript 代码块：
110+
111+
```ts
112+
import { definePlugin } from '@tempad-dev/plugins'
113+
114+
export default definePlugin({
115+
name: 'My Plugin',
116+
code: {
117+
css: {
118+
title: 'Stylus', // 自定义代码块标题
119+
lang: 'stylus', // 自定义语法高亮语言
120+
transform({ style }) {
121+
return Object.entries(style)
122+
.map(([key, value]) => `${key} ${value}`)
123+
.join('\n')
124+
}
125+
},
126+
js: false // 隐藏内置的 JavaScript 代码块
127+
}
128+
})
129+
```
130+
131+
更完整的示例可以参考 [Justineo/tempad-dev-plugin-kong](https://github.com/Justineo/tempad-dev-plugin-kong/)。
132+
133+
> [!NOTE]
134+
> 插件文件必须是合法的 ES Module，并且需要通过 `default` 导出插件对象。
135+
136+
目前我们支持 4 种插件钩子：
137+
138+
- `transform`：将样式对象或代码转换为字符串形式，用于代码块输出。适合用于 Tailwind CSS、UnoCSS 等自定义结构。
139+
- `transformVariable`：将 CSS 变量转换为其他格式，例如转换为 Sass 变量以用于设计令牌。
140+
- `transformPx`：将像素值转换为其他单位或按比例缩放。
141+
- `transformComponent`：将设计组件对象转换为开发侧的组件对象或字符串，用于生成设计系统的组件代码。
142+
143+
> [!TIP]
144+
> 如果希望在生成的 CSS 中包含 JavaScript 变量，可以使用 `\0` 字符包裹变量名。这样会被转换为 JavaScript 的字符串插值。
145+
> 例如返回 `\0foo\0`，则输入 `calc(var(--foo) + 10px)` 会被转换为 `` `calc(${foo} + 10px)` ``。
146+
147+
此外，你还可以为代码块指定自定义的 `title` 和 `lang`，或者将内置代码块设置为 `false` 以隐藏它。
148+
149+
完整的类型定义和辅助函数请参见 [`plugins/src/index.ts`](./plugins/src/index.ts)。
150+
151+
#### 部署插件
152+
153+
请确保你的插件可以通过支持跨域请求的 URL 访问，例如托管在 GitHub 仓库或 Gist 中。比如可以使用 raw 地址：
154+
155+
```text
156+
https://raw.githubusercontent.com/{username}/{repo}/refs/heads/{branch}/{filename}.js
157+
```
158+
159+
> [!NOTE]
160+
> 插件 URL 必须支持跨域请求。GitHub 或 Gist 提供的 raw URL 通常是可用的。
161+
162+
插件运行在 Web Worker 中，不会阻塞主线程，也无法访问 DOM，从而保证性能和安全性。插件上下文中只提供了有限的全局变量，具体可参考 [`codegen/safe.ts`](./codegen/safe.ts)。
163+
164+
#### 分享插件
165+
166+
你也可以将插件注册到我们的 [插件注册表文件](https://github.com/ecomfe/tempad-dev/blob/main/packages/extension/plugins/available-plugins.json) 中，这样就可以通过插件名直接安装。
167+
168+
**欢迎来 [添加你自己的精彩插件](https://github.com/ecomfe/tempad-dev/edit/main/packages/extension/plugins/available-plugins.json)！**
169+
170+
当前可用插件列表：
171+
172+
<!-- prettier-ignore-start -->
173+
<!-- availablePlugins:start -->
174+
| 插件名称 | 描述 | 作者 | 仓库 |
175+
| -- | -- | -- | -- |
176+
| `@kong` | Kong Design System | [@Justineo](https://github.com/@Justineo) | <img alt="GitHub" src="https://simpleicons.org/icons/github.svg" width="12" height="12"> [GitHub](https://github.com/Justineo/tempad-dev-plugin-kong) |
177+
| `@kong/advanced` | Kong Design System（高级版） | [@Justineo](https://github.com/@Justineo) | <img alt="GitHub" src="https://simpleicons.org/icons/github.svg" width="12" height="12"> [GitHub](https://github.com/Justineo/tempad-dev-plugin-kong) |
178+
| `@fubukicss/unocss` | FubukiCSS 的 UnoCSS | [@zouhangwithsweet](https://github.com/@zouhangwithsweet) | <img alt="GitHub" src="https://simpleicons.org/icons/github.svg" width="12" height="12"> [GitHub](https://github.com/zouhangwithsweet/fubukicss-tool) |
179+
| `@nuxt` | Nuxt UI | [@Justineo](https://github.com/@Justineo) | <img alt="GitHub" src="https://simpleicons.org/icons/github.svg" width="12" height="12"> [GitHub](https://github.com/Justineo/tempad-dev-plugin-nuxt-ui) |
180+
| `@nuxt/pro` | Nuxt UI Pro | [@Justineo](https://github.com/@Justineo) | <img alt="GitHub" src="https://simpleicons.org/icons/github.svg" width="12" height="12"> [GitHub](https://github.com/Justineo/tempad-dev-plugin-nuxt-ui) |
181+
| `@baidu-health/wz-style` | 百度健康 wz-style 自定义样式 | [@KangXinzhi](https://github.com/@KangXinzhi) | <img alt="GitHub" src="https://simpleicons.org/icons/github.svg" width="12" height="12"> [GitHub](https://github.com/KangXinzhi/tempad-dev-plugin-wz-style) |
182+
| `@baidu-health/med-style` | 百度健康 med-style 自定义样式 | [@KangXinzhi](https://github.com/@KangXinzhi) | <img alt="GitHub" src="https://simpleicons.org/icons/github.svg" width="12" height="12"> [GitHub](https://github.com/KangXinzhi/tempad-dev-plugin-med-style) |
183+
| `@tailwind` | CSS 转 Tailwind CSS | [@haydenull](https://github.com/@haydenull) | <img alt="GitHub" src="https://simpleicons.org/icons/github.svg" width="12" height="12"> [GitHub](https://github.com/haydenull/tempad-dev-plugin-tailwind) |
184+
| `@react-native` | CSS 转 React Native StyleSheet | [@CANntyield](https://github.com/@CANntyield) | <img alt="GitHub" src="https://simpleicons.org/icons/github.svg" width="12" height="12"> [GitHub](https://github.com/CANntyield/tempad-dev-plugin-react-native) |
185+
<!-- availablePlugins:end -->
186+
<!-- prettier-ignore-end -->
187+
188+
## MCP 服务器
189+
190+
TemPad Dev 内置了一个 [MCP](https://modelcontextprotocol.io/) 服务器，使得 Agent 或 IDE 可以直接从你在 Figma 中选中的节点拉取代码和上下文。在打开 TemPad Dev 面板并启用 MCP 后，服务器会暴露以下能力：
191+
192+
- `get_code`：默认输出高保真的 JSX/Vue + TailwindCSS 代码，同时包含相关资源以及使用的 codegen 预设和配置。
193+
- `get_structure`：当前选中节点的结构信息（id、类型、几何数据）。
194+
- `get_screenshot`：PNG 截图，包含 `resourceUri` 以及可直接下载的 HTTP URL。
195+
- `tempad-assets` 资源模板（`asset://tempad/{hash}`），用于访问上述工具返回的二进制资源。
196+
197+
### 配置指南
198+
199+
<picture>
200+
<source media="(prefers-color-scheme: dark)" srcset="packages/extension/assets/mcp-config-dark.png">
201+
<source media="(prefers-color-scheme: light)" srcset="packages/extension/assets/mcp-config-light.png">
202+
<img alt="TemPad Dev MCP 偏好设置面板。" src="packages/extension/assets/mcp-config-light.png" width="240">
203+
</picture>
204+
205+
1. **前置条件**：Node.js 18+，并且在 Figma 标签页中运行 TemPad Dev。
206+
2. 在 TemPad Dev 中打开 **Preferences → MCP server**，然后启用 **Enable MCP server**。
207+
3. 使用偏好设置中的快捷操作进行安装和连接，或在你的 MCP 客户端中手动添加一个 stdio 命令形式的服务器：
208+
209+
```json
210+
{
211+
"mcpServers": {
212+
"TemPad Dev": {
213+
"command": "npx",
214+
"args": ["-y", "@tempad-dev/mcp@latest"]
215+
}
216+
}
217+
}
218+
```
219+
220+
如果你的客户端使用 CLI 安装器，以下命令效果等同：
221+
- `claude mcp add --transport stdio "TemPad Dev" -- npx -y @tempad-dev/mcp@latest`
222+
- `codex mcp add "TemPad Dev" -- npx -y @tempad-dev/mcp@latest`
223+
224+
4. 使用 MCP 时，请保持 TemPad Dev 标签页处于激活状态。如果同时打开了多个 Figma 文件（也就有多个 TemPad Dev 实例），可以点击 TemPad Dev 面板中的 MCP 徽标，激活对应文件的 MCP（这会同时停用其他标签页中的 MCP）。
225+
226+
### MCP 连接状态
227+
228+
启用 MCP 后，TemPad Dev 面板标题栏中会显示一个徽标，表示当前的连接状态：
229+
230+
- **Unavailable**：本地 MCP 服务器未配置或未运行。
231+
232+
<picture>
233+
<source media="(prefers-color-scheme: dark)" srcset="packages/extension/assets/mcp-unavailable-dark.png">
234+
<source media="(prefers-color-scheme: light)" srcset="packages/extension/assets/mcp-unavailable-light.png">
235+
<img alt="MCP 状态徽标，显示为 Unavailable。" src="packages/extension/assets/mcp-unavailable-light.png" width="720">
236+
</picture>
237+
238+
- **Inactive**：TemPad Dev 已连接到本地 MCP 服务器，但由于打开了多个 Figma 标签页，此标签页当前未激活。点击徽标即可为当前标签页激活 MCP（同时会停用其他标签页的 MCP）。
239+
240+
<picture>
241+
<source media="(prefers-color-scheme: dark)" srcset="packages/extension/assets/mcp-inactive-dark.png">
242+
<source media="(prefers-color-scheme: light)" srcset="packages/extension/assets/mcp-inactive-light.png">
243+
<img alt="MCP 状态徽标，显示为 Inactive。" src="packages/extension/assets/mcp-inactive-light.png" width="720">
244+
</picture>
245+
246+
- **Active**：MCP 服务器正在运行，并且当前标签页已激活，可随时响应 MCP 工具调用。
247+
248+
<picture>
249+
<source media="(prefers-color-scheme: dark)" srcset="packages/extension/assets/mcp-active-dark.png">
250+
<source media="(prefers-color-scheme: light)" srcset="packages/extension/assets/mcp-active-light.png">
251+
<img alt="MCP 状态徽标，显示为 Active。" src="packages/extension/assets/mcp-active-light.png" width="720">
252+
</picture>
253+
254+
### 配置项
255+
256+
`@tempad-dev/mcp` 支持以下可选环境变量：
257+
258+
- `TEMPAD_MCP_TOOL_TIMEOUT`（默认 `15000`）：工具调用超时时间，单位为毫秒。
259+
- `TEMPAD_MCP_AUTO_ACTIVATE_GRACE`（默认 `1500`）：在只有一个扩展连接时，自动激活前的延迟时间。
260+
- `TEMPAD_MCP_MAX_ASSET_BYTES`（默认 `8388608`）：捕获的资源或截图允许的最大上传大小（字节）。
261+
- `TEMPAD_MCP_RUNTIME_DIR`（默认 `${TMPDIR}/tempad-dev/run`）：Hub 存储 socket 与锁文件的目录。
262+
- `TEMPAD_MCP_LOG_DIR`（默认 `${TMPDIR}/tempad-dev/log`）：MCP 日志目录。
263+
- `TEMPAD_MCP_ASSET_DIR`（默认 `${TMPDIR}/tempad-dev/assets`）：用于存储导出资源的目录，这些资源会通过 `resourceUri` 引用。
264+
265+
<details>
266+
<summary><h3>查看 TemPad 组件代码</h3></summary>
267+
268+
> 该功能仅适用于由 TemPad Figma 插件生成的节点，而该插件目前仅在 _百度_ 内部可用。
269+
270+
目前此功能仅支持 Light Design 组件。
271+
272+
如果画布中存在由 TemPad Figma 插件生成的组件，TemPad Dev 可以在 Code 面板中直接输出该组件的调用代码。你也可以快速跳转到 TemPad Playground，对可运行的代码进行预览和调试。
273+
274+
</details>
275+
276+
<details>
277+
<summary><h2><a id="quirks-mode"></a>Quirks 模式</h2></summary>
278+
279+
> [!CAUTION]
280+
> 自 2025.04.01 起，Quirks 模式已不可用。Figma 移除了用于提取样式数据的 `window.DebuggingHelpers.logSelected` API。
281+
282+
> [!NOTE]
283+
> TemPad Dev v0.1.0 新增
284+
285+
Quirks 模式是在 TemPad Dev v0.1.0 中引入的，当 `window.figma` 不可用时，你仍然可以使用该工具。该模式通过解析 Figma 的调试日志来提取样式数据，从而生成基础样式代码，但会存在一定限制。
286+
287+
当前已知无法生成或存在差异的功能包括：
288+
289+
- Effects 中添加的样式，对应的 CSS 属性如 `box-shadow`、`filter: blur()`、`backdrop-filter: blur()`。
290+
- 渐变填充样式。TemPad Dev 只能检测到渐变的存在，并输出为 `linear-gradient(<color-stops>)`。
291+
- 填充样式的混合模式，对应 CSS 的 `background-blend-mode`。
292+
- 文本节点的 `font-family`，该值通过启发式方式获取，可能不准确。
293+
- 除数字样式之外的高级 OpenType 配置，通常在实际中较少使用。
294+
- [“将选中项滚动到视图中”](#scroll-selection-into-view) 功能在该模式下不可用。
295+
296+
除上述限制外，其余功能与标准模式基本一致。如果 Quirks 模式能够满足你的使用场景，就可以避免复制到草稿文件等繁琐操作，直接在只读视图中使用。但需要注意的是，该模式同样依赖于 Figma 全局暴露的调试接口，无法保证长期可用性。如果 Figma 再次移除相关接口，该模式也会随之失效。
297+
298+
<details>
299+
<summary><h3>兼容性更新</h3></summary>
300+
301+
**2025.04.01**：Figma 移除了用于提取样式数据的 `window.DebuggingHelpers.logSelected` API，Quirks 模式因此不可用。
302+
303+
**2024.11.04**：TemPad Dev 成功在只读模式下重新获取了 `window.figma` API，但仍无法保证该能力的长期有效性。如果 Figma 再次移除相关接口，该模式也将不可用。
304+
305+
**2024.04.08**：TemPad Dev 通过当前尚未被封禁的调试接口，成功获取了大部分样式信息，并引入了新的 [Quirks 模式](#quirks-mode)。该模式不依赖 `window.figma`，而是通过解析调试日志生成样式代码，与标准模式存在少量差异。
306+
307+
**2024.03.20**：在我们向 Figma 社区论坛提交反馈后，Figma 团队表示将在未来几周内恢复只读模式下的 `window.figma` 接口。你可以在这个 [讨论帖](https://forum.figma.com/t/figma-removed-window-figma-on-view-only-pages-today/67292) 中跟踪该问题的进展。
308+
309+
</details>
310+
311+
</details>
312+
313+
## 致谢
314+
315+
使用 [WXT](https://wxt.dev/)、TypeScript 和 Vue 3 构建。
316+
317+
灵感来源于以下项目：
318+
319+
- <https://github.com/leadream/figma-viewer-chrome-plugin>
320+
- <https://github.com/zouhangwithsweet/fubukicss-tool>
321+
- <https://github.com/Inclushe/figma-ui3>

0 commit comments

Comments
 (0)