Skip to content

Commit 8b455e5

Browse files
stevenleistevenlei
committed
update documents
1 parent 034d9a4 commit 8b455e5

File tree

3 files changed

+240
-33
lines changed

3 files changed

+240
-33
lines changed

‎README.md

+80-11
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Getting DOM Elements' relative position with CSS variable when page scroll. With mapping support for values, it is easy to create scroll-to-position animation like video playback.
44

5-
Read this article in other languages: [English](README.md), [繁體中文](README.zh-Hant.md), [简体中文](README.zh-Hans.md).
5+
Read this document in other languages: [English](README.md), [繁體中文](README.zh-Hant.md), [简体中文](README.zh-Hans.md).
66

77
## Introduction
88

@@ -42,16 +42,18 @@ In the above example, CSS variable `--scrolled` will be available to `#greeting`
4242

4343
## The `tg-` Attributes
4444

45-
| Attribute | Type | Default | Description |
46-
| ----------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
47-
| `tg-name` | Required | - | The CSS variable name to store the value, with or without `--` prefix. |
48-
| `tg-from` | Optional | `0` | The start value |
49-
| `tg-to` | Optional | `1` | The end value |
50-
| `tg-steps` | Optional | `100` | How many steps between `tg-from` and `tg-to` |
51-
| `tg-step` | Optional | `0` | Step per increment, if this value is other than `0`, will override `tg-steps`. |
52-
| `tg-map` | Optional | (Empty) | map the value to another value. Format: `value: newValue; value2: newValue2`. Multiple values map to one value is also supported: `value,value2,value3: newValue` |
53-
| `tg-filter` | Optional | (Empty) | Only trigger if the scroll value is on the list. Format: `1,3,5,7,9` |
54-
| `tg-edge` | Optional | cover | When should the calculation starts. `cover` means off-screen to off-screen, the calculation begins right on the element appear; `inset` means the calculation begins after the whole element appears on screen, ends right before off-screen. |
45+
| Attribute | Type | Default | Description |
46+
| ----------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
47+
| `tg-name` | Required | - | The CSS variable name to store the value, with or without `--` prefix. |
48+
| `tg-from` | Optional | `0` | The start value |
49+
| `tg-to` | Optional | `1` | The end value |
50+
| `tg-steps` | Optional | `100` | How many steps between `tg-from` and `tg-to` |
51+
| `tg-step` | Optional | `0` | Step per increment, if this value is other than `0`, will override `tg-steps`. |
52+
| `tg-map` | Optional | (Empty) | map the value to another value. Format: `value: newValue; value2: newValue2`. Multiple values map to one value is also supported: `value,value2,value3: newValue` |
53+
| `tg-filter` | Optional | (Empty) | Only trigger if the scroll value is on the list. Format: `1,3,5,7,9`. By default, the filter mode is `retain`, if we want to switch the mode to `exact`, add an `!` at the end. Read more about this in a dedicated section below. |
54+
| `tg-edge` | Optional | cover | When should the calculation starts. `cover` means off-screen to off-screen, the calculation begins right on the element appear; `inset` means the calculation begins after the whole element appears on screen, ends right before off-screen. |
55+
| `tg-follow` | Optional | (Empty) | Use the calculation result from another element instead. The value of `tg-follow` is the value of the target element's `tg-ref`. **Important**: When `tg-follow` is set, `tg-from`, `tg-to`, `tg-steps`, `tg-step` and `tg-edge` will be ignored in the same element. |
56+
| `tg-ref` | Optional | (Empty) | Define the name that can be referenced (followed) by another element using `tg-follow`. |
5557

5658
## Value Mapping
5759

@@ -128,6 +130,73 @@ Sometimes we only interested in certain values. For example, we only want to kno
128130
</style>
129131
```
130132

133+
## The mode of `tg-filter`
134+
135+
There are two modes for `tg-filter`, `retain` by default, the other one is `exact`. Let's use an example to clarify this:
136+
137+
```html
138+
<h1
139+
id="heading"
140+
tg-name="color"
141+
tg-from="0"
142+
tg-to="10"
143+
tg-step="1"
144+
tg-filter="5"
145+
tg-map="5: blue"
146+
>
147+
Trigger.js
148+
</h1>
149+
150+
<style>
151+
body {
152+
padding: 100vh 0; /* In order to make the page have enough rooms for scrolling */
153+
}
154+
155+
#heading {
156+
--color: black;
157+
color: var(--color);
158+
}
159+
</style>
160+
```
161+
162+
In the above example, the text has an initial color of black, and it will turn blue when it arrives at the middle of the page and never turn black again because there is nothing to trigger the black color.
163+
164+
So let's say we want the text color becomes blue only when the calculation value is `5`, and becomes black for other values, We can change it to:
165+
166+
```html
167+
<h1
168+
id="heading"
169+
tg-name="color"
170+
tg-from="0"
171+
tg-to="10"
172+
tg-step="1"
173+
tg-filter="4,5,6"
174+
tg-map="4: black; 5: blue; 6: black"
175+
>
176+
Trigger.js
177+
</h1>
178+
```
179+
180+
This works, but the code becomes redundant quickly. To solve this, we can switch the filter mode to `exact` by adding an `!` at the end of `tg-filter`:
181+
182+
```html
183+
<h1
184+
id="heading"
185+
tg-name="color"
186+
tg-from="0"
187+
tg-to="10"
188+
tg-step="1"
189+
tg-filter="5!"
190+
tg-map="5: blue"
191+
>
192+
Trigger.js
193+
</h1>
194+
```
195+
196+
In `exact` mode, `--color` becomes `blue` when the value is `5`, and becomes the default when the value is other than `5`.
197+
198+
The design by adding an `!` directly to `tg-filter` is that this requirement should only happen when `tg-filter` is used. Separating to yet another attribute should not be necessary and might cause misunderstanding.
199+
131200
## Value Inheritance
132201

133202
Just like some CSS properties, the values of `tg-` attributes are inherit from parents if not being set in the current element. If we do not want to inherit from parent and set it as default value, just add the `tg-` attribute without value. For example:

‎README.zh-Hans.md

+80-11
Original file line numberDiff line numberDiff line change
@@ -40,16 +40,18 @@
4040

4141
## `tg-` 属性列表
4242

43-
| 属性名称 | 类型 | 默认值 | 简介 |
44-
| ----------- | ---- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
45-
| `tg-name` | 必填 | - | 接收卷动值的 CSS 变数名称，是否加上 `--` 前缀都可。 |
46-
| `tg-from` | 选填 | `0` | 起始值 |
47-
| `tg-to` | 选填 | `1` | 终点值 |
48-
| `tg-steps` | 选填 | `100` | 从 `tg-from` 至 `tg-to` 之间触发多少次 |
49-
| `tg-step` | 选填 | `0` | 每次递加的数值，如果此值不为 `0`，则会忽略 `tg-steps` 的设定。 |
50-
| `tg-map` | 选填 | (空白字串) | 将一个值映射至另一个值。格式：`value: newValue; value2: newValue2`。亦支援同时将多个值映射至另一个值：`value,value2,value3: newValue` |
51-
| `tg-filter` | 选填 | (空白字串) | 只当卷动值在列表当中时才触发。格式：`1,3,5,7,9` |
52-
| `tg-edge` | 选填 | cover | 计算卷动值的起始点。`cover` 代表画面外至画面外，即在元素进入画面时即开始计算；`inset` 代表在元素完整进入画面时开始计算，在刚离开画面时终止。 |
43+
| 属性名称 | 类型 | 默认值 | 简介 |
44+
| ----------- | ---- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
45+
| `tg-name` | 必填 | - | 接收卷动值的 CSS 变数名称，是否加上 `--` 前缀都可。 |
46+
| `tg-from` | 选填 | `0` | 起始值 |
47+
| `tg-to` | 选填 | `1` | 终点值 |
48+
| `tg-steps` | 选填 | `100` | 从 `tg-from` 至 `tg-to` 之间触发多少次 |
49+
| `tg-step` | 选填 | `0` | 每次递加的数值，如果此值不为 `0`，则会忽略 `tg-steps` 的设定。 |
50+
| `tg-map` | 选填 | (空白字串) | 将一个值映射至另一个值。格式：`value: newValue; value2: newValue2`。亦支援同时将多个值映射至另一个值：`value,value2,value3: newValue` |
51+
| `tg-filter` | 选填 | (空白字串) | 只当卷动值在列表当中时才触发，格式：`1,3,5,7,9`。默认情况下，过滤模式是 `retain`（保留值），在设定值末端加入 `!` 符号可以将模式切换为 `exact`（绝对）。关于两个模式的分别，请参考后续的内容。 |
52+
| `tg-edge` | 选填 | cover | 计算卷动值的起始点。`cover` 代表画面外至画面外，即在元素进入画面时即开始计算；`inset` 代表在元素完整进入画面时开始计算，在刚离开画面时终止。 |
53+
| `tg-follow` | 选填 | (空白字串) | 引用其他元素的计算值。`tg-follow` 的设定值等于目标元素的 `tg-ref` 设定值。**注意**：当设定了 `tg-follow`，同一元素下的 `tg-from`、`tg-to`、`tg-steps`、`tg-step` 以及 `tg-edge` 设定会被忽略。 |
54+
| `tg-ref` | 选填 | (空白字串) | 定义可以被其他元素通过 `tg-follow` 引用的名称。 |
5355

5456
## 映射 (Value Mapping)
5557

@@ -118,15 +120,82 @@
118120

119121
<style>
120122
body {
121-
padding: 100vh 0; /* In order to make the page have enough rooms for scrolling */
123+
padding: 100vh 0; /* 确保页面有足够空间卷动 */
124+
}
125+
126+
#heading {
127+
color: var(--color);
128+
}
129+
</style>
130+
```
131+
132+
## `tg-filter` 的模式
133+
134+
`tg-filter` 有两个模式，预设是 `retain`，另一个设定值是 `exact`。为了更好的说明差异，请参阅以下例子：
135+
136+
```html
137+
<h1
138+
id="heading"
139+
tg-name="color"
140+
tg-from="0"
141+
tg-to="10"
142+
tg-step="1"
143+
tg-filter="5"
144+
tg-map="5: blue"
145+
>
146+
Trigger.js
147+
</h1>
148+
149+
<style>
150+
body {
151+
padding: 100vh 0; /* 确保页面有足够空间卷动 */
122152
}
123153
124154
#heading {
155+
--color: black;
125156
color: var(--color);
126157
}
127158
</style>
128159
```
129160

161+
上述例子中，文字颜色初始是黑色，而将文字卷动到页面中间时，会变为蓝色。不过文字就永远都不会变回黑色了，因为没有让它改变为黑色的触发点。
162+
163+
如果我们想文字颜色只在计算值是 `5` 的时候改变为蓝色，其他时候是黑色，可以将代码更改为：
164+
165+
```html
166+
<h1
167+
id="heading"
168+
tg-name="color"
169+
tg-from="0"
170+
tg-to="10"
171+
tg-step="1"
172+
tg-filter="4,5,6"
173+
tg-map="4: black; 5: blue; 6: black"
174+
>
175+
Trigger.js
176+
</h1>
177+
```
178+
179+
这样虽然可以，不过很快我们的代码就变得冗长。为了解决这个情况，我们可以将模式切换为 `exact`，只须在 `tg-filter` 的末端加入 `!` 符号即可：
180+
181+
```html
182+
<h1
183+
id="heading"
184+
tg-name="color"
185+
tg-from="0"
186+
tg-to="10"
187+
tg-step="1"
188+
tg-filter="5!"
189+
tg-map="5: blue"
190+
>
191+
Trigger.js
192+
</h1>
193+
```
194+
195+
在 `exact` 模式下，`--color` 只会在计算值等于 `5` 的时候设定为 `blue`，其他值的时候就变为预设值。
196+
197+
直接在 `tg-filter` 中加入 `!` 符号这种设计，主要是考虑到这种需求应该只会在 `tg-filter` 中发生。如果又另外建立一个属性来设定模式，可能会变得不需要甚至容易误解。
198+
130199
## 继承
131200

132201
就像一些 CSS 属性一样，`tg-` 属性的值会继承自父级元素（如果当前元素没有设定的话）。如果不希望继承父级元素的值，并设定为默认值的话，只需增加没有值的 `tg-` 属性即可。例如：

0 commit comments

Comments
 (0)