# @finsweet/webflow-apps-utils 中文文档 规范地址：https://npmcn.com/package/%40finsweet/webflow-apps-utils/ 版本：1\.1\.1 npm 元数据更新时间：2026-09-04T10:19:53.718Z 中文译文更新时间：2026-11-14T19:13:46.551Z 软件包许可：未声明 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40finsweet/webflow-apps-utils 原文对照：https://npmcn.com/package/%40finsweet/webflow-apps-utils/?lang=original 项目主页：https://github.com/finsweet/webflow-apps-utils 源码仓库：https://github.com/finsweet/webflow-apps-utils ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.4 MB，696 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：14 个 - peer 依赖：svelte ^5\.0\.0 - 首次发布：2025-06-19T14:28:58.941Z - 最新版本发布：2026-09-04T10:19:53.533Z - 近 30 天下载量：5796（2026-10-15 至 2026-11-13，npm 官方下载统计） - 已发布版本数：63（近 12 个月 30 个） ## 中文简介 Webflow apps 共享公用事业 ## 安装 ```sh npm install @finsweet/webflow-apps-utils ``` 也可以使用：`pnpm add @finsweet/webflow-apps-utils`、`yarn add @finsweet/webflow-apps-utils`、`bun add @finsweet/webflow-apps-utils` ## README # Webflow Apps 用户端 **内部 Finsweet 库** Finsweet的Webflow应用程序的共享UI组件和公用设施. 🔗 **[现场故事书文档](https://webflow-apps-utils.pages.dev/)** ## 安装 ```bash pnpm add @finsweet/webflow-apps-utils ``` ## 使用量 ```typescript import '@finsweet/webflow-apps-utils/index.css'; import { Button, Modal, Input, siteInfo } from '@finsweet/webflow-apps-utils'; ``` ## 项目结构 ``` src/ ├── lib/ │ ├── router/ # Client-side routing utilities │ ├── stores/ # Stores for state management │ ├── types/ # TypeScript type definitions │ ├── ui/ # UI components and styling │ │ ├── components/ # Reusable UI components │ │ └── icons/ # SVG icon components │ └── utils/ # Helper functions and utilities ``` ## 编码标准 ### 命名公约 #### 文件与文件夹名称 - **文件夹**: 使用 `kebab-case` 所有目录名称 ``` ✅ custom-code/ ✅ webflow-canvas/ ✅ browser-storage/ ❌ customCode/ ❌ WebflowCanvas/ ``` - **文件**: 使用 `camelCase` 财务报告和审定财务报表 `PascalCase` 所有文件名 ``` ✅ localStorage.ts ✅ handlePaste.ts ✅ getAllAssets.ts ✅ Button.svelte ✅ Form.svelte ❌ local-storage.ts ❌ handle_paste.ts ❌ form.svelte ``` #### 代码命名 - **构成部分**: 使用 `PascalCase` 用于组件名称 - **职能**: 使用 `camelCase` 函数名称 - **变量**: 使用 `camelCase` 变量名称 - **常数**: 使用 `UPPERCASE` 常数 - **类型/界面**: 使用 `PascalCase` 类型定义 ### 文件标准 - 保持函数文档简洁 ## 测试 UI 组件 ### 测试战略 所有UI组件应包括涵盖下列内容的全面测试: - **基本渲染**: 默认道具、自定义道具和各种配置 - **构成部分备选案文**:所有可用的变体(初级、二级、危险等) - **互动国家**: 已禁用、装入、无效和其他状态组合 - **用户交互**: 单击事件、键盘导航和格式提交 - **无障碍**: ARIA属性,焦点管理和屏幕阅读器支持 - **视觉特征**: 图标、工具提示、自定义样式和布局变化 ### 测试结构 使用 Vitest 和测试库进行组件测试 : ```typescript import { fireEvent, render, screen, waitFor } from '@testing-library/svelte'; import { describe, expect, it, vi } from 'vitest'; import Component from './Component.svelte'; describe('Component Name', () => { describe('Basic Rendering', () => { it('renders with default props', () => { render(Component); const element = screen.getByRole('...'); expect(element).toBeInTheDocument(); }); }); describe('Variants', () => { // Test all component variants }); describe('States', () => { // Test disabled, loading, invalid states }); describe('Events', () => { // Test user interactions }); describe('Accessibility', () => { // Test ARIA attributes and keyboard navigation }); }); ``` ### 测试最佳做法 - **全面覆盖**:测试所有道具、变体和状态 - **用户-儿童测试**: 注重用户互动而非实施细节 - **无障碍测试**: 验证 ARIA 属性、键盘导航和屏幕读取器支持 - **主动行为**: 使用 `waitFor` 用于测试工具提示、模式和动态内容 - **事件模拟**: 正确锁定外部依赖和事件处理器 - **国家核查**: 检查视觉状态和内在属性 ### 示例:按钮组件测试 ```typescript // Testing component variants const variants: ButtonVariant[] = ['primary', 'secondary', 'danger', 'cms']; variants.forEach((variant) => { it(`renders ${variant} variant correctly`, () => { render(Button, { variant }); const button = screen.getByRole('button'); expect(button).toHaveClass(`button--${variant}`); }); }); // Testing interactive states it('renders loading state', () => { render(Button, { loading: true }); const button = screen.getByRole('button'); expect(button).toBeDisabled(); expect(button).toHaveAttribute('aria-busy', 'true'); expect(button).toHaveClass('button--loading'); }); // Testing accessibility it('has proper ARIA attributes', () => { render(Button, { ariaLabel: 'Custom label', loading: true }); const button = screen.getByRole('button'); expect(button).toHaveAttribute('aria-label', 'Custom label'); expect(button).toHaveAttribute('aria-busy', 'true'); }); // Testing async interactions (tooltips) it('shows tooltip on hover', async () => { render(Button, { tooltip: { message: 'Help text', listener: 'hover', listenerout: 'hover' } }); const button = screen.getByRole('button'); const tooltipTarget = button.closest('.target'); await fireEvent.mouseEnter(tooltipTarget || button); expect(screen.getByText('Help text')).toBeInTheDocument(); }); ``` ## 发展 ```bash # Setup pnpm install # Development pnpm dev # Start dev server pnpm storybook # Component development # Building & Testing pnpm build # Build library pnpm test # Run tests pnpm lint # Check code quality pnpm check # Check code quality ``` ## 出版 自动发布时使用变换器。 创建更改列表 : ```bash pnpm changeset ``` 通过 GitHub Actions 将更改启动自动发布到 npm . ## 常见问题 ### @finsweet/webflow-apps-utils 是什么？ Webflow apps 共享公用事业 ### 如何安装 @finsweet/webflow-apps-utils？ 在项目目录运行 npm install @finsweet/webflow-apps-utils，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：svelte（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @finsweet/webflow-apps-utils 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @finsweet/webflow-apps-utils 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @finsweet/webflow-apps-utils 可以商用吗？ @finsweet/webflow-apps-utils 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。 ### @finsweet/webflow-apps-utils 的下载量有多少？ 根据 npm 官方下载统计，@finsweet/webflow-apps-utils 在 2026/10/15 – 2026/11/13 这 30 天内被下载 5,796 次，日均约 193 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @finsweet/webflow-apps-utils 还在维护吗？ 最新版本 1\.1\.1 发布于 2026/09/04（2 个月前）；至今共发布 63 个版本，其中过去 12 个月发布了 30 个；首次发布于 2025/06/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。