# @crewlethq/artifact-kit 中文文档 规范地址：https://npmcn.com/package/%40crewlethq/artifact-kit/ 版本：0\.84\.2 npm 元数据更新时间：2026-10-31T20:00:25.070Z 中文译文更新时间：2026-10-31T22:11:14.915Z 软件包许可：MIT AND OFL-1\.1 AND ISC 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40crewlethq/artifact-kit 原文对照：https://npmcn.com/package/%40crewlethq/artifact-kit/?lang=original 项目主页：https://github.com/crewlet/uilet/tree/main/packages/artifact-kit#readme 源码仓库：https://github.com/crewlet/uilet ## 关键信息（来自 npm 元数据） - 包体积（解压后）：805 kB，14 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：0 个 - 首次发布：2026-10-18T19:07:10.864Z - 最新版本发布：2026-10-31T20:00:24.772Z - 已发布版本数：96（近 12 个月 96 个） ## 中文简介 Crewlet将系统设计为用于工件页面的无框架浏览器包：令牌、每个主题、字体和基本样式表、用于页面纯HTML的可选样式表、主题引导以及作为绑定到a的自定义元素的表 ## 安装 ```sh npm install @crewlethq/artifact-kit ``` 也可以使用：`pnpm add @crewlethq/artifact-kit`、`yarn add @crewlethq/artifact-kit`、`bun add @crewlethq/artifact-kit` ## README # @crewlethq / artifact-kit Crewlet将系统设计为一个无框架的浏览器包，用于人员和代理将页面作为工件发布。工件页面将它链接起来，并使用与它周围的指示板相同的标记、主题和字体进行绘制，随着阅读器的外观变化而变化，并且可以使用一个元素在其数据存储上绘制可编辑的工作表。 引擎为这个包裹服务 `dist/` 目录，未更改，从工件的原始位置 `/_crewlet/kit//`，因此页面永远不会从第三方主机获取它，并且在封闭的网络上工作。 ## 多好的网页链接啊 ```html ``` `` 是页面所针对的工具包版本（引擎的创作指南列出了它所服务的最新版本）；该引擎为它所提供的每个工具包版本提供服务，因此已发布的页面保留自己的版本。链接的前两个 ``， `theme.js` 作为一个经典的封锁脚本，在任何油漆之前。 `kit.js` 只有在绘图时才需要。 `content.css`，后面有链接 `kit.css`为页面自己编写的纯HTML设置样式([下面](https://npmcn.com/package/%40crewlethq/artifact-kit/#readme-plain-html-content)）. 然后用符号而不是文字值写出颜色、间距和类型： ```css .summary { padding: var(--spacing-3); border-radius: var(--radius-md); background: var(--color-surface-elevated); color: var(--color-text-primary); } ``` ## 纯HTML内容 `kit.css` 绘制标记和一个安静的文档基线，它将标题和段落的边距归零，并将按钮剥离为纯文本：编写自己组件的页面恰恰需要这些。编写纯HTML（报告、摘要、表单）链接的页面 `content.css` as well， AFTER `kit.css`，以及它的标题、段落、列表、引用、代码、表格、规则、数字、披露和表单控件在每个主题中都采用设计系统的外观： ```html ``` 阅读栏是文档的散文（一页） `h1` 在标题步，在阅读步和导读步运行文本，块与块之间有一个间隙，标题上方有更多间隙)；按钮是次要按钮，提交按钮是主要按钮；文本字段、文本区域和选择是中等大小的输入、文本区域和选择；一个方框、一个点、一个滑块和一个条代表重音；表的标题下有一条更牢固的规则，列中有数字，等等 `data-align="right"` (或 `"center"`)对于对齐，严格的策略将样式属性排除在外。一个宽的桌子在里面滚动 `
` 或者 `
` 它被写入而不是移动页面，并且有一长行代码封装。 它是可选择的，它是有范围的，所以它永远不会与页面上的任何其他内容相冲突： - **没有链接它的页面是不变的**，包括在它存在之前发布的每一页：它是一个独立的文件 `kit.css` 不带任何东西。 - **它只对作者写的东西进行排版。** 一、 ``，任何带a的元素 `crewlet-` 类（例如绘制在主体上的工作表的菜单）和其中的所有内容都留给工具包自己的样式表。页面的一个区域，它保留了自己选择的设计 `data-crewlet-content="off"`里面的所有东西都保持基线。 - **页面自己的类总是获胜。** 每条规则都有它的元素(`button` 是0 0 1，不管它的类型或状态)，那么 `.chip { ... }` 在每个州都是无效的。键盘环是一个被视为伪类的规则，所以控件在聚焦时保持自己的角；重新设计它的页面 `.chip:focus-visible`. 链接到后面 `kit.css`：对于相同的元素，它的每条规则都以相同的权重出现在后面，从而胜过基线的规则。 ## 一个公司的品牌 一家公司的品牌会重新设计印有球衣标志的每一页：口音和与之混合的一切，场地，正文，面孔和标志。品牌为 **输入槽**， `--brand-*` 自定义属性，以及工具包自己的令牌读取它们，因此已经写入的页面 `var(--color-brand-accent)` 或者 `var(--font-family-display)` 遵循品牌而不改变线条。在没有输入集的情况下，每个令牌都是主题自己的值，无论是在两种模式下，还是在每个命名的主题下，所以一个链接工具包的页面没有品牌，就像它一直拥有的那样。固定在早期工具包上的页面根本没有读取槽。 该引擎将公司采用的品牌生成到自己的样式表中，并将其链接到工具包旁边。样式表定义了 **只有 `--brand-*` 自定义属性（on） `:root`), `@font-face` 规则**，没有别的：没有选择，除了 `:root`，没有其他属性，因此它不能重新设计套件未选择从中读取的任何内容，并且它可以在之前或之后加载 `kit.css`． 页面也可以自己设置插槽。 | 槽 | 价值 | 怎么读 | | --- | --- | --- | | `--brand-primary` | `#rrggbb` | 亮模式下的重音，暗模式下的重音 `--brand-primary-on-dark` 不设； `--color-brand-mark`. | | `--brand-primary-on-dark` | `#rrggbb` | 暗模式下的重音。 | | `--brand-secondary` | `#rrggbb` | `--color-brand-highlight`的第二站 `--color-brand-gradient`. | | `--brand-text` | `#rrggbb` | `--color-text-primary` 在光模式下。暗模式保留主题的文本。 | | `--brand-light-ground` | `#rrggbb` | `--color-surface-frame` 和 `--color-surface-background` 在光模式下。 | | `--brand-dark-ground` | `#rrggbb` | 同样的两个在暗模式下。 | | `--brand-font-heading` | 一个 `font-family` 列表 | `--font-family-display`． 如果省略了，标题就占据了身体的正面。 | | `--brand-font-body` | 一个 `font-family` 列表 | `--font-family-sans`. | | `--brand-logo-primary`， `--brand-logo-on-dark`， `--brand-logo-mark` | `url(...)`，词根relative或absolute | 这个 `crewlet-logo` 类。 | | `--brand-logo-primary-ratio`， `--brand-logo-on-dark-ratio`， `--brand-logo-mark-ratio` | 一个数字，标志的宽度除以它的高度 | 这个 `crewlet-logo` 类。 | **一次输入可以在两种模式下重新设计整个家族。** 从每个模式的口音，工具包混合，与 `color-mix()`： | 令牌 | 混合了模特的口音 | | --- | --- | | `--color-brand-accent-hover`， `-active` | OKLab的90%和80%偏向黑色，暗了一步和两步 | | `--color-brand-accent-ink` | 文字重音：暗模式下55%偏向白色，亮模式下70%偏向黑色 | | `--color-brand-accent-soft` | 在黑暗模式下重音为16%，在明亮模式下重音为12.5%，无论它落在哪里 | | `--color-brand-accent-soft-strong`， `--color-border-selected` | 32%和60%的口音 | | `--color-brand-accent-deep` | 70%偏向黑色，渐变的深度停止 | | `--color-text-link-quiet` | 65%的墨水用在了次要文字上 | | `--shadow-glow` | 30%的重音，就像辉光一样 | | `--color-text-on-accent` | 从重音的WCAG亮度中计算出，黑色或白色，以在重音上清除更多对比度的那个 | 两个记号留下主题是故意的。 **对焦环** （`--color-focus`每个主题的比例是3:1，而任意颜色的混合是不可能的，所以键盘阅读器保留了一个他们可以看到的环。 **`--color-brand-accent-rgb`** 是一个通道三重，CSS不能从颜色派生；色彩与 `color-mix(in srgb, var(--color-brand-accent) 20%, transparent)` 而不是 `rgba(var(--color-brand-accent-rgb), 0.2)`，颜色随品牌而变化。每个派生值都是a `--crewlet-brand-*` 步骤命名它的输入，没有回退，所以输入未设置的步骤是无效的，令牌回落到主题的值；主题的值保存在 `--crewlet-theme-`，构建将它们移动到品牌层，因此品牌层是声明公共令牌的地方。颜色混合需要 `color-mix()` 并且，对于重音标签，相对颜色语法（当前Chrome， Edge， Firefox和Safari）。 该工具包不检查自身的对比：该品牌的文本是否能在浅色地面上阅读，其重音是否能在浅色地面上阅读，这是引擎检查管理员是否采用该品牌的方法。 映射并不仅仅是工具包的问题。它的一个来源是 `@crewlethq/tokens`＇ `stylesheets/brand.css`，出版于 `@crewlethq/tokens/css/brand`，在将主题的值移到一边后，工具包的构建将其捆绑到kit.css中；将选择器移到作用域上的同一源是 `@crewlethq/tokens/css/brand-scope`,这 `@crewlethq/ui`的BrandScope用于在仪表板内标记文档或板。工具包中的页面和仪表板的标记区域按照相同的规则绘制，工具包的套件使两者在每种模式下声明相同的步骤。工具包自己的图层部分是logo类(`src/brand.css`）。 ### 商标 这个 `crewlet-logo` 类从插槽中绘制品牌的徽标，因此页面永远不会写入URL，其徽标遵循下一个采用的品牌： ```html ``` | 属性 | 意义 | | --- | --- | | `data-variant` | `primary` （默认）：浅色模式下浅色地面的标志，深色模式下品牌有深色地面的on-dark标志。 `on-dark`：暗标志，无论模式如何，对于浅色页面上的暗带。 `mark`：单独标记。 | | `data-size` | `sm` （1.5rem），默认为2rem； `lg` (3快速眼动) `xl` (4 rem)高。一个页面自己的类可以设置 `--crewlet-logo-size` 而是任意长度。 | 宽度遵循徽标的比例。如果品牌没有标识的变体，它没有画，没有占用空间。给它 `role="img"` 公司的名字是 `aria-label`，如上所述。它带有一个 `crewlet-` 类,所以 `content.css` 留给工具包吧。 ## 的表 在其数据存储集上绘制可编辑的工作表 ``，其列声明为 ``： ```html ``` 或者从脚本中： ```js import { mountSheet } from '/_crewlet/kit//kit.js'; const sheet = mountSheet(document.querySelector('#grid'), { collection: 'vendors' }); // sheet.update({ ... }) draws it again with changed options; sheet.unmount() takes it down. ``` 没有自己的列的工作表绘制集合的模式：它的隐藏列被忽略，它的主列被冻结，并且这个工具包不知道的列类型被绘制为只读文本。 它是设计系统自己的 `SheetGrid`,组件仪表板吸引本地表,所以一张页面的外观和行为完全一样:键盘的电子表格(箭头,输入或编辑F2,逃脱,选项卡中,空间在一个复选框,输入替换,国防部+ C和Mod + V范围,删除,国防部+ Z和国防部+ Shift + Z),一个编辑绘制一次随着储蓄到引擎证实它,拒绝表示细胞的同步带才救了读者认为,冲突注意命名谁改变了下一个细胞 编辑，合作者的戒指和名字标志，以及光明和黑暗的主题和每一个调色板。 ### `` 属性 | 属性 | 意义 | | --- | --- | | `collection` | 工作表编辑的数据存储集合。必需的。 | | `label` | 表的可访问名称。模式的标题，然后是集合的名称，当不存在时。 | | `sort` | 初始顺序： `score` 提升, `-score` 下行。 | | `frozen` | 当工作表横向滚动时，有多少个前导列保持在视图中。 | | `readonly` | 无论读者做什么，只读地绘制表格。 | | `height` | 工作表的最大值，单位为px；它的行滚动过它。工作表的高度与其下面的行一样高，因此在添加行下面没有空白空间。没有它，床单就停在 `--crewlet-sheet-max-height` （默认为70%的视口）。 | ### `` 属性 | 属性 | 意义 | | --- | --- | | `field` | 文档字段。必需的。 | | `type` | `text`， `longtext`， `number`， `checkbox`， `select`， `multiselect`， `status`， `person`， `date`， `url` 或者 `rating`. `text` 当缺席;未知类型被绘制为只读文本。 | | `label` | 的头。缺席时的字段。 | | `options` | 选择、多选和状态选择： `Label:color` 成对，逗号分隔。选择的颜色是六种节点色调之一(`purple`， `cyan`， `green`， `amber`， `rose`， `blue`)或 `neutral`;状态是一种语气(`neutral`， `info`， `success`， `warning`， `danger`）。 | | `format` | 数字的形式： `plain`， `0.0` （小数保留）， `percent` 或者 `0.0%`， `currency:EUR`. | | `min`， `max` | 界限：数字的界限；评级的星数(`max`，默认为5)。 | | `max-length`， `max-items` | 文本的最长值；multi-select的大多数选项。 | | `width` | 列的宽度，单位是px。 | | `frozen`， `readonly`， `required`， `time` | 停留在视野中；无需编辑；拒绝空值；一个有时间的约会。 | ### 这床单缚得多紧啊 表单只与页面运行时对话， `window.crewlet` 运行时契约1.0，在引擎的 `docs/reference/artifact-runtime.md`)，因此它完全具有页面的功能，仅此而已： | 运行时调用 | 床单是怎么用它的 | 能力 | | --- | --- | --- | | `data.schema()` | 集合的标题，以及页面声明为none时的列 | `db` | | `data.collection(name).subscribe(callback, onError)` | 行，活；被拒绝的订阅将取代网格 | `db` | | `data.collection(name).merge(id, fields)`， `data.batch().merge(…).commit()` | 一次编辑，粘贴或清除范围作为一次全有或全无的写入 | `db` | | `data.collection(name).set(id, {})` | 添加一行，在一个id的工具包薄荷 | `db` | | `data.collection(name).delete(id)` | 一旦读者确认，就从行操作中删除行 | `db` | | `data.undo()`， `data.redo()` | Mod+Z和Mod+Shift+Z在页面自己的写；有人跨过一步说 | `db` | | `presence.roster()`， `presence.subscribe(…)`， `presence.set({ activity, focus })` | 合作者的戒指和旗帜，一小堆谁在这张表，和读者自己的细胞 | `presence` | | `identity.me()`， `identity.people()` | 查看器的只读表，以及person单元格提供的人员和姓名 | `identity` | | `connection.subscribe(…)` | 同步条带离线 | 无 | | `openLink(url)` | url单元格的链接，在打开它之前主机名（框架不能打开窗口） | 无 | 写入解决与引擎的裁决(`applied`， `pending`， `conflict`， `invalid`， `forbidden`， `quota` 或者 `gone`)，只在没有决定的情况下拒绝(`rate_limited`， `unavailable`， `capability_not_declared`）; 这张纸上写着要么，要么，整个粘贴被拒绝，从来没有部分。失败的添加行显示在带有Retry的工作表下。删除行（在行号上，或者Shift+F10）在工具包自己的确认中询问，从来没有一个浏览器对话框，工件框架拒绝；引擎拒绝的删除操作或运行时拒绝的删除操作将保留该行，并在其第一个单元格上显示，作为拒绝写操作保存。一个观众和一个 `readonly` 床单都没有提供。运行时拒绝的订阅(`forbidden`， `not_found`， `unavailable`， `capability_not_declared`)表示取代网格，而不是作为空集合绘制。一个没有声明的页面 `db` 获取一个显示上述内容的工作表，而不是一个空网格；没有 `presence` 或者 `identity` 这张纸没有合作者，也没有名字。一张表格只显示其中的成员：关注其集合的成员在他们所在的单元格上佩戴他们的戒指，网格上方的一个小堆栈为他们命名。它永远不会绘制页面的整个空间，仪表板的工件条为页面绘制一次，因此包含两个表单的页面不会重复两次。一旦运行时与主机的握手完成，就会绘制工作表(`crewlet.ready`)：运行时在它之前安装，但只有在那时才学习版本的功能，所以早先绘制的表将读取声明的页面 `db` 作为一个没有的人。当工具包在运行时之前加载时，它等待运行时 `crewlet:ready` 事件 `window` (出口 `RUNTIME_READY_EVENT`)，运行时在同一时刻调度。一个观众的表，和一个 `readonly` 第一，没有同步条：读者没有任何东西可以保存。 ## 里面有什么？ | 文件 | 内容 | | --- | --- | | `kit.css` | 规范变量，默认主题的深色和浅色调色板，每个命名主题下 `data-palette`，密度在下面 `data-density`，自托管的Geist和Geist Mono面和文档基线，读取的品牌层 `--brand-*` 槽([以上](https://npmcn.com/package/%40crewlethq/artifact-kit/#readme-a-companys-brand))及 `crewlet-logo` 类，然后将表的样式表、它的单元格和存在标记放在一个文件中。 | | `content.css` | 可选内容样式表：设计系统查找页面自己编写的纯HTML，然后链接 `kit.css`． 看到 [纯HTML内容](https://npmcn.com/package/%40crewlethq/artifact-kit/#readme-plain-html-content). | | `fonts/` | 幽灵的四个面 `kit.css` 引用, `OFL.txt`. | | `theme.js` | 主题引导，压缩在2 KB以下。 | | `kit.js` | 这个 `crewlet-sheet` 和 `crewlet-column` 元素和 `mountSheet`，一个ES模块。它携带设计系统的React组件和React本身，所以页面不需要自己的框架。 | | `THIRD_PARTY_NOTICES.txt` | 第三方代码的license `kit.js` 包含：MIT下的React、React DOM和调度器，以及ISC下的Lucide图形。 | `theme.js` 从框架URL的片段中读取阅读器的外观，仪表板将其放在(`#nonce=...&theme=dark&palette=dusk&density=compact`)，并写道 `data-theme`， `data-palette` 和 `data-density` 在 `` 在第一次油漆之前，就像仪表板写自己的一样。当仪表板传输桥接端口时，它遵循阅读器在其上的外观，因此更改仪表板中的主题将重新绘制页面而无需重新加载。每个值在写入之前都要根据允许的值进行检查。它说的电线是 `FrameProtocol` 在 `@crewlethq/ui`，捆绑而不是重述。 元素在LIGHT DOM中呈现，而不是在shadow根中呈现，因此令牌级联到表中，并且页面自己的样式表可以放在它旁边 `var(--color-*)`. ## 预算 构建拒绝超过任何预算的工具包，并且套件将构建文件保存到相同的数量(`scripts/budgets.mjs`): | 文件 | gzip预算 | | --- | --- | | `theme.js` | 2 KB | | `kit.css` | 40 KB | | `content.css` | 6 KB | | `kit.js` | 160 KB | ## 建筑 ```sh npm run build --workspace @crewlethq/artifact-kit # dist/ npm test --workspace @crewlethq/artifact-kit # the suite over dist/ ``` 它从 `@crewlethq/tokens` 和 `@crewlethq/ui` 当用户安装它们时，该工具包所携带的内容与发布的包所携带的内容完全相同。表单在页面上的行为（绑定、编辑、拒绝、存在、粘贴、撤消）如何在jdom中通过 `apps/ui-tests/src/artifact-kit.test.tsx`，包含测试工具的私有工作区。 ## 许可证 代码在 [MIT许可证](https://npmcn.com/package/%40crewlethq/artifact-kit/LICENSE)． Geist和Geist Mono字体文件 `dist/fonts/` 使用SIL开放字体许可证1.1 (`dist/fonts/OFL.txt`）. 第三方代码 `kit.js` 她在执照下 `dist/THIRD_PARTY_NOTICES.txt`． Crewlet的名称、标志和字符不在这些许可范围内；看到 [TRADEMARKS.md](https://npmcn.com/package/%40crewlethq/artifact-kit/TRADEMARKS.md). ## 常见问题 ### @crewlethq/artifact-kit 是什么？ Crewlet将系统设计为用于工件页面的无框架浏览器包：令牌、每个主题、字体和基本样式表、用于页面纯HTML的可选样式表、主题引导以及作为绑定到a的自定义元素的表 ### 如何安装 @crewlethq/artifact-kit？ 在项目目录运行 npm install @crewlethq/artifact-kit，或使用 pnpm add / yarn add / bun add。 ### @crewlethq/artifact-kit 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/crewlethq\_\_artifact-kit 是否存在。 ### @crewlethq/artifact-kit 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @crewlethq/artifact-kit 可以商用吗？ @crewlethq/artifact-kit 使用 MIT AND OFL-1\.1 AND ISC 许可。声明的许可为 MIT AND OFL-1\.1 AND ISC，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。 ### @crewlethq/artifact-kit 还在维护吗？ 最新版本 0\.84\.2 发布于 2026/11/01（2 天前）；至今共发布 96 个版本，其中过去 12 个月发布了 96 个；首次发布于 2026/10/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。