diff --git a/docs/guide/SSR.md b/docs/guide/SSR.md index c20cb354..8cf335f2 100644 --- a/docs/guide/SSR.md +++ b/docs/guide/SSR.md @@ -1,6 +1,6 @@ --- group: 指南 -order: 3 +order: 5 --- # SSR(服务端渲染)支持 diff --git a/docs/guide/advanced.md b/docs/guide/advanced.md new file mode 100644 index 00000000..870ecc23 --- /dev/null +++ b/docs/guide/advanced.md @@ -0,0 +1,6 @@ +--- +group: 指南 +order: 3 +--- + +# 进阶 diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md index 5928b025..d73c4e10 100644 --- a/docs/guide/introduction.md +++ b/docs/guide/introduction.md @@ -42,6 +42,10 @@ Banana 最大的特点是它是一个基于 Web Components 的组件库,这意 可以。Banana UI 已经在一些项目中使用。但是请注意,它仍然处于早期阶段,可能会有一些问题。如果你在使用过程中遇到了问题,欢迎在 [Issues 区](https://github.com/FriedRiceNoodles/banana-ui/issues) 上提出问题或寻求帮助。 +### Banana UI 使用了什么技术? + +Banana UI 底层基于 [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components),并使用 [Lit](https://lit.dev/)进行开发。 + > 作者注:我目前在一个跨境电商公司工作,公司最大的 C 端项目以及它的一些内部系统都在使用 Banana UI。
diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md index 87003923..701c37f6 100644 --- a/docs/guide/quick-start.md +++ b/docs/guide/quick-start.md @@ -56,6 +56,70 @@ export default function App() { } ``` +## Attribute 和 Property + +如果你使用 Google 翻译,你会发现 [Attribute](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Attributes) 和 Property 都被翻译成了属性,但实际上它们并不是等价的。 + +简单来说,Attribute 是 HTML 标签上的属性,而 Property 是 DOM 对象上的属性。 + +对于 Banana UI 而言,我们会把 Attribute 和 Property 以一定的规则互相转换。转换的规则取决于具体组件属性的类型。 + +- 如果属性是字符串类型,那么 Attribute 和 Property 是等价的。 +- \*如果属性是数字类型,那么 Attribute 在被转换成 Property 时会被自动转换成数字类型(如果可以的话)。 +- 如果属性是布尔类型,那么 Attribute 出现在标签上就表示为 true,不出现就表示为 false。 +- 如果属性是对象或者数组类型,那么 Attribute 和 Property 的转换相当于 JSON.stringify 和 JSON.parse。 + +举个例子: + +```html +/* disabled 为 true */ +按钮 +/* disabled 仍然为 true */ +按钮 +``` + +:::info +这样的规则是基于 html 标签只能写入字符串这一限制,如果你是 React 用户,使用`@banana-ui/react`,则可以无视这些规则。 +具体规则请查看[这里](https://lit.dev/docs/v2/components/properties/#conversion-type),并以组件文档为准。 +::: + +在 html 标签中传入对象或数组类型的属性时,需要使用`JSON.stringify`,如: + +```html +按钮 +``` + +这种场景我们推荐直接修改 Property,如: + +```javascript +const button = document.querySelector('b-button'); +button.data = { name: 'banana' }; +``` + +## 监听事件 + +你可以像监听普通的 DOM 事件一样监听 Banana 组件的事件。 + +```javascript +const button = document.querySelector('b-button'); +button.addEventListener('click', () => { + console.log('Hello Banana'); +}); +``` + +:::info +对于 React 用户,使用`@banana-ui/react`,事件的名称会被转换为符合 [React 事件命名规范](https://react.dev/learn/responding-to-events#naming-event-handler-props)的形式。如`afterHide`会被转换为`onAfterHide`。 +::: + +## 方法调用 + +有些组件会暴露一些方法,你可以通过调用这些方法来实现一些功能。 + +```javascript +const collapse = document.querySelector('b-collapse'); +collapse.show(); +``` + ## 服务端渲染(SSR)支持 详情请查看 [服务端渲染(SSR)支持](/guide/SSR)。 diff --git a/docs/guide/react.md b/docs/guide/react.md new file mode 100644 index 00000000..c877fe50 --- /dev/null +++ b/docs/guide/react.md @@ -0,0 +1,6 @@ +--- +group: 指南 +order: 4 +--- + +# React