NATLAN Docs

外观

走一遍共享组件的改动闭环 ​

这个仓最容易踩坑的地方不是写组件，而是改完之后：谁会自动重建、谁不会、哪条检查 会拦下什么。跟着走一遍，就能建立完整的心智模型。

前置：已完成 getting-started.md。

场景 ​

给共享库里的 EmptyState 加一句可选的副标题文案。它同时被控制台和门户使用， 文案要有四种语言。

第 1 步：找到组件，确认它在哪一层 ​

bash
ls ui/feedback/

ui/ 按组件类型分目录，不按使用方分。EmptyState 是状态反馈，所以在 feedback/。完整分类见 reference/ui/。

打开 ui/feedback/EmptyState.svelte，加一个可选 prop：

svelte
let { title, hint, action }: { title: string; hint?: string; action?: Snippet } = $props();

注意这里已经用上了两条硬规矩：

  • 库里不能出现 $lib/... / $app/...。需要宿主能力就注入或走 prop。
  • 写操作类的能力一律做成可选 prop，不传即不渲染——上面的 action 就是这个形状。 控制台传，门户不传，那段 DOM 根本不进门户的产物。

第 2 步：加文案，四种语言 ​

组件自有语义的 key 归库字典：ui/i18n.svelte.ts。

ts
// en
'empty.hintDefault': 'Nothing here yet.',
// zh / zh-Hant / ja 各加一条

判断归属的标准很简单：这个 key 的命名空间是组件语义还是应用语义？topo.*、fstat.*、pflap.* 是组件语义，进库；common.updatedAt 这类通用词汇 是应用语义，留在各 app 字典里，库通过宿主回落读到。

第 3 步：跑完整性检查 ​

bash
npm run check:i18n

如果只加了英文而漏了另外三种，或者把 key 加错了地方，这条会失败。

这条检查存在的理由：把组件搬进共享库时，它用的 key 还留在原 app 的字典里， 于是另一个站整块回显 pflap.xxx。构建不报错、类型检查也不报错，只有真的打开页面才 看得见——这个 bug 咬过两次，两次都是靠截图发现的。

第 4 步：两个站各看一眼 ​

bash
npm run dev:control    # 一个终端
npm run dev:peering    # 另一个终端

同一个组件在两边应当长得一样。如果门户那边没有颜色（图表灰掉、徽章无色）， 说明设计令牌没到位——门户的 app.css 必须 @import 共享层，而不是维护一份拷贝。

如果切换语言时组件文案不跟着变，检查 app 的 setUiHost()：必须传对象引用， 不能解构。解构会切断 $state 反应性。

第 5 步：类型检查与构建 ​

bash
npm run check
npm run build

build 会把四个站都建一遍。这一步的意义不只是验证编译——它顺带告诉你改动的波及面。

第 6 步：理解部署侧的波及面 ​

这是本文最重要的一节。改 ui/ 之后：

站会发生什么
controlpush 后 Cloudflare 自动重建部署
peering同上
home同上
auth什么都不会发生

前三个站是 Cloudflare Git 关联 Worker，Build watch paths 配的是 apps/<自己>/* + ui/*，所以改共享库会同时触发它们——这是有意的。

授权界面不在 Cloudflare 上（它由源站 nginx 同源托管，理由见 internals/auth-hosting.md），因此不受 watch paths 覆盖。改了 ui/ 之后必须手工：

bash
npm run build:auth
# 然后把 apps/auth/dist/ 投放到源站

完整投放步骤与自检见 guides/deploy-auth.md。

判断法则：只要改动落在 ui/ 里，就问一句「授权页需要重建吗」。 只要那个站 用到了改动的组件或令牌，答案就是需要。

常见分支 ​

要加的是整块看板，不是原子件？ 放 ui/boards/，并遵守「由 data prop 驱动、 自己不取数、不做轮询」——这是同一个看板既能挂控制台、又能挂只读门户的全部前提。 取数、鉴权、轮询留在 app 层。

组件需要 ?url 资源（wasm、worker）？ 注意桶文件的副作用：从 $ui 导入会把桶里 所有 re-export 的资源一并 emit 到产物目录。首页的 fleet 岛就为此绕开桶文件、 直接引 $ui/host.svelte。

要改设计令牌？ 令牌在 ui/styles/app.css，且暗色值出现两次（[data-theme] 选择器与 prefers-color-scheme 媒体查询），必须同步改两处。理由见 internals/i18n-and-theming.md。