San：百度快速轻量 JavaScript 组件框架安装与使用指南

本文是 San（百度快速轻量 JavaScript 组件框架） GitHub 官方 README 的完整中文整理版，命令、示例代码与官方仓库保持一致。

官方信息

项目简介

San 是一个快速、轻量、灵活的 JavaScript 组件框架，官方英文描述是 "A fast, portable, flexible JavaScript component framework"。它不依赖重型运行时，体积小、启动快，既可以通过 npm 引入工程，也可以直接用 CDN 标签页挂载到任意页面。San 提供组件定义、模板语法、数据绑定、事件处理等能力，适合用来构建中等规模的交互页面，也能作为嵌入式组件被已有系统集成。

"快速"体现在运行时体积小、初始化开销低，不需要复杂的构建链就能跑；"轻量"意味着它没有把路由、状态管理、请求库这些能力全部塞进核心，而是把它们拆成 san-router、san-store 等独立仓库，按需取用；"灵活"则体现在它既能配合现代前端工程化流程做大型项目，也能退化成一个 script 标签里的全局变量。这种定位决定了 San 在百度内部大量用于百度云控制台等中后台场景，san-xui 就是这些业务沉淀出来的 UI 组件库。

和其他主流前端框架相比，San 的取舍很明确：它不追求大而全家桶，而是把核心做到足够小，再用一组周边仓库把生态补全。对新团队来说，这意味着学习曲线集中在核心的"定义组件 + 数据绑定 + 挂载"三件事上，路由、状态、UI 库都可以根据团队熟悉度挑选；对老团队来说，CDN 方式让 San 可以零侵入地嵌入现有页面，不必等整站重构。

适用场景

• 中后台管理系统：表格、表单、详情页等典型后台界面，配合 santd 或 san-xui 快速搭建；
• 嵌入已有系统的轻量组件：用 CDN 方式把 San 组件挂到老页面里，不需要全量重构；
• 对包体积敏感的页面：San 核心运行时小，首屏加载快；
• 需要 SSR 的内容型页面：通过 san-ssr 做服务端直出。

安装方式

San 支持两种安装路径：

方式一：npm

$ npm i san

方式二：CDN

<script src="https://unpkg.com/san@latest"></script>

CDN 方式适合演示、原型或不想引入构建工具的场景；san@latest 会始终拉取最新版本，生产环境建议锁版本号。官方还在 dist 目录说明 中列出了发布文件的区别，按需选择对应构建产物。两种方式的选择原则是：有工程化流程、要打包发布的项目用 npm；只是临时嵌一个小组件、做个 demo，或给非前端同学快速试手，用 CDN。

使用方法：快速开始

官方最小示例展示了 San 的核心用法：用 san.defineComponent 定义组件，模板里写 {{ name }} 做插值、用 {= name =} 做双向绑定，最后 attach 到页面元素。完整示例如下：

<!DOCTYPE html>
<html>
<head>
    <title>Quick Start</title>
    <script src="https://unpkg.com/san@latest"></script>
</head>
<body>
    <script>
        const MyApp = san.defineComponent({
            template: `
                <div>
                    <input type="text" value="{=name=}">
                    <p>Hello {{name}}!</p>
                </div>
            `
        });

        let myApp = new MyApp({
            data: { name: 'San' }
        });
        myApp.attach(document.body);
    </script>
</body>
</html>

这段示例的运行效果是：页面上有一个输入框，下面一行 Hello 名字!；你在输入框里打字，下方文字会实时跟着变——这就是 {=name=} 双向绑定的效果。new MyApp({ data: {...} }) 传入初始数据，attach(document.body) 把组件挂载到 DOM 上。

逐行理解这份示例：san.defineComponent 接收一个描述对象，最核心的是 template 字段，它声明了组件的 DOM 结构与绑定关系；<input value="{=name=}"> 中的 {=name=} 表示这个输入框与 data.name 双向绑定——用户输入会写回数据，数据变化也会刷新输入框；<p>Hello {{name}}!</p> 中的 {{name}} 是单向插值，只负责把数据渲染成文本。组件定义完之后，用 new MyApp({ data: { name: 'San' } }) 实例化并传入初始数据，最后调用 attach(document.body) 把组件挂到页面 body 上。这就是 San 最核心的心智模型：定义组件 → 传数据 → 挂载。

在实际项目里，data 对象通常会比示例里复杂得多，template 也会拆成多个组件文件，但骨架不变：每个组件都是一份"模板 + 初始数据 + 行为方法"的描述，通过 defineComponent 注册，再通过 new 实例化、attach 挂载。San 官方示例里的 Todos 应用就是把这套心智模型扩展到列表、勾选、删除等交互，RealWorld App 则是把它扩展成带路由和状态管理的完整应用。

示例资源

官方提供多个学习路径：

• 在线示例集合；
• Todos（AMD 版本）；
• Todos（ESNext 版本）；
• RealWorld 完整应用（带 store）。

两个 Todos 例子分别展示了 AMD 与现代 ESNext 模块写法，RealWorld App 则是一个接入了 san-store 的完整中型应用，可以作为工程结构参考。阅读顺序建议：先打开在线示例直观感受效果，再克隆 Todos(ESNext) 对照自己机器跑一遍，最后看 RealWorld App 理解中型应用如何组织 store、路由与组件。

官方文档

• 开始
• 教程
• API 文档
• ANode 说明
• APack 说明

其中 ANode 是 San 的内部抽象节点模型，APack 是对应的打包格式，深入定制渲染器时才需要看；日常使用从"开始 → 教程 → API"顺序阅读即可。官方文档站同时提供中英文两个版本，README 顶部的 HomePage 链接指向英文版，"网站"链接指向中文版，初次阅读建议用中文版，查阅 API 时再切到英文版。

周边生态

San 的生态由一系列独立仓库组成，按用途分类：

实际选型上，一个新工程通常的组合是：san-cli 起项目 → san-router 做路由 → san-store 管状态 → 三选一 UI 库（santd / san-mui / san-xui）→ san-test-utils 写测试；需要 SEO 时再加 san-ssr。这套组合的好处是每一层都可以独立替换：比如不喜欢内置状态管理，可以换自己的方案；不喜欢内置 UI 库，也可以基于原生 San 组件自己画。

常见问题（FAQ）

• 问：San 和 Vue/React 是什么关系？ 答：它是百度自研的轻量组件框架，提供类似的组件化、模板、数据绑定能力，但不依赖虚拟 DOM 运行时，体积更小，适合对首屏和包体积敏感的页面。
• 问：怎么引入到项目？ 答：npm 工程执行 npm i san；纯静态页面直接 <script src="https://unpkg.com/san@latest"></script>。
• 问：双向绑定怎么写？ 答：模板里用 {=name=}，例如 <input value="{=name=}">，输入变化会自动同步到 data.name；普通插值用 {{ name }}。
• 问：想做单页应用要配什么？ 答：官方提供 san-router，支持 hash 与 html5 两种路由模式；状态管理用 san-store。
• 问：有没有现成 UI 组件库？ 答：有三套：santd 走 Ant Design 风格、san-mui 走 Material Design 风格、san-xui 是百度云控制台风格。
• 问：支持服务端渲染吗？ 答：支持，用 san-ssr 这个官方框架。
• 问：单文件组件怎么配？ 答：用 san-cli 起工程，配合 san-loader 这个 Webpack loader。
• 问：单元测试用什么？ 答：官方有 san-test-utils。
• 问：版本更新记录在哪看？ 答：见 CHANGELOG.md。
• 问：模板里除了 {{}} 和 {= =} 还支持什么？ 答：官方文档"教程"和"API"里列出了完整指令清单，包括事件绑定、条件渲染、列表渲染等；深入用法以官方 API 文档为准。
• 问：想调试组件内部数据怎么办？ 答：安装 san-devtools 浏览器扩展，它可以在开发者工具里展开组件树、查看每个组件的 data。
• 问：怎么贡献代码？ 答：仓库 README 没有单独的贡献流程章节，按标准 GitHub fork → 分支 → PR 流程即可；遇到问题先在 Issues 搜索。
• 问：MIT 协议可以商用吗？ 答：可以。San 是 MIT 协议，允许任意商业使用与二次开发。
• 问：RealWorld 应用长什么样？ 答：san-realworld-app 是按 RealWorld 规范实现的完整社区应用，包含文章列表、详情、评论、登录注册等模块，是观察 San 中型项目结构的最佳样本。
• 问：AMD 和 ESNext 两个 Todos 示例怎么选？ 答：新项目直接看 Todos(ESNext)；想了解老系统如何用 AMD 方式加载 San 时再看 Todos(AMD)。
• 问：CDN 用 unpkg 还是自己托管？ 答：示例里用的是 https://unpkg.com/san@latest，演示方便；正式生产建议把对应的构建产物下载到自己的 CDN 或静态服务器，避免依赖第三方 CDN 的可用性。
• 问：npm 包名是什么？ 答：就是 san，安装命令 npm i san，包主页在 npmjs.com/package/san。
• 问：San 有中文版文档吗？ 答：有。官网中文版在 baidu.github.io/san，英文版在 baidu.github.io/san/en，README 顶部也直接放了两个入口。
• 问：特别感谢里提到的"文心快码源力计划"是什么？ 答：README 末尾放了一张文心快码源力计划的标志，表示该项目在开发过程中得到了百度文心快码（Comate）源力计划的支持，属于致谢信息。
• 问：san 包当前版本怎么看？ 答：README 顶部的 npm 徽章会实时显示当前版本号，也可以直接访问 npmjs.com/package/san 查看版本、下载量与许可证。
• 问：能不能只用 CDN 写一个完整的小应用？ 答：可以。把 Quick Start 里的单文件 HTML 复制下来，扩展 template 里的交互、加几个方法即可，不需要任何构建工具；官方示例 Todos(AMD) 就是这种思路的完整版本。
• 问：san-cli 解决什么问题？ 答：它是官方命令行工具，用于快速创建 San 应用骨架，免去自己配 Webpack、目录结构、构建脚本的重复劳动；配合 san-loader 还能直接使用单文件组件（.san）。
• 问：san-test-utils 怎么用？ 答：它是官方的单元测试工具库，封装了挂载组件、触发事件、查找子组件、断言渲染结果等常用操作，让你不必自己写胶水代码来在测试环境里跑 San 组件。
• 问：san-update 是干什么的？ 答：它是一个 Immutable 风格的数据更新库，在管理嵌套状态时让你用声明式方式产生新对象而不改动原对象，配合 san-store 使用。
• 问：san-composition 是什么？ 答：组合式 API，提供与组合式函数类似的逻辑组织方式，便于把可复用的业务逻辑抽出来在多个组件间共享。
• 问：san-factory 解决什么问题？ 答：组件工厂，帮助你在不同运行环境下更灵活地注册和实例化组件，比如在 SSR 或多实例场景下复用同一份组件定义。
• 问：san-anode-utils 是什么？ 答：ANode 处理工具库，给需要深入到 San 内部模板编译与抽象节点操作的高级用户使用，日常业务开发不需要碰。

跳转链接

• 仓库：github.com/baidu/san
• 官网（中文）：baidu.github.io/san
• 官网（英文）：baidu.github.io/san/en/index.html
• npm：npmjs.com/package/san
• 在线示例：baidu.github.io/san/example
• 教程：baidu.github.io/san/tutorial/setup
• API：baidu.github.io/san/doc/api

San 基于 MIT 协议 开源，可自由商用。官方在 README 末尾特别感谢了 文心快码源力计划 对项目的支持。

整体上，San 是一个"小核心 + 大周边"的组件框架：核心只提供组件定义、模板、双向绑定和挂载；路由、状态、SSR、UI 库、调试、测试、CLI 全部由独立仓库承担。初次接触按"npm 安装 → 跑通 Quick Start → 阅读在线示例 → 挑一个 UI 库搭 CRUD 页面 → 接入 router 与 store"的路径即可上手。